openspecui 0.0.0

package/references/openspec/openspec/changes/archive/2025-09-12-add-view-dashboard-command/proposal.md

@@ -0,0 +1,38 @@
+# Change: Add View Dashboard Command
+
+## Why
+
+Users need a quick, at-a-glance overview of their OpenSpec project status without running multiple commands. Currently, users must run `openspec list --changes` and `openspec list --specs` separately to understand the project state. A unified dashboard view would improve developer experience and provide immediate insight into project progress.
+
+## What Changes
+
+### Added `openspec view` Command
+
+The new command provides an interactive dashboard displaying:
+- Summary metrics (total specs, requirements, changes, task progress)
+- Active changes with visual progress bars
+- Completed changes
+- Specifications with requirement counts
+
+### Specifications Affected
+
+- **cli-view** (NEW): Complete specification for the view dashboard command
+
+## Implementation Details
+
+### File Structure
+- Created `/src/core/view.ts` implementing the `ViewCommand` class
+- Registered command in `/src/cli/index.ts`
+- Reuses existing utilities from `task-progress.ts` and `MarkdownParser`
+
+### Visual Design
+- Uses Unicode box drawing characters for borders
+- Color coding: cyan for specs, yellow for active, green for completed
+- Progress bars using filled (█) and empty (░) blocks
+- Clean alignment with proper padding
+
+### Technical Approach
+- Async data fetching from changes and specs directories
+- Parallel processing of specs and changes
+- Error handling for missing or invalid data
+- Maintains consistency with existing list command output

package/references/openspec/openspec/changes/archive/2025-09-12-add-view-dashboard-command/specs/cli-view/spec.md

@@ -0,0 +1,109 @@
+# CLI View Command - Changes
+
+## ADDED Requirements
+
+### Requirement: Dashboard Display
+
+The system SHALL provide a `view` command that displays a dashboard overview of specs and changes.
+
+#### Scenario: Basic dashboard display
+
+- **WHEN** user runs `openspec view`
+- **THEN** system displays a formatted dashboard with sections for summary, active changes, completed changes, and specifications
+
+#### Scenario: No OpenSpec directory
+
+- **WHEN** user runs `openspec view` in a directory without OpenSpec
+- **THEN** system displays error message "✗ No openspec directory found"
+
+### Requirement: Summary Section
+
+The dashboard SHALL display a summary section with key project metrics.
+
+#### Scenario: Complete summary display
+
+- **WHEN** dashboard is rendered with specs and changes
+- **THEN** system shows total number of specifications and requirements
+- **AND** shows number of active changes in progress
+- **AND** shows number of completed changes
+- **AND** shows overall task progress percentage
+
+#### Scenario: Empty project summary
+
+- **WHEN** no specs or changes exist
+- **THEN** summary shows zero counts for all metrics
+
+### Requirement: Active Changes Display
+
+The dashboard SHALL show active changes with visual progress indicators.
+
+#### Scenario: Active changes with progress bars
+
+- **WHEN** there are in-progress changes with tasks
+- **THEN** system displays each change with change name left-aligned
+- **AND** visual progress bar using Unicode characters
+- **AND** percentage completion on the right
+
+#### Scenario: No active changes
+
+- **WHEN** all changes are completed or no changes exist
+- **THEN** active changes section is omitted from display
+
+### Requirement: Completed Changes Display
+
+The dashboard SHALL list completed changes in a separate section.
+
+#### Scenario: Completed changes listing
+
+- **WHEN** there are completed changes (all tasks done)
+- **THEN** system shows them with checkmark indicators in a dedicated section
+
+#### Scenario: Mixed completion states
+
+- **WHEN** some changes are complete and others active
+- **THEN** system separates them into appropriate sections
+
+### Requirement: Specifications Display
+
+The dashboard SHALL display specifications sorted by requirement count.
+
+#### Scenario: Specs listing with counts
+
+- **WHEN** specifications exist in the project
+- **THEN** system shows specs sorted by requirement count (descending) with count labels
+
+#### Scenario: Specs with parsing errors
+
+- **WHEN** a spec file cannot be parsed
+- **THEN** system includes it with 0 requirement count
+
+### Requirement: Visual Formatting
+
+The dashboard SHALL use consistent visual formatting with colors and symbols.
+
+#### Scenario: Color coding
+
+- **WHEN** dashboard elements are displayed
+- **THEN** system uses cyan for specification items
+- **AND** yellow for active changes
+- **AND** green for completed items
+- **AND** dim gray for supplementary text
+
+#### Scenario: Progress bar rendering
+
+- **WHEN** displaying progress bars
+- **THEN** system uses filled blocks (█) for completed portions and light blocks (░) for remaining
+
+### Requirement: Error Handling
+
+The view command SHALL handle errors gracefully.
+
+#### Scenario: File system errors
+
+- **WHEN** file system operations fail
+- **THEN** system continues with available data and omits inaccessible items
+
+#### Scenario: Invalid data structures
+
+- **WHEN** specs or changes have invalid format
+- **THEN** system skips invalid items and continues rendering

package/references/openspec/openspec/changes/archive/2025-09-12-add-view-dashboard-command/tasks.md

@@ -0,0 +1,47 @@
+# Implementation Tasks
+
+## Design Phase
+- [x] Research existing list command implementation
+- [x] Design dashboard layout and information architecture
+- [x] Choose appropriate command verb (`view`)
+- [x] Define visual elements (progress bars, colors, layout)
+
+## Core Implementation
+- [x] Create ViewCommand class in `/src/core/view.ts`
+- [x] Implement getChangesData method for fetching change information
+- [x] Implement getSpecsData method for fetching spec information
+- [x] Implement displaySummary method for summary metrics
+- [x] Add progress bar visualization with Unicode characters
+- [x] Implement color coding using chalk
+
+## Integration
+- [x] Import ViewCommand in CLI index
+- [x] Register `openspec view` command with commander
+- [x] Add proper error handling and ora spinner integration
+- [x] Ensure command appears in help documentation
+
+## Data Processing
+- [x] Reuse TaskProgress utilities for change progress
+- [x] Integrate MarkdownParser for spec requirement counting
+- [x] Handle async operations for file system access
+- [x] Sort specifications by requirement count
+
+## Testing and Validation
+- [x] Build project successfully with new command
+- [x] Test command with sample data
+- [x] Verify correct requirement counts match list --specs
+- [x] Test progress bar display for various completion states
+- [x] Run existing test suite to ensure no regressions
+- [x] Verify TypeScript compilation with no errors
+
+## Documentation
+- [x] Add command description in CLI help
+- [x] Create change proposal documentation
+- [x] Update README with view command example (if needed)
+- [x] Add view command to user documentation (if exists)
+
+## Polish
+- [x] Ensure consistent formatting and alignment
+- [x] Add helpful footer text referencing list commands
+- [x] Optimize for terminal width considerations
+- [x] Review and refine color choices for accessibility

package/references/openspec/openspec/changes/archive/2025-09-29-add-agents-md-config/proposal.md

@@ -0,0 +1,28 @@
+# Add AGENTS.md Standard Support To Init/Update
+
+## Summary
+- Teach `openspec init` to manage a root-level `AGENTS.md` file using the same marker system as `CLAUDE.md`.
+- Allow `openspec update` to refresh or scaffold that root `AGENTS.md` so AGENTS-compatible tools always receive current instructions.
+- Keep the existing `openspec/AGENTS.md` template as the canonical source while ensuring assistants that read `AGENTS.md` opt-in instructions get the latest guidance automatically.
+
+## Motivation
+The README now points teams to AGENTS.md-compatible assistants, but the CLI only manages `CLAUDE.md`. Projects must hand-roll a root `AGENTS.md` file to benefit from the standard, and updates will drift unless maintainers remember to copy content manually. Extending `init` and `update` closes that gap so OpenSpec actually delivers on the promise of first-class AGENTS support.
+
+## Proposal
+1. Extend the `openspec init` selection flow with an "AGENTS.md standard" option that creates or refreshes a root `AGENTS.md` file wrapped in OpenSpec markers, mirroring the existing CLAUDE integration.
+2. When generating the file, pull the managed content from the same template used in `openspec/AGENTS.md`, ensuring both locations stay in sync.
+3. Update `openspec update` so it always refreshes the root `AGENTS.md` (creating it if missing) alongside `openspec/AGENTS.md` and any other configured assistants.
+4. Document the new behavior in CLI specs and verify marker handling (no duplicates, preserve user content outside the block) with tests for both commands.
+
+## Out of Scope
+- Adding additional AGENTS-specific prompts or workflows beyond the shared instructions block.
+- Non-interactive flags or bulk configuration for multiple standards in one run.
+- Broader restructuring of how templates are stored or loaded.
+
+## Risks & Mitigations
+- **Risk:** Accidentally overwriting user-edited content surrounding the managed block.
+  - **Mitigation:** Reuse the existing marker-update helper shared with `CLAUDE.md`, and add tests that cover files containing custom text before and after the block.
+- **Risk:** Divergence between `openspec/AGENTS.md` and the root file.
+  - **Mitigation:** Source the root file content from the canonical template rather than duplicating strings inline.
+- **Risk:** Confusion about when the file is created.
+  - **Mitigation:** Log creation vs update, and ensure help text references the AGENTS option during `init`.

package/references/openspec/openspec/changes/archive/2025-09-29-add-agents-md-config/specs/cli-init/spec.md

@@ -0,0 +1,71 @@
+## MODIFIED Requirements
+### Requirement: AI Tool Configuration
+The command SHALL configure AI coding assistants with OpenSpec instructions based on user selection.
+
+#### Scenario: Prompting for AI tool selection
+
+- **WHEN** run
+- **THEN** prompt user to select AI tools to configure:
+  - Claude Code (✅ OpenSpec custom slash commands available)
+  - Cursor (✅ OpenSpec custom slash commands available)
+  - AGENTS.md (works with Codex, Amp, Copilot, …)
+
+### Requirement: AI Tool Configuration Details
+The command SHALL properly configure selected AI tools with OpenSpec-specific instructions using a marker system.
+
+#### Scenario: Configuring Claude Code
+
+- **WHEN** Claude Code is selected
+- **THEN** create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+
+#### Scenario: Configuring AGENTS standard
+
+- **WHEN** the AGENTS.md standard is selected
+- **THEN** create or update `AGENTS.md` in the project root directory (not inside openspec/)
+
+#### Scenario: Creating new CLAUDE.md
+
+- **WHEN** CLAUDE.md does not exist
+- **THEN** create new file with OpenSpec content wrapped in markers:
+```markdown
+<!-- OPENSPEC:START -->
+# OpenSpec Project
+
+This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
+
+This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
+
+See @openspec/AGENTS.md for detailed conventions and guidelines.
+<!-- OPENSPEC:END -->
+```
+
+#### Scenario: Creating new AGENTS.md
+
+- **WHEN** AGENTS.md does not exist in the project root
+- **THEN** create new file with OpenSpec content wrapped in markers using the same template as CLAUDE.md
+
+#### Scenario: Updating existing CLAUDE.md
+
+- **WHEN** CLAUDE.md already exists
+- **THEN** preserve all existing content
+- **AND** insert OpenSpec content at the beginning of the file using markers
+- **AND** ensure markers don't duplicate if they already exist
+
+#### Scenario: Updating existing AGENTS.md
+
+- **WHEN** AGENTS.md already exists in the project root
+- **THEN** preserve all existing content
+- **AND** ensure the OpenSpec-managed block at the beginning of the file is refreshed without duplicating markers
+
+#### Scenario: Managing content with markers
+
+- **WHEN** using the marker system
+- **THEN** use `<!-- OPENSPEC:START -->` to mark the beginning of managed content
+- **AND** use `<!-- OPENSPEC:END -->` to mark the end of managed content
+- **AND** allow OpenSpec to update its content without affecting user customizations
+- **AND** preserve all content outside the markers intact
+
+WHY use markers:
+- Users may have existing CLAUDE.md or AGENTS.md instructions they want to keep
+- OpenSpec can update its instructions in future versions
+- Clear boundary between OpenSpec-managed and user-managed content

package/references/openspec/openspec/changes/archive/2025-09-29-add-agents-md-config/specs/cli-update/spec.md

@@ -0,0 +1,41 @@
+## MODIFIED Requirements
+### Requirement: Update Behavior
+The update command SHALL update OpenSpec instruction files to the latest templates in a team-friendly manner.
+
+#### Scenario: Running update command
+
+- **WHEN** a user runs `openspec update`
+- **THEN** the command SHALL:
+  - Check if the `openspec` directory exists
+  - Replace `openspec/AGENTS.md` with the latest template (complete replacement)
+  - Create or refresh a root-level `AGENTS.md` file using the managed marker block (create if missing)
+  - Update **only existing** AI tool configuration files (e.g., CLAUDE.md)
+    - Check each registered AI tool configurator
+    - For each configurator, check if its file exists
+    - Update only files that already exist using their markers
+    - Preserve user content outside markers
+  - Display success message listing updated files
+
+### Requirement: Tool-Agnostic Updates
+The update command SHALL handle file updates in a predictable and safe manner while respecting team tool choices.
+
+#### Scenario: Updating files
+
+- **WHEN** updating files
+- **THEN** completely replace `openspec/AGENTS.md` with the latest template
+- **AND** create or update the root-level `AGENTS.md` using the OpenSpec markers
+- **AND** update only the OpenSpec-managed blocks in **existing** AI tool files using markers
+- **AND** use the default directory name `openspec`
+- **AND** be idempotent (repeated runs have no additional effect)
+- **AND** respect team members' AI tool choices by not creating additional tool files beyond the root `AGENTS.md`
+
+### 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/AGENTS.md` with the latest template
+- **AND** ensure the root-level `AGENTS.md` matches the latest template via the marker block
+- **AND** update existing AI tool configuration files within markers
+- **AND** display the message: "Updated OpenSpec instructions"

package/references/openspec/openspec/changes/archive/2025-09-29-add-agents-md-config/tasks.md

@@ -0,0 +1,17 @@
+# Implementation Tasks
+
+## 1. Extend Init Workflow
+- [x] 1.1 Add an "AGENTS.md standard" option to the `openspec init` tool-selection prompt, respecting the existing UI conventions.
+- [x] 1.2 Generate or refresh a root-level `AGENTS.md` file using the OpenSpec markers when that option is selected, sourcing content from the canonical template.
+
+## 2. Enhance Update Command
+- [x] 2.1 Ensure `openspec update` writes the root `AGENTS.md` from the latest template (creating it if missing) alongside `openspec/AGENTS.md`.
+- [x] 2.2 Update success messaging and logging to reflect creation vs refresh of the AGENTS standard file.
+
+## 3. Shared Template Handling
+- [x] 3.1 Refactor template utilities if necessary so both commands reuse the same content without duplication.
+- [x] 3.2 Add automated tests covering init/update flows for projects with and without an existing `AGENTS.md`, ensuring markers behave correctly.
+
+## 4. Documentation
+- [x] 4.1 Update CLI specs and user-facing docs to describe AGENTS standard support.
+- [x] 4.2 Run `openspec validate add-agents-md-config --strict` and document any notable behavior changes.

package/references/openspec/openspec/changes/archive/2025-09-29-add-multi-agent-init/proposal.md

@@ -0,0 +1,35 @@
+# Allow Additional AI Tool Initialization After Setup
+
+## Summary
+- Let `openspec init` configure new AI coding tools for projects that already contain an OpenSpec structure.
+- Keep the initialization flow safe by skipping structure creation and only generating files for tools the user explicitly selects.
+- Provide clear feedback so users know which tool files were added versus already present.
+
+## Motivation
+Today `openspec init` exits with an error once an `openspec/` directory exists. That protects the directory layout, but it blocks
+teams that start with one assistant (for example, Claude Code) and later want to add another such as Cursor. They have to create
+those files by hand or rerun `init` in a clean clone, which undermines the "easy onboarding" promise. Letting the command extend
+an existing installation keeps the workflow consistent and avoids manual file management.
+
+## Proposal
+1. Detect an existing OpenSpec structure at the start of `openspec init` and branch into an "extend" mode instead of exiting.
+   - Announce that the base structure already exists and that the command will only manage AI tool configuration files.
+   - Keep the existing guard for directories or files we must not overwrite.
+2. Present the usual AI tool selection prompt even in extend mode, showing which tools are already configured.
+   - Skip disabled options that remain "coming soon".
+   - Mark already configured tools as such so users know whether selecting them will refresh or add files.
+3. When the user selects additional tools, generate the same initialization files that a fresh run would create (e.g., Cursor
+   workspace files) while leaving untouched tools intact apart from marker-managed sections.
+   - Do nothing when the user selects no new tools and keep the previous error messaging to avoid silently succeeding.
+4. Summarize the outcome (created, refreshed, skipped) before exiting with code 0 when work was performed.
+   - Include friendly guidance that future updates to shared content still come from `openspec update`.
+
+## Out of Scope
+- Changing how `openspec update` discovers or updates AI tool files.
+- Supporting brand-new AI tools beyond those already wired into the CLI.
+- Adding non-interactive flags for selecting multiple tools in one run (follow-up if needed).
+
+## Risks & Mitigations
+- **User confusion about extend mode** → Explicitly log what will happen before prompting and summarise results afterward.
+- **Accidental overwrites** → Continue using marker-based updates and skip files unless the user chooses that tool.
+- **Inconsistent state if init fails mid-run** → Reuse existing rollback/transaction logic so partial writes clean up.

package/references/openspec/openspec/changes/archive/2025-09-29-add-multi-agent-init/specs/cli-init/spec.md

@@ -0,0 +1,45 @@
+## MODIFIED Requirements
+### Requirement: Safety Checks
+The command SHALL perform safety checks to prevent overwriting existing structures and ensure proper permissions.
+
+#### Scenario: Detecting existing initialization
+- **WHEN** the `openspec/` directory already exists
+- **THEN** inform the user that OpenSpec is already initialized, skip recreating the base structure, and enter an extend mode
+- **AND** continue to the AI tool selection step so additional tools can be configured
+- **AND** display the existing-initialization error message only when the user declines to add any AI tools
+
+### Requirement: Interactive Mode
+The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.
+
+#### Scenario: Displaying interactive menu
+- **WHEN** run in fresh or extend mode
+- **THEN** present a looping select menu that lets users toggle tools with Enter and finish via a "Done" option
+- **AND** label already configured tools with "(already configured)" while keeping disabled options marked "coming soon"
+- **AND** change the prompt copy in extend mode to "Which AI tools would you like to add or refresh?"
+- **AND** display inline instructions clarifying that Enter toggles a tool and selecting "Done" confirms the list
+
+## ADDED Requirements
+### Requirement: Additional AI Tool Initialization
+`openspec init` SHALL allow users to add configuration files for new AI coding assistants after the initial setup.
+
+#### Scenario: Configuring an extra tool after initial setup
+- **GIVEN** an `openspec/` directory already exists and at least one AI tool file is present
+- **WHEN** the user runs `openspec init` and selects a different supported AI tool
+- **THEN** generate that tool's configuration files with OpenSpec markers the same way as during first-time initialization
+- **AND** leave existing tool configuration files unchanged except for managed sections that need refreshing
+- **AND** exit with code 0 and display a success summary highlighting the newly added tool files
+
+### Requirement: Success Output Enhancements
+`openspec init` SHALL summarize tool actions when initialization or extend mode completes.
+
+#### Scenario: Showing tool summary
+- **WHEN** the command completes successfully
+- **THEN** display a categorized summary of tools that were created, refreshed, or skipped (including already-configured skips)
+- **AND** personalize the "Next steps" header using the names of the selected tools, defaulting to a generic label when none remain
+
+### Requirement: Exit Code Adjustments
+`openspec init` SHALL treat extend mode with no selected tools as a guarded error.
+
+#### Scenario: Preventing empty extend runs
+- **WHEN** OpenSpec is already initialized and the user selects no additional tools
+- **THEN** exit with code 1 after showing the existing-initialization guidance message

package/references/openspec/openspec/changes/archive/2025-09-29-add-multi-agent-init/tasks.md

@@ -0,0 +1,16 @@
+# Implementation Tasks
+
+## 1. Extend Init Guard
+- [x] 1.1 Detect existing OpenSpec structures at the start of `openspec init` and enter an extend mode instead of failing.
+- [x] 1.2 Log that core scaffolding will be skipped while still protecting against missing write permissions.
+
+## 2. Update AI Tool Selection
+- [x] 2.1 Present AI tool choices even in extend mode, indicating which tools are already configured.
+- [x] 2.2 Ensure disabled "coming soon" tools remain non-selectable.
+
+## 3. Generate Additional Tool Files
+- [x] 3.1 Create configuration files for newly selected tools while leaving untouched tools unaffected apart from marker-managed sections.
+- [x] 3.2 Summarize created, refreshed, and skipped tools before exiting with the appropriate code.
+
+## 4. Verification
+- [x] 4.1 Add tests covering rerunning `openspec init` to add another tool and the scenario where the user declines to add anything.

package/references/openspec/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md

@@ -0,0 +1,119 @@
+# Add Slash Command Support for Coding Agents
+
+## Summary
+- Enable OpenSpec to generate and update custom slash commands for supported coding agents (Claude Code and Cursor).
+- Provide three slash commands aligned with OpenSpec's workflow: proposal (start a change proposal), apply (implement), and archive.
+- Share slash command templating between agents to make future extensions simple.
+
+## Motivation
+Developers use different coding agents and editors. Having consistent slash commands across tools for the OpenSpec workflow reduces friction and ensures a standard way to trigger the workflow. Supporting both Claude Code and Cursor now lays a foundation for future agents that introduce slash command features.
+
+## Proposal
+1. During `openspec init`, when a user selects a supported tool, generate slash command configuration for three OpenSpec workflow stages:
+   - Claude (namespaced): `/openspec/proposal`, `/openspec/apply`, `/openspec/archive`.
+   - Cursor (flat, prefixed): `/openspec-proposal`, `/openspec-apply`, `/openspec-archive`.
+   - Semantics:
+     - Create – scaffold a change (ID, `proposal.md`, `tasks.md`, delta specs); validate strictly.
+     - Apply – implement an approved change; complete tasks; validate strictly.
+     - Archive – archive after deployment; update specs if needed.
+   - Each command file MUST embed concise, step-by-step instructions sourced from `openspec/README.md` (see Template Content section).
+2. Store slash command files per tool:
+   - Claude Code: `.claude/commands/openspec/{proposal,apply,archive}.md`
+   - Cursor: `.cursor/commands/{openspec-proposal,openspec-apply,openspec-archive}.md`
+   - Ensure nested directories are created.
+3. Command file format and metadata:
+   - Use Markdown with optional YAML frontmatter for tool metadata (name/title, description, category/tags) when supported by the tool.
+   - Place OpenSpec markers around the body only, never inside frontmatter.
+   - Keep the visible slash name, file name, and any frontmatter `name`/`id` consistently aligned (e.g., `proposal`, `openspec-proposal`).
+   - Namespacing: categorize these under “OpenSpec” and prefer unique IDs (e.g., `openspec-proposal`) to avoid collisions.
+4. Centralize templates: define command bodies once and reuse across tools; apply minimal per-tool wrappers (frontmatter, categories, filenames).
+5. During `openspec update`, refresh only existing slash command files (per-file basis) within markers; do not create missing files or new tools.
+
+## Design Ideas
+- Introduce `SlashCommandConfigurator` to manage multiple files per tool.
+  - Expose targets rather than a single `configFileName` (e.g., `getTargets(): Array<{ path: string; kind: 'slash'; id: string }>`).
+  - Provide `generateAll(projectPath, openspecDir)` for init and `updateExisting(projectPath, openspecDir)` for update.
+- Per-tool adapters add only frontmatter and pathing; bodies come from shared templates.
+- Templates live in `TemplateManager` with helpers that extract concise, authoritative snippets from `openspec/README.md`.
+- Update flow logs per-file results so users see exactly which slash files were refreshed.
+
+### Marker Placement
+- Markers MUST wrap only the Markdown body contents:
+  - Frontmatter (if present) goes first.
+  - Then `<!-- OPENSPEC:START -->` … body … `<!-- OPENSPEC:END -->`.
+  - Avoid inserting markers into the YAML block to prevent parse errors.
+
+### Idempotency and Creation Rules
+- `init`: create all three files for the chosen tool(s) once; subsequent `init` runs are no-ops for existing files.
+- `update`: refresh only files that exist; skip missing ones without creating new files.
+- Directory creation for `.claude/commands/openspec/` and `.cursor/commands/` is the configurator’s responsibility.
+
+### Command Naming & UX
+- Claude Code: use namespacing in the slash itself for readability and grouping: `/openspec/proposal`, `/openspec/apply`, `/openspec/archive`.
+- Cursor: use flat names with an `openspec-` prefix: `/openspec-proposal`, `/openspec-apply`, `/openspec-archive`. Group via `category: OpenSpec` when supported.
+- Consistency: align file names, visible slash names, and any frontmatter `id` (e.g., `id: openspec-apply`).
+- Migration: do not rename existing commands during `update`; apply new naming only on `init` (or via an explicit migrate step).
+
+## Open Questions
+- Validate exact metadata/frontmatter supported by each tool version; if unsupported, omit frontmatter and ship Markdown body only.
+- Confirm the final Cursor command file location for the targeted versions; fall back to Markdown-only if Cursor does not parse frontmatter.
+- Evaluate additional commands beyond the initial three (e.g., `/show-change`, `/validate-all`) based on user demand.
+
+## Alternatives
+- Hard-code slash command text per tool (rejected: duplicates content; increases maintenance).
+- Delay Cursor support until its config stabilizes (partial accept): gate Cursor behind a feature flag until verified in real environments.
+
+## Risks
+- Tool configuration formats may change, requiring updates to wrappers/frontmatter.
+- Incorrect paths or categories can hide commands; add path existence checks and clear logging.
+- Marker misuse (inside frontmatter) can break parsing; enforce placement rules in tests.
+
+## Future Work
+- Support additional editors/agents that expose slash command APIs.
+- Allow users to customize command names and categories during `openspec init`.
+- Provide a dedicated command to regenerate slash commands without running full `update`.
+
+## File Format Examples
+The following examples illustrate expected structure. If a tool does not support frontmatter, omit the YAML block and keep only the markers + body.
+
+### Claude Code: `.claude/commands/openspec/proposal.md`
+```markdown
+---
+name: OpenSpec: Proposal
+description: Scaffold a new OpenSpec change and validate strictly.
+category: OpenSpec
+tags: [openspec, change]
+---
+<!-- OPENSPEC:START -->
+...command body from shared template...
+<!-- OPENSPEC:END -->
+```
+
+Slash invocation: `/openspec/proposal` (namespaced)
+
+### Cursor: `.cursor/commands/openspec-proposal.md`
+```markdown
+---
+name: /openspec-proposal
+id: openspec-proposal
+category: OpenSpec
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+...command body from shared template...
+<!-- OPENSPEC:END -->
+```
+
+Slash invocation: `/openspec-proposal` (flat, prefixed)
+
+## Template Content
+Templates should be brief, actionable, and sourced from `openspec/README.md` to avoid duplication. Each command body includes:
+- Guardrails: ask 1–2 clarifying questions if needed; follow minimal-complexity rules; use `pnpm` for Node projects.
+- Step list tailored to the workflow stage (proposal, apply, archive), including strict validation commands.
+- Pointers to `openspec show`, `openspec list`, and troubleshooting tips when validation fails.
+
+## Testing Strategy
+- Golden snapshots for generated files per tool (frontmatter + markers + body).
+- Partial presence tests: if 1–2 files exist, `update` only refreshes those and does not create missing ones.
+- Marker placement tests: ensure markers never appear inside frontmatter; cover missing/duplicated marker recovery behavior.
+- Logging tests: `update` reports per-file updates for slash commands.

package/references/openspec/openspec/changes/archive/2025-09-29-add-slash-command-support/specs/cli-init/spec.md

@@ -0,0 +1,21 @@
+## ADDED 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

package/references/openspec/openspec/changes/archive/2025-09-29-add-slash-command-support/specs/cli-update/spec.md

@@ -0,0 +1,22 @@
+## ADDED 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/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: 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-09-29-add-slash-command-support/tasks.md

@@ -0,0 +1,20 @@
+# Implementation Tasks
+
+## 1. Templates and Configurators
+- [x] 1.1 Create shared templates for the Proposal, Apply, and Archive commands with instructions for each workflow stage from `openspec/README.md`.
+- [x] 1.2 Implement a `SlashCommandConfigurator` base and tool-specific configurators for Claude Code and Cursor.
+
+## 2. Claude Code Integration
+- [x] 2.1 Generate `.claude/commands/openspec/{proposal,apply,archive}.md` during `openspec init` using shared templates.
+- [x] 2.2 Update existing `.claude/commands/openspec/*` files during `openspec update`.
+
+## 3. Cursor Integration
+- [x] 3.1 Generate `.cursor/commands/{openspec-proposal,openspec-apply,openspec-archive}.md` during `openspec init` using shared templates.
+- [x] 3.2 Update existing `.cursor/commands/*` files during `openspec update`.
+
+## 4. Verification
+- [x] 4.1 Add tests verifying slash command files are created and updated correctly.
+
+## 5. OpenCode Integration
+- [x] 5.1 Generate `.opencode/commands/{openspec-proposal,openspec-apply,openspec-archive}.md` during `openspec init` using shared templates.
+- [x] 5.2 Update existing `.opencode/commands/*` files during `openspec update`.