Spec Develop

OpenSpec Apply (Task Execution)

Guide for implementing code changes driven by tasks.md.

Input Files

| File | Purpose | Action | |------|---------|--------| | {specs_path}/tasks.md | Implementation checklist | Read, execute, mark done | | {specs_path}/design.md | Architecture decisions | Reference during implementation | | {specs_path}/proposal.md | Context and motivation | Reference if unclear on intent |

Path Enforcement: The specs_path MUST be .scaffolding/conversations/{UUID}/specs/ where {UUID} is a valid UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). NEVER use descriptive folder names.

Execution Protocol

Step 1: Read tasks.md

Parse all task groups and checkboxes. Identify dependency order.

Step 2: Execute tasks in order

For each task (- [ ] N.M description):

1. Read the task description and target file path
2. Check design.md for relevant requirements and decisions
3. Implement the change following project patterns
4. Mark complete: change - [ ] to - [x]

Step 3: Run validation after each group

| Stack | Validation Command | |-------|--------------------| | Backend | pytest | | Frontend | npm run validate | | Both | Run both commands |

Step 4: Handle blockers

If a task cannot be completed:

- [ ] 2.3 Implement caching layer
  > BLOCKED: Redis connection config not yet available. Depends on devops setup.

Continue with unblocked tasks. Do not stop the entire chain.

Rules

| Rule | Detail | |------|--------| | Execute in order | Respect dependency sequence | | Mark progress | - [ ] -> - [x] as you complete | | Reference design | Check design.md before implementing | | Never modify specs | Only modify tasks.md checkboxes, never change spec content | | Validate per group | Run tests after each task group | | Note blockers | Add > BLOCKED: note, skip and continue | | Search before write | Check core/utils/, core/exceptions.py before creating helpers |

Progress Tracking

Checkpoint format in tasks.md

## 2. Core Implementation

- [x] 2.1 Implement service in `./backend/service.py`
- [x] 2.2 Add Pydantic schemas in `./backend/schemas.py`
- [ ] 2.3 Add router in `./backend/router.py`
  > BLOCKED: Waiting for auth middleware decision
- [x] 2.4 Run validation: `pytest`

Resuming after interruption

If tasks.md has some [x] items already:

1. Skip completed tasks
2. Resume from first unchecked - [ ]
3. Re-read design.md for context on remaining work

Integration with Design Decisions

When design.md specifies a technical choice, follow it:

| Design says | You do | |-------------|--------| | "Use Repository pattern" | Create repository class, not inline queries | | "Use Pydantic v2 model_validator" | Use @model_validator, not @validator | | "Max 500 lines per file" | Split if approaching limit | | "Existing utility in core/utils" | Import it, do not recreate |

Anti-Patterns

| Avoid | Instead | |-------|---------| | Skipping validation steps | Run tests after every group | | Modifying design.md content | Only reviewer or planner changes specs | | Implementing out of order | Follow dependency sequence | | Ignoring blocked tasks silently | Add explicit > BLOCKED: note | | Creating duplicate utilities | Search core/ first |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: komluk
• Source: komluk/scaffolding
• License: MIT

Install and usage instructions live in the source repository linked above.