1  # OpenSpec: Instructions for AI Agents
  2  
  3  This document explains how AI agents should read, write, and maintain OpenSpec specification files. All agents in the harness must follow these conventions.
  4  
  5  ## What is OpenSpec?
  6  
  7  OpenSpec is a lightweight specification format designed for AI-agent workflows. It provides a single source of truth for what a system should do (requirements), how to verify it (scenarios), and what has actually been built (implementation status). Every line of code traces back to a spec, and every spec traces forward to tests.
  8  
  9  ## Directory Structure
 10  
 11  ```
 12  openspec/
 13    project.md              # Project-wide conventions (naming, coding standards)
 14    AGENTS.md               # This file -- instructions for AI agents
 15    capabilities/
 16      {capability-name}/
 17        spec.md             # Requirements and scenarios
 18        design.md           # Technical design (how to build it)
 19    change-proposals/
 20      {proposal-id}.md      # Proposed changes to existing specs
 21  ```
 22  
 23  ## Spec File Structure (spec.md)
 24  
 25  Every capability has a `spec.md` with this structure:
 26  
 27  ```markdown
 28  # Capability: {{Name}}
 29  
 30  **Version**: {{semver}}
 31  **Status**: Draft | Active | Deprecated
 32  **Last Updated**: {{ISO date}}
 33  **Owner**: {{agent or human}}
 34  
 35  ## Overview
 36  {{Brief description of what this capability does}}
 37  
 38  ## Requirements
 39  
 40  ### REQ-{{CAP}}-{{NNN}}: {{Title}}
 41  - **Priority**: MUST | SHOULD | MAY
 42  - **Status**: SPECIFIED | IMPLEMENTED | PARTIALLY_IMPLEMENTED | DEFERRED
 43  - **Description**: {{What the system must do}}
 44  - **Rationale**: {{Why this requirement exists}}
 45  
 46  ## Scenarios
 47  
 48  ### SCENARIO-{{CAP}}-{{FLOW}}-{{NNN}}: {{Title}}
 49  - **Priority**: CRITICAL | NORMAL
 50  - **References**: REQ-{{CAP}}-{{NNN}}
 51  - **Preconditions**: {{What must be true before this scenario}}
 52  
 53  **Given** {{initial context}}
 54  **When** {{action or event}}
 55  **Then** {{expected outcome}}
 56  
 57  ## Implementation Status
 58  
 59  | REQ ID | Status | Test Coverage | Notes |
 60  |--------|--------|---------------|-------|
 61  | REQ-{{CAP}}-001 | IMPLEMENTED | tests/test_{{cap}}.py | |
 62  
 63  ## Change History
 64  
 65  | Date | Change | Rationale |
 66  |------|--------|-----------|
 67  | {{date}} | {{what changed}} | {{why}} |
 68  ```
 69  
 70  ## Naming Conventions
 71  
 72  ### Requirement IDs: REQ-{CAP}-{NNN}
 73  
 74  - `{CAP}`: Short uppercase abbreviation for the capability (e.g., AUTH, DASH, SYNC)
 75  - `{NNN}`: Three-digit sequential number, zero-padded (001, 002, ...)
 76  - Examples: `REQ-AUTH-001`, `REQ-DASH-012`, `REQ-SYNC-003`
 77  
 78  ### Scenario IDs: SCENARIO-{CAP}-{FLOW}-{NNN}
 79  
 80  - `{CAP}`: Same abbreviation as the capability
 81  - `{FLOW}`: Short uppercase name for the user flow or feature area (e.g., LOGIN, EXPORT, FILTER)
 82  - `{NNN}`: Three-digit sequential number
 83  - Examples: `SCENARIO-AUTH-LOGIN-001`, `SCENARIO-DASH-FILTER-003`
 84  
 85  ### Design Decision IDs: ADR-{NNN}
 86  
 87  - Sequential across the project
 88  - Examples: `ADR-001`, `ADR-015`
 89  
 90  ### Story IDs: STORY-{EPIC}-{NNN}
 91  
 92  - `{EPIC}`: Short uppercase abbreviation for the epic
 93  - `{NNN}`: Three-digit sequential number
 94  - Examples: `STORY-AUTH-001`, `STORY-ONBOARD-003`
 95  
 96  ## How to Read Specs (All Agents)
 97  
 98  ### Finding Relevant Specs
 99  1. Check `openspec/capabilities/` for capability directories
