OpenSpec Workflow

1. Folder Structure

openspec/
└── changes/
    └── NNNNN-name/
        ├── proposal.md
        └── tasks.md

2. Numbering

Find last number

ls openspec/changes/ | sort -r | head -1

New number

• Last number + 1
• Format: 5 digits with leading zeros
• Examples: 00001, 00027, 00128

3. proposal.md Template

# NNNNN: Change Name

## Status
PENDING | IN_PROGRESS | DEPLOYED

## Goal
What do we want to achieve?

## Scope
### Included
- Item 1
- Item 2

### Excluded
- Item 1

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Design
(Added by architect agent)

### Files to Modify
- `path/to/file1.cpp`
- `path/to/file2.h`

### New Files
- `path/to/new_file.cpp`
- `path/to/new_file.h`

### Class Diagram
(If needed)

## Notes
Additional context or decisions.

4. tasks.md Template

# Tasks for #NNNNN

## Implementation
- [ ] Task 1 description
- [ ] Task 2 description
- [ ] Task 3 description

## Testing
- [ ] Write unit tests
- [ ] Manual testing

## Documentation
- [ ] Update CHANGELOG.md
- [ ] Update ROADMAP.md (if new feature)

5. Status Lifecycle

PENDING → IN_PROGRESS → DEPLOYED

PENDING

• Proposal created
• Requirements gathered
• Waiting for design

IN_PROGRESS

• Design complete
• Implementation ongoing
• Testing ongoing

DEPLOYED

• All tasks complete
• Code reviewed
• Tests passed
• Documentation updated
• Committed to git

6. Creating a Task

1. User says "new task" or similar
2. Ask if user has an idea:
   • YES → Step 4
   • NO → Step 3
3. Read ROADMAP.md:
   • Find 3 uncompleted items [ ]
   • Propose to user
   • Wait for selection
4. Gather requirements:
   • GOAL: What to achieve?
   • SCOPE: What's in/out?
   • CRITERIA: How to verify done?
   • Ask until user says "OK" or "enough"
5. Find last OpenSpec number
6. Create folder: openspec/changes/NNNNN-name/
7. Generate proposal.md
8. Generate tasks.md
9. Report:
   • "Created OpenSpec #NNNNN"
   • "Next: architect will analyze"

7. Tracking Progress

1. Find active OpenSpec (Status = IN_PROGRESS)
2. Check tasks.md:
   • Count [x] vs [ ]
3. Report:
   • "OpenSpec #NNNNN: 4/7 tasks done"
   • "Next step: [description]"

8. Closing a Task

1. Verify completeness:
   • All checkboxes in tasks.md = [x]?
   • Code review passed?
   • Tests passed?
2. Verify documentation:
   • CHANGELOG.md has entry in [Unreleased]?
   • ROADMAP.md has checkbox [x] (if feature)?
3. If missing → report what's missing
4. If OK:
   • Change status → DEPLOYED
   • Propose commit message
   • "Task #NNNNN ready to close"