tasks-to-code

Tasks to Code

Purpose

This skill is the final step in the build pipeline:

idea-to-prd  →  prd-to-design  →  design-to-tasks  →  tasks-to-code
  (what/why)      (architecture)     (task list)         (build)

It takes a tasks.md produced by design-to-tasks and implements one task at a time, following the project’s existing patterns and recording every decision made. The plans/ folder becomes a complete, auditable paper trail from idea through to shipped code.

File Structure

This skill reads plans/<name>/prd.md, tasks.md, and plans/<name>/design.md when it exists, updates tasks.md, and writes plans/<name>/decisions.md. The full plans/ layout is defined in shared conventions.

Rules:

• Always read both tasks.md and prd.md before touching any code; also read design.md when present — it is the architecture the task implements
• Never modify prd.md or design.md — they are the source of truth for requirements and structure
• Always update tasks.md at the start (mark [~]) and end (mark [x] or [!]) of each task
• Decisions are recorded in plans/<name>/decisions.md (created if it doesn’t exist)

Workflow

Phase 1: Orient

Before writing any code, understand what to work on and what “done” looks like.

1. Read tasks.md — identify the next task to implement. Default: the first [ ] task with the highest priority (P0 before P1 before P2). If the user specifies a task by ID (e.g. “work on task 2.3”), use that task instead.
2. Read prd.md (and design.md if the plan has one) — locate the functional requirements, user stories, and acceptance criteria referenced by this task, plus the component boundaries and contracts the design defines. The PRD is the authoritative source of truth for requirements; if the task and PRD disagree, surface the conflict to the user before proceeding.
3. Check dependencies — confirm all listed dependencies are [x] complete. If a dependency is not done, mark the current task [!] with a note explaining the block and stop.
4. Mark the task [~] — update tasks.md before beginning any implementation work. Only one task should be [~] at a time.

What you need from this phase:

• The exact acceptance criteria you must satisfy
• The PRD requirements this task traces to (FR-N, US-N, NFR-N)
• Whether any open questions or blocks exist

Phase 2: Discover

Understand how the project does the thing this task requires — before inventing your own approach.

Run targeted discovery focused on the task’s implementation area. Do not re-run full codebase discovery if it was recently done; supplement with task-specific investigation.

See ../idea-to-prd/references/codebase-discovery.md for the full discovery checklist. For implementation, focus especially on:

• Existing patterns — find the closest analogous feature already in the codebase. If Task 2.3 is “add a notifications endpoint”, find the existing endpoints and follow their structure exactly.
• File placement — where does this type of file live? What is the naming convention?
• Test patterns — where do tests for this type of component live? What test utilities already exist?
• Quality gates — confirm which commands must pass: lint, test, build, typecheck, etc. These are all required. Miss one and the task is not complete.

If you cannot find an analogous pattern and the right approach is genuinely unclear, do not guess. Surface the question to the user in Phase 3.

See references/implementation-guide.md for pattern-first implementation principles.

Phase 3: Plan

Before writing any code, state your approach explicitly.

Produce a brief implementation plan (in your working context, not a file):

1. Files to create or modify — list each one with a one-line description of the change
2. Approach — one paragraph describing how you will implement the task, referencing the specific patterns you found in Phase 2
3. Risks and unknowns — anything that could cause the implementation to deviate from the acceptance criteria

Stop here if:

• A dependency is unmet (mark [!] and explain)
• An open question in the PRD would materially change the implementation
• You cannot find a clean pattern to follow and the right choice is not obvious
• The plan has a design.md and the implementation cannot honor one of its contracts, boundaries, or ADRs (the chosen library can’t do it, the contract doesn’t survive contact with the code)

In these cases, surface the specific question to the user. Do not make major architectural decisions silently. A design conflict routes through prd-to-design’s design-change protocol — the design and its ADRs are revised there and tasks updated by design-to-tasks; never quietly implement something other than what design.md says.

For minor unknowns (e.g., which of two equivalent naming conventions to use), pick the one more consistent with the surrounding code, proceed, and log the decision in decisions.md.

Phase 4: Implement

Write the code. Follow the principles in references/implementation-guide.md.

Core rules:

1. Pattern-first — implement using the patterns found in Phase 2, not generic patterns from outside the project
2. Minimal footprint — implement only what the acceptance criteria require. Do not refactor adjacent code, add extra features, or improve things not in scope for this task. If you spot an improvement, note it in decisions.md under “Future Opportunities” — do not implement it.
3. One task, one deliverable — each implementation produces a single verifiable unit of work
4. Justify new dependencies — if the task requires a library not already in the project, call this out explicitly before adding it. Prefer extending existing dependencies.
5. Error handling — follow the project’s existing error patterns. Do not introduce a new error handling approach unless the PRD explicitly requires one.

Phase 5: Verify

