| name | implement-spec |
| description | Execute an approved spec plan, implementing each task in sequence with mandatory build/test verification before reporting completion. |
Implement Spec
Execute an approved spec plan, implementing each task in sequence.
Auto Mode Selection
This command automatically enters Build mode. If you are currently in plan mode, exit plan mode and switch to build mode before proceeding.
Important Guidelines
- Always use AskUserQuestion tool when asking the user anything
- Follow the plan — Execute tasks as specified, don't improvise unless blocked
- Report progress — Keep the user informed as tasks complete
- Handle blockers — If a task can't be completed, explain why and ask for guidance
Prerequisites
This command requires an existing spec with a plan. Check for:
- Recent specs in
agent-os/specs/
- A
plan.md file within the spec folder
If no spec exists:
No spec found. Run /shape-spec first to create a plan, then return here to implement it.
Process
Step 1: Identify the Spec to Implement
Check agent-os/specs/ for available specs. If multiple exist, use AskUserQuestion:
I found these specs:
1. **2026-01-15-1430-user-comment-system** — User commenting feature
2. **2026-01-14-0900-auth-improvements** — Authentication flow updates
Which spec should we implement? (1, 2, or specify path)
If only one spec exists, confirm it:
Found spec: agent-os/specs/2026-01-15-1430-user-comment-system/
Implement this spec? (yes / or specify different path)
Step 2: Load the Plan
Read the plan.md file from the selected spec folder. Parse the tasks and present a summary:
Loaded plan for: User Comment System
Tasks to implement:
1. Save Spec Documentation [if not already done]
2. Create comment model and database migration
3. Build comment API endpoints
4. Add comment UI components
5. Write tests for comment functionality
Ready to begin implementation? (yes / review plan first)
If they want to review, show the full plan content.
Step 3: Load Standards Context
Read standards.md from the spec folder to understand which standards apply. Keep these in context during implementation.
If standards.md doesn't exist, check agent-os/standards/index.yml and use AskUserQuestion to confirm relevant standards before proceeding.
Step 4: Execute Tasks Sequentially
For each task in the plan:
4a. Announce the Task
Starting Task 2: Create comment model and database migration
This task involves:
- Creating the Comment model with fields for content, author, timestamps
- Writing the database migration
- Following the migration patterns from our standards
4b. Implement the Task
Execute the implementation:
- Write code following the standards
- Create necessary files
- Make required changes
4c. Report Completion
✓ Task 2 Complete: Create comment model and database migration
Created:
- src/models/comment.ts
- src/db/migrations/20260115_create_comments.ts
Moving to Task 3...
4d. Handle Blockers
If a task can't be completed, stop and use AskUserQuestion:
⚠️ Blocked on Task 3: Build comment API endpoints
Issue: The user model doesn't have an `id` field that the comment model references.
Options:
1. Add `id` field to user model first
2. Skip this task and continue
3. Modify the approach (I'll explain alternatives)
How should we proceed?
Step 5: Mandatory Verification
CRITICAL: Before reporting completion, you MUST run these commands and ensure they all pass. Do NOT skip this step. Do NOT report success if any command fails.
-
Build all affected packages:
pnpm build
If build fails, fix the errors before proceeding.
-
Run all tests:
pnpm test
If any tests fail, fix them. This includes tests that were broken by your changes — update test assertions to match the new behavior. Never leave failing tests.
-
Only after both pass, proceed to the final summary.
If a test or build failure is unrelated to your changes (pre-existing failure), note it explicitly but still attempt to fix it if possible.
Step 6: Final Summary
After all tasks complete AND verification passes:
✓ Implementation Complete
Spec: User Comment System
Tasks completed: 5/5
Verification: ✓ build passed, ✓ tests passed (586 tests)
Files created:
- src/models/comment.ts
- src/db/migrations/20260115_create_comments.ts
- src/api/comments.ts
- src/components/CommentList.tsx
- src/components/CommentForm.tsx
- tests/comments.test.ts
Files modified:
- src/api/index.ts (added comment routes)
- src/models/index.ts (exported Comment model)
Next steps:
- Review the changes before committing
- Consider running /discover-standards if new patterns emerged
Handling Deviations
Sometimes the plan needs adjustment during implementation. Handle these cases:
Minor Adjustments
If a small change is needed (different file name, additional import):
- Make the change
- Note it in the completion report
- Don't stop for approval
Significant Deviations
If a major change is needed (different approach, missing dependency, architectural issue):
- Stop and use AskUserQuestion to explain
- Get approval before proceeding
- Update the plan if needed
New Tasks Discovered
If implementation reveals additional work needed:
During Task 3, I discovered we also need:
- A notification system for new comments
- Rate limiting on the comment API
Options:
1. Add these as new tasks and continue
2. Note them for a future spec
3. Skip for now, handle separately
How should we handle these?
Integration with Standards
During implementation:
- Reference standards when making decisions
- Follow patterns established in standards
- If you notice a new pattern emerging, mention it:
Note: I'm using a consistent error handling pattern here that might be worth documenting.
After implementation, consider running /discover-standards on the API code.
Tips
- Trust the plan — The shaping phase already made key decisions
- Stay focused — Implement what's in the plan, defer new ideas
- Communicate progress — Users appreciate knowing where things stand
- Test as you go — Run tests after each task if possible
- Commit checkpoints — Suggest commits after major milestones
