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

CLI Init Specification

Purpose

The openspec init command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants.

Requirements

Requirement: Progress Indicators

The command SHALL display progress indicators during initialization to provide clear feedback about each step.

Scenario: Displaying initialization progress

• WHEN executing initialization steps
• THEN validate environment silently in background (no output unless error)
• AND display progress with ora spinners:
  • Show spinner: "⠋ Creating OpenSpec structure..."
  • Then success: "✔ OpenSpec structure created"
  • Show spinner: "⠋ Configuring AI tools..."
  • Then success: "✔ AI tools configured"

Requirement: Directory Creation

The command SHALL create the complete OpenSpec directory structure with all required directories and files.

Scenario: Creating OpenSpec structure

• WHEN openspec init is executed
• THEN create the following directory structure:

openspec/
├── project.md
├── AGENTS.md
├── specs/
└── changes/
    └── archive/

Requirement: File Generation

The command SHALL generate required template files with appropriate content for immediate use.

Scenario: Generating template files

• WHEN initializing OpenSpec
• THEN generate openspec/AGENTS.md containing complete OpenSpec instructions for AI assistants
• AND generate project.md with project context template

Requirement: AI Tool Configuration

The command SHALL configure AI coding assistants with OpenSpec instructions using a marker system.

Scenario: Prompting for AI tool selection

