openspecui 0.0.0

package/references/openspec/openspec/changes/archive/2025-08-19-bulk-validation-interactive-selection/specs/cli-validate/spec.md

@@ -0,0 +1,149 @@
+# CLI Validate Command Spec
+
+## ADDED Requirements
+
+### Requirement: Top-level validate command
+
+The CLI SHALL provide a top-level `validate` command for validating changes and specs with flexible selection options.
+
+#### Scenario: Interactive validation selection
+
+- **WHEN** executing `openspec validate` without arguments
+- **THEN** prompt user to select what to validate (all, changes, specs, or specific item)
+- **AND** perform validation based on selection
+- **AND** display results with appropriate formatting
+
+#### Scenario: Non-interactive environments do not prompt
+
+- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
+- **WHEN** executing `openspec validate` without arguments
+- **THEN** do not prompt interactively
+- **AND** print a helpful hint listing available commands/flags and exit with code 1
+
+#### Scenario: Direct item validation
+
+- **WHEN** executing `openspec validate <item-name>`
+- **THEN** automatically detect if item is a change or spec
+- **AND** validate the specified item
+- **AND** display validation results
+
+### Requirement: Bulk and filtered validation
+
+The validate command SHALL support flags for bulk validation (--all) and filtered validation by type (--changes, --specs).
+
+#### Scenario: Validate everything
+
+- **WHEN** executing `openspec validate --all`
+- **THEN** validate all changes in openspec/changes/ (excluding archive)
+- **AND** validate all specs in openspec/specs/
+- **AND** display a summary showing passed/failed items
+- **AND** exit with code 1 if any validation fails
+
+#### Scenario: Scope of bulk validation
+
+- **WHEN** validating with `--all` or `--changes`
+- **THEN** include all change proposals under `openspec/changes/`
+- **AND** exclude the `openspec/changes/archive/` directory
+
+- **WHEN** validating with `--specs`
+- **THEN** include all specs that have a `spec.md` under `openspec/specs/<id>/spec.md`
+
+#### Scenario: Validate all changes
+
+- **WHEN** executing `openspec validate --changes`
+- **THEN** validate all changes in openspec/changes/ (excluding archive)
+- **AND** display results for each change
+- **AND** show summary statistics
+
+#### Scenario: Validate all specs
+
+- **WHEN** executing `openspec validate --specs`
+- **THEN** validate all specs in openspec/specs/
+- **AND** display results for each spec
+- **AND** show summary statistics
+
+### Requirement: Validation options and progress indication
+
+The validate command SHALL support standard validation options (--strict, --json) and display progress during bulk operations.
+
+#### Scenario: Strict validation
+
+- **WHEN** executing `openspec validate --all --strict`
+- **THEN** apply strict validation to all items
+- **AND** treat warnings as errors
+- **AND** fail if any item has warnings or errors
+
+#### Scenario: JSON output
+
+- **WHEN** executing `openspec validate --all --json`
+- **THEN** output validation results as JSON
+- **AND** include detailed issues for each item
+- **AND** include summary statistics
+
+#### Scenario: JSON output schema for bulk validation
+
+- **WHEN** executing `openspec validate --all --json` (or `--changes` / `--specs`)
+- **THEN** output a JSON object with the following shape:
+  - `items`: Array of objects with fields `{ id: string, type: "change"|"spec", valid: boolean, issues: Issue[], durationMs: number }`
+  - `summary`: Object `{ totals: { items: number, passed: number, failed: number }, byType: { change?: { items: number, passed: number, failed: number }, spec?: { items: number, passed: number, failed: number } } }`
+  - `version`: String identifier for the schema (e.g., `"1.0"`)
+- **AND** exit with code 1 if any `items[].valid === false`
+
+Where `Issue` follows the existing per-item validation report shape `{ level: "ERROR"|"WARNING"|"INFO", path: string, message: string }`.
+
+#### Scenario: Show validation progress
+
+- **WHEN** validating multiple items (--all, --changes, or --specs)
+- **THEN** show progress indicator or status updates
+- **AND** indicate which item is currently being validated
+- **AND** display running count of passed/failed items
+
+#### Scenario: Concurrency limits for performance
+
+- **WHEN** validating multiple items
+- **THEN** run validations with a bounded concurrency (e.g., 4–8 in parallel)
+- **AND** ensure progress indicators remain responsive
+
+### Requirement: Item type detection and ambiguity handling
+
+The validate command SHALL handle ambiguous names and explicit type overrides to ensure clear, deterministic behavior.
+
+#### Scenario: Direct item validation with automatic type detection
+
+- **WHEN** executing `openspec validate <item-name>`
+- **THEN** if `<item-name>` uniquely matches a change or a spec, validate that item
+
+#### Scenario: Ambiguity between change and spec names
+
+- **GIVEN** `<item-name>` exists both as a change and as a spec
+- **WHEN** executing `openspec validate <item-name>`
+- **THEN** print an ambiguity error explaining both matches
+- **AND** suggest passing `--type change` or `--type spec`, or using `openspec change validate` / `openspec spec validate`
+- **AND** exit with code 1 without performing validation
+
+#### Scenario: Unknown item name
+
+- **WHEN** the `<item-name>` matches neither a change nor a spec
+- **THEN** print a not-found error
+- **AND** show nearest-match suggestions when available
+- **AND** exit with code 1
+
+#### Scenario: Explicit type override
+
+- **WHEN** executing `openspec validate --type change <item>`
+- **THEN** treat `<item>` as a change ID and validate it (skipping auto-detection)
+
+- **WHEN** executing `openspec validate --type spec <item>`
+- **THEN** treat `<item>` as a spec ID and validate it (skipping auto-detection)
+
+### Requirement: Interactivity controls
+
+- The CLI SHALL respect `--no-interactive` to disable prompts.
+- The CLI SHALL respect `OPEN_SPEC_INTERACTIVE=0` to disable prompts globally.
+- Interactive prompts SHALL only be shown when stdin is a TTY and interactivity is not disabled.
+
+#### Scenario: Disabling prompts via flags or environment
+
+- **WHEN** `openspec validate` is executed with `--no-interactive` or with environment `OPEN_SPEC_INTERACTIVE=0`
+- **THEN** the CLI SHALL not display interactive prompts
+- **AND** SHALL print non-interactive hints or chosen outputs as appropriate

