Specification Implementation

Systematically implements approved spec proposals by executing tasks sequentially with proper testing and validation.

Quick Start

Implementation follows a read → execute → test → validate cycle for each task:

1. Read the full proposal and task list
2. Execute tasks one at a time, in order
3. Test each completed task
4. Mark complete only after verification

Critical rule: Use TodoWrite to track progress. Never skip tasks or mark incomplete work as done.

Workflow

Copy this checklist and track progress:

Implementation Progress:
- [ ] Step 1: Load and understand the proposal
- [ ] Step 2: Set up TodoWrite task tracking
- [ ] Step 3: Execute tasks sequentially
- [ ] Step 4: Test and validate each task
- [ ] Step 5: Update living specifications (if applicable)
- [ ] Step 6: Mark proposal as implementation-complete

Step 1: Load and understand the proposal

Before starting, read all context:

# Read the proposal
cat spec/changes/{change-id}/proposal.md

# Read all tasks
cat spec/changes/{change-id}/tasks.md

# Read spec deltas to understand requirements
find spec/changes/{change-id}/specs -name "*.md" -exec cat {} \;

Understand:

• Why this change is needed (from proposal.md)
• What the expected outcomes are
• Which specs will be affected
• What the acceptance criteria are (from scenarios)

Step 2: Set up TodoWrite task tracking

Load tasks from tasks.md into TodoWrite before starting work:

**Pattern**:
Read tasks.md → Extract numbered list → Create TodoWrite entries

**Example**:
If tasks.md contains:
1. Create database migration
2. Implement API endpoint
3. Add tests
4. Update documentation

Then create TodoWrite with:
- content: "Create database migration", status: "in_progress"
- content: "Implement API endpoint", status: "pending"
- content: "Add tests", status: "pending"
- content: "Update documentation", status: "pending"

Why this matters: TodoWrite gives the user visibility into progress and ensures nothing gets skipped.

Step 3: Execute tasks sequentially

Work through tasks one at a time, in order:

For each task:
1. Mark as "in_progress" in TodoWrite
2. Execute the work
3. Test the work
4. Only mark "completed" after verification

NEVER skip ahead or batch multiple tasks before testing.

Task execution pattern:

## Task: {Task Description}

**What**: [Brief explanation of what this task does]

**Implementation**:
[Code changes, file edits, commands run]

**Verification**:
[How to verify this task is complete]
- [ ] Code compiles/runs
- [ ] Tests pass
- [ ] Meets requirement scenarios

**Status**: ✓ Complete / ✗ Blocked / ⚠ Partial

Step 4: Test and validate each task

After each task, verify it works:

For code tasks:

# Run relevant tests
npm test # or pytest, cargo test, etc.

# Run linter
npm run lint

# Check types (if applicable)
npm run type-check

For database tasks:

# Verify migration runs
npm run db:migrate

# Check schema matches expected
npm run db:schema

For API tasks:

# Test endpoint manually
curl -X POST http://localhost:3000/api/endpoint \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

# Or run integration tests
npm run test:integration

Only mark task complete after all verifications pass.

Step 5: Update living specifications (if applicable)

During implementation, if you discover the spec deltas need updates:

1. Document the discovery in proposal.md or a notes file
2. Do NOT modify spec deltas during implementation
3. After implementation completes, consider whether spec needs adjustment

Note: Spec deltas are merged during archiving (Step 6), not during implementation.

Step 6: Mark proposal as implementation-complete

After all tasks are complete:

# Create a completion marker
echo "Implementation completed: $(date)" > spec/changes/{change-id}/IMPLEMENTED

Tell the user:

## Implementation Complete

**Change**: {change-id}
**Tasks completed**: {count}
**Tests**: All passing

**Next step**: Archive this change to merge spec deltas into living documentation.
Say "openspec archive {change-id}" or "archive this change" when ready.

Best Practices

Pattern 1: Blocked Tasks

If a task cannot be completed:

**Mark as blocked**:
- Keep status as "in_progress" (NOT "completed")
- Document the blocker clearly
- Create a new task for resolving the blocker
- Inform the user immediately

**Example**:
Task: "Implement payment processing"
Blocker: "Missing API credentials for payment gateway"
Action: Create new task "Obtain payment gateway credentials"

Pattern 2: Task Dependencies

If tasks have dependencies, verify prerequisites before starting:

# Example: Database migration must run before API code
# Check migration status
npm run db:status

# Only proceed with API task if migratio

...