mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
f8eca37796
* feat(init): slim root agent instructions * Fix marker updates to ignore inline mentions * styling updates * update instructions * fix tests
112 lines
4.6 KiB
Markdown
112 lines
4.6 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 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** update the root-level `AGENTS.md` using the OpenSpec markers only when that file already exists, keeping the stub content that links to `@/openspec/AGENTS.md`
|
|
- **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`
|
|
- **AND** do not create new root-level stub files when none are present
|
|
|
|
### 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: 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)
|