# Implement

> Turns an approved SpecScore Plan into focused, AC-traceable source-code changes by dispatching one subagent per task in parallel batches computed from the Plan's **Depends-On:** dependency graph. Fires the `implementation.pre_commit` / `implementation.pre_push` reviewer gates at its checkpoints, so per-batch approval is gate-config-driven (a `type: human` reviewer is the human checkpoint; a `auto-approve` gate commits autonomously). Applies publication policy at approved implementation milestones; provides a Verifies: commit-message trailer template. Also accepts a Feature directly (no Plan) or an Idea directly (no Feature or Plan) for single-pass conversational implementation. Trigger: "implement", "/implement", "implement this plan", "specstudio:implement", or event `plan.approved`.

- Skill: `specscore/implement` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add specscore/implement`
- Raw SKILL.md: https://api.skillmd.com/api/skills/specscore/implement/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: specscore (https://skillmd.com/u/specscore)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/specscore/implement

---


# Implement

Turn an approved SpecScore Plan, Feature, or Idea into AC-traceable source-code changes. Plan-sourced mode uses parallel subagent dispatch; each commit is gated by the `implementation.pre_commit` reviewer gate and each push by `implementation.pre_push`, so per-batch approval is gate-config-driven rather than a hardcoded step (a `type: human` reviewer is the human checkpoint; a `auto-approve`/`deterministic`-only gate releases autonomously). Feature-sourced and Idea-sourced modes operate as a single-pass conversation. After the commit gate releases, the skill applies the shared publication policy at the implementation milestone; downstream verification still requires the relevant Feature or implementation commits to exist in git history.

## Hard Gate

<HARD-GATE>
Do NOT invoke `specstudio:verify`, `writing-plans`, `frontend-design`, `mcp-builder`, or ANY downstream skill until ALL FIVE conditions hold for **every batch** produced in the current invocation:
  1. Every subagent in the batch returned a terminal status (`DONE`, `DONE_WITH_CONCERNS`, or `BLOCKED` with user decision); no subagent is still `NEEDS_CONTEXT`.
  2. The consolidated staged diff for the batch is lint-clean (`specscore spec lint` exits zero against the project, including any Plan-file changes staged in stub mode).
  3. The conflict-detection check has passed (no line-overlap between sibling subagents' staged diffs) OR the user has explicitly approved a manual conflict-resolution path.
  4. The batch's `implementation.pre_commit` gate released (`Approved`) before the commit. Approval is **gate-config-driven**, not hardcoded: a `auto-approve`/`deterministic`-only gate releases autonomously (no human prompt); a gate with a `type: human` reviewer stops for that human before committing. On `Issues Found` the commit is blocked and the gate's findings are surfaced.
  5. Publication policy for the approved implementation milestone has been resolved, disclosed, and applied; and when a push/promote is attempted, its `implementation.pre_push` gate released (`Approved`) first. If the allowed actions did not create a commit, the user has committed the approved set manually before the next batch or downstream verification. The skill MUST NOT advance to the next batch while the working tree still has the prior batch staged but uncommitted.

The only skill invoked after `specstudio:implement` is `specstudio:verify` (or — while `verify` is unshipped — a hand-back to the user with that recommendation).
</HARD-GATE>

## When to Use

- **Plan-sourced:** An approved Plan at `spec/plans/<slug>.md` is ready for implementation (`**Status:**` is `Approved` or `Executing`).
- **Plan-sourced:** The event `plan.approved` has fired and the user has confirmed they want to implement.
- **Plan-sourced:** The user wants to resume an in-flight Plan after a prior `implement` session (Plan Status: `Executing`).
- **Feature-sourced:** A Feature at `spec/features/<slug>/README.md` has `**Status:** ∈ {Approved, Implementing, Stable}` and no Plan exists for it. The user wants to implement directly against the Feature's ACs without writing a Plan first.
- **Idea-sourced:** An Idea at `spec/ideas/<slug>.md` has `**Status:** Approved` and no Feature or Plan exists for it. The user wants to implement directly against the Idea's Recommended Direction without writing a Feature or Plan first.

**Refuse and redirect when:**

- The Plan's `**Status:**` is `Draft`, `In Review`, or `Implemented` → tell the user to run `specstudio:plan` (or that there's nothing to implement).
- The Plan's `**Source Feature:**` has regressed to `Draft` or `In Review` → stop, surface the spec drift, recommend re-approving the Feature via `specstudio:specify` or reverting.
- The Feature's `**Status:**` is `Draft` or `In Review` → tell the user to run `specstudio:specify` first.
- The Idea's `**Status:**` is `Draft` or `In Review` → tell the user to run `specstudio:ideate` first.
- The user asks the skill to commit or push before the consolidated diff is lint-clean and conflict-checked and its gate has released → refuse; the commit is available only after the `implementation.pre_commit` gate releases, and the push only after the `implementation.pre_push` gate releases (and publication-policy branch-safety passes).

## Pre-Flight

1. **Input resolution.** Resolve the input to one of three entry modes, checked in priority order:
   - **(a) Plan-sourced.** `spec/plans/<slug>.md` with `**Status:** ∈ {Approved, Executing}`. Proceed with full batch-dispatch workflow.
   - **(b) Feature-sourced.** `spec/features/<slug>/README.md` with `**Status:** ∈ {Approved, Implementing, Stable}` and no Plan exists for this Feature. Proceed in single-pass mode (see Entry Modes below).
   - **(c) Idea-sourced.** `spec/ideas/<slug>.md` with `**Status:** Approved` and no Feature or Plan exists for this Idea. Proceed in single-pass mode (see Entry Modes below).
   Refuse if no artifact matches or Status is outside the accepted set for its type.
2. **Source-Feature validity.** Read the Plan's `**Source Feature:**`. Confirm the referenced Feature is at `spec/features/<feature-slug>/README.md` with `**Status:** ∈ {Approved, Implementing, Stable}`. On regression to Draft/In Review, stop and surface the drift. Additionally confirm the Feature exists at git HEAD via `git cat-file -e HEAD:spec/features/<feature-slug>/README.md`. If the Feature exists only in the working tree (uncommitted), refuse to dispatch and instruct the user to commit it first — the `Verifies:` trailer must reference a Feature that exists in git history.
3. **Parse the Plan.** Use `specscore` CLI's Plan parser (do not re-implement). Surface: per-task `**Verifies:**`, `**Status:**`, `**Depends-On:**`, body (prose for `full`, placeholder `<!-- implement: pending -->` for `stub`). Parse failures stop the skill with the CLI's lint-rule citation.
4. **Git-log cross-check.** Run `git log --grep='^Verifies:'` on the current branch. For each task: if Plan says `**Status:** complete` but no commit references the task's ACs, surface the divergence as a warning. If Plan says `**Status:** planning` but a commit DOES reference its ACs, offer to update the Status (with user confirmation) before dispatching. **Git log is authoritative; Plan Status is the at-a-glance signal.**
5. **Compute next batch.** Topological reduction of the dependency graph: batch = tasks where all `**Depends-On:**` predecessors are `**Status:** complete` AND own `**Status:** planning`. As these tasks become batch-eligible they transition `planning → queued`. Exclude tasks already in `queued`, `in_progress`, `complete`, or `blocked` status.
6. **Pre-existing-Plan catch-up.** If the Plan pre-dates the plan-Feature revision (no `**Status:**` fields), initialize: scan git log for `Verifies:` trailers; mark matched-AC tasks `complete`, rest `planning`. Save these initializations as a Plan-file edit that will land in the first batch's staging.

## Entry Modes

### Plan-sourced (default)

The skill resolves a Plan, parses its tasks and dependency graph, dispatches subagents in batches, and gates each batch's commit on the `implementation.pre_commit` reviewer gate (and each push on `implementation.pre_push`) — so whether a human is asked per batch is gate config, not hardcoded. `Verifies:` trailers reference Feature AC IDs (e.g., `Verifies: <feature-slug>#ac:<ac-slug>`). Per-task Status writes track progress on the Plan file. The full Checklist below applies.

