---
name: implementation-planning
description: "Synthesise requirements, codebase analysis, and library research into a concrete implementation plan that splits every acceptance criterion into automated test cases and manual test steps, plus a CI readiness check and a documentation update plan. Runs inline (not as an isolated agent) so it can ask the user directly when the test strategy can't be inferred. Posts the plan to the Task Issue (or creates a standalone Issue) via gh. Use for Phase 6, after Phases 1-5 have completed."
---

Read [the Codex runtime adapter](../../docs/codex-runtime.md) before following this workflow.

# Implementation Planning — Phase 6

You are the **Implementation Planner**. Unlike the investigation phases, you
run inline in the orchestrator's session, specifically so you can ask the user
directly when a criterion's routing can't be inferred from the available
reports.

Your plan has two consumers, and the split matters: **`test-writer` reads the
test-case table and the manual steps to write the specification, and
`implementer` reads the technical specification to satisfy it.** Write the
test-case table as behaviour a human will approve at a gate, not as a list of
functions to cover.

## Quick Reference

- Plan template: [templates/implementation-plan-template.md](templates/implementation-plan-template.md)
- Criterion routing and CI rules: [reference.md](reference.md)
- This project's Test Command and any Verification Tool, if documented:
  `docs/tools/implementation-planning.md` (absent is fine — fall back to the
  defaults `reference.md` describes)
- Where the plan itself is allowed to live: [../../docs/vcs-minimalism.md](../../docs/vcs-minimalism.md)
- The test-first contract the plan feeds: [../../docs/test-first.md](../../docs/test-first.md)
- The filesystem/network constraints this run operates under (you write the
  plan file and post it via `gh`): [../../docs/sandbox-environment.md](../../docs/sandbox-environment.md)

---

## Workflow

### 1. Read All Available Reports

`requirements-report.md`, `impact-analysis-report.md`,
`library-usage-report.md` (if present), `AGENTS.md`, and the
`docs/design/<slug>.md` this task belongs to.

### 2. Route Every Acceptance Criterion

There is no single "test strategy" to pick. Each acceptance criterion in the
requirements report's Definition of Done goes into one of three buckets, and
most tasks end up with something in more than one:

| Bucket | Becomes | Where it lands |
|---|---|---|
| A runner can check it | An automated test case | The test suite |
| A runner genuinely cannot | A manual test step | `docs/manual-tests/<slug>.md` — committed |
| Deliberately not specified this task | An out-of-scope row | The plan's Out-of-Scope section |

Both kinds are written by `test-writer`, approved by the human at the Phase 9
gate, and frozen in the same test commit. The only difference is that one is
executable and the other isn't (`../../docs/test-first.md`).

`automated` is the default and the strong preference — an executable document
can't silently rot. [reference.md](reference.md) has the full routing rules
(the Definition of Done first, then `docs/tools/implementation-planning.md`),
including what does *not* count as a reason to send a criterion to manual.

**If a criterion is genuinely ambiguous, ask
the user** — `ask_user`, naming the criterion and what makes it
ambiguous, with "automated test" and "manual test step" as the options. This is
the reason this phase runs inline rather than as an isolated agent; use it.

### 3. Check CI Readiness (whenever there are automated test cases)

Look for CI that will actually run this suite: `.github/workflows/*.yml` and
`*.yaml`, plus the Test Command in `docs/tools/implementation-planning.md`, if
that file exists. Record in the plan which of these holds:

- CI exists and runs this suite — nothing to do.
- CI exists but doesn't cover it — `test-writer` extends it.
- No CI at all — `test-writer` adds it, in the test commit.

Approved tests that nothing runs on merge are a specification nobody enforces,
so this is in scope for the task rather than deferred (see
[reference.md](reference.md)).

### 4. Write Both Tables

**Automated test cases** — one row per behaviour, phrased as the observable
behaviour and its expected result. Include the boundaries the requirement
implies: empty input, the limit and limit ± 1, the specified error cases.

**Manual test steps** — one numbered step per behaviour, each with its action
and the exact observation that constitutes a pass, plus a one-line reason it
isn't automated. Name any Verification Tool from
`docs/tools/implementation-planning.md` a step needs.

Either table may be empty; say "none" explicitly rather than omitting the
section. **Both empty is not a valid plan** — that task has no specification to
approve at the Phase 9 gate.

Mark anything deliberately unspecified as out-of-scope rather than dropping it
silently; the human sees these tables' consequences at the Phase 9 gate.

### 5. Compose the Plan

Write `.codex/workflow-runs/implementation-workflow/<task-id>/implementation-plan.md` from
[templates/implementation-plan-template.md](templates/implementation-plan-template.md).

The **Documentation Update Plan** section covers only `AGENTS.md` and
`README.md` — never `docs/design/<slug>.md`. And note in the plan any decision
you can already see coming that will need an ADR, so the implementer isn't
deciding under time pressure at the end. [reference.md](reference.md) has both
in full.

### 6. Publish

- `source_type == map-issue`: `gh issue comment <task-issue-number>
  --body-file -` with the plan content.
- `source_type == standalone`: `gh issue create --title "[<task-id>]
  <summary>" --body-file -` with the plan content; record the new number/URL.

The plan lives on the Issue, not in the repository — it's *how*, and it's a
snapshot of intent at one moment. Never commit it.

## Return Value

Return the plan path, the automated/manual test-case counts, the CI readiness
finding,
and the **tracking issue number** (the Task Issue for `map-issue`, or the one
just created for `standalone`) plus its URL. The orchestrator calls this
`TRACKING_ISSUE_NUMBER` from here on; every later phase that touches GitHub
uses it regardless of `source_type`.