package/references/openspec/openspec/changes/archive/2025-08-19-bulk-validation-interactive-selection/tasks.md

@@ -0,0 +1,81 @@
+# Implementation Tasks
+
+## 1. Change Command: Interactive Validation Selection
+- [x] 1.1 Add `--no-interactive` flag to `change validate` in `src/cli/index.ts`
+- [x] 1.2 Implement interactivity gate respecting TTY and `OPEN_SPEC_INTERACTIVE=0` in `src/commands/change.ts`
+- [x] 1.3 When no `[change-name]` is provided and interactivity is allowed, prompt with a list of active changes (exclude `archive/`) and validate the selected one
+- [x] 1.4 Preserve current non-interactive fallback: print available change IDs and hint, set `process.exitCode = 1`
+- [x] 1.5 Tests: add coverage for interactive and non-interactive flows
+  - Added `test/commands/change.interactive-validate.test.ts`
+
+## 2. Spec Command: Interactive Validation Selection
+- [x] 2.1 Make `spec validate` accept optional `[spec-id]` in `src/commands/spec.ts` registration
+- [x] 2.2 Add `--no-interactive` flag to `spec validate`
+- [x] 2.3 Implement interactivity gate respecting TTY and `OPEN_SPEC_INTERACTIVE=0`
+- [x] 2.4 When no `[spec-id]` provided and interactivity allowed, prompt to select from `openspec/specs/*/spec.md` and validate the selected spec
+- [x] 2.5 Preserve current non-interactive fallback when no spec-id and no interactivity: print existing error and exit code non-zero
+- [x] 2.6 Tests: add coverage for interactive and non-interactive flows
+  - Added `test/commands/spec.interactive-validate.test.ts`
+
+## 3. New Top-level `validate` Command
+- [x] 3.1 Add `validate` command in `src/cli/index.ts`
+  - Options: `--all`, `--changes`, `--specs`, `--type <change|spec>`, `--strict`, `--json`, `--no-interactive`
+  - Usage: `openspec validate [item-name]`
+- [x] 3.2 Create `src/commands/validate.ts` implementing:
+  - [x] 3.2.1 Interactive selector when no args (choices: All, Changes, Specs, Specific item)
+  - [x] 3.2.2 Non-interactive fallback with helpful hint and exit code 1
+  - [x] 3.2.3 Direct item validation with automatic type detection
+  - [x] 3.2.4 Ambiguity error when name exists as both change and spec; suggest `--type` or subcommands
+  - [x] 3.2.5 Unknown item handling with nearest-match suggestions
+  - [x] 3.2.6 Bulk validation for `--all`, `--changes`, `--specs` (exclude `openspec/changes/archive/`)
+  - [x] 3.2.7 Respect `--strict` and `--json` options; JSON shape per spec
+  - [x] 3.2.8 Exit with code 1 if any validation fails
+  - [x] 3.2.9 Bounded concurrency (default 4–8) for bulk validation
+  - [x] 3.2.10 Progress indication during bulk runs (current item, running counts)
+
+## 4. Utilities and Shared Helpers
+- [x] 4.1 Add `src/utils/interactive.ts` with `isInteractive(stdin: NodeJS.ReadStream, noInteractiveFlag?: boolean): boolean`
+  - Considers: `process.stdin.isTTY`, `--no-interactive`, `OPEN_SPEC_INTERACTIVE=0`
+- [x] 4.2 Add `src/utils/item-discovery.ts` with:
+  - `getActiveChangeIds(root = process.cwd()): Promise<string[]>` (exclude `archive/`)
+  - `getSpecIds(root = process.cwd()): Promise<string[]>` (folders with `spec.md`)
+- [ ] 4.3 Optional: `src/utils/concurrency.ts` helper for bounded parallelism
+- [x] 4.4 Reuse `src/core/validation/validator.ts` for item validation
+
+## 5. JSON Output (Bulk Validation)
+- [x] 5.1 Implement JSON schema:
+  - `items: Array<{ id: string, type: "change"|"spec", valid: boolean, issues: Issue[], durationMs: number }>`
+  - `summary: { totals: { items: number, passed: number, failed: number }, byType: { change?: { items: number, passed: number, failed: number }, spec?: { items: number, passed: number, failed: number } } }`
+  - `version: "1.0"`
+- [x] 5.2 Ensure process exit code is 1 if any `items[].valid === false`
+- [x] 5.3 Tests for JSON shape (keys, types, counts) and exit code behavior
+  - Added `test/commands/validate.test.ts`
+
+## 6. Progress and UX
+- [x] 6.1 Use `ora` or minimal console progress to show current item and running counts
+- [x] 6.2 Keep output stable in `--json` mode (no extra logs to stdout; use stderr for progress if needed)
+- [x] 6.3 Ensure responsiveness with concurrency limits
+
+## 7. Tests
+- [x] 7.1 Add top-level validate tests: `test/commands/validate.test.ts`
+  - Includes non-interactive hint, --all JSON, --specs with concurrency, ambiguity error
+- [ ] 7.2 Add unit tests for `isInteractive` and item discovery helpers
+- [x] 7.3 Extend existing change/spec command tests to cover interactive `validate`
+  - Added `test/commands/change.interactive-validate.test.ts`, `test/commands/spec.interactive-validate.test.ts`
+
+## 8. CLI Help and Docs
+- [x] 8.1 Update command descriptions/options in `src/cli/index.ts`
+- [x] 8.2 Verify help output includes `validate` command and flags
+- [x] 8.3 Ensure existing specs under `openspec/changes/bulk-validation-interactive-selection/specs/*` remain satisfied
+
+## 9. Non-functional
+- [x] 9.1 Code style and types: explicit types for exported APIs; avoid `any`
+- [x] 9.2 No linter errors; stable formatting; avoid unrelated refactors
+- [x] 9.3 Maintain existing behavior for unaffected commands
+
+## 10. Acceptance Criteria Mapping
+- [x] AC-1: `openspec change validate` interactive selection when no arg (TTY only; respects `--no-interactive`/env) — matches cli-change spec
+- [x] AC-2: `openspec spec validate` interactive selection when no arg (TTY only; respects `--no-interactive`/env) — matches cli-spec spec
+- [x] AC-3: New `openspec validate` supports interactive selection, bulk/filtered validation, JSON schema, progress, concurrency, exit codes — matches cli-validate spec
+
+