### Feature-sourced (single-pass)

No Plan exists. The skill resolves a Feature directly. Instead of batch dispatch, the skill operates as a **single-pass conversation**: the user describes the change, the skill implements and stages it. There are no subagents, no batch dispatch, no task-status writes, no stub/full posture distinction.

- **Pre-flight:** Step 1(b) resolves the Feature. Step 2 validates the Feature's Status. Steps 3–6 (Plan parsing, git-log cross-check, batch computation, catch-up) are skipped.
- **Implementation:** The skill implements the user's described change conversationally, staging via `git add`.
- **Verifies: trailer:** Uses Feature AC IDs: `Verifies: <feature-slug>#ac:<ac-slug>, ...` listing every AC addressed by the staged change.
- **Lint and self-review:** `specscore spec lint` still runs against staged changes.
- **Commit/push gates:** The consolidated staged diff is gated by `implementation.pre_commit` before commit and `implementation.pre_push` before push, evaluated via the reviewer-gates loader + runner (same as Plan-sourced steps 13–14). A `type: human` reviewer on the gate is the human-approval checkpoint; a `auto-approve`/`deterministic`-only gate releases autonomously.
- **Promotion:** On completion, hand off to `specstudio:verify` (or hand-back if unshipped), same as Plan-sourced.

### Idea-sourced (single-pass)

No Feature or Plan exists. The skill resolves an Idea directly. Same single-pass conversation model as Feature-sourced, with two differences:

