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:

Read the full proposal and task list
Execute tasks one at a time, in order
Test each completed task
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:

bash

# 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:

markdown

**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:

markdown

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:

markdown

## 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:

bash

# 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:

bash

# Verify migration runs
npm run db:migrate

# Check schema matches expected
npm run db:schema

For API tasks:

bash

# 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:

Document the discovery in proposal.md or a notes file
Do NOT modify spec deltas during implementation
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:

bash

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

Tell the user:

markdown

## 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:

markdown

**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:

bash

# 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:

markdown

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:

Database schema/migration
Data access layer (models)
Business logic layer (services)
API endpoints (controllers)
UI integration
End-to-end tests

Pattern 2: Feature Flags

For gradual rollouts:

Implement feature behind flag
Test with flag enabled
Deploy with flag disabled
Enable flag incrementally
Remove flag after full rollout

Pattern 3: Breaking Changes

For API breaking changes:

Implement new version (v2)
Keep old version (v1) working
Add deprecation warnings to v1
Migrate users to v2
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:

markdown

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:

markdown

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:

markdown

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.

openspec-implementation

NPX Install

Tags

SKILL.md Content

Specification Implementation

Quick Start

Workflow

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

Best Practices

Pattern 1: Blocked Tasks

Pattern 2: Task Dependencies

Pattern 3: Incremental Testing

Pattern 4: Living Documentation

Advanced Topics

Common Patterns

Pattern 1: Database + API + UI

Pattern 2: Feature Flags

Pattern 3: Breaking Changes

Anti-Patterns to Avoid

Troubleshooting

Issue: Tests failing after task completion

Issue: Task is too large

Issue: Dependency not met

Reference Materials