fission-ai__openspec/openspec/specs/cli-update/spec.md

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)