package/references/openspec/openspec/changes/archive/2025-08-19-fix-update-tool-selection/proposal.md

@@ -0,0 +1,40 @@
+# Fix Update Command Tool Selection
+
+## Problem
+
+The `openspec update` command currently forces the creation/update of CLAUDE.md regardless of which AI tool was selected during initialization. This violates the tool-agnostic design principle and creates confusion for users who selected different AI assistants.
+
+Additionally, different team members may use different AI tools, so we cannot rely on a shared configuration file.
+
+## Solution
+
+Modify the update command to:
+1. Only update AI tool configuration files that already exist
+2. Never create new AI tool configuration files
+3. Always update the core OpenSpec files (README.md, etc.)
+
+## Implementation
+
+- Remove hardcoded CLAUDE.md update from update command
+- Implement file existence check before updating any AI tool config
+- Update each existing AI tool config file with its appropriate markers
+- No configuration file needed (avoids team conflicts)
+
+## Success Criteria
+
+- Update command only modifies existing AI tool configuration files
+- No new AI tool files created during update
+- Team members can use different AI tools without conflicts
+- Existing projects continue to work (backward compatibility)
+
+## Why
+
+Users need predictable, tool-agnostic behavior from `openspec update`. Creating or forcing updates for AI tool files that a project does not use causes confusion and merge conflicts. Restricting updates to existing files and always updating core OpenSpec files keeps the workflow consistent for mixed-tool teams.
+
+## What Changes
+
+- **cli-update:** Modify update behavior to update only existing AI tool configuration files and never create new ones; always update core OpenSpec files and display an ASCII-safe success message.
+
+## ADDED Requirements
+
+Removed from proposal to follow conventions. See `specs/cli-update/spec.md` for the delta requirements content.

