--- name: Spec Executor slug: spec-executor category: AI Engineering description: Spec Executor implements one approved spec in a forked execution thread and returns a structured receipt. Use it when a final SPEC READY block is approved and the work fits one implementation session. github: "https://github.com/tt-a1i/matt-skills-with-to-goal/tree/main/skills/engineering/spec-executor" language: Shell stars: 29 forks: 7 install: "npx degit https://github.com/tt-a1i/matt-skills-with-to-goal/tree/main/skills/engineering/spec-executor ~/.claude/skills/spec-executor" installs_to: ~/.claude/skills/spec-executor source_path: skills/engineering/spec-executor/SKILL.md collection_size: 40 category_size: 2451 collection_url: "https://dirskills.com/collections/tt-a1i/matt-skills-with-to-goal" added: 2026-08-12T04:44:22.144Z last_synced: 2026-08-12T04:44:22.144Z canonical_url: "https://dirskills.com/skills/spec-executor" --- # Spec Executor Spec Executor implements one approved spec in a forked execution thread and returns a structured receipt. Use it when a final SPEC READY block is approved and the work fits one implementation session. **Install:** ```bash npx degit https://github.com/tt-a1i/matt-skills-with-to-goal/tree/main/skills/engineering/spec-executor ~/.claude/skills/spec-executor ``` ## README # Spec Executor Implement one approved spec in the forked execution thread. Treat the planning thread as the source of product decisions, keep implementation detail here, and return a compact receipt that can be pasted back. ## Resolve the execution contract 1. Find the latest `SPEC READY` block in inherited conversation history. Later user corrections override it; older conflicting requirements do not. 2. Read the complete spec artifact referenced by that block, including tracker comments or directly linked decisions. Do not reconstruct a second long goal. 3. Require the route to say that the spec is suitable for forked execution. If it says `to-tickets`, contains unresolved product decisions, or cannot fit one implementation context, stop and explain the routing problem. 4. If no `SPEC READY` block exists, proceed only when the user explicitly identifies an approved spec and asks for its implementation. Otherwise ask for the final source rather than guessing which draft won. 5. Extract and preserve: - repository and starting baseline; - user-visible outcome and acceptance criteria; - agreed test seam; - explicit non-goals and workspace boundaries; - authorization for commit, push, review request, deployment, tracker edits, data changes, and other external effects. Do not reopen settled product questions. Pause only when the final spec is internally contradictory, conflicts materially with the repository, lacks a required external contract, or requires new authority. ## Lock scope before editing Inspect repository instructions, branch, `HEAD`, worktree status, recent relevant history, and the current implementation at the agreed seam. Record the actual pre-implementation `HEAD` as the review fixed point. Send a short execution lock before substantive edits: ```text Executing: Source: In scope: Out of scope: Validation: External authority: ``` Create or switch to an appropriate local branch when needed. Never discard, overwrite, or absorb unrelated dirty or untracked work. If the requested baseline has drifted, determine whether the spec is still applicable and record the current fixed point; stop if drift changes product behavior or acceptance criteria. ## Implement the spec 1. Trace each acceptance criterion to existing behavior, the smallest code seam that can satisfy it, and observable evidence. 2. Use `/tdd` where practical at the pre-agreed seam. Prefer behavior tests over implementation-detail tests. 3. Implement the narrowest complete vertical path. Do not pull in downstream tickets, opportunistic refactors, or new product behavior. 4. Run the smallest relevant check during development, then the repository-required broad gates in proportion to risk. 5. Compare the finished diff with every acceptance criterion and run `/code-review` against the recorded fixed point. Fix in-scope P0/P1 findings; resolve or explicitly report lower-priority findings. 6. Inspect the final worktree and separate this execution's changes from anything pre-existing. Invoking this skill authorizes in-scope local implementation and validation. It does not by itself authorize committing, pushing, opening or merging a review, changing tracker state, deploying, writing production data, calling costly real services, or messaging people. Perform those actions only when the final spec or a later user message explicitly authorizes them. Never broaden one authorization into another. ## Handle blockers and context overflow When blocked, exhaust safe read-only investigation and local validation first. Then stop with evidence and the smallest decision or authority needed from the planning thread. If the work proves too large for one reliable implementation context, do not continue by silently dropping history. Return a partial receipt, preserve the worktree, and recommend splitting with `to-tickets` or compiling the remaining slice with `to-goal`. ## Return the receipt Do not write a handoff file unless requested. End with one copy-pasteable block: ```text SPEC EXECUTION RECEIPT - Conclusion: completed / partially completed / blocked - Spec source: - Review fixed point: - Acceptance criteria: - Main changes: - Changed files: - Branch / commit / review: - Validation results: - Review findings: - Not validated or not executed: - Risks and remaining work: - Planning-thread decision needed: - Final worktree state: - External effects: ``` Keep the receipt concise but evidence-bearing. Include exact commands, counts, identifiers, and links when they materially prove completion. Never claim a real environment, deployment, or external action that was not verified. Redact credentials, tokens, cookies, personal data, and sensitive environment identifiers before the receipt leaves the execution thread.