mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
938d03be9a
Add prominent restart instruction in success message to inform users they need to restart their IDE/coding tool for slash commands to appear. Applies to all tools when slash commands are created or refreshed. Also updates cli-init spec to document the restart instruction requirement.
191 lines
10 KiB
Markdown
191 lines
10 KiB
Markdown
# Update Command Specification
|
|
|
|
## Purpose
|
|
|
|
As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions.
|
|
## 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** replace `openspec/AGENTS.md` with the latest template
|
|
- **AND** if a root-level stub (`AGENTS.md`/`CLAUDE.md`) exists, refresh it so it points to `@/openspec/AGENTS.md`
|
|
|
|
### Requirement: Prerequisites
|
|
|
|
The command SHALL require an existing OpenSpec structure before allowing updates.
|
|
|
|
#### Scenario: Checking prerequisites
|
|
|
|
- **GIVEN** the command requires an existing `openspec` directory (created by `openspec init`)
|
|
- **WHEN** the `openspec` directory does not exist
|
|
- **THEN** display error: "No OpenSpec directory found. Run 'openspec init' first."
|
|
- **AND** exit with code 1
|
|
|
|
### Requirement: File Handling
|
|
The update command SHALL handle file updates in a predictable and safe manner.
|
|
|
|
#### Scenario: Updating files
|
|
- **WHEN** updating files
|
|
- **THEN** completely replace `openspec/AGENTS.md` with the latest template
|
|
- **AND** if a root-level stub exists, update the managed block content so it keeps directing teammates to `@/openspec/AGENTS.md`
|
|
|
|
### Requirement: Tool-Agnostic Updates
|
|
The update command SHALL refresh OpenSpec-managed files in a predictable manner while respecting each team's chosen tooling.
|
|
|
|
#### Scenario: Updating files
|
|
- **WHEN** updating files
|
|
- **THEN** completely replace `openspec/AGENTS.md` with the latest template
|
|
- **AND** create or refresh the root-level `AGENTS.md` stub using the managed marker block, even if the file was previously absent
|
|
- **AND** update only the OpenSpec-managed sections inside existing AI tool files, leaving user-authored content untouched
|
|
- **AND** avoid creating new native-tool configuration files (slash commands, CLAUDE.md, etc.) unless they already exist
|
|
|
|
### 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** if a root-level stub exists, refresh it so it still directs contributors to `@/openspec/AGENTS.md`
|
|
|
|
### Requirement: Slash Command Updates
|
|
The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.
|
|
|
|
#### 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 CodeBuddy Code
|
|
- **WHEN** `.codebuddy/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 Cline
|
|
- **WHEN** `.clinerules/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
|
|
- **THEN** refresh each file using shared templates
|
|
- **AND** include Cline-specific Markdown heading frontmatter
|
|
- **AND** ensure templates include instructions for the relevant workflow stage
|
|
|
|
#### Scenario: Updating slash commands for Crush
|
|
- **WHEN** `.crush/commands/` contains `openspec/proposal.md`, `openspec/apply.md`, and `openspec/archive.md`
|
|
- **THEN** refresh each file using shared templates
|
|
- **AND** include Crush-specific frontmatter with OpenSpec category and tags
|
|
- **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 Factory Droid
|
|
- **WHEN** `.factory/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
|
|
- **THEN** refresh each file using the shared Factory templates that include YAML frontmatter for the `description` and `argument-hint` fields
|
|
- **AND** ensure the template body retains the `$ARGUMENTS` placeholder so user input keeps flowing into droid
|
|
- **AND** update only the content inside the OpenSpec managed markers, leaving any unmanaged notes untouched
|
|
- **AND** skip creating missing files during update
|
|
|
|
#### 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
|
|
- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
|
|
|
|
#### 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: Updating slash commands for Gemini CLI
|
|
- **WHEN** `.gemini/commands/openspec/` contains `proposal.toml`, `apply.toml`, and `archive.toml`
|
|
- **THEN** refresh the body of each file using the shared proposal/apply/archive templates
|
|
- **AND** replace only the content between `<!-- OPENSPEC:START -->` and `<!-- OPENSPEC:END -->` markers inside the `prompt = """` block so the TOML framing (`description`, `prompt`) stays intact
|
|
- **AND** skip creating any missing `.toml` files during update; only pre-existing Gemini commands are refreshed
|
|
|
|
#### Scenario: Updating slash commands for iFlow CLI
|
|
- **WHEN** `.iflow/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
|
|
- **THEN** refresh each file using shared templates
|
|
- **AND** preserve the YAML frontmatter with `name`, `id`, `category`, and `description` fields
|
|
- **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
|
|
|
|
### Requirement: Archive Command Argument Support
|
|
The archive slash command template SHALL support optional change ID arguments for tools that support `$ARGUMENTS` placeholder.
|
|
|
|
#### Scenario: Archive command with change ID argument
|
|
- **WHEN** a user invokes `/openspec:archive <change-id>` with a change ID
|
|
- **THEN** the template SHALL instruct the AI to validate the provided change ID against `openspec list`
|
|
- **AND** use the provided change ID for archiving if valid
|
|
- **AND** fail fast if the provided change ID doesn't match an archivable change
|
|
|
|
#### Scenario: Archive command without argument (backward compatibility)
|
|
- **WHEN** a user invokes `/openspec:archive` without providing a change ID
|
|
- **THEN** the template SHALL instruct the AI to identify the change ID from context or by running `openspec list`
|
|
- **AND** proceed with the existing behavior (maintaining backward compatibility)
|
|
|
|
#### Scenario: OpenCode archive template generation
|
|
- **WHEN** generating the OpenCode archive slash command file
|
|
- **THEN** include the `$ARGUMENTS` placeholder in the frontmatter
|
|
- **AND** wrap it in a clear structure like `<ChangeId>\n $ARGUMENTS\n</ChangeId>` to indicate the expected argument
|
|
- **AND** include validation steps in the template body to check if the change ID is valid
|
|
|
|
## Edge Cases
|
|
|
|
### Requirement: Error Handling
|
|
|
|
The command SHALL handle edge cases gracefully.
|
|
|
|
#### Scenario: File permission errors
|
|
|
|
- **WHEN** file write fails
|
|
- **THEN** let the error bubble up naturally with file path
|
|
|
|
#### Scenario: Missing AI tool files
|
|
|
|
- **WHEN** an AI tool configuration file doesn't exist
|
|
- **THEN** skip updating that file
|
|
- **AND** do not create it
|
|
|
|
#### Scenario: Custom directory names
|
|
|
|
- **WHEN** considering custom directory names
|
|
- **THEN** not supported in this change
|
|
- **AND** the default directory name `openspec` SHALL be used
|
|
|
|
## Success Criteria
|
|
|
|
Users SHALL be able to:
|
|
- Update OpenSpec instructions with a single command
|
|
- Get the latest AI agent instructions
|
|
- See clear confirmation of the update
|
|
|
|
The update process SHALL be:
|
|
- Simple and fast (no version checking)
|
|
- Predictable (same result every time)
|
|
- Self-contained (no network required)
|