package/references/openspec/openspec/changes/archive/2025-08-19-fix-update-tool-selection/specs/cli-update/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Tool-Agnostic Updates
+
+The update command SHALL update only existing AI tool configuration files and SHALL NOT create new ones.
+
+#### Scenario: Updating existing tool files
+
+- **WHEN** a user runs `openspec update`
+- **THEN** update each AI tool configuration file that exists (e.g., CLAUDE.md, COPILOT.md)
+- **AND** do not create missing tool configuration files
+- **AND** preserve user content outside OpenSpec markers
+
+### Requirement: Core Files Always Updated
+
+The update command SHALL always update the core OpenSpec files and display an ASCII-safe success message.
+
+#### Scenario: Successful update
+
+- **WHEN** the update completes successfully
+- **THEN** replace `openspec/README.md` with the latest template
+- **AND** update existing AI tool configuration files within markers
+- **AND** display the message: "Updated OpenSpec instructions"

package/references/openspec/openspec/changes/archive/2025-08-19-fix-update-tool-selection/tasks.md

@@ -0,0 +1,21 @@
+# Implementation Tasks
+
+## 1. Update Update Command
+- [x] Remove hardcoded CLAUDE.md update from `src/core/update.ts`
+- [x] Add logic to check for existing AI tool configuration files
+- [x] Update only existing files using their appropriate configurators
+- [x] Iterate through all registered configurators to check for existing files
+
+## 2. Update Configurator Registry
+- [x] Add method to get all configurators for update command
+- [x] Ensure each configurator can check if its file exists
+
+## 3. Add Tests
+- [x] Test update command with only CLAUDE.md present
+- [x] Test update command with no AI tool files present
+- [x] Test update command with multiple AI tool files present
+- [x] Test that update never creates new AI tool files
+
+## 4. Update Documentation
+- [x] Update README to clarify team-friendly behavior
+- [x] Document that update only modifies existing files

