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:

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

1. **Document the discovery** in proposal.md or a notes file