Specful Implement

Implementing a plan

Execute the plan the user names, one step at a time. The plan is the specification. The repository's instructions own branching, commits, pushes, and merges; this skill never merges.

A change plan is one step. Its frontmatter status is the step status. Checkpoint records the last completed task, its evidence, and the branch when one exists. Next names the current task and nothing else. Blocked records a deviation and its evidence. Amendments records approved deviations with their dates. While a step with its own change plan is active, that plan's frontmatter is authoritative and the arc row is updated from it at the step boundary.

A change plan starts in draft; treat that as its pending state. For a change plan, references below to Notes mean Blocked for a deviation and Amendments for an approved change. Its Verification table supplies the Completion verification rows.

Read

In a Specful repository, apply the development workflow: start at docs/specs/index.md, follow scope indexes and relevant Requirements, Designs and ADRs, then check their claims against targeted code and existing tests. Use broader search when coverage or directions are missing or inaccurate. Identify the step's affected obligations. Propose a worthwhile missing artifact's subject, type and durable benefit for the user's decision and input before writing it; a change beyond the plan follows Deviation below. Routine code work can follow the workflow directly without a saved plan; this skill remains for executing a named plan.

1. Read the plan in full, then the artifacts its Binding inputs cite at the cited lines, before any task creates a branch or worktree. A cited line that no longer carries what the table says it locks is a deviation.
2. Read the Progress log. The first pending or active step is the current step; never repeat a complete or skipped step.
3. For an active step, check its branch when the repository has one. With commits, judge the work against the step's Exit criteria. With a merged pull request, set the step complete; the merge is the maintainer's confirmation of every Merge condition. Without commits, treat the step as pending.
4. Confirm every Prerequisite with its command before the first step.

Execute one step

1. Set the step active in the Progress log and record the branch when the repository has one. For a change plan, set frontmatter status: active.
2. Read the step's Context and confirm it matches the repository. A mismatch is a deviation.
3. Do the tasks in order. Every statement is exact. An open choice stated in the task with a reason is the executor's; record the choice made in Notes. Where the plan is silent, follow the repository's instructions and do what is correct.
4. Run each task's Verify command and compare the output to the expected result. A mismatch is a deviation.
5. Run the step's Verification and the plan's every-step rows. Check the Exit criteria. Complete required local verification before publication, including after remediation. For each consequential affected acceptance criterion, record exact-revision test or inspection evidence and its result, or the unresolved gap, in the step's evidence. Reuse existing checks before proposing additional tests; corpus validation and a Design's satisfies link are not proof of implemented behaviour.
6. After opening or updating a pull request, inspect remote checks once for its exact head. Remediate completed CI failures within approved scope; failures requiring a deviation follow Deviation below. If checks are pending, record them as unrun Merge conditions and stop after any in-scope remediation. Each published update gets one inspection. Do not poll, watch, sleep, or keep the session active solely for CI unless the user explicitly asks to monitor or wait. Checks that have not appeared or cannot be inspected remain unrun, never presumed successful.
7. Record the evidence in Notes and report the PR URL, exact head SHA, completed checks and their results, pending checks, and every other Merge condition unrun, then stop. The step stays active until its pull request merges, and a review change is an amendment on the active step. The user starts the next step.

Deviation

A deviation is anything the plan states that the repository contradicts, any change correctness requires beyond what the plan states, or any verification that does not match its expected result.

1. Stop the step. Do not work around it.
2. Set the step blocked. Record in Notes what the plan states, what was found, and the proposed change with its evidence. When a tool wrote a verdict, quote that line before any inferred cause.
3. Report and wait. On approval, record the change under Amendments with the date, then continue.

Mutate

Apply only an approved change. Record every mutation in Notes with its reason.

• Split: rename Step N to Na, add Nb, update the graph.
• Insert: add a letter suffix, never renumber, update the graph.
• Skip: mark the heading [SKIP: reason], set the row skipped, never delete.
• Reorder: only where the graph allows, then re-check that no step reads a later step's output.
• Abandon: set frontmatter status: complete, record the reason in Notes, never delete.
• A change to a Binding input is not a mutation; it stops for the owner.

Complete

When every step is complete or skipped, run the plan's Completion verification rows. When they pass, set frontmatter status: complete and report. When durable rationale in the plan has no ADR, say so in the report; do not write one.