package/references/openspec/openspec/changes/archive/2025-08-19-improve-validate-error-messages/proposal.md

@@ -0,0 +1,25 @@
+# improve-validate-error-messages
+
+## Why
+
+Developers struggle to resolve validation failures because current errors lack actionable guidance. Common issues include: missing deltas, missing required sections, and misformatted scenarios that are silently ignored. Without clear remediation steps, users cannot quickly correct structure or formatting, leading to frustration and rework. Improving error messages with concrete fixes, file/section hints, and suggested commands will significantly reduce time-to-green and make OpenSpec more approachable.
+
+## What Changes
+
+- Validation errors SHALL include specific remediation steps (what to change and where).
+- "No deltas found" error SHALL guide users to create `specs/` with proper delta headers and suggest debug commands.
+- Missing required sections (Spec: Purpose/Requirements; Change: Why/What Changes) SHALL include expected header names and a minimal skeleton example.
+- Likely misformatted scenarios (bulleted WHEN/THEN/AND) SHALL emit a targeted warning explaining the `#### Scenario:` format and show a conversion template.
+- All reported issues SHALL include the source file path and structured location (e.g., `deltas[0].requirements[0]`).
+- Non-JSON output SHOULD end with a short "Next steps" footer when invalid.
+
+## Impact
+
+- Affected CLI: validate
+- Affected code:
+  - `src/commands/validate.ts`
+  - `src/core/validation/validator.ts`
+  - `src/core/validation/constants.ts`
+  - `src/core/parsers/*` (wrapping thrown errors with richer context)
+
+

package/references/openspec/openspec/changes/archive/2025-08-19-improve-validate-error-messages/specs/cli-validate/spec.md

@@ -0,0 +1,55 @@
+# Validate Command
+
+## ADDED Requirements
+
+### Requirement: Validation SHALL provide actionable remediation steps
+Validation output SHALL include specific guidance to fix each error, including expected structure, example headers, and suggested commands to verify fixes.
+
+#### Scenario: No deltas found in change
+- **WHEN** validating a change with zero parsed deltas
+- **THEN** show error "No deltas found" with guidance:
+  - Ensure `openspec/changes/{id}/specs/` exists with `.md` files
+  - Use delta headers: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements`
+  - Each requirement must include at least one `#### Scenario:` block
+  - Try: `openspec change show {id} --json --deltas-only` to inspect what was parsed
+
+#### Scenario: Missing required sections
+- **WHEN** a required section is missing
+- **THEN** the validator SHALL include expected header names and a minimal skeleton:
+  - For Spec: `## Purpose`, `## Requirements`
+  - For Change: `## Why`, `## What Changes`
+  - Show an example snippet of the missing section
+
+### Requirement: Validator SHALL detect likely misformatted scenarios and warn with a fix
+The validator SHALL recognize bulleted lines that look like scenarios (e.g., lines beginning with WHEN/THEN/AND) and emit a targeted warning with a conversion example to `#### Scenario:`.
+
+#### Scenario: Bulleted WHEN/THEN under a Requirement
+- **WHEN** bullets that start with WHEN/THEN/AND are found under a requirement without any `#### Scenario:` headers
+- **THEN** emit warning: "Scenarios must use '#### Scenario:' headers", and show a conversion template:
+```
+#### Scenario: Short name
+- **WHEN** ...
+- **THEN** ...
+- **AND** ...
+```
+
+### Requirement: All issues SHALL include file paths and structured locations
+Error, warning, and info messages SHALL include:
+- Source file path (`openspec/changes/{id}/proposal.md`, `.../specs/{cap}/spec.md`)
+- Structured path (e.g., `deltas[0].requirements[0].scenarios`)
+
+#### Scenario: Zod validation error
+- **WHEN** a schema validation fails
+- **THEN** the message SHALL include `file`, `path`, and a remediation hint if applicable
+
+### Requirement: Invalid results SHALL include a Next steps footer in human-readable output
+The CLI SHALL append a Next steps footer when the item is invalid and not using `--json`, including:
+- Summary line with counts
+- Top-3 guidance bullets (contextual to the most frequent or blocking errors)
+- A suggestion to re-run with `--json` and/or the debug command
+
+#### Scenario: Change invalid summary
+- **WHEN** a change validation fails
+- **THEN** print "Next steps" with 2-3 targeted bullets and suggest `openspec change show <id> --json --deltas-only`
+
+