• WHEN run interactively
• THEN prompt the user with "Which AI tools do you use?" using a multi-select menu
• AND list every available tool with a checkbox:
  • Claude Code (creates or refreshes CLAUDE.md and slash commands)
  • Cursor (creates or refreshes .cursor/commands/* slash commands)
  • OpenCode (creates or refreshes .opencode/command/openspec-*.md slash commands)
  • Windsurf (creates or refreshes .windsurf/workflows/openspec-*.md workflows)
  • Kilo Code (creates or refreshes .kilocode/workflows/openspec-*.md workflows)
  • Codex (creates or refreshes global prompts at ~/.codex/prompts/openspec-*.md)
  • AGENTS.md standard (creates or refreshes AGENTS.md with OpenSpec markers)
• AND show "(already configured)" beside tools whose managed files exist so users understand selections will refresh content
• AND treat disabled tools as "coming soon" and keep them unselectable
• AND allow confirming with Enter after selecting one or more tools

Requirement: AI Tool Configuration Details

The command SHALL properly configure selected AI tools with OpenSpec-specific instructions using a marker system.

Scenario: Configuring Claude Code

• WHEN Claude Code is selected
• THEN create or update CLAUDE.md in the project root directory (not inside openspec/)
• AND populate the managed block with a short stub that points teammates to @/openspec/AGENTS.md

Scenario: Creating new CLAUDE.md

• WHEN CLAUDE.md does not exist
• THEN create new file with stub instructions wrapped in markers so the full workflow stays in openspec/AGENTS.md:

<!-- OPENSPEC:START -->
# OpenSpec Instructions

This project uses OpenSpec to manage AI assistant workflows.

- Full guidance lives in '@/openspec/AGENTS.md'.
- Keep this managed block so 'openspec update' can refresh the instructions.
<!-- OPENSPEC:END -->

Requirement: Interactive Mode

The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.

Scenario: Displaying interactive menu

• WHEN run in fresh or extend mode
• THEN present a looping select menu that lets users toggle tools with Space and review selections with Enter
• AND when Enter is pressed on a highlighted selectable tool that is not already selected, automatically add it to the selection before moving to review so the highlighted tool is configured
• AND label already configured tools with "(already configured)" while keeping disabled options marked "coming soon"
• AND change the prompt copy in extend mode to "Which AI tools would you like to add or refresh?"
• AND display inline instructions clarifying that Space toggles tools and Enter selects the highlighted tool before reviewing selections

Requirement: Safety Checks

The command SHALL perform safety checks to prevent overwriting existing structures and ensure proper permissions.

Scenario: Detecting existing initialization

• WHEN the openspec/ directory already exists
• THEN inform the user that OpenSpec is already initialized, skip recreating the base structure, and enter an extend mode
• AND continue to the AI tool selection step so additional tools can be configured
• AND display the existing-initialization error message only when the user declines to add any AI tools

Requirement: Success Output

The command SHALL provide clear, actionable next steps upon successful initialization.

Scenario: Displaying success message

• WHEN initialization completes successfully
• THEN include prompt: "Please explain the OpenSpec workflow from openspec/AGENTS.md and how I should work with you on this project"

Requirement: Exit Codes

The command SHALL use consistent exit codes to indicate different failure modes.

Scenario: Returning exit codes

• WHEN the command completes
• THEN return appropriate exit code:
  • 0: Success
  • 1: General error (including when OpenSpec directory already exists)
  • 2: Insufficient permissions (reserved for future use)
  • 3: User cancelled operation (reserved for future use)

Requirement: Additional AI Tool Initialization

openspec init SHALL allow users to add configuration files for new AI coding assistants after the initial setup.

Scenario: Configuring an extra tool after initial setup

• GIVEN an openspec/ directory already exists and at least one AI tool file is present
• WHEN the user runs openspec init and selects a different supported AI tool
• THEN generate that tool's configuration files with OpenSpec markers the same way as during first-time initialization
• AND leave existing tool configuration files unchanged except for managed sections that need refreshing
• AND exit with code 0 and display a success summary highlighting the newly added tool files

Requirement: Success Output Enhancements

openspec init SHALL summarize tool actions when initialization or extend mode completes.

Scenario: Showing tool summary

• WHEN the command completes successfully
• THEN display a categorized summary of tools that were created, refreshed, or skipped (including already-configured skips)
• AND personalize the "Next steps" header using the names of the selected tools, defaulting to a generic label when none remain

Requirement: Exit Code Adjustments

openspec init SHALL treat extend mode with no selected tools as a guarded error.

Scenario: Preventing empty extend runs

• WHEN OpenSpec is already initialized and the user selects no additional tools
• THEN exit with code 1 after showing the existing-initialization guidance message

Requirement: Slash Command Configuration

The init command SHALL generate slash command files for supported editors using shared templates.

Scenario: Generating slash commands for Claude Code

• WHEN the user selects Claude Code during initialization
• THEN create .claude/commands/openspec/proposal.md, .claude/commands/openspec/apply.md, and .claude/commands/openspec/archive.md
• AND populate each file from shared templates so command text matches other tools
• AND each template includes instructions for the relevant OpenSpec workflow stage

Scenario: Generating slash commands for Cursor

• WHEN the user selects Cursor during initialization
• THEN create .cursor/commands/openspec-proposal.md, .cursor/commands/openspec-apply.md, and .cursor/commands/openspec-archive.md
• AND populate each file from shared templates so command text matches other tools
• AND each template includes instructions for the relevant OpenSpec workflow stage

Scenario: Generating slash commands for OpenCode

• WHEN the user selects OpenCode during initialization
• THEN create .opencode/commands/openspec-proposal.md, .opencode/commands/openspec-apply.md, and .opencode/commands/openspec-archive.md
• AND populate each file from shared templates so command text matches other tools
• AND each template includes instructions for the relevant OpenSpec workflow stage

Scenario: Generating slash commands for Windsurf

• WHEN the user selects Windsurf during initialization
• THEN create .windsurf/workflows/openspec-proposal.md, .windsurf/workflows/openspec-apply.md, and .windsurf/workflows/openspec-archive.md
• AND populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
• AND each template includes instructions for the relevant OpenSpec workflow stage

Scenario: Generating slash commands for Kilo Code

• WHEN the user selects Kilo Code during initialization
• THEN create .kilocode/workflows/openspec-proposal.md, .kilocode/workflows/openspec-apply.md, and .kilocode/workflows/openspec-archive.md
• AND populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
• AND each template includes instructions for the relevant OpenSpec workflow stage

Scenario: Generating slash commands for Codex

• WHEN the user selects Codex during initialization
• THEN create global prompt files at ~/.codex/prompts/openspec-proposal.md, ~/.codex/prompts/openspec-apply.md, and ~/.codex/prompts/openspec-archive.md (or under $CODEX_HOME/prompts if set)
• AND populate each file from shared templates that map the first numbered placeholder ($1) to the primary user input (e.g., change identifier or question text)
• AND wrap the generated content in OpenSpec markers so openspec update can refresh the prompts without touching surrounding custom notes

Scenario: Generating slash commands for GitHub Copilot

• WHEN the user selects GitHub Copilot during initialization
• THEN create .github/prompts/openspec-proposal.prompt.md, .github/prompts/openspec-apply.prompt.md, and .github/prompts/openspec-archive.prompt.md
• AND populate each file with YAML frontmatter containing a description field that summarizes the workflow stage
• AND include $ARGUMENTS placeholder to capture user input
• AND wrap the shared template body with OpenSpec markers so openspec update can refresh the content
• AND each template includes instructions for the relevant OpenSpec workflow stage

Requirement: Non-Interactive Mode

The command SHALL support non-interactive operation through command-line options for automation and CI/CD use cases.

Scenario: Select all tools non-interactively

• WHEN run with --tools all
• THEN automatically select every available AI tool without prompting
• AND proceed with initialization using the selected tools

Scenario: Select specific tools non-interactively

• WHEN run with --tools claude,cursor
• THEN parse the comma-separated tool IDs and validate against available tools
• AND proceed with initialization using only the specified valid tools

Scenario: Skip tool configuration non-interactively

• WHEN run with --tools none
• THEN skip AI tool configuration entirely
• AND only create the OpenSpec directory structure and template files

Scenario: Invalid tool specification

• WHEN run with --tools containing any IDs not present in the AI tool registry
• THEN exit with code 1 and display available values (all, none, or the supported tool IDs)

Scenario: Help text lists available tool IDs

• WHEN displaying CLI help for openspec init
• THEN show the --tools option description with the valid values derived from the AI tool registry

Why

Manual creation of OpenSpec structure is error-prone and creates adoption friction. A standardized init command ensures:

• Consistent structure across all projects
• Proper AI instruction files are always included
• Quick onboarding for new projects
• Clear conventions from the start