Implement Spec

---
description: Implements a feature based on provided context or spec file
argument-hint: [specIdOrNameOrPath]
---

# Implement

Follow the `Workflow` steps in the exact order to implement the spec then `Report` the completed work.

## Variables

- $specIdOrNameOrPath: $1 (required) - Either a timestamp ID (e.g., `2510241201`), feature name (e.g., `workflow-safety`), or full path

## Instructions

**Parse and resolve $specIdOrNameOrPath:**

- If it's a full path (contains `/`): use as-is
- Otherwise, look up in `.agent/specs/index.json`:
  - For timestamp ID: Match by `id` field
  - For feature name: Fuzzy match path (e.g., `message-queue` matches `todo/2510241201-message-queue-implementation/spec.md`)
  - Use path from index: `.agent/specs/{path}`
- **If not found in index.json, fallback to directory search:**
  - Search in order: todo/, backlog
  - For ID: Pattern `{id}-*/spec.md`
  - For feature name: Pattern `*{feature-name}*/spec.md` (fuzzy match)
- If still not found: stop and report error

## Task Tracking Requirements

**CRITICAL: You MUST track your progress in the spec file as you work. This is NOT optional.**

### What to Update

1. **Individual Tasks** - Check off IMMEDIATELY after completing each task:
   - Change `- [ ] 1.1 Task description` to `- [x] 1.1 Task description`
   - Do this AFTER finishing each task, NOT in batches
   - Never move to the next task without checking off the current one

2. **Completion Notes** - Fill in after finishing each task group/phase:
   - Each task group has a `#### Completion Notes` section
   - Write 2-4 bullet points with:
     - What was implemented
     - Any deviations from the plan
     - Important context for reviewers
     - Known issues or follow-ups

### Example of Good Progress Tracking

**Before starting task 1.1:**

```markdown
### 1: Project Initialization

- [ ] 1.1 Initialize Bun project
- [ ] 1.2 Configure package.json

After completing task 1.1:

### 1: Project Initialization

- [x] 1.1 Initialize Bun project
- [ ] 1.2 Configure package.json

After completing all tasks in group 1:

### 1: Project Initialization

- [x] 1.1 Initialize Bun project
- [x] 1.2 Configure package.json

#### Completion Notes

- Project initialized with Bun and TypeScript
- Used stricter tsconfig settings than spec suggested for better type safety
- All dependencies installed successfully

Workflow

1. Parse and resolve the spec file path according to the instructions above
2. Update spec Status:
   • If spec is in todo/ folder with Status "draft", update Status to "in-progress"
   • This indicates work has started without moving the file
3. Update index.json:
   • Update the spec's status field to "in-progress"
   • Update the spec's updated field to current timestamp
   • Write updated index back to .agent/specs/index.json
4. Read $spec_path file, think hard about the plan
5. Implement the plan, one phase at a time:
   • Work through tasks in order, top to bottom
   • IMMEDIATELY check off each task in $spec_path after completing it
   • Run validation after each logical step
6. After completing each task group/phase:
   • Fill in the "Completion Notes" section with implementation context
   • Include any deviations, decisions, or important notes for reviewers
7. Continue until all tasks are checked off and all completion notes are filled
8. Update spec Status to "review":
   • Update Status field in spec.md to "review"
   • Update index.json:
     • Set status field to "review"
     • Update updated field to current timestamp
   • Write updated index back to .agent/specs/index.json
   • This indicates implementation is complete and ready for review

Validation Commands

Run validation checks from the spec's Validation section after each logical step:

Critical Checks (must pass):

• Build: pnpm build (or package-specific build command)
• Type-check: pnpm check-types (or tsc --noEmit)

Important Checks (should pass):

• Lint: pnpm lint (or package-specific lint command)
• Tests: pnpm test (or package-specific test command)

Run these after completing:

• Each phase (minimum)
• Complex tasks (recommended)
• Before marking spec as "review" (required)

Error Handling

If a task fails during implementation:

1. Document the failure:

   • Add failure note in Completion Notes
   • Mark failed task: - [ ] ~~1.1 Task description~~ ❌ FAILED: [reason]

2. Assess impact:

   • Can you continue with other tasks?
   • Is this a blocker for subsequent tasks?

3. Update status:

   • Set implementation_status: "partial" in JSON output
   • Keep spec status as "in-progress"
   • Populate error field with details

4. Report to user:

   • Include failure details in JSON output
   • Ask for guidance if blocked

Success/Failure Criteria

Success (success: true):

• All tasks completed (tasks.completed === tasks.total)
• All critical validation checks passed (build, type-check)
• No critical errors during implementation
• Spec file updated to status: "review"
• implementation_status: "completed"

Failure (success: false):

• Any task not completed (tasks.completed < tasks.total)
• Critical validation failed (build or type-check errors)
• Process interrupted or error thrown
• Spec file remains in status: "in-progress"
• implementation_status: "partial" or "failed"

Partial Completion: When some tasks complete but others fail, set success: false with implementation_status: "partial" and populate error field.

Report

IMPORTANT: Output ONLY raw JSON (see .agent/docs/slash-command-json-output-format.md).

{ "success": true, "summary": "- Implemented feature-name with core functionality and UI integration\n- Added new components and backend services to support the feature\n- Completed all 15 tasks successfully with all validation checks passing", "spec_id": "2511131522", ```