name: review-gated version: 1 description: OpenSpec workflow - proposal → specs/design → tasks → apply 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 and WHAT changes at a high level. A proposal is a logical, objective approval artifact. It should persuade by clearly defining the problem/opportunity, proposed outcome, scope, and impact. It is not a design document, implementation plan, research log, roadmap, or retrospective. The generated document MUST NOT contain hedging language. If information is uncertain, record it as an explicit open question or blocker instead of weakening the language. Sections: - **Why**: State the problem, opportunity, motivation, and expected benefit. Include only the background needed to understand why this change is worth doing now. - **What Changes**: Describe the high-level WHAT: new, modified, or removed behavior/capabilities; proposal-level goals/outcomes; scope boundaries; explicit non-goals or limitations when they prevent ambiguity. Mark breaking changes with **BREAKING**. - **Capabilities**: Identify which existing specs will be modified or which genuinely new capability specs are needed: - Check `openspec/specs/` for existing capability names before creating new ones. Reuse an existing capability when the behavior belongs to an existing concept; do not create overlapping specs for the same behavior. - **New Capabilities**: List only capabilities that introduce a distinct new product/domain concept not covered by an existing spec. Each becomes a new `specs//spec.md`. Use kebab-case capability names (e.g., `user-auth`, `data-export`), not the change name. - **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. Leave empty if no requirement changes. - **Impact**: Affected users, code, APIs, dependencies, systems, compatibility, operations, risks, constraints, caveats, or open questions at proposal level. 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 WHY and high-level WHAT, not HOW. Detailed architecture, API design, task breakdown, tests, CI, and implementation mechanics belong in downstream artifacts. The proposal must be void of extra narrative. Do not include research chronology, discovery process, rejected investigation paths, agent reasoning, broad history, unrelated roadmap, or retrospective content just to make the document feel like a cohesive story. This is the foundation - specs, design, and tasks all build on this. requires: [] - id: design generates: design.md description: Technical design document with implementation details template: design.md instruction: | Create the design document that explains the chosen HOW and why it is the right trade-off for this change. The generated document MUST NOT contain hedging language. If information is uncertain, record it as an explicit open question or blocker instead of weakening the language. Include design.md when any apply: - Cross-cutting change (multiple services/modules) or new architectural pattern - New external dependency or significant data model changes - Security, performance, reliability, observability, migration, or operational complexity - Ambiguity that benefits from technical decisions before coding Ground the design in completed planning artifacts: - Use proposal.md for motivation, scope, non-goals, and impact. - Use specs/**/*.md for required behavior and acceptance scenarios. - Every major design element should trace to a proposal goal, spec requirement, constraint, or quality goal. Sections: - **Context**: Current state, relevant constraints, stakeholders/affected systems, and the narrow background needed to understand the design. Avoid broad historical narrative. - **Goals / Non-Goals**: What this design achieves and explicitly excludes. - **Solution Strategy**: The high-level approach, key abstractions, top-level decomposition, and why this shape fits the goals and constraints. - **Components / Interfaces**: Modules, services, boundaries, APIs, contracts, data/state model, and important integration points where relevant. - **Runtime / Operational View**: Important flows, failure paths, concurrency/state transitions, deployment/operational behavior, observability, and supportability where relevant. - **Migration Plan**: Deployment steps, data/backfill needs, rollout, rollback, compatibility/version-skew, and recovery plan if applicable. - **Decisions**: Key technical choices with rationale, trade-offs, and credible alternatives considered. - **Quality / Cross-Cutting Concerns**: Reliability, security, privacy, performance, observability, maintainability, compatibility, and scalability where relevant. - **Risks / Trade-offs**: Known limitations, assumptions, technical debt, and mitigations. - **Open Questions**: Outstanding decisions or unknowns to resolve before or during implementation. Focus on architecture and approach, not line-by-line implementation. Include enough detail for implementers, reviewers, operators, and future maintainers to build, review, test, operate, and understand the design without rediscovering major decisions. Good design docs explain the "why" behind technical decisions and preserve decision memory. requires: - proposal - id: specs generates: "specs/**/*.md" description: Detailed specifications for the change template: spec.md instruction: | Create OpenSpec scenario-based delta specifications that define WHAT observable behavior changes. The generated document MUST NOT contain hedging language. If information is uncertain, record it as an explicit open question or blocker instead of weakening the language. 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. - Do not create orphan spec files for capabilities not named in the proposal unless the proposal is first updated. Requirements quality: - Each requirement must be necessary and traceable to the proposal/user intent or an existing accepted spec change. - Each requirement should be singular, unambiguous, complete enough, consistent, feasible, and bounded to this change. - Requirements describe externally observable behavior or constraints, not internal architecture, implementation mechanics, task steps, or test/CI procedure. - Use SHALL/MUST for normative requirements; avoid should/may, vague adjectives, aspiration, or subjective success language. - Unresolved behavior questions are not requirements. Mark them as open questions/blockers instead of encoding ambiguity. Scenario quality: - Every requirement MUST have at least one scenario. - Each scenario MUST use exactly 4 hashtags: `#### Scenario: `. Using 3 hashtags or bullets will fail silently. - Scenarios use concrete WHEN/THEN examples: clear trigger/precondition and observable expected outcome. - Scenarios are acceptance-test seeds. A reviewer should be able to derive concrete tests from them. - Cover important success, failure, permission/security, boundary, edge, compatibility, and migration cases where relevant. - Keep the scenario set efficient: avoid duplicate scenarios that prove the same rule. Delta operations (use ## headers): - **ADDED Requirements**: New capabilities or new behavior/rules. - **MODIFIED Requirements**: Changed existing behavior - MUST include full updated content. - **REMOVED Requirements**: Deprecated behavior - MUST include **Reason** and **Migration**. - **RENAMED Requirements**: Name changes only - use FROM:/TO: format. 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. Keep specs void of extra narrative. Do not include research chronology, design rationale, roadmap, retrospective, task planning, tests/CI detail, or implementation mechanics. 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 acceptance test case. 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. The generated document MUST NOT contain hedging language. If information is uncertain, record it as an explicit open question or blocker instead of weakening the language. **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.