pi-config/extensions/openspec/schemas/spec-driven/schema.yaml

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/<name>/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/<capability>/spec.md).
      - Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/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: <name>` followed by description
      - Use SHALL/MUST for normative requirements (avoid should/may)
      - Each scenario: `#### Scenario: <name>` 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/<capability>/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.