implement

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# 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`.

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills