diff --git a/openspec/changes/add-opencode-slash-commands/proposal.md b/openspec/changes/add-opencode-slash-commands/proposal.md new file mode 100644 index 00000000..614d0de2 --- /dev/null +++ b/openspec/changes/add-opencode-slash-commands/proposal.md @@ -0,0 +1,35 @@ +# Add OpenCode Slash Command Support + +## Summary +- Extend OpenSpec's slash command scaffolding to support OpenCode's `.opencode/command/` markdown commands alongside Claude and Cursor. +- Generate and refresh three workflow-aligned commands (`openspec-proposal`, `openspec-apply`, `openspec-archive`) using the shared templates already used by other agents. +- Ensure OpenCode appears in the CLI tool selection flow so teams can opt into slash command automation during `init` and keep them updated via `update`. + +## Motivation +Teams adopting OpenSpec increasingly rely on OpenCode's slash command system to standardize how collaborators invoke AI helpers. We already provide purpose-built commands for Claude and Cursor to guide proposal, implementation, and archiving flows. Without equivalent commands in OpenCode, mixed-tool teams must recreate these instructions manually, leading to drift and inconsistent workflows. Adding first-class OpenCode support keeps multi-agent teams aligned and reduces setup friction for users migrating between tools. + +## Proposal +1. **Tool selection** + - Add OpenCode as an available configurator in the interactive `openspec init` flow (and any non-interactive selection plumbing). + - Describe the option as creating `.opencode/command/*.md` slash commands so users understand the outcome. +2. **Slash command generation** + - Reuse the shared slash command template bodies and produce three files under `.opencode/command/`: `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`. + - Wrap command content in OpenSpec markers placed after any YAML frontmatter so future updates remain idempotent. + - Populate frontmatter with at minimum a `description` summarizing the workflow stage; allow optional OpenCode-specific keys (`agent`, `model`) to remain user-editable outside the markers. +3. **Slash command updates** + - During `openspec update`, detect existing `.opencode/command/openspec-*.md` files and refresh only the managed sections using the same templates. + - Skip creation if the files are missing, mirroring current behavior for other tools. +4. **User feedback & documentation** + - Reflect OpenCode updates in CLI logging alongside Claude and Cursor so users see which commands changed. + - Update any user-facing success messaging or docs snippets that enumerate supported slash-command tools. + +## Open Questions +- Should we scaffold default `agent` and `model` values in the frontmatter, or leave them blank so teams can decide which OpenCode agent executes each command? +- Do we need a migration strategy if existing OpenCode commands already exist with different filenames or markers? + +## Out of Scope +- Adding additional OpenSpec commands beyond the core proposal/apply/archive trio. +- Building a standalone command to regenerate slash commands outside of `init`/`update`. + +## Dependencies +- Shares the slash command template system introduced in `add-slash-command-support`; confirm the templates can emit OpenCode-specific wrappers without duplication. diff --git a/openspec/changes/add-opencode-slash-commands/specs/cli-init/spec.md b/openspec/changes/add-opencode-slash-commands/specs/cli-init/spec.md new file mode 100644 index 00000000..4b18af31 --- /dev/null +++ b/openspec/changes/add-opencode-slash-commands/specs/cli-init/spec.md @@ -0,0 +1,64 @@ +## 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 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) + - 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: AI Tool Configuration Details + +The command SHALL properly configure selected AI tools with OpenSpec-specific instructions using a marker system. + +#### Scenario: Configuring OpenCode + +- **WHEN** OpenCode is selected +- **THEN** create or update `.opencode/command/openspec-proposal.md`, `.opencode/command/openspec-apply.md`, and `.opencode/command/openspec-archive.md` +- **AND** ensure the `command/` directory exists before writing files +- **AND** place OpenSpec markers around the shared command body while leaving any YAML frontmatter intact for user customization +- **AND** align visible slash names, filenames, and any frontmatter identifiers (e.g., `/openspec-proposal`, `openspec-proposal.md`) + +### Requirement: Interactive Mode + +The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions. + +#### Scenario: Displaying interactive menu + +- **WHEN** run +- **THEN** prompt the user with: "Which AI tools do you use?" +- **AND** show a checkbox-based multi-select menu with available tools (Claude Code, Cursor, OpenCode, AGENTS.md standard) +- **AND** show disabled options as "coming soon" (not selectable) +- **AND** display inline help indicating Space toggles selections and Enter confirms + +## 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/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 +- **AND** place OpenSpec markers after any YAML frontmatter so updates remain idempotent diff --git a/openspec/changes/add-opencode-slash-commands/specs/cli-update/spec.md b/openspec/changes/add-opencode-slash-commands/specs/cli-update/spec.md new file mode 100644 index 00000000..288bc36a --- /dev/null +++ b/openspec/changes/add-opencode-slash-commands/specs/cli-update/spec.md @@ -0,0 +1,22 @@ +## 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** keep OpenSpec markers wrapped around the command body so user frontmatter stays intact + +#### Scenario: Missing slash command file +- **WHEN** a tool lacks a slash command file +- **THEN** do not create a new file during update diff --git a/openspec/changes/add-opencode-slash-commands/tasks.md b/openspec/changes/add-opencode-slash-commands/tasks.md new file mode 100644 index 00000000..4823dc3d --- /dev/null +++ b/openspec/changes/add-opencode-slash-commands/tasks.md @@ -0,0 +1,12 @@ +# Tasks + +- [ ] 1. Update the CLI tool registry and interactive prompts to list OpenCode as a configurable assistant. + - [ ] 1.1 Ensure non-interactive selections (flags/env) accept OpenCode identifiers. +- [ ] 2. Extend the slash command configurator to emit OpenCode targets using the shared templates. + - [ ] 2.1 Generate `.opencode/command/openspec-{proposal,apply,archive}.md` with proper marker placement. + - [ ] 2.2 Populate descriptive frontmatter while leaving user-editable metadata outside the managed block. +- [ ] 3. Teach `openspec update` to detect and refresh existing OpenCode command files without creating new ones. + - [ ] 3.1 Log per-file update results alongside other tools. +- [ ] 4. Add automated coverage (or golden fixtures) for OpenCode generation and update flows. + - [ ] 4.1 Include mixed-tool scenarios where only some commands exist to confirm update skips missing files. +- [ ] 5. Refresh user-facing docs or success messaging that enumerates slash-command capable tools.