package/references/openspec/openspec/changes/archive/2025-08-19-improve-validate-error-messages/tasks.md

@@ -0,0 +1,21 @@
+## 1. Enhance validation messages
+- [x] 1.1 Add remediation guidance for "No deltas found"
+- [x] 1.2 Include file path and structured path in all issues
+- [x] 1.3 Improve messages for missing required sections (Spec, Change)
+- [x] 1.4 Detect likely misformatted scenarios and warn with conversion example
+- [x] 1.5 Add "Next steps" footer for non-JSON invalid output
+
+## 2. Update constants and helpers
+- [x] 2.1 Centralize guidance snippets in `VALIDATION_MESSAGES`
+- [x] 2.2 Provide minimal skeleton examples for missing sections
+
+## 3. Parser integration
+- [x] 3.1 Capture parser-thrown errors and wrap with richer context
+- [x] 3.2 Add file/section references to surfaced parser errors
+
+## 4. Tests
+- [x] 4.1 Unit tests for validator message composition
+- [x] 4.2 CLI integration tests for human-readable output (with footer)
+- [x] 4.3 JSON mode tests (structure unchanged, content enriched)
+
+

package/references/openspec/openspec/changes/archive/2025-08-19-structured-spec-format/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+OpenSpec specifications lack a consistent structure that makes sections visually identifiable and programmatically parseable across different specs. This makes it harder to maintain consistency and build tooling.
+
+## What Changes
+
+**Specification Format Section**
+- From: No formal structure requirements for specifications
+- To: Structured format with `### Requirement:` and `#### Scenario:` headers
+- Reason: Visual consistency and parseability across all specs
+- Impact: Non-breaking - existing specs can migrate gradually
+
+**Keyword Formatting**
+- From: Inconsistent use of WHEN/THEN/AND keywords
+- To: Bold keywords (**WHEN**, **THEN**, **AND**) in scenario bullets
+- Reason: Improved readability and consistent visual hierarchy
+- Impact: Non-breaking - formatting enhancement only
+
+**Format Flexibility**
+- From: Implicit understanding that different content needs different formats
+- To: Explicit allowance for alternative formats (OpenAPI, JSON Schema, etc.)
+- Reason: Address concern that not all specs fit requirement/scenario pattern
+- Impact: Non-breaking - clarifies existing practice
+
+**Migration Guidelines**
+- From: No migration guidance
+- To: Documented gradual migration approach
+- Reason: Allows incremental adoption without disrupting existing specs
+- Impact: Non-breaking - opt-in migration as specs are modified
+
+## Impact
+
+- Affected specs: openspec-conventions (enhancement to existing capability)
+- Affected code: None initially - this is a documentation standard enhancement
+- Migration: Gradual - existing specs migrate as they're modified
+- Tooling: Enables future parsing tools but doesn't require them

package/references/openspec/openspec/changes/archive/2025-08-19-structured-spec-format/specs/openspec-conventions/spec.md

