implement-mainspec

# Implement Mainspec Implements all slices from a mainspec in dependency order, sequentially. Agent-first: invoked headless by the harness dispatcher, runs end-to-end with no approval gates, exits. ## Invocation Contract **Invoked by the dispatcher as:** `claude -p "/implement-mainspec <feature>"`, run from inside the feature worktree (the dispatcher `cd`s into it). **Single argument:** `<feature>` — kebab-case feature slug. The mainspec path is `specs/<feature>/mainspec.md` relative to cwd. **Inputs read from disk (paths relative to cwd):** - `specs/<feature>/mainspec.md` - `specs/<feature>/slices/*.md` - Current `feature/<feature>` branch state. **Outputs to disk / remote:** - All implementation code committed and pushed on `feature/<feature>`, one commit per slice. **No sentinel.** The dispatcher's success signal for this step is `./prds/<feature>/run-prd-test.sh` exits 0, verified externally. The final slice's Success Criteria encodes this into a slice so completing all slices implies the PRD test passes. We do not write a sentinel file — the *dispatcher* records the green result in `specs/<feature>/.prd-passed` once the runner first exits 0; this skill neither writes nor reads that file. **Idempotency:** - On every invocation, inspect `feature/<feature>` git history. Determine which slices are already committed (look for commits like `Implement slice <n>: <name>`). - The orchestrator reads the mainspec's Slice Dependency Map inline to plan its execution order. - Work only on remaining slices. - If all slices appear committed, exit cleanly. The dispatcher will re-verify the PRD test externally. **No approval gates anywhere.** No `AskUserQuestion` for plan approval, default-branch warning, or any other decision. Every decision is deterministic or deferred to the next dispatcher tick. ## Workflow Overview ``` Phase 1: Parse & Resume — Read mainspec Slice Dependency Map, determine execution order, inspect feature/<feature> for already-committed slices Phase 2: Implement — Delegate each remaining slice to slice-implementer subagent (foreground). Orchestrator handles git directly on feature/<feature>. Phase 3: Log — Log final status of this invocation to stdout for observability ``` ## Pre-conditions The dispatcher guarantees a clean worktree on `feature/<feature>` before invoking. Verify deterministically and exit on violation — the dispatcher will re-derive state on the next tick. 1. **Git repository** — `git rev-parse --git-dir` succeeds. If not, exit non-zero. 2. **Current branch matches `feature/<feature>`** — must match the argument exactly. If not, exit. (Never create the feature branch; the dispatcher's atomic rename from `prd/<author>/<feature>` did that.) 3. **Clean working tree** — `git status --porcelain` empty. If not, exit (the dispatcher's wipe should guarantee this; if it trips, something upstream is wrong). 4. **Remote configured** — `git remote get-url origin` succeeds. If not, exit. ## Phase 1: Parse & Resume ### Slice Ordering Read the mainspec's "Slice Dependency Map" table directly. For each slice, note its number, name, and `Depends On` list. Use that understanding to plan the execution order — slices whose dependencies are already committed (or have no dependencies) can run next; slices with outstanding dependencies wait. Reference the slice file path convention: `specs/<feature>/slices/<number>-<kebab-name>.md`. ### Resume Detection (Idempotency) Before implementing anything, inspect what's already committed on `feature/<feature>`: ``` 1. git fetch origin 2. For each slice in the mainspec: - Check whether a commit referencing "Implement slice <number>:" exists in git log feature/<feature> (e.g., git log --oneline --grep "Implement slice <number>:"). - If yes, mark slice as ALREADY-COMMITTED. Skip it. - Otherwise, mark slice as REMAINING. 3. If all slices are ALREADY-COMMITTED, log "all slices committed, nothing to do" and exit cleanly. 4. Otherwise, proceed with REMAINING slices in their dependency order. ``` ### Plan Logging (No Approval) Log the computed plan to stdout for observability — which slices are remaining vs. already-committed. **No approval gate, no `AskUserQuestion`.** Proceed directly to Phase 2. ``` ## Execution Plan: <mainspec-name> Total slices: N (already-committed: M, remaining: K) Remaining order: 1. Slice X.Y: <name> 2. Slice X.Y: <name> ``` ## Phase 2: Implementation The preconditions already guaranteed we are on `feature/<feature>`, so we commit directly to it. No default-branch warning, no approval prompt. For each **REMAINING** slice in dependency order (skipping already-committed ones from Phase 1): 1. Create TODO list — One item per slice. 2. Mark slice in_progress. 3. Delegate to a `slice-implementer` subagent (foreground, NOT background): - Use `subagent_type: "slice-implementer"` and `mode: "bypassPermissions"`. - Use the prompt template from `references/subagent-prompt-template.md`. - Set working directory to the repo root. - Wait for subagent to complete. 4. After subagent completes successfully: - Orchestrator runs `git status` to detect changes. - Orchestrator runs `git add <changed-files>` (only files the subagent created/modified). - Orchestrator runs `git commit -m "Implement slice <number>: <name>"`. - Orchestrator runs `git push origin feature/<feature>`. 5. If subagent reports FAILURE: - Log the failure (slice number, error text) to stdout. - Do not commit any partial state. - Exit. The dispatcher will re-fire on the next tick; idempotency in Phase 1 will skip the already-completed slices and retry this one. 6. Mark slice complete. After all remaining slices: proceed to Phase 3 (Log). ## Phase 3: Stdout Log (Observability Only) There is no human to report to. Write a concise stdout log of what this invocation did so the dispatcher's log is readable. ``` ## /implement-mainspec invocation summary: <feature> Skipped (already-committed): <list of slice numbers> (or none) Implemented this invocation: <list of slice numbers> Failed this invocation: <list of slice numbers> (or none) Branch: feature/<feature> (pushed) ``` ## TODO Structure ``` [ ] X.Y-<slice-name> [ ] X.Y-<slice-name> ... ``` ## References - **Subagent prompt template**: Read `references/subagent-prompt-template.md` when spawning subagents in Phase 2 - **Error handling**: Read `references/error-handling.md` when any phase encounters errors ## Guidelines **DO:** - Log the execution plan to stdout for observability (no approval gate; proceed directly). - Use absolute paths for all spec file references. - Delegate slice implementation to `slice-implementer` subagents — orchestrator stays lean. - Use `subagent_type: "slice-implementer"` and `mode: "bypassPermissions"` for all subagent spawns. - Handle all git operations (add, commit, push) in the orchestrator — subagents do NOT run git. This includes any Expert-file changes a subagent's Reflect step wrote. - Use `git status` to detect changed files after subagent completion. - Read only the current slice file — never read all slices at once. - Treat the current branch as the feature branch (must match `feature/<feature>`); never create it. - Inspect `feature/<feature>` git history at the start of every invocation to determine which slices are already committed; idempotency depends on this. - On any failure: log clearly, exit. The dispatcher's next tick is the retry mechanism. **DON'T:** - Use `AskUserQuestion` anywhere. The dispatcher provides no input, and the human is not in the loop. - Implement slices inline — always delegate to `slice-implementer` subagent. - Read files to embed in subagent prompts — subagents read their own files. - Skip slices or implement out of order (within remaining work). - Proceed with failing tests. - Over-engineer beyond slice scope. - Create worktrees, per-slice branches, or PRs for individual slices. - Create a sentinel file for this skill. The dispatcher's success check is `./prds/<feature>/run-prd-test.sh` exit code, not a sentinel.