100  2. Read the `spec.md` in each relevant capability directory
101  3. Use REQ-* IDs as stable references -- they do not change once assigned
102  4. Check Implementation Status to understand what is built vs. planned
103  
104  ### Understanding Priority
105  - **MUST** requirements: Non-negotiable. The system is broken without them.
106  - **SHOULD** requirements: Expected in a complete implementation. May be deferred with rationale.
107  - **MAY** requirements: Nice-to-have. Implement if time permits.
108  
109  - **CRITICAL** scenarios: Must pass for a sprint to succeed. Zero tolerance for failure.
110  - **NORMAL** scenarios: Must pass at the configured threshold rate (typically 90%).
111  
112  ### Cross-referencing
113  - Every SCENARIO-* references one or more REQ-* items
114  - Every REQ-* should have at least one SCENARIO-* that tests it
115  - Stories reference the REQ-* items they implement
116  - Test files reference the SCENARIO-* items they verify
117  
118  ## How to Write Specs (Planner, Architect)
119  
120  ### Creating a New Capability Spec
121  
122  1. Create directory: `openspec/capabilities/{capability-name}/`
123  2. Create `spec.md` following the structure above
124  3. Assign REQ-* IDs sequentially starting from 001
125  4. Write at least one SCENARIO-* for each REQ-*
126  5. Set all Implementation Status to SPECIFIED
127  6. Set spec status to Draft
128  
129  ### Rules for Writing Requirements
130  
131  - **One requirement, one concern**: Do not combine "system shall authenticate users AND log all access attempts" into one REQ. Split them.
132  - **Testable**: A requirement must be verifiable. "System should be fast" is not testable. "System responds within 200ms for 95th percentile" is.
133  - **Unambiguous**: Avoid "should handle errors gracefully." Specify WHAT errors and WHAT handling.
134  - **Traced**: Every REQ must have a rationale connecting it to a user need or business goal.
135  
136  ### Rules for Writing Scenarios
137  
138  - **Given/When/Then format**: Always. No exceptions.
139  - **Specific**: Include concrete values, not vague descriptions. "Given a user with email 'test@example.com'" not "Given a user."
140  - **Independent**: Each scenario should be verifiable without depending on other scenarios running first.
141  - **Complete**: Cover happy path, error paths, edge cases, and boundary conditions.
142  - **Prioritized**: Mark scenarios that are essential for basic functionality as CRITICAL. Mark nice-to-have verifications as NORMAL.
143  
144  ### Modifying an Existing Spec
145  
146  Never modify a published spec directly without a change proposal. The process:
147  
148  1. Create `openspec/change-proposals/{CP-NNN}.md`:
149  
150  ```markdown
151  # Change Proposal: CP-{{NNN}}
152  
153  **Date**: {{ISO date}}
154  **Author**: {{agent name}}
155  **Affects**: {{list of spec files}}
156  **Status**: Proposed | Accepted | Rejected
157  
158  ## Motivation
159  {{Why this change is needed}}
160  
161  ## Changes
162  
163  ### Modified Requirements
164  - REQ-{{CAP}}-{{NNN}}: {{current text}} -> {{proposed text}}
165    - Rationale: {{why}}
166  
167  ### New Requirements
168  - REQ-{{CAP}}-{{NNN}}: {{proposed text}}
169    - Rationale: {{why}}
170  
171  ### Removed Requirements
172  - REQ-{{CAP}}-{{NNN}}: {{current text}}
173    - Rationale: {{why removing}}
174  
175  ### Modified Scenarios
176  {{Same pattern as requirements}}
177  
178  ### New Scenarios
179  {{Same pattern}}
180  
181  ## Impact Analysis
182  - Code changes required: {{list affected files/components}}
183  - Test changes required: {{list affected test files}}
184  - Other specs affected: {{list}}
185  ```
186  
187  2. Apply the changes to the spec after the change proposal is accepted (by the harness or user)
188  
189  **Exception**: The Generator may update Implementation Status directly without a change proposal, since this reflects reality, not a change in intent.
190  
191  ## The Reconciliation Protocol
192  
193  Specs and code must always agree. When they diverge:
194  
195  ### Code Diverges from Spec (Generator finds spec is wrong or impractical)
196  
197  1. Implement what actually works
198  2. Update the spec to match the implementation
199  3. Add a Change History entry with rationale: "Implementation revealed that X was not feasible because Y. Updated to Z."
200  4. Flag in the handoff file so the Evaluator knows
201  
202  ### Spec Diverges from Code (Evaluator finds code does not match spec)
203  
204  1. The Evaluator flags this as a spec fidelity issue
205  2. The Generator must either:
206     a. Fix the code to match the spec, OR
207     b. Update the spec with a rationale explaining why the code is correct
208  3. Option (b) requires a change proposal for non-trivial divergences
209  
210  ### The Cardinal Rule
211  
212  **Never leave specs and code disagreeing silently.** If they disagree, someone must explicitly reconcile them with documented rationale. Silent divergence is the number one failure mode of spec-anchored development.
213  
214  ## Traceability Chain
215  
216  The full traceability chain is:
217  
218  ```
219  User Need
220    -> PRD (product-brief.md, prd.md)
221      -> REQ-* (spec.md)
222        -> SCENARIO-* (spec.md)
223          -> Story (epics/stories/)
224            -> Test (tests/)
225              -> Implementation (src/)
226                -> Implementation Status (spec.md)
227  ```
228  
229  Every link in this chain should be navigable in both directions. If you cannot trace a piece of code back to a REQ-*, or a REQ-* forward to a test, the chain is broken and must be repaired.
230  
231  ## Quick Reference for Each Agent
232  
233  | Agent | Reads Specs? | Writes Specs? | Key Action |
234  |-------|-------------|---------------|------------|
235  | Discovery | Yes (for context) | No | Understands existing capabilities |
236  | Planner | Yes | Yes (new specs, change proposals) | Creates REQ-* and SCENARIO-* |
237  | Architect | Yes | Yes (design.md only) | Designs how to implement REQ-* |
238  | Design | Yes (for context) | No | Uses SCENARIO-* to define UX flows |
239  | Generator | Yes | Yes (Implementation Status only) | Implements REQ-*, tests SCENARIO-* |
240  | Evaluator | Yes | No (writes evaluations, not specs) | Verifies SCENARIO-*, checks fidelity |