mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
f3eed6fab8
Archived: - enhance-validation-error-messages (updated cli-validate spec) - improve-agent-instruction-usability (created docs-agent-instructions spec) - update-cli-init-root-agents (updated cli-init and cli-update specs) - update-release-automation (no spec updates)
133 lines
6.1 KiB
Markdown
133 lines
6.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.
|
|
|
|
#### 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
|
|
|
|
## 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)
|