| name | OpenSpec Workflow |
| description | Spec-driven development workflow — proposals, requirements, design docs, task breakdowns, and implementation using the OpenSpec framework.
Use when: Starting a new feature or change that needs planning, someone says "I want to build X", creating proposals or specs, breaking down requirements into tasks, or transitioning from planning to implementation.
Don't use when: Debugging or troubleshooting (use appropriate troubleshooting skill). Don't use for Kubernetes manifest changes (use pr-workflow). Don't use for reviewing existing code (use code-review).
Outputs: OpenSpec change folder with proposal.md, specs/, design.md, and tasks.md. Implementation follows directly from tasks.md.
|
| requires | [] |
OpenSpec Skill
Document templates and workflow patterns for spec-driven development.
Routing
Use This Skill When
- Starting a new feature or change that needs planning
- Someone says "I want to build X" or "let's add Y"
- Creating proposals, requirements, or design documents
- Breaking down a feature into implementable tasks
- Transitioning from planning to implementation
- Running
/opsx:new, /opsx:ff, /opsx:apply, or /opsx:archive
Don't Use This Skill When
- Debugging a runtime issue -> use the appropriate troubleshooting skill
- Changing Kubernetes manifests -> use pr-workflow (dyson)
- Reviewing a PR -> use code-review
- The task is small enough to just do without a spec -> skip planning
Philosophy
OpenSpec is built on these principles:
> fluid not rigid
> iterative not waterfall
> easy not complex
> built for brownfield not just greenfield
> scalable from personal projects to enterprises
Key insight: Actions, not phases. Commands are things you can do, not stages you're stuck in.
Workflow Commands
/opsx:new
Creates a new change folder structure:
openspec/changes/<change-name>/
├── proposal.md # Why we're doing this
├── specs/ # Requirements and scenarios
│ ├── requirements.md
│ └── scenarios.md
├── design.md # Technical approach
├── tasks.md # Implementation checklist
└── .state # Current workflow state
When to use: Starting any new change, feature, or fix.
/opsx:ff (fast-forward)
Generates all planning documents in sequence:
- Creates
proposal.md — captures the "why"
- Creates
specs/ requirements and scenarios
- Creates
design.md — technical approach
- Creates
tasks.md — implementation breakdown
- Sets state to "ready for implementation"
When to use: Requirements are clear enough to plan the full scope.
/opsx:apply
Signals ready for implementation. Planning is complete; proceed with implementation from tasks.md.
Context available:
- Path to
tasks.md
- Path to
specs/ for reference
- Path to
design.md for technical context
- Any risks or gotchas discovered
When to use: Planning is complete and approved by Raj.
/opsx:archive
Moves completed change to archive:
openspec/changes/archive/YYYY-MM-DD-<change-name>/
Updates any merged specs in the main documentation.
When to use: Implementation is complete and change is merged.
Document Templates
proposal.md
# Proposal: <Change Title>
## Problem
What's the current situation? What problem are we solving?
## Solution
What are we proposing to do?
## Success Criteria
How do we know this worked?
- [ ] Criterion 1
- [ ] Criterion 2
## Alternatives Considered
| Alternative | Why Not Selected |
|-------------|------------------|
| Option A | Reason it was rejected |
| Option B | Reason it was rejected |
## Scope
### In Scope
- Thing 1
- Thing 2
### Out of Scope
- Thing that sounds related but isn't included
- Future enhancements
## Risks
| Risk | Mitigation |
|------|------------|
| Risk description | How we'll handle it |
specs/requirements.md
# Requirements: <Change Title>
## Functional Requirements
| ID | Requirement | Priority | Acceptance Criteria |
|----|-------------|----------|---------------------|
| FR-1 | System shall do X | Must | Can verify by... |
| FR-2 | System shall do Y | Should | Can verify by... |
## Non-Functional Requirements
| ID | Requirement | Target |
|----|-------------|--------|
| NFR-1 | Performance: operation completes within | 100ms |
| NFR-2 | Compatibility: works with | existing API |
## Constraints
- Must work with existing architecture
- Must not break backward compatibility
- Must follow existing patterns in codebase
specs/scenarios.md
# Scenarios: <Change Title>
## Happy Path
**Given** initial state
**When** user action
**Then** expected result
## Edge Cases
### Edge Case 1: <Description>
**Given** unusual but valid state
**When** user action
**Then** expected handling
### Edge Case 2: <Description>
...
## Error Scenarios
| Scenario | Trigger | Expected Behavior |
|----------|---------|-------------------|
| Invalid input | Malformed request | Return 400 with specific error |
| Dependency down | Service unavailable | Return 503, retry logic |
design.md
# Design: <Change Title>
## Overview
High-level approach: what components change and how.
## Architecture
[Diagram or description of component interactions]
### Component A
- Responsibility
- Interface changes
- Dependencies
### Component B
...
## Data Flow
1. Step 1
2. Step 2
3. Step 3
## Dependencies
| Dependency | What we need from it |
|------------|---------------------|
| Package X | Version bump, new API |
| Service Y | Endpoint available |
## Migration Plan
If this changes existing behavior:
1. Phase 1: Deploy X
2. Phase 2: Migrate Y
3. Phase 3: Clean up Z
## Testing Strategy
- Unit tests for: component A, component B
- Integration tests for: end-to-end flow
- Manual verification: specific scenario
tasks.md
# Tasks: <Change Title>
## Task Group 1: <Descriptive Name>
- [ ] 1.1 Task description
- Notes: implementation context
- Files: relevant files to modify
- Tests: what to verify
- [ ] 1.2 Task description
- Depends on: 1.1
- Notes: implementation hints
## Task Group 2: <Descriptive Name>
- [ ] 2.1 Task description
- Notes: specific considerations
- Edge case: handle X
## Verification
- [ ] All acceptance criteria from proposal.md met
- [ ] All scenarios from specs/scenarios.md pass
- [ ] Code review completed
- [ ] Tests passing
Pattern from Landlord
Landlord demonstrates spec-driven infrastructure patterns applicable to software:
- Declarative desired state — specs say what should be, not how
- Workflow orchestration — clear steps from spec to reality
- State reconciliation — actual state vs desired state
- Pluggable backends — designs that allow future flexibility
Apply to planning documents:
specs/ = declarative desired state (what the system should do)tasks.md = workflow orchestration (steps to get there)design.md = state reconciliation model (how we track progress)- Implementation approach can vary based on context
Working with Raj
Typical flow:
- Raj says: "I want to add dark mode"
- Leon asks: "Scope questions..."
- Leon runs:
/opsx:new add-dark-mode
- Leon runs:
/opsx:ff -> generates all docs
- Raj reviews and approves
- Leon runs:
/opsx:apply -> proceeds with implementation
- Leon implements from
tasks.md
- Leon runs:
/opsx:archive when complete
Brownfield considerations:
- Always check existing patterns in codebase
- Note any migration steps in design.md
- Highlight compatibility concerns in risks
- Reference existing implementations when relevant
Command Quick Reference
| Command | Creates/Updates | State After |
|---|
/opsx:new | Change folder structure | proposal pending |
/opsx:ff | proposal, specs, design, tasks | ready for implementation |
/opsx:apply | Transitions to implementation | in progress |
/opsx:archive | Archive folder | complete |
Edge Cases
- Scope creep during planning: If requirements keep expanding, pause and re-scope with Raj before continuing
- Brownfield conflicts: If the proposed design conflicts with existing architecture, document the conflict in design.md and flag it
- Multiple concurrent changes: Each change gets its own folder — don't mix changes in the same spec
Compaction Notes
For long planning sessions:
mkdir -p /tmp/outputs before writing any artifacts- Write each document (proposal, specs, design, tasks) to disk as you go
- The OpenSpec folder structure itself serves as persistent state — commit early