@@ -0,0 +1,192 @@
+# OpenSpec Conventions Specification
+
+## ADDED Requirements
+
+### Requirement: Structured Format Adoption
+
+Behavioral specifications SHALL adopt the structured format with `### Requirement:` and `#### Scenario:` headers as the default.
+
+#### Scenario: Use structured headings for behavior
+
+- **WHEN** documenting behavioral requirements
+- **THEN** use `### Requirement:` for requirements
+- **AND** use `#### Scenario:` for scenarios with bold WHEN/THEN/AND keywords
+
+## Purpose
+
+OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions.
+
+## Core Principles
+
+The system SHALL follow these principles:
+- Specs reflect what IS currently built and deployed
+- Changes contain proposals for what SHOULD be changed
+- AI drives the documentation process
+- Specs are living documentation kept in sync with deployed code
+
+## Directory Structure
+
+WHEN an OpenSpec project is initialized
+THEN it SHALL have this structure:
+```
+openspec/
+├── project.md              # Project-specific context
+├── README.md               # AI assistant instructions
+├── specs/                  # Current deployed capabilities
+│   └── [capability]/       # Single, focused capability
+│       ├── spec.md         # WHAT and WHY
+│       └── design.md       # HOW (optional, for established patterns)
+└── changes/                # Proposed changes
+    ├── [change-name]/      # Descriptive change identifier
+    │   ├── proposal.md     # Why, what, and impact
+    │   ├── tasks.md        # Implementation checklist
+    │   ├── design.md       # Technical decisions (optional)
+    │   └── specs/          # Complete future state
+    │       └── [capability]/
+    │           └── spec.md # Clean markdown (no diff syntax)
+    └── archive/            # Completed changes
+        └── YYYY-MM-DD-[name]/
+```
+
+## Specification Format
+
+### Requirement: Structured Format for Behavioral Specs
+
+Behavioral specifications SHALL use a structured format with consistent section headers and keywords to ensure visual consistency and parseability.
+
+#### Scenario: Writing requirement sections
+
+- **WHEN** documenting a requirement in a behavioral specification
+- **THEN** use a level-3 heading with format `### Requirement: [Name]`
+- **AND** immediately follow with a SHALL statement describing core behavior
+- **AND** keep requirement names descriptive and under 50 characters
+
+#### Scenario: Documenting scenarios
+
+- **WHEN** documenting specific behaviors or use cases
+- **THEN** use level-4 headings with format `#### Scenario: [Description]`
+- **AND** use bullet points with bold keywords for steps:
+  - **GIVEN** for initial state (optional)
+  - **WHEN** for conditions or triggers
+  - **THEN** for expected outcomes
+  - **AND** for additional outcomes or conditions
+
+#### Scenario: Adding implementation details
+
+- **WHEN** a step requires additional detail
+- **THEN** use sub-bullets under the main step
+- **AND** maintain consistent indentation
+  - Sub-bullets provide examples or specifics
+  - Keep sub-bullets concise
+
+### Requirement: Format Flexibility
+
+The structured format SHALL be the default for behavioral specifications, but alternative formats MAY be used when more appropriate for the content type.
+
+#### Scenario: Documenting API specifications
+
+- **WHEN** documenting REST API endpoints or GraphQL schemas
+- **THEN** OpenAPI, GraphQL SDL, or similar formats MAY be used
+- **AND** the spec SHALL clearly indicate the format being used
+- **AND** behavioral aspects SHALL still follow the structured format
+
+#### Scenario: Documenting data schemas
+
+- **WHEN** documenting data structures, database schemas, or configurations
+- **THEN** JSON Schema, SQL DDL, or similar formats MAY be used
+- **AND** include the structured format for behavioral rules and constraints
+
+#### Scenario: Using simplified format
+
+- **WHEN** documenting simple capabilities without complex scenarios
+- **THEN** a simplified WHEN/THEN format without full structure MAY be used
+- **AND** this should be consistent within the capability
+
+## Change Storage Convention
+
+### Future State Storage
+
+WHEN creating a change proposal
+THEN store the complete future state of affected specs
+AND use clean markdown without diff syntax
+
+The `changes/[name]/specs/` directory SHALL contain:
+- Complete spec files as they will exist after the change
+- Clean markdown without `+` or `-` prefixes
+- All formatting and structure of the final intended state
+
+### Proposal Format
+
+WHEN documenting what changes
+THEN the proposal SHALL explicitly describe each change:
+
+```markdown
+**[Section or Behavior Name]**
+- From: [current state/requirement]
+- To: [future state/requirement]
+- Reason: [why this change is needed]
+- Impact: [breaking/non-breaking, who's affected]
+```
+
+This explicit format compensates for not having inline diffs and ensures reviewers understand exactly what will change.
+
+## Change Lifecycle
+
+The change process SHALL follow these states:
+
+1. **Propose**: AI creates change with future state specs and explicit proposal
+2. **Review**: Humans review proposal and future state
+3. **Approve**: Change is approved for implementation
+4. **Implement**: Follow tasks.md checklist (can span multiple PRs)
+5. **Deploy**: Changes are deployed to production
+6. **Update**: Specs in `specs/` are updated to match deployed reality
+7. **Archive**: Change is moved to `archive/YYYY-MM-DD-[name]/`
+
+## Viewing Changes
+
+WHEN reviewing proposed changes
+THEN reviewers can compare using:
+- GitHub PR diff view when changes are committed
+- Command line: `diff -u specs/[capability]/spec.md changes/[name]/specs/[capability]/spec.md`
+- Any visual diff tool comparing current vs future state
+
+The system relies on tools to generate diffs rather than storing them.
+
+## Capability Naming
+
+Capabilities SHALL use:
+- Verb-noun patterns (e.g., `user-auth`, `payment-capture`)
+- Hyphenated lowercase names
+- Singular focus (one responsibility per capability)
+- No nesting (flat structure under `specs/`)
+
+## When Changes Require Proposals
+
+A proposal SHALL be created for:
+- New features or capabilities
+- Breaking changes to existing behavior
+- Architecture or pattern changes
+- Performance optimizations that change behavior
+- Security updates affecting access patterns
+
+A proposal is NOT required for:
+- Bug fixes restoring intended behavior
+- Typos or formatting fixes
+- Non-breaking dependency updates
+- Adding tests for existing behavior
+- Documentation clarifications
+
+## Why This Approach
+
+Clean future state storage provides:
+- **Readability**: No diff syntax pollution
+- **AI-compatibility**: Standard markdown that AI tools understand
+- **Simplicity**: No special parsing or processing needed
+- **Tool-agnostic**: Any diff tool can show changes
+- **Clear intent**: Explicit proposals document reasoning
+
+The structured format adds:
+- **Visual Consistency**: Requirement and Scenario prefixes make sections instantly recognizable
+- **Parseability**: Consistent structure enables tooling and automation
+- **Flexibility**: Alternative formats supported where appropriate
+- **Gradual Adoption**: Existing specs can migrate incrementally

package/references/openspec/openspec/changes/archive/2025-08-19-structured-spec-format/tasks.md

@@ -0,0 +1,19 @@
+## 1. Update OpenSpec Conventions Spec
+
+- [x] 1.1 Add "Specification Format" section to openspec-conventions
+- [x] 1.2 Document structured format with Requirement/Scenario headers
+- [x] 1.3 Define bold keyword usage (WHEN/THEN/AND) for scenarios
+- [x] 1.4 Include examples demonstrating the format within the spec itself
+
+## 2. Update Documentation
+
+- [x] 2.1 Update the "Why This Approach" section with structured format benefits
+- [x] 2.2 Ensure spec follows its own format as a demonstration
+
+## 3. Update Existing Specs
+
+- [x] 3.1 Update cli-init spec to use structured format in Behavior section
+- [x] 3.2 Update cli-list spec to use structured format in Behavior section
+- [x] 3.3 Update cli-update spec to use structured format in Behavior section
+- [x] 3.4 Update cli-diff spec to use structured format in Behavior section
+- [x] 3.5 Update cli-archive spec to use structured format in Behavior section