plan-to-code

Plan to Code

Stage 3 of 4. Consumes a plan and one task number. Produces code, one commit, and ticked checkboxes. Runs once per task, in its own session.

Announce at start: "Using plan-to-code to implement Task N of this plan, and only Task N."

The whole point of this skill is that it stops. It stops before verifying, because the user verifies. It stops at the task boundary, because the next task gets a fresh session. Momentum past either of those points is the failure mode this design exists to prevent.

1. Take the arguments

You need a plan path and a task number. Never choose a task yourself.

If the task number is missing, read the plan, then print exactly and stop:

No task number was given, so I have not started anything.

Unchecked tasks in <plan path>:

  Task 4: <title>
  Task 5: <title>

Next is Task 4. Start it with:

  Use the plan-to-code skill with <plan path> task 4

I will not pick a task on my own.

If the plan has no task with that number, print the same list and stop.

2. Check the preconditions, before writing anything

Both gates run before any file is touched, including the plan file.

Dirty working tree. Run git status --short. If anything is listed, print exactly and stop:

The working tree has uncommitted changes, so I have not started Task <N>.

<git status --short output>

This skill commits exactly one task, and it cannot do that cleanly on top of unrelated
changes. Commit or stash them, then run this again.

Out of order. Scan the plan for - [ ] **Task lines with a lower number than the one requested. If any exist, print exactly and stop:

Task <N> was requested, but earlier tasks are still unchecked:

  Task 1: <title>
  Task 2: <title>

Tasks are ordered because later ones consume interfaces earlier ones produce.

Reply "proceed anyway" to start Task <N> regardless, or start Task 1 instead.
I will not proceed until you answer.

Already ticked. If the requested task's box is already ticked, say so and stop.

3. Pin the base commit and the branch

Read the plan header. If **Base commit:** is empty, this is the first task to run against this plan, so record the fixed point now, before any change:

• **Base commit:** gets the output of git rev-parse HEAD.
• **Branch:** gets the output of git rev-parse --abbrev-ref HEAD.

Write both into the plan header and nothing else. If either is already filled, leave it exactly as it is. This is the fixed point code-to-review diffs against, so it is recorded once and never revised.

When you fill these in and the branch is main or master, add this line once, as a notice and not a refusal, since this skill never creates branches:

Note: base commit pinned on <branch>. Every task in this plan will commit here.

4. Load the context, and no more

Read exactly this much:

Earlier tasks exist to tell you the names and signatures you must consume. Their steps, their code, and their tests are none of your business this session.

State in one short block which artifacts you read.

The ## Global Constraints section applies to this task even though it is not repeated inside it. Treat every line of it as a requirement of Task N.

5. Implement exactly one task

Follow the task's steps in order. Write the failing test, then the implementation, as the task lays out.

Do not start, peek at, or quickly also do any other task. If implementing this task reveals work that belongs elsewhere, write it on a deferred list for the closing report and stop at the task boundary regardless. A task that is easy to also do is still a different task, and it gets its own session, its own verification, and its own commit.

If a step cannot be followed as written because the plan is wrong about the codebase, say so and stop. Do not improvise around a plan defect.

6. Tick nothing yet

Do not touch a checkbox during implementation. A checkbox records verified work, not attempted work. There is no partial credit and no in progress state.

7. Stop and name the tests

Do not run the build. Do not run the test suite. Do not run a single test. Building and testing is the user's job, and this skill has no opinion it is entitled to form about the result.

Do not print a build command or a test command either. The user builds and runs their own project every day and does not need to be told how. What they cannot know without reading the task is which tests this task made relevant.

Print exactly this, filled from the task, then wait:

Task <N> is implemented. I have not built it and I have not run any tests.

Tests to run:

  New       <test name>
            <test name>
  Affected  <test name>

A pass looks like: <the task's "A pass looks like" line>

Tell me the result. I will not tick a checkbox or commit until you confirm those pass.

Omit the New or Affected group if the task has neither. If the task names no tests at all, say so plainly rather than inventing some, and ask what the user wants to verify.

Then stop and wait. Silence is not confirmation.

8. The failure path

If the user reports a build break or a test failure, fix it within the scope of this task, then reprint the block from step 7 with one added line naming what changed. Loop until the user confirms a pass.

If the fix would need work outside this task, print exactly and stop:

Fixing this needs work outside Task <N>.

  You reported:  <the failure>
  The cause:     <what is actually wrong>
  The fix needs: <what it would take>
  Out of scope because: <which task owns it, or that no task does>

Task <N> stays as it is. Tell me whether to expand Task <N> deliberately, defer this to
a new task, or stop here. I will not widen the task on my own.

9. Tick, only after explicit confirmation

Only once the user has said in words that the project builds and the tests pass:

• Tick every step checkbox in Task N.
• Tick the - [ ] **Task N complete** box.

Edit the plan file in place. The plan is the single source of truth for progress. Never write a separate state file, a progress log, or a summary document.

10. Commit, locally

git add <the files this task touched> <the plan path>
git commit -m "<the task's Commit message, verbatim>"

Stage the task's files plus the updated plan. Use the plan's commit message unchanged.

Forbidden, without exception: creating a branch, creating a worktree, pushing, opening a pull request, merging, rebasing, tagging, or amending an earlier commit. If the user wants any of those, they will ask for them themselves.

11. Close the session

If unchecked tasks remain, print exactly:

plan-to-code complete for Task <N>.

  Plan:    <plan path>
  Commit:  <short SHA>  <commit subject>
  Ticked:  Task <N> and its <n> steps

Deferred work discovered:
  - <item>, belongs to <task or nothing>
  (or: None.)

Next: Task <N+1>, in a fresh session.

  Use the plan-to-code skill with <plan path> task <N+1>

This session is done. I will not start Task <N+1>.

If this was the last unchecked task, replace the last three lines with:

Every task in this plan is now ticked.

Next stage: code-to-review, once, against the whole plan.

  Use the code-to-review skill with <plan path>

This session is done.

Then stop. Do not continue, do not offer to continue, and do not summarise the feature.

Refuse rather than improvise

• No task number means no work. Never infer which task is next and start it.
• A dirty tree means stop, not "commit it for them".
• Unconfirmed tests mean no tick and no commit, however obviously correct the code looks

to you.

• Work outside the task is written down, never done.
• A defect in the plan is raised, never patched around.

Less common branches, including a filled base commit that HEAD has diverged from, a branch mismatch, and abandoning a task part way, are in TROUBLESHOOTING.md.