- **Source of truth:** The Idea's `## Recommended Direction` section (instead of Feature ACs).
- **Verifies: trailer:** Uses `Verifies: idea:<slug>` (instead of Feature AC IDs).

All other single-pass behavior (no subagents, no batch dispatch, no task-status writes, lint, the `implementation.pre_commit`/`pre_push` gates, publication milestone) is identical to Feature-sourced.

## Cross-Repo Master-Plan Execution

When the supplied Plan is a **master plan** — sourced `**Source:** idea:<slug>` with tasks that carry `**Sub-Plan:** <plan-ref>` delegation refs (and no `**Verifies:**`) — `implement` acts as the **outer coordinator** over per-repo sub-plans. It does not reimplement intra-repo execution; each sub-plan runs through the ordinary single-repo flow. This implements `skills/implement`'s `master-plan-detection`, `subplan-dispatch-via-existing-engine`, `cross-repo-ordering-honored`, `cross-repo-ref-resolution-at-execution`, and `integration-and-tests-phase` REQs.

1. **Detect.** Recognize a master plan by its shape (idea source + `**Sub-Plan:**` tasks). Treat each master task as a delegation, not as source code to edit.
2. **Order.** Compute the cross-sub-plan order from the master's task `**Depends-On:**` graph. A sub-plan whose master task depends on another MUST NOT start until that predecessor sub-plan reaches terminal success — this is how the CLI/bootstrap sub-plan is forced to land first.
3. **Resolve.** Resolve each `**Sub-Plan:** <repo-slug>:<plan-slug>` reference to a sibling repo at execution time (the sibling-repo detection used by destination resolution). On an unresolvable reference, surface it to the user and **halt that branch** — never silently skip it.
4. **Dispatch.** Run the referenced sub-plan via the ordinary per-sub-plan `implement` flow (batch computation, subagent dispatch, conflict detection, per-batch user-approval gate) **inside the sub-plan's own repo**. Do not bypass or duplicate that engine.
5. **Integrate.** After all sub-plans reach terminal success, run the master's final **integration-and-tests** task (last in `**Depends-On:**`) — the cross-repo build/test that proves the repos work together. The master plan is incomplete until it passes; its failure surfaces as a blocked task like any other.

## Checklist (per invocation)

Create a task for each and complete in order:

1. **Pre-flight** (steps above).
2. **If no executable batch** (all tasks complete or blocked) → re-run `specscore spec lint --fix` so the Plan's execution-band `**Status:**` is derived from the task-status rollup, then transition to `specstudio:verify` (or hand-back), stop.
3. **Dispatch the batch.** For each task in the next executable batch (cap at 5 concurrent — see Max-Parallel below), dispatch one subagent via the Agent tool with `subagent_type: general-purpose`. Construct an isolated prompt per posture (see Subagent Contract below). When the batch has > 5 tasks, queue the rest; dispatch each queued task as a slot frees.
4. **Stage Status writes.**
   - **4a. Task Status.** As each subagent is dispatched, transition that task's `**Status:** queued → in_progress` on the Plan file. Stage via `git add`. (In `full` mode this is the only Plan-file change; in `stub` mode it will be joined by the post-return writeback.)
   - **4b. Plan body-metadata Status (lint-derived, not hand-set).** The Plan's execution-band `**Status:**` (`Executing` / `Blocked` / `Implemented` / `Failed`) is **derived** by `specscore spec lint --fix` from the rollup of task statuses (the SpecScore status-vocabulary `plan-executing-derived` divergence). The skill MUST NOT hand-write the band. Once the first task is marked `in_progress` (4a) and lint runs (step 9), the band is derived to `Executing` automatically; staging the task-status edit is sufficient.
