name: spec-driven version: 1 description: Default OpenSpec workflow - proposal → specs → design → tasks artifacts: - id: proposal generates: proposal.md description: Initial proposal document outlining the change template: proposal.md instruction: | Create the proposal document that establishes WHY this change is needed. Sections: - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now? - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**. - **Capabilities**: Identify which specs will be created or modified: - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs//spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`). - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes. - **Impact**: Affected code, APIs, dependencies, or systems. IMPORTANT: The Capabilities section is critical. It creates the contract between proposal and specs phases. Research existing specs before filling this in. Each capability listed here will need a corresponding spec file. Keep it concise (1-2 pages). Focus on the "why" not the "how" - implementation details belong in design.md. This is the foundation - specs, design, and tasks all build on this. requires: [] - id: specs generates: "specs/**/*.md" description: Detailed specifications for the change template: spec.md instruction: | Create specification files that define WHAT the system should do. Create one spec file per capability listed in the proposal's Capabilities section. - New capabilities: use the exact kebab-case name from the proposal (specs//spec.md). - Modified capabilities: use the existing spec folder name from openspec/specs// when creating the delta spec at specs//spec.md. Delta operations (use ## headers): - **ADDED Requirements**: New capabilities - **MODIFIED Requirements**: Changed behavior - MUST include full updated content - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration** - **RENAMED Requirements**: Name changes only - use FROM:/TO: format Format requirements: - Each requirement: `### Requirement: ` followed by description - Use SHALL/MUST for normative requirements (avoid should/may) - Each scenario: `#### Scenario: ` with WHEN/THEN format - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently. - Every requirement MUST have at least one scenario. MODIFIED requirements workflow: 1. Locate the existing requirement in openspec/specs//spec.md 2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios) 3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior 4. Ensure header text matches exactly (whitespace-insensitive) Common pitfall: Using MODIFIED with partial content loses detail at archive time. If adding new concerns without changing existing behavior, use ADDED instead. Example: ``` ## ADDED Requirements ### Requirement: User can export data The system SHALL allow users to export their data in CSV format. #### Scenario: Successful export - **WHEN** user clicks "Export" button - **THEN** system downloads a CSV file with all user data ## REMOVED Requirements ### Requirement: Legacy export **Reason**: Replaced by new export system **Migration**: Use new export endpoint at /api/v2/export ``` Specs should be testable - each scenario is a potential test case. requires: - proposal - id: design generates: design.md description: Technical design document with implementation details template: design.md instruction: | Create the design document that explains HOW to implement the change. When to include design.md (create only if any apply): - Cross-cutting change (multiple services/modules) or new architectural pattern - New external dependency or significant data model changes - Security, performance, or migration complexity - Ambiguity that benefits from technical decisions before coding Sections: - **Context**: Background, current state, constraints, stakeholders - **Goals / Non-Goals**: What this design achieves and explicitly excludes - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision. - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation - **Migration Plan**: Steps to deploy, rollback strategy (if applicable) - **Open Questions**: Outstanding decisions or unknowns to resolve Focus on architecture and approach, not line-by-line implementation. Reference the proposal for motivation and specs for requirements. Good design docs explain the "why" behind technical decisions. requires: - proposal - id: tasks generates: tasks.md description: Implementation checklist with trackable tasks template: tasks.md instruction: | Create the task list that breaks down the implementation work. **IMPORTANT: Follow the template below exactly.** The apply phase parses checkbox format to track progress. Tasks not using `- [ ]` won't be tracked. Guidelines: - Group related tasks under ## numbered headings - Each task MUST be a checkbox: `- [ ] X.Y Task description` - Tasks should be small enough to complete in one session - Order tasks by dependency (what must be done first?) Example: ``` ## 1. Setup - [ ] 1.1 Create new module structure - [ ] 1.2 Add dependencies to package.json ## 2. Core Implementation - [ ] 2.1 Implement data export function - [ ] 2.2 Add CSV formatting utilities ``` Reference specs for what needs to be built, design for how to build it. Each task should be verifiable - you know when it's done. requires: - specs - design apply: requires: [tasks] tracks: tasks.md instruction: | Read context files, work through pending tasks, mark complete as you go. Pause if you hit blockers or need clarification.