openspec-implementation-cn

Original：🇨🇳 Chinese
Translated

Execute and implement approved specification proposals in sequence with testing and verification as the priority. It is used for implementing changes, applying proposals, executing specification tasks, or building according to approved plans. Trigger words include "openspec development", "development", "implementation", "implement proposal", "apply change", "execute specification", "complete tasks in order", "build feature", "start implementation"

30installs
Sourceforztf/open-skilled-sdd
Added on

NPX Install

npx skill4agent add forztf/open-skilled-sdd openspec-implementation-cn

Tags

Translated version includes tags in frontmatter
specification-implementationtask-trackingtest-verificationworkflow-managementtodowrite-usage

SKILL.md Content (Chinese)

View Translation Comparison →

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:
  1. Read the complete proposal and task list
  2. Execute tasks one by one in order
  3. Test each completed task
  4. 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:
  1. Record findings in proposal.md or a note file
  2. Do not modify specification differences during implementation
  3. 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:
  1. Database schema/migration
  2. Data access layer (model)
  3. Business logic layer (service)
  4. API endpoint (controller)
  5. UI integration
  6. End-to-end testing

Pattern 2: Feature Flag

Progressive release:
  1. Implement feature behind flag
  2. Enable flag for testing
  3. Deploy with flag disabled by default
  4. Gradually enable flag
  5. Remove flag after full release

Pattern 3: Breaking API Changes

For breaking API changes:
  1. Implement new version (v2)
  2. Keep old version (v1) running
  3. Add deprecation notice in v1
  4. Migrate users to v2
  5. 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.