5. **Wait for terminal returns.** Each subagent returns one of `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`. `NEEDS_CONTEXT` → re-dispatch that specific subagent with augmented context (sibling subagents unaffected). `BLOCKED` → surface the cited cause to the user, do NOT silently retry.
6. **Update Status fields.** `DONE` / `DONE_WITH_CONCERNS` → `**Status:** complete`. `BLOCKED` (with user decision to defer) → `**Status:** blocked`. Stage all Plan-file edits.
7. **Stub-mode writeback** (only when `**Mode:** stub`). For each `DONE` / `DONE_WITH_CONCERNS` task, replace the placeholder body `<!-- implement: pending -->` with the subagent's SHA-free 1–2 sentence "what landed" summary. Stage via `git add` as part of the same staging set as the code changes.
8. **Conflict detection.** Run `git diff --staged`. Detect line-overlap between sibling subagents' changes on the same file. On conflict: surface to user with file paths and line ranges; offer three resolutions (rewrite Plan with explicit `**Depends-On:**`, manual `git restore --staged` + re-run, abort). On user choice of rewrite-Plan or abort: unstage all batch changes, revert Statuses, stop.
9. **Lint.** Run `specscore spec lint`. On failure (typically Plan-file edits the skill produced), run `specscore spec lint --fix` exactly once, re-lint. On persistent failure: unstage Plan-file changes (`git restore --staged spec/plans/<slug>.md`), surface violations with rule IDs, stop the batch.
10. **Inline self-review.** Scan staged Plan-file changes for: (a) Status transitions violating the state machine (e.g., `complete → in_progress` without user action), (b) writeback bodies still containing placeholder tokens (`<!-- implement: pending -->`, `TBD`, `TODO`), (c) Status values outside the canonical lifecycle set. Findings stop the batch.
11. **Emit `implement.batch-started`** (already done on step 3 — confirm payload was emitted: Plan slug, batch number, task numbers, dispatched count).
12. **Present consolidated diff.** User-facing message contains: per-task status summary (including any `DONE_WITH_CONCERNS` concerns or `BLOCKED` reports), the staged diff (or per-file summary if very large), and the proposed commit-message template with mandatory `Verifies:` trailer listing every AC ID covered by **successful** tasks (DONE / DONE_WITH_CONCERNS only; BLOCKED tasks' ACs NOT included). This consolidated diff is the artifact the `implementation.pre_commit` gate (step 13) reviews; when that gate includes a `type: human` reviewer the message also carries the explicit approval instruction the human responds to (when the gate is `auto-approve`/`deterministic`-only, no approval prompt is needed). Also state that publication policy will be resolved at the checkpoint and may leave the change unstaged, stage it, commit it, or commit and push it.
13. **`implementation.pre_commit` gate (before the commit).** Approval is gate-config-driven — the skill carries no hardcoded per-batch user-approval step. Fire the `implementation.pre_commit` gate-point event ([events.md](../shared/events.md), multi-fire — once per commit) and evaluate `gates.implementation.pre_commit`: load + validate the gate's reviewer list via [reviewer-gates/loader.md](../shared/reviewer-gates/loader.md) (event key `implementation.pre_commit`), then run it via [reviewer-gates/runner.md](../shared/reviewer-gates/runner.md). The consolidated staged diff is the artifact under review; a `type: human` reviewer, if configured, reviews that diff and the runner uses this skill's existing approval-phrase recognizer (`approve`/`approved`/`accept`/`accepted`/`lgtm` or semantic equivalents → `Approved`; a vague positive like `looks good`/`ship it`/`🚀` → ask one explicit confirmation question, never silently advance; an explicit change request → `Issues Found`). Proceed to step 14 **only when the gate releases (`Approved`)**. On `Issues Found`: block the commit, surface the gate's `Blocker` findings to the user, and do not advance. With a `auto-approve`/`deterministic`-only gate (no `type: human`) the gate releases autonomously and the commit happens with no human prompt; with a `type: human` reviewer the skill stops for that human before committing. Because `implementation.pre_commit` is multi-fire, each commit is an independent gate evaluation (a fresh first-pass run per the runner's per-occurrence contract). The boundary at which commits are produced (per-task / per-batch / per-plan) is resolved per the `autonomy:` namespace — see [Commit Cadence and the `autonomy:` Namespace](#commit-cadence-and-the-autonomy-namespace) — not here.
14. **Publication checkpoint.** Build the approved manifest from subagent-touched code paths, Plan status/writeback paths, single-pass edits, and any CLI-reported touched paths. Resolve and disclose [publication-policy.md](../shared/publication-policy.md) for milestone `implement.batch-approved` in Plan-sourced mode or `implement.single-pass-approved` in Feature/Idea-sourced mode. If the allowed actions include `commit`, commit only after the unrelated-index check and verify the new `HEAD` contains the required `Verifies:` trailer. If actions do not include `commit`, refuse to advance until the user commits the approved set manually with the trailer. If actions include `push`: first fire the `implementation.pre_push` gate-point event ([events.md](../shared/events.md)) and evaluate `gates.implementation.pre_push` via [reviewer-gates/loader.md](../shared/reviewer-gates/loader.md) (event key `implementation.pre_push`) + [reviewer-gates/runner.md](../shared/reviewer-gates/runner.md); the push proceeds **only when that gate releases (`Approved`)**, and on `Issues Found` the push is blocked and the gate's findings surfaced. When that gate includes a `type: human` reviewer, present a **cumulative review** as the reviewer's context (see [Cumulative Review at the Push Gate](#cumulative-review-at-the-push-gate)) — the full set of commits accumulated during the run, not merely the final commit. The `pre_push` gate **complements** publication-policy push branch-safety — it does not replace it: branch-safety is a non-negotiable floor that runs on every push (see [Push Safety Floor](#push-safety-floor)). Do not amend, squash, sign, or include non-manifest changes unless the user explicitly broadens the manifest.
15. **Emit `implement.batch-completed`.** Payload: Plan slug, batch number, task numbers, commit SHA when one exists (from `git rev-parse HEAD` after the user commit or policy-created commit), `Verifies:` AC IDs covered, and `publication_result`.
16. **Emit `plan.updated`.** Apply publication policy for `plan.updated` only to any Plan-file changes not already included in the batch milestone, then emit with `publication_result`. Payload's `changed_sections` lists every task slug whose Status or body changed in this batch. `change_summary` factual, ≤2 sentences.
17. **Loop back to step 2.** Compute next batch; if none, transition.
18. **Final transition.** When all tasks `**Status:** complete`: re-run `specscore spec lint --fix` so the Plan's execution-band `**Status:**` is derived to `Implemented` from the all-complete task rollup (the skill does not hand-write the band — see 4b), emit `plan.updated`, hand off to `specstudio:verify` (or, if `verify` is unshipped, recommend the user run their project's test/Rehearse suite manually).
19. **Throughout** — watch for sidekick ideas. When an out-of-scope improvement surfaces (e.g., a Feature change, a refactoring opportunity), invoke `specstudio:sidekick` with a one-liner, acknowledge in one line, and return to the current checklist step. Do not derail.

## Subagent Contract

Each subagent is dispatched with an **isolated prompt** — it MUST NOT inherit the parent session's context. Construct the prompt freshly per posture.

### Full posture (`**Mode:** full`)

Subagent prompt contains, in this order:

1. **Task identification.** `### Task N: <task-name>`.
2. **AC list.** The task's `**Verifies:**` AC IDs.
3. **AC full text.** For each referenced AC, the complete `Given / When / Then` text quoted verbatim from the source Feature at `spec/features/<feature-slug>/README.md`.
4. **Authored task body.** The 1–3 sentence prose from the Plan task body, verbatim.
5. **Commit-message trailer convention.** `Verifies: <feature-slug>#ac:<ac-slug>, ...` listing every AC ID from this task's `**Verifies:**`.
6. **Discipline pointer.** For tasks involving behavior change: the TDD pointer — reference `agent-skills:test-driven-development` or `superpowers:test-driven-development` when available; otherwise an in-skill TDD instruction (write failing test → minimal fix → refactor). For tasks with no testable surface (pure-documentation edits, file renames, deletions, formatting-only changes): substitute the AC-verification adapter clause — "re-read the artifact after editing and confirm each predicate in the AC's `Then` clause directly." The adapter preserves the verification discipline while honoring the actual task shape.
7. **Return-shape contract.** One of `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`, with required fields per status.
8. **Stage-only instruction.** "Stage your changes with `git add`. Do NOT run `git commit`. The parent skill aggregates the approved batch and handles the commit gate."

### Stub posture (`**Mode:** stub`)

Subagent prompt contains items 1, 2, 3, 5, 6, 7, 8 from full posture (item 4 — authored body — does NOT apply because there isn't one), plus:

a. **Plan-level approach.** The Plan's `## Approach` section verbatim (the planner's higher-level decomposition strategy).
b. **Predecessor summaries.** For each task in `**Depends-On:**`, a brief summary of what that predecessor delivered (extracted from the predecessor's `Verifies:` commit trailer + the predecessor task's now-journaled body, if available).
c. **Inference-and-summary instruction.** "Infer your implementation approach from the source Feature's ACs and the Plan's Approach. After staging your changes, return a SHA-free 1–2 sentence 'what landed' summary describing your implementation choices. This summary will become the canonical body of the task via the writeback step. **Do NOT reference a commit SHA** — no SHA exists yet at writeback time; SHA linkage lives in the `implement.batch-completed` event payload."

### Status protocol (both postures, adopted from SDD)

| Status | Meaning | Parent skill behavior |
|---|---|---|
| `DONE` | Task complete, changes staged, no concerns | Keep staged; mark Plan `**Status:** complete`; include in batch commit |
| `DONE_WITH_CONCERNS` | Task complete + staged, but subagent flagged observations (e.g., "this file is getting large") | Keep staged; mark Plan `**Status:** complete`; surface concerns to user in consolidated diff |
| `NEEDS_CONTEXT` | Subagent needs information not provided | Re-dispatch this subagent with augmented context; siblings unaffected; Plan Status stays `in_progress` |
| `BLOCKED` | Subagent cannot complete the task as specified (cites specific cause) | Surface to user with full report; offer revise-Feature / mark-blocked / abort; do NOT silently retry |

## Max Parallel

Cap concurrent subagents at **5 per batch** in MVP. When the next executable batch has > 5 tasks, dispatch the first 5 and queue the rest; dispatch each queued task as a concurrent slot frees. The cap may become configurable per project via `specscore.yaml` in a future revision — MVP hardcodes 5.

## Commit Cadence and the `autonomy:` Namespace

`implement` execution knobs live under a top-level `autonomy:` key in `specscore.yaml`, keyed by skill name (MVP: `autonomy.implement`). This is a concern distinct from `gates:` — `gates:` declares *who approves* each event; `autonomy:` declares *execution knobs*. Workflow-step names (e.g., `implement:`) MUST NOT appear as top-level config keys; the knobs are reached only via `autonomy.implement.*`.

### `commit_cadence`

`autonomy.implement.commit_cadence` selects the boundary at which the skill commits:

| Value | Boundary |
|---|---|
| `task` | one commit per task |
| `batch` | one commit per integrated batch *(default when unset)* |
| `plan` | one commit at run end |

Resolution follows the publication-policy **scope ladder** (run → session → project → user), narrower overriding broader. When unset at every scope, the cadence is `batch`. Example: `autonomy.implement.commit_cadence: task` at project scope with no narrower (run/session) override resolves to `task` → one commit per task.

`commit_cadence: plan` is allowed, but the skill MUST warn that it defers all commits to run end, weakening per-batch revert granularity (a failure late in the run cannot be reverted batch-by-batch). No additional guard mechanism is provided in MVP — the warning is the safeguard.

### Cadence drives `pre_commit` firing

The resolved cadence determines how many commits a run produces, and `implementation.pre_commit` fires **once per commit** (per task, per batch, or once for the plan) — each firing an independent gate evaluation per the runner's multi-fire semantics. So a `batch`-cadence run that produces three batch commits fires `implementation.pre_commit` three times, once before each commit. The gate-evaluation mechanics live in Checklist step 13; this section owns only *where the commit boundaries fall*.

## Conflict Detection and Rollback

**Detection: line-overlap only** (post-batch). Run `git diff --staged` after all subagents return terminal statuses. Two subagents are in conflict when their staged changes touch the same file at overlapping line ranges. Semantic conflicts (two subagents implementing the same Feature differently in different files) are explicitly out of MVP scope.

**Rollback: atomic.** On detected conflict:

1. Surface to user: offending task numbers, file path, overlapping line range.
2. Offer three resolutions: (a) rewrite Plan with explicit `**Depends-On:**` that serializes the conflicting tasks, (b) manual `git restore --staged <path>` + re-run, (c) abort and investigate.
3. On (a) or (c): unstage ALL batch changes (`git restore --staged` per touched file), revert each task's `**Status:** in_progress → planning` (or → `blocked` if conflict implies a missing dependency), stop.

**Mixed terminal statuses are NOT conflicts.** A batch where 3 subagents are DONE and 2 are BLOCKED is a partial success: present the 3 DONE subagents' diff, run it through the `implementation.pre_commit` gate, and commit on release, mark the 2 BLOCKED tasks `**Status:** blocked` (with cited causes), advance. Atomic-rollback semantics apply only to *line-overlap conflicts*, not to mixed-terminal batches. (A BLOCKED subagent is also an anomaly-halt trigger — see [Anomaly Halts and Re-arm](#anomaly-halts-and-re-arm).)

## Anomaly Halts and Re-arm

Some failures are **execution-state anomalies**, not gate verdicts — a reviewer does not "approve" a merge conflict or a BLOCKED task. Regardless of gate configuration — **including a fully autonomous (`auto-approve`) `pre_commit` gate** — `implement` MUST halt the run on any of:

- **(a)** a sibling integration/merge conflict (the line-overlap conflict of [Conflict Detection and Rollback](#conflict-detection-and-rollback));
- **(b)** a BLOCKED subagent;
- **(c)** a lint failure that `specscore spec lint --fix` did not resolve in its single pass;
- **(d)** source-Feature drift (the Plan's source Feature regressed below `Approved`).

These halts are **not subject to the gate verdict** — an autonomous gate does not suppress them.

On an anomaly-halt, `implement` MUST stop, name the **specific cause**, perform **no auto-resolution**, and **not advance**:

| Anomaly | Surfaced cause |
|---|---|
| sibling conflict | the conflicting task numbers, file paths, and overlapping line range |
| BLOCKED subagent | the BLOCKED task and its cited reason |
| unresolved lint | the remaining lint violations (with rule IDs) |
| source-Feature drift | the drifted Feature and its current status |

### Explicit re-arm

After the user addresses the cause, `implement` MUST NOT auto-resume when the anomaly clears. It resumes autonomous execution only after the user issues an **explicit re-arm signal** — the lowercase standalone token **`continue`** (recognized in the same style as the approval phrases).

A re-arm re-enables autonomy for the **remainder of the current `implement` run only**. A subsequent run starts from the resolved `autonomy:` / `gates:` config — never from a prior run's re-armed state.

## Detached / Background Execution

When `implement` is launched as a detached background session (per [Feature: Detached Background Plan Implementation](../../spec/features/detached-background-implement/README.md) — a `claude --bg` process started from the plan-approval checkpoint, running in its own worktree), it follows an **autonomous progress contract** that maximizes forward progress instead of stopping at the first obstacle:

- **Maximize progress.** Complete every task the run can. (`#ac:continues-past-a-blocker`)
- **Defer blocked tasks — do not abort.** A task the run cannot complete (needs a human decision, missing information, an unresolved test failure, or a permission it lacks) is marked `**Status:** blocked` and skipped; the run continues with other unblocked tasks. Only the blocked task's own dependents are blocked. In this mode a deferrable blocked task is **not** a run-level anomaly-halt — this overrides the `BLOCKED`-subagent halt of [Anomaly Halts and Re-arm](#anomaly-halts-and-re-arm) for background runs. (`#ac:continues-past-a-blocker`)
- **Approval-requiring actions last.** Schedule any action that will need human approval after all independently-completable work, so a pause does not stall work that could proceed. (`#ac:approval-work-deferred-last`)
- **Pause — never improvise — when only blockers remain.** When no unblocked task is left, the run pauses and waits for input. It MUST NOT abort and MUST NOT improvise a decision that requires a human. (`#ac:pause-on-remaining-blockers`)
- **Blocker surface (v1): the live session only.** Blockers are resolved by attaching to the paused session (`claude attach <id>`). The run is not required to produce a `BLOCKED.md` or any other durable blocker artifact. (`#ac:no-blocked-artifact-required`)

The **integrity** anomaly-halts still apply unchanged even in background mode — a sibling integration conflict, a lint failure unresolved after the single `--fix` pass, and source-Feature drift all still halt the whole run. Only the deferrable "unfinishable task" case is relaxed here.

## Staging, Publication Policy, and Commit-Message Template

Subagents stage their own changes so the parent can aggregate and review a consolidated diff. The parent skill applies [publication-policy.md](../shared/publication-policy.md) only after the consolidated diff has passed conflict detection, lint, self-review, and the `implementation.pre_commit` gate's release (step 13). Policy does not persist as an `implement`-specific override; durable preferences are saved only through `specscore publication set`.

### Policy-created commits

When the resolved policy allows `commit`, the skill MAY run `git commit` using the proposed template unless the user supplies an exact commit message. The commit MUST include the required `Verifies:` trailer for the successful tasks in the batch or single-pass change. Before committing, compare the approved manifest to the staged index and stop on unrelated staged paths per the shared protocol. The skill MUST verify the commit succeeded and that `git rev-parse HEAD` changed before emitting `implement.batch-completed`.

The override MUST NOT:

- Bypass the `implementation.pre_commit` gate (commit only after it releases `Approved`).
- Commit before conflict detection, lint, and inline self-review pass.
- Commit unrelated staged or unstaged files.
- Amend, squash, sign, or otherwise rewrite history unless the user leaves `implement` and explicitly requests that separate git operation.
- Push before the `implementation.pre_push` gate releases, or without branch-policy approval and an upstream branch.
- Allow subagents to commit; subagents always stage only.

### Commit-message template (provided every batch / single-pass)

**Plan-sourced and Feature-sourced:**

```
<short summary describing what was implemented>

<optional longer body the user may edit>

Verifies: <feature-slug>#ac:<ac-slug>, <feature-slug>#ac:<ac-slug>, ...
```

**Idea-sourced:**

```
<short summary describing what was implemented>

<optional longer body the user may edit>

Verifies: idea:<slug>
```

**Trailer rules:**

- Keyword is exactly `Verifies:` (case-sensitive, Conventional Commits trailer convention).
- Follows the body, separated by a blank line.
- **Plan-sourced:** Lists every AC ID covered by **successful** tasks in the batch (DONE / DONE_WITH_CONCERNS only). BLOCKED tasks' ACs are NOT in the trailer. AC IDs deduplicated, ordered by task number then AC slug.
- **Feature-sourced:** Lists every AC ID addressed by the staged change.
- **Idea-sourced:** Uses `idea:<slug>` referencing the source Idea.
- May be a single comma-separated line OR multiple `Verifies:` lines — both valid.

The skill MUST NOT enforce the user's actual commit message format (that's the user's call). But the *suggested* template always includes the trailer.

## Per-Task Status Writes

| When | Transition | Apply in postures |
|---|---|---|
| Task's `**Depends-On:**` predecessors all `complete` (becomes batch-eligible) | `planning → queued` | both |
| Subagent dispatched | `queued → in_progress` | both |
| Subagent returns `DONE` or `DONE_WITH_CONCERNS` | `in_progress → complete` | both |
| Subagent returns `BLOCKED` (user defers) | `in_progress → blocked` | both |
| User manually resolves a `blocked` task | (user edit) `blocked → planning` | both |

The canonical task-status lifecycle is `planning → queued → in_progress → complete`, with `blocked`/`failed`/`aborted` as the other available terminal/interrupt outcomes. The full vocabulary is `{planning, queued, in_progress, blocked, complete, failed, aborted}`.

`**Status:**` writes apply identically to `full` and `stub` Plans. The body-writeback exclusion in `full` mode is specifically about task bodies, not about Status.

## Stub-Posture Body Writeback (Bundled)

When `**Mode:** stub` and a subagent returns `DONE` / `DONE_WITH_CONCERNS`:

1. Replace the task's placeholder body `<!-- implement: pending -->` with the subagent's SHA-free 1–2 sentence "what landed" summary.
2. Stage the Plan-file change via `git add` as part of the **same staging set** as the subagent's code changes.
3. The user reviews one consolidated `git diff --staged` containing both code and Plan-file edits.
4. The approved publication checkpoint commits both atomically when policy allows `commit`; otherwise the user commits both atomically with the suggested template before the skill advances.

**No two-phase commit.** No placeholder SHAs to reconcile. No separate "approve the journal entry" step.

When `**Mode:** full`: NO body writeback. Task bodies were authored at plan time and remain unchanged by `implement`. Only `**Status:**` is written.

## Lint and Self-Review

After every batch's staging phase, before presenting the consolidated diff to the user:

1. **Lint.** Run `specscore spec lint`. On failure: run `specscore spec lint --fix` exactly **once**, re-lint. If still failing: unstage Plan-file changes (`git restore --staged spec/plans/<slug>.md`), surface remaining violations with rule IDs, stop the batch. The skill MUST NOT loop `--fix`.

2. **Inline self-review.** Scan staged Plan-file changes for:
   - State-machine-violating Status transitions (e.g., `complete → in_progress` without explicit user action).
   - Writeback bodies still containing placeholder tokens (`<!-- implement: pending -->`, `TBD`, `TODO`).
   - Status values outside the canonical lifecycle set `{planning, queued, in_progress, blocked, complete, failed, aborted}`.

Findings stop the batch and prompt the user — never auto-fix beyond the one `--fix` pass above.

## No Code-Review Subagent

**Deliberate departure from `superpowers:subagent-driven-development`.** That skill dispatches a spec-compliance reviewer AND a code-quality reviewer per task. `implement` does **neither** in MVP.

- The `implementation.pre_commit` / `implementation.pre_push` reviewer gates on the consolidated batch diff ARE the quality gates `implement` enforces. What sits in each gate (a `type: human` checkpoint, an automated `deterministic` check, or an auto-approving `auto-approve`) is project config, not hardcoded here.
- Code-quality and architecture review are the responsibility of `specstudio:review` downstream.
- Spec-compliance review for *the Feature spec* is owned by `specstudio:specify`'s reviewer subagent, not `implement`.

This keeps `implement` focused on dispatch + staging + firing the gate-point events, and avoids triple-gating inside the loop. The `implement`-specific reviewer subagents this section forgoes are distinct from the configured `implementation.pre_commit`/`pre_push` gate reviewers, which `implement` fires but does not itself author.

## Cumulative Review at the Push Gate

When `implement` fires `implementation.pre_push` and that gate includes a `type: human` reviewer, that human is the **single human checkpoint of an autonomous run**. `implement` MUST present a **cumulative review** as the reviewer's context — the full set of commits accumulated during the run, not merely the final commit:

- **Default (small change):** the run's commits plus their **consolidated diff**, when the change is within ~**150 changed lines** *and* ~**10 files**.
- **Large change:** when either bound is exceeded (more than ~150 changed lines OR more than ~10 files), switch to a **per-commit summary** — one entry per commit (subject + `Verifies:` AC IDs + file/line counts) — instead of the full consolidated diff.

This threshold keeps the human's review context bounded; the cumulative set (commits, not just the tip) is presented either way.

## Push Safety Floor

Every promote/push MUST route through [`change-publication-policy`](../shared/publication-policy.md) push branch-safety, which denies `main`/`master`/`release/*` by default. Autonomy MUST NOT weaken or bypass this floor: a publication-policy-denied branch is refused regardless of `autonomy:` / `gates:` settings. A `type: deterministic` branch-safety reviewer configured on `implementation.pre_push` **complements** the publication-policy check (it can add project-specific refusals) — it is **not** a substitute for it. Both run on every push.

## Promotion Boundary

The next skill is `specstudio:verify`, and only `specstudio:verify`.

#### Transition

When all tasks reach `**Status:** complete` (no more eligible batches AND no planning/queued/blocked tasks):

1. Re-run `specscore spec lint --fix` so the Plan's execution-band `**Status:**` is derived to `Implemented` from the all-complete task rollup. The skill does not hand-write the band (see Checklist step 4b).
2. Add CLI-reported

…(truncated)