Confirm the implementation satisfies the task before marking it complete.

See references/verification-guide.md for the full checklist. Key steps:

1. Run all quality gates — run every quality gate command discovered for the project (lint, test, build, typecheck, format — all of them). If any gate fails, fix it before proceeding. Do not mark a task [x] with a failing quality gate.
2. Check acceptance criteria — step through each acceptance criterion in the task. Verify it concretely: run a command, inspect output, check a file exists. Check off each sub-checkbox as it passes.
3. Regression check — confirm no existing tests were broken by the change.
4. Manual verification when needed — for UI/UX tasks, generated output, or security-sensitive changes: surface the result to the user for visual or contextual inspection before marking complete.

If verification reveals that the implementation does not satisfy the acceptance criteria, fix it in Phase 4 and re-verify. Do not mark the task complete until all criteria pass.

Phase 6: Record

Update the task list and decision log to reflect the completed work.

In tasks.md:

1. Check off each satisfied acceptance criterion sub-checkbox: [ ] → [x]
2. Change the task marker from [~] to [x]
3. Add a completion note under the task’s Notes field:

- **Completed**: YYYY-MM-DD. [One sentence summarizing what was done and any notable decision made.]

4. Update the statistics table in the Overview section — recompute it with the deterministic helper rather than adjusting counts by hand:

python3 skills/_shared/scripts/plan-metrics.py plans/<name>/tasks.md

Copy its totals into the statistics table; if the table and the script ever disagree, the script is the arbiter.

5. Update the phase header count (e.g. Phase 1: Foundation (6/8 tasks complete)) from the script’s per-phase breakdown

In decisions.md:

Record any decisions made during implementation. See references/decision-log.md for the format. Log decisions for:

• Deviations from the PRD (even minor ones)
• Assumptions made when acceptance criteria were ambiguous
• Pattern or library choices when multiple valid options existed
• Anything that future work should know about this implementation

Looping

After completing a task and updating both files, ask the user:

Task N.M is complete. The next task is [N.M+1 title] [priority] [effort]. Shall I continue?

Wait for confirmation before starting the next task. Do not auto-chain tasks without user acknowledgment.

If the user says to continue, return to Phase 1 for the next task. If the user wants to stop, leave tasks.md in its current state — the in-progress task is already marked [x] and the next task remains [ ].

Batch authorization. When the user explicitly authorizes a batch up front (“implement all of phase 1”, “keep going until the phase is done”, or an autonomous run with standing approval), auto-chaining within that batch is allowed. The batch changes pacing, never rigor: every task still gets the full Phase 1–6 treatment, one task is [~] at a time, and the batch stops immediately at the first [!] block, failing quality gate, or design conflict — never push through a failure to keep the batch moving. At the batch boundary, report per-task results, run plan-metrics.py for the updated totals, and return control.

Phase boundaries. When a task completes its phase, recommend a code-review pass over the phase’s changes before starting the next phase — a phase is a natural, independently-deployable review unit, and catching a systemic issue now is cheaper than after three more phases build on it. Always recommend code-review when the plan’s remaining work depends on the code just written.

Handling Blocks

When a task cannot be completed, mark it [!] and stop:

- [!] **Task title** `[P0]` `[M]`
  - **Blocked**: [Specific reason. What needs to happen to unblock. Who needs to act.]

Common block reasons:

• A dependency task is not [x] complete
• An open PRD question would change the implementation direction
• A required external resource (API key, design spec, third-party access) is unavailable
• A quality gate cannot be made to pass without resolving an underlying issue in another part of the codebase

When blocked, do not attempt a workaround that violates the task’s scope. Surface the block clearly and stop.

Key Principles

The PRD is authoritative. The task list is a derivative. If a task’s acceptance criteria and the PRD conflict, the PRD wins. Surface conflicts before implementing.

One task at a time. Never have more than one task marked [~]. Finish, block, or hand off the current task before claiming another.

No gold-plating. Only implement what the acceptance criteria require. Every line of code should trace back to an acceptance criterion.

Decisions are documented. Any non-obvious choice made during implementation must appear in decisions.md. Future work depends on understanding why things were built the way they were.

Quality gates are non-negotiable. A task is not complete if a quality gate fails. Fix the gate or mark the task [!] with the specific gate failure noted.

References

• references/implementation-guide.md — Pattern-first implementation principles and discipline rules
• references/decision-log.md — Format and standards for recording implementation decisions
• references/verification-guide.md — How to verify a task against its acceptance criteria and quality gates
• ../_shared/scripts/README.md — plan-metrics.py: deterministic statistics for the tasks.md Overview table
• ../_shared/references/conventions.md — Shared status markers, priority, and the plans/ layout (single source of truth)
• ../idea-to-prd/references/codebase-discovery.md — Full codebase discovery checklist (shared reference)