mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
65ffe1ce64
Merged and archived four concurrent changes that modified the same specs: - add-cline-support: Added Cline AI tool configuration - add-crush-support: Added Crush AI tool configuration - add-factory-slash-commands: Added Factory Droid slash commands - add-archive-command-arguments: Added archive command argument support Changes to cli-init/spec.md: - Added Cline and CodeBuddy Code configuration scenarios - Added slash command scenarios for CodeBuddy Code, Cline, Crush, Factory Droid Changes to cli-update/spec.md: - Added update scenarios for CodeBuddy Code, Cline, Crush, Factory Droid - Added Archive Command Argument Support requirement - Modified OpenCode scenario to support $ARGUMENTS placeholder This required manual intervention to prevent data loss from OpenSpec's requirement-level replacement during archiving. The archive operations initially overwrote scenarios from earlier changes, requiring restoration of all missing content to preserve complete spec state. All four changes successfully archived to openspec/changes/archive/.
178 lines
9.1 KiB
Markdown
178 lines
9.1 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: 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)
|