akornmeier/openspec-dev

OpenSpec Development Adapter

Converts OpenSpec change proposals into executable plans and delegates implementation to superpowers:subagent-driven-development.

Prerequisites

• Active OpenSpec change with approved proposal.md
• Populated tasks.md with tasks organized by phase
• Clean git state on main branch

Invocation

/openspec-dev <change-id> [phases]

Arguments:

• <change-id> — Required. The OpenSpec change directory name
• [phases] — Optional. Phase filter using numeric ranges (e.g., 1,3,5-7)

Examples:

• /openspec-dev add-launch-features — Execute all phases
• /openspec-dev add-launch-features 2 — Execute phase 2 only
• /openspec-dev add-launch-features 1,3-5 — Execute phases 1, 3, 4, and 5

---

Phase Filtering

When [phases] is provided, only matching phases from tasks.md are executed.

Parsing rules:

• Single number: 2 → phase 2 only
• Comma-separated: 1,3,5 → phases 1, 3, and 5
• Range with dash: 2-4 → phases 2, 3, and 4
• Mixed: 1,3-5,7 → phases 1, 3, 4, 5, and 7
• Whitespace ignored, duplicates removed, sorted ascending

Phase numbering: Phases are numbered by order in tasks.md (first ## Phase ... = 1, second = 2, etc.)

Error handling:

• Invalid phase number (doesn't exist): Warn and skip, continue with valid phases
• Phase already complete (all tasks checked): Log "Phase N: No unchecked tasks, skipping"
• Malformed input (non-numeric, zero, negative): Error with usage example

---

Workflow

Parse OpenSpec → Extract phases → Per phase: branch + subagent-driven-dev + PR

---

Step 1: Parse OpenSpec Structure

Read and extract from openspec/changes/<change-id>/:

1. proposal.md — identify phases/milestones
2. tasks.md — extract tasks, group by phase
3. Apply phase filter (if [phases] provided):
   • Parse phase numbers from argument
   • Filter to only matching phases
   • Warn for non-existent phases
   • Log and skip phases with no unchecked tasks

# Example tasks.md structure
## Phase 1: Core API
- [ ] Add user authentication endpoint
- [ ] Create data validation layer

## Phase 2: UI Components
- [ ] Build login form component
- [ ] Add dashboard layout

Extract unchecked tasks (- [ ]) grouped by their phase heading. When [phases] is specified, only process matching phases.

---

Step 2: Execute Each Phase

For each phase with unchecked tasks:

2a. Create Phase Branch

git checkout main && git pull
git checkout -b feat/<change-id>-phase-N

2b. Prepare Plan for Subagent-Driven-Development

Convert phase tasks into a plan format:

# Phase N: <Phase Name>

## Context
OpenSpec change: <change-id>
Spec reference: openspec/specs/<capability>/spec.md

## Tasks
1. <Task description from tasks.md>
2. <Task description from tasks.md>
...

2c. Invoke Subagent-Driven-Development

Follow the superpowers:subagent-driven-development workflow:

• Dispatch implementer subagent per task (sequential)
• Two-stage review: spec compliance → code quality
• Use TDD discipline throughout

The subagent-driven-development skill handles:

• Implementer prompts and self-review
• Spec compliance review
• Code quality review
• Retry loops for issues

2d. Create PR for Phase

When all phase tasks complete:

gh pr create \
  --title "feat(<change-id>): Phase N - <phase name>" \
  --body "## Summary
<bullet points of changes>

## OpenSpec Reference
- Change: openspec/changes/<change-id>/proposal.md
- Tasks: Phase N from tasks.md

## Test Coverage
<list of test files added/modified>"

---

Step 3: Sync Progress to Source tasks.md

Critical: Keep openspec/changes/<change-id>/tasks.md updated as the source of truth.

After Each Task Completes

When a task passes both reviews in subagent-driven-development:

1. Update the source file openspec/changes/<change-id>/tasks.md
2. Change - [ ] to - [x] for the completed task
3. Commit the update to the phase branch

# Example: mark task complete in source file
# In openspec/changes/add-launch-features/tasks.md:
# - [ ] Add user authentication endpoint  →  - [x] Add user authentication endpoint
git add openspec/changes/<change-id>/tasks.md
git commit -m "chore(openspec): mark task complete - <task description>"

After Phase PR Created

Add PR reference to completed tasks:

## Phase 1: Core API
- [x] Add user authentication endpoint (PR #142)
- [x] Create data validation layer (PR #142)

Why This Matters

• Resumability: If execution stops mid-phase, progress isn't lost
• Visibility: Anyone can check tasks.md to see current status
• Idempotency: Re-running the skill skips already-completed tasks (- [x])

---

Step 4: Final Report

After all phases:

## OpenSpec Development Complete: <change-id>

| Phase | Branch | PR | Status |
|-------|--------|-----|--------|
| Phase 1: Core API | feat/change-id-phase-1 | #142 | Ready |
| Phase 2: UI Components | — | — | Skipped (not in filter) |
| Phase 3: Tests | — | — | Skipped (already complete) |
| Phase 4: Docs | feat/change-id-phase-4 | #143 | Ready |

### Next Steps
- Review and merge PRs in phase order
- Run again if tasks were added or skipped

Status values:

• Ready — PR created, awaiting review
• Skipped (not in filter) — Phase excluded by [phases] argument
• Skipped (already complete) — All tasks in phase already checked

---

Integration

This skill is a thin adapter that delegates to:

| Skill | Purpose | |-------|---------| | superpowers:subagent-driven-development | Task execution, reviews, retry loops | | superpowers:test-driven-development | TDD discipline (used by implementers) | | superpowers:finishing-a-development-branch | Final cleanup if needed |

Do not duplicate the implementation/review logic from subagent-driven-development.