openspecui 0.0.0

package/references/openspec/openspec/changes/archive/2025-09-29-update-agent-instructions/design.md

@@ -0,0 +1,130 @@
+# Design: Agent Instructions Update
+
+## Approach
+
+### Information Architecture
+- **Front-load critical information** - Three-stage workflow comes first
+- **Clear hierarchy** - Core Workflow → Quick Start → Commands → Details → Edge Cases
+- **50% length reduction** - Target ~285 lines from current ~575 lines
+- **Imperative mood** - "Create proposal" vs "You should create a proposal"
+- **Bullet points over paragraphs** - Scannable, concise information
+
+### Three-Stage Workflow Documentation
+The workflow is now prominently featured as a core concept:
+1. **Creating** - Proposal generation phase
+2. **Implementing** - Code development phase with explicit steps:
+   - Read proposal.md for understanding
+   - Read design.md for technical context
+   - Read tasks.md for checklist
+   - Implement tasks sequentially
+   - Mark complete immediately after each task
+3. **Archiving** - Post-deployment finalization phase
+
+This structure helps agents understand the lifecycle and their role at each stage. The implementation phase is particularly detailed to prevent common mistakes like skipping documentation or batching task completion.
+
+### CLI Documentation Updates
+- **Comprehensive command coverage** - All 9 primary commands documented
+- **`openspec list` prominence** - Essential for discovering changes and specs
+- **Interactive mode documentation** - How agents can use prompts effectively
+- **Complete flag documentation** - All options like --json, --type, --skip-specs
+- **Deprecation cleanup** - Remove noun-first patterns (openspec change show)
+
+### Agent-Specific Enhancements
+Based on industry best practices for coding agents (Claude Code, Cursor, etc.):
+
+**Implementation Workflow**
+- Explicit steps prevent skipping critical context
+- Reading proposal/design first ensures understanding before coding
+- Sequential task completion maintains focus
+- Immediate marking prevents losing track of progress
+- Addresses common failure mode: jumping straight to code
+
+**Spec Discovery Workflow**
+- Always check existing specs before creating new ones
+- Use `openspec list --specs` to discover current capabilities
+- Prefer modifying existing specs over creating duplicates
+- Prevents fragmentation and maintains coherent architecture
+
+**Decision Clarity**
+- Clear decision trees eliminating ambiguous conditions
+- Concrete examples for each decision branch
+- Simplified bug vs feature determination
+
+**Tool Usage Guidance**
+- Tool selection matrix (when to use Grep vs Glob vs Read)
+- Error recovery patterns for common failures
+- Verification workflows to confirm correctness
+
+**Context Management**
+- "Before Any Task" checklist for gathering context
+- What to read before starting any work
+- How to maintain state across interactions
+
+**Spec File Structure Documentation**
+- Complete examples with ADDED/MODIFIED/REMOVED sections
+- Critical scenario formatting (#### Scenario: headers)
+- Delta file location clarity (changes/{name}/specs/)
+- Addresses most common creation errors from retrospective
+
+**Troubleshooting and Debugging**
+- Common error messages with solutions
+- Delta detection debugging steps
+- Validation best practices
+- JSON output for inspection
+- Prevents hours of frustration from silent failures
+
+**Best Practices**
+- Be concise (one-line answers when appropriate)
+- Be specific (file.ts:42 line references)
+- Start simple (<100 lines, single-file defaults)
+- Justify complexity (require metrics/data)
+
+## Design Rationale
+
+### Why These Changes Matter
+
+**Cognitive Load Reduction**
+- Agents process instructions better with clear structure
+- Front-loading critical info reduces scanning time
+- Decision trees eliminate analysis paralysis
+
+**Industry Alignment**
+- Follows patterns proven effective in Claude Code, Cursor, GitHub Copilot
+- Addresses common failure modes (ambiguous decisions, missing context)
+- Optimizes for LLM strengths (pattern matching) vs weaknesses (calculations)
+
+**Addressing Critical Pain Points (from Retrospective)**
+- **Scenario formatting** - Biggest struggle, now explicitly documented with examples
+- **Complete spec structure** - Full examples prevent structural errors
+- **Delta detection issues** - Debugging commands help diagnose problems
+- **Silent parsing failures** - Troubleshooting section explains common issues
+
+**Practical Impact**
+- Faster agent comprehension of tasks
+- Fewer misinterpretations of requirements
+- More consistent implementation quality
+- Better error recovery when things go wrong
+- Prevents the most common errors identified in user experience
+
+## Trade-offs
+
+### What We're Removing
+- Lengthy explanations of concepts that can be inferred
+- Redundant examples that don't add clarity
+- Verbose edge case documentation (moved to reference section)
+- Deprecated command documentation
+
+### What We're Keeping
+- All critical workflow steps
+- Complete CLI command reference
+- Complexity management principles
+- Directory structure visualization
+- Quick reference summary
+
+## Implementation Notes
+
+The CLAUDE.md template is intentionally more concise than README.md since:
+- It appears in every project root
+- Agents can reference the full README.md for details
+- It needs to load quickly in AI context windows
+- Focus is on immediate actionable guidance

package/references/openspec/openspec/changes/archive/2025-09-29-update-agent-instructions/proposal.md

@@ -0,0 +1,117 @@
+# Update OpenSpec Agent Instructions
+
+## Why
+
+The current OpenSpec agent instructions need updates to follow best practices for AI assistant instructions (brevity, clarity, removing ambiguity), ensure CLI commands are current with the actual implementation, and properly document the three-stage workflow pattern that agents should follow.
+
+## What Changes
+
+### Core Structure Improvements
+- **Front-load the 3-stage workflow** as the primary mental model:
+  1. Creating a change proposal (proposal.md, spec deltas, design.md, tasks.md)
+  2. Implementing a change proposal:
+     - First read proposal.md to understand the change
+     - Read design.md if it exists for technical context
+     - Read tasks.md for the implementation checklist
+     - Complete tasks one by one
+     - Mark each task complete immediately after finishing
+  3. Archiving the change proposal (using archive command after deployment)
+- **Reduce instruction length by 50%** while maintaining all critical information
+- **Restructure with clear hierarchy**: Core Workflow → Quick Start → Commands → Details → Edge Cases
+
+### Decision Clarity Enhancements
+- **Add clear decision trees** for common scenarios (bug vs feature, proposal needed vs not)
+- **Remove ambiguous conditions** that confuse agent decision-making
+- **Add "Before Any Task" checklist** for context gathering
+- **Add "Before Creating Specs" rule** - Always check existing specs first to avoid duplicates
+
+### CLI Documentation Updates
+- **Complete command documentation** with all current functionality:
+  - `openspec init [path]` - Initialize OpenSpec in a project
+  - `openspec list` - List all active changes (default)
+  - `openspec list --specs` - List all specifications
+  - `openspec show [item]` - Display change or spec with auto-detection
+  - `openspec show` - Interactive mode for selection
+  - `openspec diff [change]` - Show spec differences for a change
+  - `openspec validate [item]` - Validate changes or specs
+  - `openspec archive [change]` - Archive completed change after deployment
+  - `openspec update [path]` - Update OpenSpec instruction files
+- **Document all flags and options**:
+  - `--json` output format for programmatic use
+  - `--type change|spec` for disambiguation
+  - `--skip-specs` for tooling-only archives
+  - `--strict` for strict validation mode
+  - `--no-interactive` to disable prompts
+- **Remove deprecated command references** (noun-first patterns like `openspec change show`)
+- **Add concrete examples** for each command variation
+- **Document debugging commands**:
+  - `openspec show [change] --json --deltas-only` for inspecting deltas
+  - `openspec validate [change] --strict` for comprehensive validation
+
+### Spec File Structure Documentation
+- **Complete spec file examples** showing proper structure:
+  ```markdown
+  ## ADDED Requirements
+  ### Requirement: Clear requirement statement
+  The system SHALL provide the functionality...
+  
+  #### Scenario: Descriptive scenario name
+  - **WHEN** condition occurs
+  - **THEN** expected outcome
+  - **AND** additional outcomes
+  ```
+- **Scenario formatting requirements** (critical - most common error):
+  - MUST use `#### Scenario:` headers (4 hashtags)
+  - NOT bullet lists or bold text
+  - Each requirement MUST have at least one scenario
+- **Delta file location** - Clear explanation:
+  - Spec files go in `changes/{name}/specs/` directory
+  - Deltas are automatically extracted from these files
+  - Use operation prefixes: ADDED, MODIFIED, REMOVED, RENAMED
+
+### Troubleshooting Section
+- **Common errors and solutions**:
+  - "Change must have at least one delta" → Check specs/ directory exists with .md files
+  - "Requirement must have at least one scenario" → Check scenario uses `#### Scenario:` format
+  - Silent scenario parsing failures → Verify exact header format
+- **Delta detection debugging**:
+  - Use `openspec show [change] --json --deltas-only` to inspect parsed deltas
+  - Check that spec files have operation prefixes (## ADDED Requirements)
+  - Verify specs/ subdirectory structure
+- **Validation best practices**:
+  - Always use `--strict` flag for comprehensive checks
+  - Use JSON output for debugging: `--json | jq '.deltas'`
+
+### Agent-Specific Improvements
+- **Implementation workflow** - Clear step-by-step process:
+  1. Read proposal.md to understand what's being built
+  2. Read design.md (if exists) for technical decisions
+  3. Read tasks.md for the implementation checklist
+  4. Implement tasks one by one in order
+  5. Mark each task complete immediately: `- [x] Task completed`
+  6. Never skip ahead or batch task completion
+- **Spec discovery workflow** - Always check existing specs before creating new ones:
+  - Use `openspec list --specs` to see all current specs
+  - Check if capability already exists before creating
+  - Prefer modifying existing specs over creating duplicates
+- **Tool selection matrix** - When to use Grep vs Glob vs Read
+- **Error recovery patterns** - How to handle common failures
+- **Context management guide** - What to read before starting tasks
+- **Verification workflows** - How to confirm changes are correct
+
+### Best Practices Section
+- **Be concise** - One-line answers when appropriate
+- **Be specific** - Use exact file paths and line numbers (file.ts:42)
+- **Start simple** - Default to <100 lines, single-file implementations
+- **Justify complexity** - Require data/metrics for any optimization
+
+## Impact
+
+- Affected specs: None (this is a tooling/documentation change)
+- Affected code: 
+  - `src/core/templates/claude-template.ts` - Update CLAUDE.md template
+- Affected documentation:
+  - `openspec/README.md` - Main OpenSpec instructions
+  - CLAUDE.md files generated by `openspec init` command
+
+Note: This is a tooling/infrastructure change that doesn't require spec updates. When archiving, use `openspec archive update-agent-instructions --skip-specs`.

package/references/openspec/openspec/changes/archive/2025-09-29-update-agent-instructions/tasks.md

@@ -0,0 +1,69 @@
+# Implementation Tasks
+
+## 1. Restructure OpenSpec README.md
+- [x] 1.1 Front-load the three-stage workflow as primary content
+- [x] 1.2 Restructure with hierarchy: Core Workflow → Quick Start → Commands → Details → Edge Cases
+- [x] 1.3 Reduce total length by 50% (target: ~285 lines from current ~575)
+- [x] 1.4 Add "Before Any Task" context-gathering checklist
+- [x] 1.5 Add "Before Creating Specs" rule to check existing specs first
+
+## 2. Add Decision Clarity  
+- [x] 2.1 Create clear decision trees for "Create Proposal?" scenarios
+- [x] 2.2 Remove ambiguous conditions that confuse agents
+- [x] 2.3 Add concrete examples for each decision branch
+- [x] 2.4 Simplify bug vs feature determination logic
+- [x] 2.5 Add explicit Stage 2 implementation steps (read → implement → mark complete)
+
+## 3. Update CLI Documentation
+- [x] 3.1 Document `openspec list` and `openspec list --specs` commands
+- [x] 3.2 Document `openspec show` with all flags and interactive mode
+- [x] 3.3 Document `openspec diff [change]` for viewing spec differences
+- [x] 3.4 Document `openspec archive` with --skip-specs option
+- [x] 3.5 Document `openspec validate` with --strict and batch modes
+- [x] 3.6 Document `openspec init` and `openspec update` commands
+- [x] 3.7 Remove all deprecated noun-first command references
+- [x] 3.8 Add concrete usage examples for each command variation
+- [x] 3.9 Document all flags: --json, --type, --no-interactive, etc.
+- [x] 3.10 Document debugging commands: `show --json --deltas-only`
+
+## 4. Add Spec File Documentation
+- [x] 4.1 Add complete spec file structure example with ADDED/MODIFIED sections
+- [x] 4.2 Document scenario formatting requirements (#### Scenario: headers)
+- [x] 4.3 Explain delta file location (changes/{name}/specs/ directory)
+- [x] 4.4 Show how deltas are automatically extracted
+- [x] 4.5 Include warning about most common error (scenario formatting)
+
+## 5. Add Troubleshooting Section
+- [x] 5.1 Document common errors and their solutions
+- [x] 5.2 Add delta detection debugging steps
+- [x] 5.3 Include validation best practices (--strict flag)
+- [x] 5.4 Show how to use JSON output for debugging
+- [x] 5.5 Add examples of silent parsing failures
+
+## 6. Add Agent-Specific Sections
+- [x] 6.1 Add implementation workflow (read docs → implement tasks → mark complete)
+- [x] 6.2 Add spec discovery workflow (check existing before creating)
+- [x] 6.3 Create tool selection matrix (Grep vs Glob vs Read)
+- [x] 6.4 Add error recovery patterns section
+- [x] 6.5 Add context management guide
+- [x] 6.6 Add verification workflows section
+- [x] 6.7 Add best practices section (concise, specific, simple)
+
+## 7. Update CLAUDE.md Template
+- [x] 7.1 Update `src/core/templates/claude-template.ts` with streamlined content
+- [x] 7.2 Include three-stage workflow prominently
+- [x] 7.3 Add comprehensive CLI quick reference (list, show, diff, archive, etc.)
+- [x] 7.4 Add "Before Any Task" checklist
+- [x] 7.5 Add "Before Creating Specs" rule
+- [x] 7.6 Keep complexity management principles
+- [x] 7.7 Add critical scenario formatting note (#### Scenario: headers)
+- [x] 7.8 Include debugging command reference
+
+## 8. Testing and Validation
+- [x] 8.1 Test all documented CLI commands for accuracy
+- [x] 8.2 Run `openspec init` to verify CLAUDE.md generation
+- [x] 8.3 Validate instruction clarity with example scenarios
+- [x] 8.4 Ensure no critical information was lost in streamlining
+- [x] 8.5 Verify decision trees eliminate ambiguity
+- [x] 8.6 Test scenario formatting examples work correctly
+- [x] 8.7 Verify troubleshooting steps resolve common errors

package/references/openspec/openspec/changes/archive/2025-09-29-update-markdown-parser-crlf/proposal.md

@@ -0,0 +1,19 @@
+# Update Markdown Parser CRLF Handling
+
+## Problem
+Windows users report that `openspec validate` raises “Change must have a Why section” even when the section exists (see GitHub issue #77). The CLI currently splits markdown on `\n` and compares headers without stripping `\r`, so files saved with CRLF line endings keep a trailing carriage return in the header token. As a result the parser fails to detect `## Why`/`## What Changes`, triggering false validation errors and breaking the workflow on Windows-default editors.
+
+## Solution
+- Normalize markdown content inside the parser so CRLF and lone-CR inputs are treated as `\n` before section detection, trimming any carriage returns from titles and content comparisons.
+- Reuse the normalized reader everywhere `MarkdownParser` is constructed to keep behavior consistent for validation, view, spec, and list flows.
+- Add regression coverage that reproduces the failure (unit test around `parseChange` and a CLI spawn/e2e test that writes a CRLF change then runs `openspec validate`).
+- Update the `cli-validate` spec to codify the expectation that required sections are recognized regardless of line-ending style.
+
+## Benefits
+- Restores correct validation behavior for Windows editors without requiring manual line-ending conversion.
+- Locks in the fix with targeted tests so future parser refactors keep cross-platform support.
+- Clarifies the spec so downstream work (e.g., cross-shell e2e plan) understands the non-negotiable behavior.
+
+## Risks
+- Low: parser normalization touches shared code paths that parse specs and changes; need to ensure no regressions in other command consumers (mitigated by existing parser tests plus the new CRLF fixtures).
+

package/references/openspec/openspec/changes/archive/2025-09-29-update-markdown-parser-crlf/specs/cli-validate/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+### Requirement: Parser SHALL handle cross-platform line endings
+The markdown parser SHALL correctly identify sections regardless of line ending format (LF, CRLF, CR).
+
+#### Scenario: Required sections parsed with CRLF line endings
+- **GIVEN** a change proposal markdown saved with CRLF line endings
+- **AND** the document contains `## Why` and `## What Changes`
+- **WHEN** running `openspec validate <change-id>`
+- **THEN** validation SHALL recognize the sections and NOT raise parsing errors

package/references/openspec/openspec/changes/archive/2025-09-29-update-markdown-parser-crlf/tasks.md

@@ -0,0 +1,11 @@
+## 1. Guard the regression
+- [x] 1.1 Add a unit test that feeds a CRLF change document into `MarkdownParser.parseChange` and asserts `Why`/`What Changes` are detected.
+- [x] 1.2 Add a CLI spawn/e2e test that writes a CRLF change, runs `openspec validate`, and expects success.
+
+## 2. Normalize parsing
+- [x] 2.1 Normalize line endings when constructing `MarkdownParser` so headers and content comparisons ignore `\r`.
+- [x] 2.2 Ensure all CLI entry points (validate, view, spec conversion) reuse the normalized parser path.
+
+## 3. Document and verify
+- [x] 3.1 Update the `cli-validate` spec with a scenario covering CRLF line endings.
+- [x] 3.2 Run the parser and CLI test suites (`pnpm test`, relevant spawn tests) to confirm the fix.

package/references/openspec/openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md

@@ -0,0 +1,25 @@
+## Why
+- Codex (the VS Code extension formerly known as Codeium Chat) exposes "slash commands" by reading Markdown prompt files from `~/.codex/prompts/`. Each file name becomes the `/command` users can run, with YAML frontmatter for metadata (`description`, `argument-hint`) and `$ARGUMENTS` to capture user input. The workflow screenshot shared by Kevin Kern ("Codex problem analyzer") shows the format OpenSpec should target so teams can invoke curated workflows straight from the chat palette.
+- Teams already rely on OpenSpec to manage the slash-command surface area for Claude, Cursor, OpenCode, Kilo Code, and Windsurf. Leaving Codex out forces them to manually copy/paste OpenSpec guardrails into `~/.codex/prompts/*.md`, which drifts quickly and undermines the "single source of truth" promise of the CLI.
+- Codex commands live outside the repository (under the user's home directory), so shipping an automated configurator that both scaffolds the prompts and keeps them refreshed via `openspec update` eliminates error-prone manual steps and keeps OpenSpec instructions synchronized across assistants.
+
+## What Changes
+- Add Codex to the `openspec init` tool picker with the same "already configured" detection we use for other editors, wiring an implementation that writes managed Markdown prompts directly to Codex's global directory (`~/.codex/prompts` or `$CODEX_HOME/prompts`) with OpenSpec marker blocks.
+- Produce three Codex prompt files—`openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`—whose content mirrors the shared slash-command templates while using YAML frontmatter (`description` and `argument-hint` fields) and `$ARGUMENTS` to capture all arguments as a single string (matching the GitHub Copilot pattern and official Codex specification).
+- Document Codex's global-only discovery and that OpenSpec writes prompts directly to `~/.codex/prompts` (or `$CODEX_HOME/prompts`).
+- Teach `openspec update` to refresh existing Codex prompts in-place (and only when they already exist) in the global directory, updating both frontmatter and body.
+- Document Codex support alongside other slash-command integrations and add regression coverage that exercises init/update behaviour against a temporary global prompts directory via `CODEX_HOME`.
+
+## Impact
+- Specs: `cli-init`, `cli-update`
+- Code: `src/core/config.ts`, `src/core/configurators/slash/*`, `src/core/templates/slash-command-templates.ts`, CLI tool summaries, docs
+- Tests: integration coverage for Codex prompt scaffolding and refresh logic
+- Docs: README and CHANGELOG entries announcing Codex slash-command support
+
+## Current Spec Reference
+- `specs/cli-init/spec.md`
+  - Requirements cover init UX, directory scaffolding, AI tool configuration, and the existing slash-command support for Claude Code, Cursor, and OpenCode.
+  - Our `## MODIFIED` delta in `changes/.../specs/cli-init/spec.md` copies the full "Slash Command Configuration" requirement (header, description, and all scenarios) before appending the new Codex scenario so archiving will retain every prior scenario.
+- `specs/cli-update/spec.md`
+  - Requirements define update preconditions, template refresh behavior, and slash-command refresh logic for Claude Code, Cursor, and OpenCode.
+  - The corresponding delta preserves the entire "Slash Command Updates" requirement while adding the Codex refresh scenario, ensuring the archive workflow replaces the block without losing the existing scenarios or the "Missing slash command file" guardrail.

package/references/openspec/openspec/changes/archive/2025-10-14-add-codex-slash-command-support/specs/cli-init/spec.md

@@ -0,0 +1,56 @@
+## MODIFIED Requirements
+### Requirement: AI Tool Configuration
+The command SHALL configure AI coding assistants with OpenSpec instructions using a marker system.
+#### Scenario: Prompting for AI tool selection
+- **WHEN** run interactively
+- **THEN** prompt the user with "Which AI tools do you use?" using a multi-select menu
+- **AND** list every available tool with a checkbox:
+  - Claude Code (creates or refreshes CLAUDE.md and slash commands)
+  - Cursor (creates or refreshes `.cursor/commands/*` slash commands)
+  - OpenCode (creates or refreshes `.opencode/command/openspec-*.md` slash commands)
+  - Windsurf (creates or refreshes `.windsurf/workflows/openspec-*.md` workflows)
+  - Kilo Code (creates or refreshes `.kilocode/workflows/openspec-*.md` workflows)
+  - Codex (creates or refreshes global prompts at `~/.codex/prompts/openspec-*.md`)
+  - AGENTS.md standard (creates or refreshes AGENTS.md with OpenSpec markers)
+- **AND** show "(already configured)" beside tools whose managed files exist so users understand selections will refresh content
+- **AND** treat disabled tools as "coming soon" and keep them unselectable
+- **AND** allow confirming with Enter after selecting one or more tools
+
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/command/openspec-proposal.md`, `.opencode/command/openspec-apply.md`, and `.opencode/command/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes

package/references/openspec/openspec/changes/archive/2025-10-14-add-codex-slash-command-support/specs/cli-update/spec.md

@@ -0,0 +1,41 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Kilo Code
+- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Codex
+- **GIVEN** the global Codex prompt directory contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **WHEN** a user runs `openspec update`
+- **THEN** refresh each file using the shared slash-command templates (including placeholder guidance)
+- **AND** preserve any unmanaged content outside the OpenSpec marker block
+- **AND** skip creation when a Codex prompt file is missing
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update

package/references/openspec/openspec/changes/archive/2025-10-14-add-codex-slash-command-support/tasks.md

@@ -0,0 +1,19 @@
+## 1. CLI integration
+- [x] 1.1 Add Codex to the init tool picker with display text that clarifies prompts live in the global `.codex/prompts/` directory and implement "already configured" detection by checking for managed Codex prompt files.
+- [x] 1.2 Implement a `CodexSlashCommandConfigurator` that writes `.codex/prompts/openspec-{proposal,apply,archive}.md`, ensuring the prompt directory exists and wrapping content in OpenSpec markers.
+// (No helper command required)
+- [x] 1.3 Register the configurator with the slash-command registry and include Codex in init/update wiring so both commands invoke the new configurator when appropriate.
+
+## 2. Prompt templates
+- [x] 2.1 Extend the shared slash-command templates (or add a Codex-specific wrapper) to inject numbered placeholders (`$1`, `$2`, …) where Codex expects user-supplied arguments.
+- [x] 2.2 Verify generated Markdown stays within Codex's formatting expectations (no front matter, heading-first layout) and matches the problem-analyzer style shown in the reference screenshot.
+
+## 3. Update support & tests
+- [x] 3.1 Update the `openspec update` flow to refresh existing Codex prompts without creating new ones when files are missing.
+- [x] 3.2 Add integration coverage that exercises init/update against a temporary global Codex prompts directory by setting `CODEX_HOME`, asserting marker preservation and idempotent updates.
+- [x] 3.3 Document Codex's global-only discovery and automatic installation in README and CHANGELOG.
+- [x] 3.3 Confirm error handling surfaces clear paths when the CLI cannot write to the Codex prompt directory (permissions, missing home directory, etc.).
+
+## 4. Documentation
+- [x] 4.1 Document Codex slash-command support in the README and changelog alongside other assistant integrations.
+- [x] 4.2 Add a release note snippet that points Codex users to the generated `/openspec-proposal`, `/openspec-apply`, and `/openspec-archive` commands.

package/references/openspec/openspec/changes/archive/2025-10-14-add-github-copilot-prompts/proposal.md

@@ -0,0 +1,25 @@
+## Why
+- GitHub Copilot supports custom slash commands through markdown files in `.github/prompts/<name>.prompt.md`. Each file includes YAML frontmatter with a `description` label and uses `$ARGUMENTS` to capture user input. This format allows teams to expose curated workflows directly in Copilot's chat interface.
+- Teams already rely on OpenSpec to manage slash-command configurations for Claude Code, Cursor, OpenCode, Codex, Kilo Code, and Windsurf. Excluding GitHub Copilot forces developers to manually maintain OpenSpec prompts in `.github/prompts/`, which leads to drift and undermines OpenSpec's "single source of truth" promise.
+- GitHub Copilot discovers prompts from the repository's `.github/prompts/` directory, making it straightforward to version control and share across the team. Adding automated generation and refresh through `openspec init` and `openspec update` eliminates manual synchronization and keeps OpenSpec instructions consistent across all AI assistants.
+
+## What Changes
+- Add GitHub Copilot to the `openspec init` tool picker with "already configured" detection similar to other editors, wiring an implementation that writes managed Markdown prompt files to `.github/prompts/` with OpenSpec marker blocks.
+- Generate three GitHub Copilot prompt files—`openspec-proposal.prompt.md`, `openspec-apply.prompt.md`, and `openspec-archive.prompt.md`—whose content mirrors shared slash-command templates while conforming to Copilot's frontmatter and `$ARGUMENTS` placeholder convention.
+- Document GitHub Copilot's repository-based discovery and that OpenSpec writes prompts to `.github/prompts/` with managed blocks.
+- Teach `openspec update` to refresh existing GitHub Copilot prompts in-place (only when they already exist) in the repository's `.github/prompts/` directory.
+- Document GitHub Copilot support alongside other slash-command integrations and add test coverage that exercises init/update behavior for `.github/prompts/` files.
+
+## Impact
+- Specs: `cli-init`, `cli-update`
+- Code: `src/core/configurators/slash/github-copilot.ts` (new), `src/core/configurators/slash/registry.ts`, `src/core/templates/slash-command-templates.ts`, CLI tool summaries, docs
+- Tests: integration coverage for GitHub Copilot prompt scaffolding and refresh logic
+- Docs: README and CHANGELOG entries announcing GitHub Copilot slash-command support
+
+## Current Spec Reference
+- `specs/cli-init/spec.md`
+  - Requirements cover init UX, directory scaffolding, AI tool configuration, and existing slash-command support for Claude Code, Cursor, OpenCode, Codex, Kilo Code, and Windsurf.
+  - Our `## MODIFIED` delta in `changes/.../specs/cli-init/spec.md` will copy the full "Slash Command Configuration" requirement (header, description, and all scenarios) before appending the new GitHub Copilot scenario so archiving retains every prior scenario.
+- `specs/cli-update/spec.md`
+  - Requirements define update preconditions, template refresh behavior, and slash-command refresh logic for existing tools.
+  - The corresponding delta preserves the entire "Slash Command Updates" requirement while adding the GitHub Copilot refresh scenario, ensuring the archive workflow replaces the block without losing existing scenarios or the "Missing slash command file" guardrail.

package/references/openspec/openspec/changes/archive/2025-10-14-add-github-copilot-prompts/specs/cli-init/spec.md

@@ -0,0 +1,48 @@
+## MODIFIED Requirements
+
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes
+
+#### Scenario: Generating slash commands for GitHub Copilot
+- **WHEN** the user selects GitHub Copilot during initialization
+- **THEN** create `.github/prompts/openspec-proposal.prompt.md`, `.github/prompts/openspec-apply.prompt.md`, and `.github/prompts/openspec-archive.prompt.md`
+- **AND** populate each file with YAML frontmatter containing a `description` field that summarizes the workflow stage
+- **AND** include `$ARGUMENTS` placeholder to capture user input
+- **AND** wrap the shared template body with OpenSpec markers so `openspec update` can refresh the content
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage

package/references/openspec/openspec/changes/archive/2025-10-14-add-github-copilot-prompts/specs/cli-update/spec.md

@@ -0,0 +1,48 @@
+## MODIFIED Requirements
+
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Kilo Code
+- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Codex
+- **GIVEN** the global Codex prompt directory contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **WHEN** a user runs `openspec update`
+- **THEN** refresh each file using the shared slash-command templates (including placeholder guidance)
+- **AND** preserve any unmanaged content outside the OpenSpec marker block
+- **AND** skip creation when a Codex prompt file is missing
+
+#### Scenario: Updating slash commands for GitHub Copilot
+- **WHEN** `.github/prompts/` contains `openspec-proposal.prompt.md`, `openspec-apply.prompt.md`, and `openspec-archive.prompt.md`
+- **THEN** refresh each file using shared templates while preserving the YAML frontmatter
+- **AND** update only the OpenSpec-managed block between markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update