Openspec Implementation

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 migration succeeded

Pattern 3: Incremental Testing

Test incrementally, not at the end:

Good:

Task 1: Create model → Test model → Mark complete
Task 2: Create API → Test API → Mark complete
Task 3: Add validation → Test validation → Mark complete

Bad:

Task 1, 2, 3 → Implement all → Test everything → Debug failures

Pattern 4: Living Documentation

Keep README, API docs, and comments up to date as you go:

When adding a new API endpoint, also:
- Update API documentation
- Add example request/response
- Update OpenAPI/Swagger spec
- Add inline code comments

Advanced Topics

Parallel work: If tasks are truly independent (e.g., separate modules), you can work on them in parallel, but each must be tested independently.

Integration points: When task dependencies exist, use integration tests to verify the connection works.

Rollback strategy: For risky changes, create rollback tasks before deploying.

Common Patterns

Pattern 1: Database + API + UI

Typical order:

1. Database schema/migration
2. Data access layer (models)
3. Business logic layer (services)
4. API endpoints (controllers)
5. UI integration
6. End-to-end tests

Pattern 2: Feature Flags

For gradual rollouts:

1. Implement feature behind flag
2. Test with flag enabled
3. Deploy with flag disabled
4. Enable flag incrementally
5. Remove flag after full rollout

Pattern 3: Breaking Changes

For API breaking changes:

1. Implement new version (v2)
2. Keep old version (v1) working
3. Add deprecation warnings to v1
4. Migrate users to v2
5. Remove v1 (separate task/proposal)

Anti-Patterns to Avoid

Don't:

• Skip testing individual tasks
• Mark tasks complete before verification
• Ignore failing tests ("I'll fix it later")
• Batch multiple tasks before testing
• Modify living specs during implementation
• Work out of order (dependencies break)

Do:

• Test each task immediately
• Fix failing tests before proceeding
• Update TodoWrite in real-time
• Document blockers clearly
• Communicate progress to user
• Keep commits atomic and descriptive

Troubleshooting

Issue: Tests failing after task completion

Solution:

1. Do NOT mark task complete
2. Debug the failure
3. Fix the code
4. Re-run tests
5. Only mark complete after pass

Issue: Task is too large

Solution:

1. Break into subtasks
2. Update TodoWrite with subtasks
3. Complete subtasks sequentially
4. Mark parent task complete after all subtasks done

Issue: Dependency not met

Solution:

1. Pause current task
2. Complete dependency first
3. Test dependency
4. Resume original task

Reference Materials

• TASK_PATTERNS.md - Common task execution patterns
• TESTING_STRATEGIES.md - Testing approaches by task type

Token budget: This SKILL.md is approximately 430 lines, under the 500-line recommended limit.