--- name: executing-specs description: Orchestrates parallel implementation of decomposed specifications with incremental progress tracking. Use when running the /flow:execute stage (the EXECUTE stage of the /flow engine). disable-model-invocation: true --- # Executing Specifications Implement a specification by orchestrating parallel background agents across dependency-aware batches, with incremental persistence to survive context compaction. ## Stage: EXECUTE in the `/flow` model This skill is the **EXECUTE stage** of the unified `/flow` stage model (the spec's stage spine: … DECOMPOSE → **EXECUTE** → VERIFY → ⟦HUMAN REVIEW⟧ → DONE …). A PM transition into the EXECUTE stage and the thin `/flow:execute` command are two triggers for this same skill; its PM projection is In Progress + the `agent/claimed` label. When tracker I/O is needed (claiming the work item, the In Progress transition, breadcrumbs), route it through the `linear-adapter` skill by naming its capability verbs — this skill never touches a tracker string directly. The behavior below is unchanged. ## Supporting Files | File | When Loaded | Purpose | | ------------------------------------ | ------------------- | ----------------------------------------- | | `implementation-summary-template.md` | Phase 1 (once) | Scaffold for `04-implementation.md` | | `analysis-agent-prompt.md` | Phase 2 (once) | Full prompt for the analysis agent | | `implementation-agent-prompt.md` | Phase 3 (per batch) | Full prompt for each implementation agent | **Key rule**: Read supporting files on demand, not upfront. This keeps context lean. --- ## Phase 0: Choose Workspace Execution changes code — decide where it runs before any agent starts. ### 0.1 Detect Current State ```bash git rev-parse --git-dir --git-common-dir && git branch --show-current && git status --porcelain ``` If the two rev-parse paths **differ**, the session is already in a secondary worktree — skip the rest of this phase and execute here. ### 0.2 Worktree Triggers These triggers are the repo-wide _one checkout, one writer_ rule applied to execution (`AGENTS.md` → Worktrees; mechanics in the `working-in-worktrees` skill). Spec execution is multi-commit code work in a routinely-shared checkout, so the default is to **isolate** — recommend an isolated worktree when any of these hold (in this repo, at least one usually does): - the working tree has uncommitted changes unrelated to this spec - the current branch is a different topic than this spec - another agent or session is working in this checkout - a dev server in the main checkout should keep running undisturbed ### 0.3 Offer, Never Force If a trigger applies, use AskUserQuestion: execute in place, or isolate in a worktree. To isolate: 1. Run the `/worktree:create spec-` flow (provisions dependencies, ports, and env automatically) 2. Switch this session into it with the EnterWorktree tool (`path` = the new worktree's location) — no CLI restart needed If no trigger applies, execute in place without asking. ### 0.4 Record the Choice If a worktree was created, note its path and branch in `04-implementation.md` (Session section) so the completion step and the `/flow:done` stage can offer cleanup. --- ## Phase 1: Setup & Scaffold ### 1.1 Extract Feature Slug ``` SPEC_FILE = SLUG = extract second path segment (e.g., "user-auth" from "specs/user-auth/02-specification.md") TASKS_JSON = "specs//03-tasks.json" TASKS_FILE = "specs//03-tasks.md" IMPL_FILE = "specs//04-implementation.md" ``` Display: ``` Executing specification: Feature slug: ``` ### 1.2 Quick Validation 1. **Verify spec exists**: Check `SPEC_FILE` exists 2. **Verify tasks exist**: Use `TaskList()` to check for tasks with `[]` in subject - If no tasks: Display "No tasks found. Run the `/flow:decompose` stage first." and stop 3. **Count tasks**: Total, completed, pending/in-progress ### 1.3 Scaffold 04-implementation.md (IMMEDIATELY) This is the critical behavioral change: scaffold the implementation file NOW, before any agents run. **If `IMPL_FILE` does NOT exist (new session):** 1. Read `.claude/skills/executing-specs/implementation-summary-template.md` 2. Extract the feature name from the spec's title (first `# heading` in `02-specification.md`) 3. Substitute variables: - `[FEATURE_NAME]` → feature name from spec - `[DATE]` → today's date (YYYY-MM-DD) - `[SLUG]` → feature slug - `[TOTAL]` → total task count 4. Write to `specs//04-implementation.md` **If `IMPL_FILE` DOES exist (resume session):** 1. Read the existing file 2. Find the last `### Session N` header, increment to N+1 3. Append a new session section: ``` ### Session - _(No tasks completed yet)_ ``` 4. Update "Last Updated" date in frontmatter Display: ``` Quick validation: Specification found Tasks found: tasks for [New implementation / Resuming session ] Implementation file: specs//04-implementation.md (scaffolded) ``` --- ## Phase 2: Spawn Analysis Agent 1. Read `.claude/skills/executing-specs/analysis-agent-prompt.md` 2. Substitute `[SPEC_PATH]` and `[SLUG]` in the prompt text 3. Launch background agent: ``` Task( description: "Analyze execution plan", prompt: , subagent_type: "general-purpose", run_in_background: true ) ``` Display: ``` Analyzing tasks and building execution plan... ``` 4. Wait for result: `TaskOutput(task_id: , block: true)` 5. Parse the returned execution plan (session info, batches, cross-session context) --- ## Phase 3: Execute Batches ### 3.1 Display Execution Plan ``` ═══════════════════════════════════════════════════ EXECUTION PLAN ═══════════════════════════════════════════════════ Task Summary: Completed: tasks (skipping) In Progress: tasks (will resume) Pending: tasks (will execute) Execution Batches (parallel groups): Batch 1: [Task 1.1, 1.2, 1.3] - No dependencies Batch 2: [Task 2.1, 2.2] - Depends on Batch 1 ... Estimated: parallel batches (vs sequential tasks without parallelization) ═══════════════════════════════════════════════════ ``` ### 3.2 Proceed (Default: Auto-Execute) By default, proceed immediately to full execution — **do not ask**. Only pause if the user explicitly passed `--pause`, `--step`, or `--review` in the arguments. If a pause flag was passed: ``` AskUserQuestion: "Ready to execute tasks in parallel batches?" Options: - "Execute all batches" (Recommended) - Run all tasks to completion - "Execute one batch" - Run only the first batch, then pause - "Review tasks first" - Show detailed task list before executing ``` Otherwise, display: ``` Executing all tasks across batches... ``` ### 3.3 Execute Each Batch For each batch in the execution plan: **Step A: Read prompt and launch agents** 1. Read `.claude/skills/executing-specs/implementation-agent-prompt.md` 2. For each task in the batch: - Substitute `[TASK_ID]` with the task's ID - Substitute `[CROSS_SESSION_CONTEXT]` with context from the analysis agent (or "N/A - first session") - Launch: ``` Task( description: "Implement ", prompt: , subagent_type: , run_in_background: true ) ``` Display: ``` Batch : Launching parallel agents -> -> ``` **Step B: Wait for all agents in batch** ``` for agent_id in batch.agent_ids: result = TaskOutput(task_id: agent_id, block: true) ``` Display as each completes: ``` [Task 1] Completed [Task 2] Completed with warnings ``` **Step C: Handle failures** If any task failed: ``` Batch had failures: [Task 3]: Options: - "Retry failed tasks" - Re-launch failed tasks - "Skip and continue" - Mark as blocked, proceed to next batch - "Stop execution" - Pause for manual intervention ``` **Step D: Two-Stage Review (per task)** After each task's agent completes successfully: **Stage 1 — Spec Compliance Review:** Dispatch a review agent to verify the implementation matches the task spec: - Did the agent implement everything requested? - Did the agent add anything not requested? - Did the agent misinterpret any requirements? - CRITICAL: The reviewer must read actual code, not trust the implementer's report. If issues found: dispatch the implementer agent to fix, then re-review. **Stage 2 — Code Quality Review (only after Stage 1 passes):** Dispatch the `code-reviewer` agent with: - `{WHAT_WAS_IMPLEMENTED}`: from the implementer's report - `{PLAN_OR_REQUIREMENTS}`: the task description from `03-tasks.json` - `{BASE_SHA}`: commit before task - `{HEAD_SHA}`: current commit - `{DESCRIPTION}`: task summary If Critical or Important issues found: dispatch fix agent, then re-review. Never start Stage 2 before Stage 1 passes. **Step E: APPEND batch results to 04-implementation.md (INCREMENTAL WRITE)** This is the second critical behavioral change: persist results after EACH batch, not at the end. 1. Read current `specs//04-implementation.md` 2. For each successful task in the batch, parse the agent's result report 3. **Update "Tasks Completed" section** — Under the current session header, replace `_(No tasks completed yet)_` (if first batch) or append after existing entries: ``` - Task #: ``` 4. **Update "Files Modified/Created" section** — Append any new files from agent reports (deduplicate) 5. **Update "Known Issues" section** — Append any issues from agent reports 6. **Update task count** — Increment "Tasks Completed: X / Total" in the Progress section 7. Write the updated file **Step F: Update task status** ``` for task in batch.successful_tasks: TaskUpdate({ taskId: task.id, status: "completed" }) ``` **Step G: Display batch summary** ``` Batch complete: / tasks succeeded Proceeding to Batch ... ``` --- ## Phase 4: Finalize After all batches complete: ### 4.1 Finalize Implementation Summary 1. Read `specs//04-implementation.md` 2. Change `**Status:** In Progress` to `**Status:** Complete` 3. Verify task count matches total 4. Add any final implementation notes under the current session 5. Write the updated file ### 4.1b Update Manifest Status Update the spec manifest to reflect completed implementation: ```bash node --experimental-strip-types --disable-warning=ExperimentalWarning .claude/scripts/spec-manifest-ops.ts update-status implemented --quiet ``` This ensures the manifest stays in sync even when the PostToolUse hook doesn't fire (e.g., when agents write files). ### 4.2 Display Completion Summary ``` ═══════════════════════════════════════════════════ IMPLEMENTATION COMPLETE ═══════════════════════════════════════════════════ All tasks completed successfully Summary: - Tasks completed: - Files modified: - Execution time: Implementation summary: specs//04-implementation.md Documentation Review: Run /docs:reconcile to check for drift Next steps: - Manifest status updated to "implemented" - Run /git:commit to commit changes - Run /spec:feedback if you have feedback to incorporate - If this ran in a dedicated worktree (Phase 0): merge via PR, then /worktree:remove --delete-branch ═══════════════════════════════════════════════════ ``` --- ## Execution Modes ### Full Execution (Default) Execute all batches to completion. Best for dedicated implementation sessions. ### Single Batch Mode Execute one batch at a time, pause for review. Best for large implementations or when you want to review progress between phases. ### Dry Run Mode Show execution plan without executing. Best for understanding scope or verifying task dependencies. --- ## Error Handling ### Agent Timeout If an agent doesn't complete within expected time: 1. Check agent status with `TaskOutput(task_id, block: false)` 2. Offer to wait longer or cancel ### Task Failure If an agent reports failure: 1. Display the error details 2. Offer options: retry, skip, or stop 3. If skipping, mark dependent tasks as blocked ### Dependency Issues If circular dependencies detected: 1. Display the cycle 2. Ask user which task to execute first 3. Or suggest running the `/flow:decompose` stage to fix dependencies --- ## Session Continuity 1. **First run**: Phase 1 scaffolds `04-implementation.md` with Session 1 2. **Each batch**: Phase 3 Step E appends results incrementally 3. **Subsequent runs**: Phase 1 detects existing file, increments session number 4. **Context preservation**: Completed tasks, files modified, known issues passed to agents via cross-session context 5. **No duplication**: Completed tasks skipped automatically via TaskList status --- ## Integration with Other Stages & Commands EXECUTE is one stage of the `/flow` spine (`… DECOMPOSE → **EXECUTE** → VERIFY → ⟦REVIEW⟧ → DONE …`). Its neighbors: | Stage / Command | Relationship | | ------------------ | --------------------------------------------------------------------------------- | | `/flow:decompose` | **The prior stage** — creates the `03-tasks.json` tasks to execute | | `/worktree:create` | Offered in Phase 0 when the checkout is shared or on another topic | | `/flow:verify` | **The next stage** — proves completion, opens the PR, hands to REVIEW | | `/spec:feedback` | Run to incorporate post-implementation feedback, then re-decompose and re-execute | | `/git:commit` | Run after execution to commit changes | | `/docs:reconcile` | Run after to check if guides need updates | | `/flow:done` | Closes the work after REVIEW approval; offers Phase 0 worktree cleanup | | `/worktree:remove` | Run after merge to clean up a Phase 0 worktree | --- ## Troubleshooting ### "No tasks found" Run the `/flow:decompose` stage first to create tasks from the specification. ### "All tasks already completed" The implementation is done. Check `04-implementation.md` for summary. ### Agents taking too long Large tasks may take several minutes. Use `TaskOutput(block: false)` to check progress. ### Context limits in agents Each agent has isolated context. If a single task is too large, consider splitting it in the decompose phase.