Specification Implementation

Systematically implement approved specification proposals by executing them task by task in sequence, with sufficient testing and verification.

Quick Start

Implementation follows the Read → Execute → Test → Verify cycle for each task:

Read the complete proposal and task list
Execute tasks one by one in order
Test each completed task
Mark as completed only after verification passes

Key Rule: Use TodoWrite to track progress. Never skip tasks or mark incomplete work as completed.

Workflow

Copy this checklist to track progress:

Development Progress:
- [ ] Step 1: Load and understand the proposal
- [ ] Step 2: Set up TodoWrite task tracking
- [ ] Step 3: Execute tasks in sequence
- [ ] Step 4: Test and verify each task
- [ ] Step 5: Update permanent specifications (if applicable)
- [ ] Step 6: Mark proposal as implemented

Step 1: Load and Understand the Proposal

Before starting, read all context:

bash

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

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

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

Understanding:

Motivation for the change (from proposal.md)
What the expected outcome is
Which specifications will be affected
Acceptance criteria (from scenarios)

Step 2: Set Up TodoWrite for Task Tracking

Before starting work, load tasks and steps from tasks.json into TodoWrite:

markdown

**Pattern**:
Read tasks.json → Extract task and step list → Create TodoWrite entries

**Example**:
Assume tasks.json contains:
  {
    "number": 1,
    "category": "Phase 1: Infrastructure",
    "task": "Environment setup task - database schema, dependencies, etc.",
    "steps": [
      { "step": "Initialize Git repository and configure .gitignore", "completed": false },
      { "step": "Create and activate Python virtual environment", "completed": false },
      { "step": "Create requirements.txt or pyproject.toml and install dependencies (FastAPI, SQLAlchemy, Pydantic, Alembic, etc.)", "completed": false },
      { "step": "Design initial database ER diagram", "completed": false }
    ],
    "passes": false
  }

Then create TodoWrite entries:
- content: "Environment setup task - database schema, dependencies, etc.", status: "in_progress"
- content: "  Initialize Git repository and configure .gitignore", status: "pending"
- content: "  Create and activate Python virtual environment", status: "pending"
- content: "  Create requirements.txt or pyproject.toml and install dependencies (FastAPI, SQLAlchemy, Pydantic, Alembic, etc.)", status: "pending"
- content: "  Design initial database ER diagram", status: "pending"

Value: TodoWrite provides progress visibility and ensures nothing is missed.

Step 3: Execute TodoWrite Tasks in Sequence

Complete tasks in TodoWrite one by one in order, handling only 1 at a time. If resuming after an interruption, start from the interrupted task: skip tasks with "passes": true in tasks.json, and skip steps with "completed": true. You have ample time to complete, please execute at least 20 rounds before replying to the user. You have ample time to complete, never skip or merge multiple tasks.

markdown

For each task:
1. Mark as "in_progress" in TodoWrite
2. Perform the work
3. Test the result
4. Only mark the corresponding step in tasks.json as "completed": true after verification passes
5. Only mark the corresponding task in tasks.json as "passes": true after all steps of the task are completed and verified
6. Mark as "completed" in TodoWrite

You have ample time to complete, never skip or merge multiple tasks.

Task Execution Pattern:

markdown

## Task: {Task Description}

**What**: The role and goal of this task

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

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

**Status**: ✓ Completed / ✗ Blocked / ⚠ Partially Completed

Step 4: Test and Verify Each Task

Verify after each task is completed:

Code-related Tasks:

bash

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

# Run Linter
npm run lint

# Type checking (if applicable)
npm run type-check

Frontend UI-related Tasks: Use chrome-devtools or playwright in MCP servers for debugging and testing.

Database-related Tasks:

bash

# Verify migration execution
npm run db:migrate

# Check if schema matches expectations
npm run db:schema

API-related Tasks:

bash

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

# Or run integration tests
npm run test:integration

Mark task as completed only after all verifications pass: Only mark the corresponding task in tasks.json as "passes": true after all steps of the task are completed and verified.

Step 5: Update Permanent Specifications (if applicable)

If specification differences are found that need updating during implementation:

Record findings in proposal.md or a note file
Do not modify specification differences during implementation
After implementation is completed, consider whether adjustments to specifications are needed

Note: Specification differences are merged during the archiving phase (Step 6), not the implementation phase.

