Task: Implement a Plan — TDD with Tasks and Subagents

Task: Implement a Plan — TDD with Tasks and Subagents

Objective

Produce working code that satisfies an implementation plan, plus an IMPLEMENTATION.md that serves as the post-implementation record of what actually happened — every task completed, every test run, every deviation from the plan, and every issue encountered. The document must let a downstream agent (reviewer, verifier, next work unit) pick up without re-reading the diff: it states the final test-suite state, the interfaces that were stabilised, and the gotchas discovered along the way.

The defining discipline — and the commonest violation — is tests first, green before next task, deviations from the plan documented with rationale: every task starts by writing tests that fail for the right reason, every task ends with the full suite green, and every divergence from the plan is captured in the output with a one-sentence why. The commonest failure is moving on to the next task while a test is still red — or silently making a design change that the plan did not call for and leaving the deviation undocumented. Both of those break the chain that downstream review and verification depend on.

Inputs

1. Implementation plan (required) — the source of truth for what to build and in what order. Usually a PLAN.md in the repo; may also be a document or direct user input. Task ordering, verification criteria, and interface definitions come from here.
2. Existing codebase (required, auto-discovered) — the current state of the repository. Discovered from the working directory. The plan may reference or build upon existing files; read them before writing.
3. Unit identifier (optional) — the u<NN> the plan belongs to, if the project organises work in units/<area>/u<NN>/. Auto-discovered from the plan's frontmatter or from the unit folder path. Used in the output frontmatter's unit field.
4. Upstream artifacts (optional, auto-discovered) — DOMAIN.md, INTERFACES.md, BEHAVIOR.md, or sibling SPEC.mds referenced by the plan. Read on demand when the plan cites them; do not pre-load everything.

Workflow

Implementation proceeds in four phases: task creation, iterative TDD implementation, verification, and documentation.

Phase 1: Create Tasks

Read the plan and break it into trackable tasks. Use your judgment on how to split them — the plan's structure is a guide, not a mandate. Each task should be a meaningful, completable unit of work.

Phase 2: TDD Implementation Loop

Work through tasks following the plan's ordering. For each task, the recommended approach is test-driven development:

1. Write tests first. Based on the plan's verification criteria, write test cases covering happy path, error paths, and edge cases.
2. Run tests — confirm they fail. Verify the new tests fail for the right reasons (missing implementation, not syntax errors).
3. Write the implementation. Build the code described in the plan step.
4. Run tests — confirm they pass. Run the full test suite to verify correctness and no regressions.
5. Iterate if needed. If tests fail, fix and re-run. Do not move to the next task until all tests pass.
6. Mutate to verify the test catches regressions. For behavioural tests, mutate the production code to break the behaviour the test asserts, re-run the test, confirm it fails for the right reason, then restore the production code. Skip for trivial assertions, refactors, and doc-only changes.

Mark each task as completed before moving to the next.