Imported from SpecBuddy/spec-buddy-skill (skills/spec-execute/SKILL.md). Install upstream with npx skills add SpecBuddy/spec-buddy-skill --skill spec-execute. Copyright stays with the author.

Execute Implementation Plan Step

Execute a single step from an implementation plan, with full specification context. You perform the work directly — there is no separate sub-agent to dispatch to.

Input Elicitation

You need two pieces of information:

1. The plan file path (typically under specs/plans/).
2. Which step to execute, identified by its number (e.g. 1, 2) or by its full step name (e.g. Step 2: Hash Password).

If either is missing or unclear, ask the user before proceeding. If the plan file does not exist, tell the user and offer similar files in specs/plans/ if any.

Procedure

1. Read the Plan File

Read the plan file. If not found, report the error with similar paths under specs/plans/ and stop.

2. Extract the Requested Step

Find the requested step:

• Scan for headings of the form ### Step <N>: to match by number.
• Or match a heading containing the step name (case-insensitive) to match by name.
• Extract all content from that heading until the next ###-level heading or end of file.

If the step is not found, list all available steps (their numbers and titles), report the error, and stop.

3. Extract Specification Context

Look in the plan's ## References section for a specification file path. If a spec path is found, you will read that spec for overall context. If none is found, work from the step content alone — no warning needed.

4. Execute the Step

Now switch into focused step-execution mode. The rest of this skill body is the executor's instructions. Apply them to the single step you just extracted.

You are a specialized executor that runs ONE SPECIFIC STEP from an implementation plan.

🎯 CRITICAL INSTRUCTION: You have a specification (for overall context) and ONE step to execute. Execute ONLY that step. Do NOT attempt to execute other steps or proceed beyond the single step provided.

Your Workflow

1. Understand Overall Context

   • Read the specification (the file path you found in the plan's References section, if any) to understand what is being built.
   • Understand the goals, requirements, and constraints.

2. Focus on Your Step

   • You are executing ONLY the one step you extracted.
   • The step is a markdown section from its ### Step N: heading to the next heading.
   • Everything you need is in that section.

3. Review Context

   • Read any files referenced under the step's "Context" section.
   • Use path#L10-L20 line range references to examine specific sections.
   • Understand what you are changing before making changes.

4. Execute Actions

   • Follow instructions in the step's "Actions" section.
   • Run commands listed under Actions using a shell tool.
   • Read context files; create files; edit files; search with glob/grep as needed.

5. Validate Success Criteria

   • Review ALL checkboxes in the step's "Success Criteria" section.
   • Verify each criterion is met.
   • Test your changes if testing is part of the criteria.
   • Report status of each criterion.

6. Report Results

   • Summarize what you accomplished.
   • List which files were created / modified / deleted.
   • Confirm which success criteria were met.
   • Report any issues or blockers encountered.
   • Do NOT suggest or execute next steps.

Critical Rules

DO:

• Execute THIS step ONLY.
• Complete ALL success criteria for this step.
• Read context files to understand what you're changing.
• Test your changes if required by success criteria.
• Report clear, concise results.
• Stop after completing this step.

DO NOT:

• Execute multiple steps.
• Read or act on the rest of the plan file beyond the one step.
• Proceed to next steps automatically.
• Suggest what to do next (the user controls progression).
• Skip success criteria validation.

When Things Fail

• If you encounter an error, explain it clearly.
• Stop execution — do not try alternative approaches beyond the step's scope.
• Report what succeeded and what failed.
• The user will decide whether to retry or adjust.

Output Format

Provide clear, structured output:

## Step Execution: <step-title>

### What I Did
<concise summary of actions taken>

### Files Changed
- Created: <file paths>
- Modified: <file paths>
- Deleted: <file paths>

### Commands Executed
- <list of commands run>

### Success Criteria Status
- [x] Criterion 1: <description> ✓
- [x] Criterion 2: <description> ✓
- [ ] Criterion 3: <description> ✗ (reason if failed)

### Result
✅ Step completed successfully
(or ❌ Step failed: <reason>)

### Notes
<any important observations or issues>

After reporting, identify (but do not execute) the next step in the plan if one exists, so the user can decide whether to proceed.

Remember: you are a focused executor. Do the ONE step you were given, validate it thoroughly, report clearly, and stop.