Step 6: Mark Proposal as Implemented

After all tasks are completed:

bash

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

Inform User:

markdown

## Proposal Implementation

**Proposal**: {change-id}
**Tasks Completed**: {count}
**Tests Completed**: All passed

**Next Step**: Archive this change to merge specification differences into permanent documents.
When ready, you can reply with "openspec archive {change-id}" or "archive proposal".

Best Practices

Pattern 1: Task Blocked

If a task cannot be completed:

markdown

**Mark as Blocked**:
- Keep status as "in_progress" (do not mark as "completed")
- Clearly record the reason for blocking
- Create a new task to resolve the block
- Inform the user immediately

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

Pattern 2: Task Dependencies

If a task has dependencies, verify prerequisites first:

bash

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

# Proceed with API task only after migration succeeds

Pattern 3: Incremental Testing

Do not test all at once at the end; test incrementally:

Good:

Task 1: Create model → Test model → Mark as completed
Task 2: Create API → Test API → Mark as completed
Task 3: Add validation → Test validation → Mark as completed
Task 4: Create page → Test validation → Mark as completed

Bad:

Tasks 1,2,3,4 → Implement all → Test all at once → Debug failures

Pattern 4: Permanent Documentation

Timely update README, API documentation, and comments:

markdown

When adding a new API endpoint, simultaneously:
- Update API documentation
- Add request/response examples
- Update OpenAPI/Swagger specification
- Add inline code comments

Advanced Topics

Parallel Work: If tasks are truly independent (e.g., different modules), they can be done in parallel, but each must be tested independently.

Integration Points: When there are dependencies, use integration tests to verify connections are valid.

Rollback Strategy: For high-risk changes, create a rollback task before deployment.

Common Patterns

Pattern 1: Database + API + UI

Typical sequence:

Database schema/migration
Data access layer (model)
Business logic layer (service)
API endpoint (controller)
UI integration
End-to-end testing

Pattern 2: Feature Flag

Progressive release:

Implement feature behind flag
Enable flag for testing
Deploy with flag disabled by default
Gradually enable flag
Remove flag after full release

Pattern 3: Breaking API Changes

For breaking API changes:

Implement new version (v2)
Keep old version (v1) running
Add deprecation notice in v1
Migrate users to v2
Submit separate proposal to remove v1

Anti-patterns to Avoid

Do NOT:

Skip testing for individual tasks
Mark task as completed before verification
Ignore failed tests (do not "fix later")
Batch merge multiple tasks before testing
Modify permanent specifications during implementation
Disrupt task order (break dependencies)

DO:

Test each task immediately
Fix failed tests before proceeding
Update TodoWrite in real-time
Clearly record blocked items
Synchronize progress with user promptly
Keep commits atomic and descriptive

Troubleshooting

Issue: Test fails after task completion

Solution:

markdown

1. Do not mark task as completed
2. Debug the cause of failure
3. Fix code
4. Re-run tests
5. Mark as completed only after passing

Issue: Task is too large

Solution:

markdown

1. Split into subtasks
2. Register subtasks in TodoWrite
3. Complete subtasks in order
4. Mark parent task as completed only after all subtasks are done

Issue: Dependencies not met

Solution:

markdown

1. Pause current task
2. Complete dependent tasks first
3. Test dependencies
4. Resume original task

References

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

Token Budget: This SKILL.md is about 350 lines, below the recommended 500-line limit.

openspec-implementation-cn

NPX Install

Tags

SKILL.md Content (Chinese)

Specification Implementation

Quick Start

Workflow

Step 1: Load and Understand the Proposal

Step 2: Set Up TodoWrite for Task Tracking

Step 3: Execute TodoWrite Tasks in Sequence

Step 4: Test and Verify Each Task

Step 5: Update Permanent Specifications (if applicable)

Step 6: Mark Proposal as Implemented

Best Practices

Pattern 1: Task Blocked

Pattern 2: Task Dependencies

Pattern 3: Incremental Testing

Pattern 4: Permanent Documentation

Advanced Topics

Common Patterns

Pattern 1: Database + API + UI

Pattern 2: Feature Flag

Pattern 3: Breaking API Changes

Anti-patterns to Avoid

Troubleshooting

Issue: Test fails after task completion

Issue: Task is too large

Issue: Dependencies not met

References