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`. Name each capability for a durable system behavior (for example, `user-auth`), not the work in this change (for example, `add-login-endpoint`). Choose a cohesive boundary that can own related requirements as the system evolves; avoid broad catch-all capabilities. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization. - **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. Use the exact existing path under `openspec/specs/`. 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: run `openspec list --specs` for the project's capability inventory, then `openspec show "" --type spec --json --no-scenarios` for any that look related - that returns a capability's purpose and requirement texts without pulling whole spec files into context. Append `--store ""` to both commands only for a registered standalone store, and keep `--type spec`: a change and a spec sharing a name is otherwise an ambiguous-item error. `openspec list` without `--specs` lists in-flight changes, not specs - it never shows what the project already covers. Reuse an existing capability's exact path instead of introducing a near-duplicate name. The filtered read is only an overview. Before deciding what is already covered or what should change, read each relevant spec in full, including scenarios, with `openspec show "" --type spec` (same `--store` rule). Each capability listed here will need a corresponding spec file. Every change must either declare at least one capability (new or modified) or explicitly opt out of specs: `openspec validate` rejects a change with zero deltas unless the change's `.openspec.yaml` sets `skip_specs: true`. Use `skip_specs: true` only when no spec-level behavior changes (pure refactor, tooling, docs) - specs describe behavior, so if behavior does not change, no spec should change either. Do not invent a requirement just to satisfy validation. 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. A spec is a behavior contract, not an implementation plan. Good spec content: - Observable behavior users or downstream systems rely on - Inputs, outputs, and error conditions - External constraints (security, privacy, reliability, compatibility) - Scenarios that can be tested or explicitly validated Avoid in specs: - Internal class/function names - Library or framework choices - Step-by-step implementation details - Detailed execution plans (those belong in design.md or tasks.md) Quick test: if the implementation can change without changing externally visible behavior, it likely does not belong in the spec. Create one spec file per capability listed in the proposal's Capabilities section. `` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path: - New capabilities: use the exact path from the proposal at `specs//spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout. - Modified capabilities: use the exact existing path from `openspec/specs//` when creating the delta at `specs//spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store ""` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability. Write the spec files one at a time, so the user sees progress and an interrupted run keeps the files it already wrote: - Before writing anything, compare the capabilities the proposal lists with the `specs//spec.md` files that already exist, and start with the first capability that has no file. Do not rewrite an existing file unless the user asks you to. - Before each file, say in one line which capability you are writing. - Write each file as soon as you have drafted it. Do not plan every file before writing the first. - Stop when every capability the proposal lists has its file. There must be at least one spec file unless the change's `.openspec.yaml` sets `skip_specs: true` (no spec-level behavior change) - `openspec validate` rejects a zero-delta change without that marker. If the proposal lists no capabilities and `skip_specs` is not set, revisit the proposal first. 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. - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios. New capabilities only: the delta spec's first section is `## Purpose` - one or two sentences (50+ characters, or `openspec validate --strict` reports it as too brief) describing what the capability is for. Archive copies it into the main spec it creates; without it the new main spec is left with a `TBD ... Update Purpose after archive` placeholder to fill in by hand. Do NOT add `## Purpose` to a delta for an existing capability - that spec already has one and the delta's is ignored. To change an existing capability's Purpose - including a leftover `TBD` placeholder - edit `/openspec/specs//spec.md` directly. `planningHome.root` comes from the `openspec instructions ... --json` response. Always use it rather than a repo-relative path: it resolves to the store whenever the change lives in one - whether that came from `--store`, a project `store:` pointer, or a global default store - and to the current repository otherwise. Do not try to work out which case applies; the field already has. MODIFIED requirements workflow: 1. Locate the existing requirement in `/openspec/specs//spec.md` (the same store-aware root as above) 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 (a new capability, so its first section is `## Purpose`): ``` # Spec Delta ## Purpose Lets users take their data out of the product in a portable format. ## 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**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why"). - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries. - **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**: Unknowns that can safely be answered later without changing the specs, the approach, or the task breakdown. Omit if none. Open questions are for genuinely deferrable unknowns, not decisions you skipped. If a question would change the specs, the chosen approach, or the task breakdown, resolve it now - ask the user instead of guessing. Focus on architecture and approach, not line-by-line implementation. The proposal covers why and what; design covers how. Reference the proposal for motivation and, once written, the specs for requirements - if a section would only restate them, point to them instead. 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. Before writing tasks, check design.md for Open Questions. If any of them would change what gets built, resolve them with the user first - do not bake an unstated assumption into the task list. **IMPORTANT: Follow the template below for tracked tasks.** The apply phase parses checkbox format to track progress. A box holding only `x` counts as done, upper or lower case and with any spacing, so `- [ x]` is done too. Every other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as unfinished. A line with no checkbox is not tracked at all. Guidelines: - Group related tracked tasks under ## numbered headings - Each tracked 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?) - Track implementation and verification work that can be completed before archive. If the requested workflow includes archive or work that requires this change to be archived, preserve those steps as plain bullets in an optional `## Workflow follow-up` section at the end of tasks.md. These bullets are reference information outside tracked task progress. - Each task MUST state how to verify completion (a test, command, observable behavior, or delivered artifact). Put the verification in that task's checkbox description. Use a separate verification task only when it checks broader integration or system behavior that spans multiple implementation tasks. - Each task group MUST land the tests and documentation its own work calls for. Do NOT collect testing or documentation into a final group - when a late group first exercises work from an early one, the failures cascade back through every group in between and force rework. A group whose work calls for neither, such as scaffolding or dependency setup, carries neither. A final group is for integration checks only, not for the tests and docs an earlier group owed. Example: ``` # Tasks ## 1. Setup - [ ] 1.1 Create new module structure and verify expected files are present - [ ] 1.2 Add dependencies to package.json and verify package installation succeeds ## 2. Core Implementation - [ ] 2.1 Implement data export function and verify the export test passes - [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters - [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written ``` When applicable, append workflow follow-up as plain bullets, for example: ``` ## Workflow follow-up - Archive the change after the project's review requirements are satisfied. - Verify the archived result. ``` Reference specs for what needs to be built, design for how to build it. 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.

Specifications