* feat(cli): add openspec config command for global configuration management
Implements the `openspec config` command with subcommands:
- `path`: Show config file location
- `list [--json]`: Show all current settings
- `get <key>`: Get a specific value (raw output for scripting)
- `set <key> <value> [--string]`: Set a value with auto type coercion
- `unset <key>`: Remove a key (revert to default)
- `reset --all [-y]`: Reset configuration to defaults
- `edit`: Open config in $EDITOR/$VISUAL
Key features:
- Dot notation for nested key access (e.g., featureFlags.someFlag)
- Auto type coercion (true/false → boolean, numbers → number)
- --string flag to force string storage
- Zod schema validation with unknown field passthrough
- Reserved --scope flag for future project-local config
- Windows-compatible editor spawning with proper path quoting
- Shell completion registry integration
* test(config): add additional unit tests for validation and coercion
- Add tests for unknown fields with various types
- Add test to verify error message path for featureFlags
- Add test for number values rejection in featureFlags
- Add config set simulation tests to verify full coerce → set → validate flow
* fix(config): avoid shell parsing in config edit to handle paths with spaces
Use spawn with shell: false and pass configPath as an argument instead
of building a shell command string. This correctly handles spaces in
both the EDITOR path and config file path on all platforms.
* chore(openspec): archive add-config-command and create cli-config spec
Move completed change to archive and apply spec deltas to create
the cli-config specification documenting the config command interface.
* Validate config keys on set
Fixes#367
The CLI was hanging when run as a pre-commit hook because @inquirer/prompts
was statically imported at module load time. Even when prompts were never
called (e.g., `openspec validate --specs --no-interactive`), the import
itself could set up stdin references that prevented clean process exit
when stdin was piped.
Changes:
- Convert all static `@inquirer/prompts` imports to dynamic imports
- Dynamically import `InitCommand` (which uses `@inquirer/core`)
- Update `isInteractive()` to accept options object with both
`noInteractive` and Commander's negated `interactive` property
- Handle empty validation queue with proper exit code
Now when running in non-interactive mode, the inquirer modules are never
loaded, allowing the process to exit cleanly after completion.
Prioritize XDG_CONFIG_HOME on Windows to fix test environment overrides.
Previously, Windows would always use APPDATA regardless of XDG_CONFIG_HOME,
causing tests to fail. Now XDG_CONFIG_HOME is checked first on all platforms
before falling back to platform-specific defaults.
Also update the Windows APPDATA test to explicitly clear XDG_CONFIG_HOME
when testing the fallback behavior.
* feat(core): implement global config directory with XDG support
Add new global-config module following XDG Base Directory Specification with platform-specific fallbacks (Unix: ~/.config/openspec, Windows: %APPDATA%/openspec). Includes config loading with defaults, config saving with directory creation, and full test coverage. Archive add-global-config-dir change.
* docs(spec): add Purpose section to global-config spec
Replace placeholder text with a concise description of what the spec governs, its scope, and high-level objectives.
- Fix canWriteFile to use fs.access with W_OK flag instead of Unix-style
permission bits (stats.mode & 0o222) which don't work on Windows
- Update test paths to use platform-specific invalid paths that fail on
both Unix and Windows
- Use regex for path separator matching in test assertions
* shell completions for zsh
* after code review changes
* expose only postinstall.js script
* Replace _openspec "$@" with compdef in zsh-generator.ts to prevent execution during load
* Update test/commands/completion.test.ts
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* - Fix dispatcher to use $words instead of $line for subcommand routing
- Add __complete endpoint with tab-separated output for safe parsing
- Replace brittle awk parsing with __complete in completion helpers
- Add uninstall confirmation prompt with --yes flag to skip
- Prefer $ZSH env var for Oh My Zsh detection before dir check
- Add fpath verification guidance for OMZ installations
- Update cli-completion spec to document generate subcommand
* improve shell detection and installation handling
- Return structured result from detectShell() with shell and detected name
- Detect already-installed completions and skip reinstall
- Add update detection with automatic backup of previous version
- Add debug logging to silent catch blocks for diagnostics
- Quote fpath directories to handle paths with spaces
- Verify Oh My Zsh fpath configuration and add to .zshrc if needed
- Show helpful error for detected but unsupported shells
- Update all tests for new detection API
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
Remove the `agent: build` field from OpenCode slash command templates
to allow OpenCode to use the current/custom agent instead of requiring
the build agent to be available.
Fixes#334
Add prominent restart instruction in success message to inform users
they need to restart their IDE/coding tool for slash commands to appear.
Applies to all tools when slash commands are created or refreshed.
Also updates cli-init spec to document the restart instruction requirement.
* support iflow-cli
* docs: add iFlow to supported AI tools in README ([#268](https://github.com/Fission-AI/OpenSpec/pull/268))
Add iFlow to the Native Slash Commands table in the README. iFlow support was implemented but was missing from the documentation.
* add UTs for iflow-cli
* Enhance proposal guidelines in slash-command-templates.ts
- Added instructions to avoid writing code during the proposal stage and focus on creating design documents.
- Emphasized the design phase by including a reminder not to implement code until the apply stage.
- Updated validation steps to clarify the importance of confirming project conventions before proceeding with tasks.
* Update proposal guidelines in slash-command-templates.ts to clarify that no implementation code should be written during the design phase.
* Refine proposal and apply steps in slash-command-templates.ts
- Removed redundant instruction in proposal steps to streamline the process.
- Clarified the initial reading order for apply steps by omitting the project conventions document, focusing on the proposal and design documents instead.
* feat(roocode): Added RooCode tool support and related configurations
Added RooCode tool integration, including:
- Added RooCode configurator class
- Registered RooCode to the tool registry
- Implemented RooCode template files
- Added RooCode slash command support
- Updated README documentation
- Added related test cases
* Removed RooCode related configurations from the project. This includes deleting the RooCode configurator, its template, and associated tests.
* fix(cline): use workflows instead of rules for slash commands
- Update ClineSlashCommandConfigurator to use .clinerules/workflows/ paths
- Update tests to expect correct workflow file locations
- Update README.md to reflect workflows instead of rules
- Fixes Cline integration to match Cline's architecture per their blog post
* Adds spec for fix-cline-workflows-implementation
---------
Co-authored-by: didier <didier.boff@axess.fr>
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
* feat: add Gemini CLI support with TOML-based slash commands
- Add GeminiSlashCommandConfigurator for .gemini/commands/openspec/
- Register Gemini CLI in AI_TOOLS config and slash command registry
- Generate TOML files with description and prompt fields
- Add comprehensive test coverage for Gemini CLI integration
- Update README to list Gemini CLI under Native Slash Commands
- Remove Gemini CLI from AGENTS.md compatible list (now native)
Implements GitHub issue #248
* [add]
* feat: address PR feedback - remove changeset and add update test
- Remove .changeset/add-gemini-cli-support.md as requested by maintainer
- Add test for Gemini CLI TOML update/refresh path
- Test verifies that existing TOML files are properly updated when running init again
Addresses feedback from TabishB in PR #256
---------
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
This change adds the $ARGUMENTS property to the OpenCode apply slash command template, allowing users to pass arguments when invoking the apply command. The template now includes instructions for the agent to find and implement the change proposal, with guidance to ask for clarification when ambiguous.
* feat(ai-tools): add Costrict integration support
Add support for Costrict AI tool with slash commands and configuration template. Includes configurator, registry entries, templates, and comprehensive test coverage.
* feat(config): update branding from 'Costrict' to 'CoStrict'
* fix: recreate missing openspec template files in extend mode
The init command now checks for and recreates missing template files
(like openspec/AGENTS.md and openspec/project.md) when running in
extend mode, instead of skipping file generation entirely.
Previously, if a user deleted openspec/AGENTS.md and ran init again,
the file would not be recreated because the openspec/ directory
existed, triggering extend mode which skipped all file generation.
Changes:
- Added ensureTemplateFiles() method to check and recreate missing files
- Modified extend mode to call ensureTemplateFiles() instead of skipping
- Updated message to "Checking for missing files..." for clarity
- Added tests for recreating deleted openspec/AGENTS.md and project.md
* refactor: consolidate duplicate logic in template file generation
Extracted shared logic from generateFiles() and ensureTemplateFiles()
into a new writeTemplateFiles() method with a skipExisting parameter.
This eliminates code duplication while maintaining the same behavior.
* test: improve extend mode test coverage and reduce duplication
- Extracted testFileRecreationInExtendMode helper to reduce code duplication
- Added test to verify existing files are preserved in extend mode
- Ensures skipExisting behavior is properly tested
* fix: prevent false "already configured" detection for tools
Fixes#195
## Problem
Users with existing tool config files (like CLAUDE.md) would see those
tools marked as "already configured" even when running `openspec init`
for the first time. This caused confusion as users thought OpenSpec was
already set up when it wasn't.
Root causes:
1. Tool detection checked only for file existence, not OpenSpec ownership
2. Detection ran even in fresh projects without openspec/ folder
## Solution
Two-part fix:
1. **Conditional detection**: Only check tool configuration when in extend
mode (when openspec/ directory already exists). Fresh initializations
skip the check entirely, treating all tools as unconfigured.
2. **Marker-based validation**: For tools to be considered "configured by
OpenSpec", their files must contain OpenSpec markers (<!-- OPENSPEC:START -->
and <!-- OPENSPEC:END -->). For tools with both config files and slash
commands (like Claude Code), BOTH must have markers.
## Changes
- Modified getExistingToolStates() to accept extendMode parameter
- Rewrote isToolConfigured() to verify OpenSpec markers in files
- Added OPENSPEC_MARKERS to imports
- Added 4 comprehensive test cases covering the new behavior
## Test Coverage
- Fresh init with existing CLAUDE.md → NOT shown as configured ✅
- Fresh init with existing slash commands → NOT shown as configured ✅
- Extend mode with OpenSpec files → shown as configured ✅
- Fresh init with global Codex prompts → NOT shown as configured ✅
All 240 tests pass.
* refactor: optimize tool state detection and improve code clarity
Address code review feedback:
1. **Parallelize tool state checks**: Changed from sequential `for` loop to
`Promise.all()` for checking multiple tools simultaneously. This reduces
I/O latency during extend mode initialization.
2. **Extract marker validation helper**: Created `fileHasMarkers()` helper
function to eliminate code duplication between config file and slash
command checks. Makes the logic clearer and more maintainable.
3. **Clarify slash command policy**: Added explicit comment that "at least
one file with markers is sufficient" (not all required) for slash commands.
This is correct because OpenSpec creates all files together - if any
exists with markers, the tool was configured by OpenSpec.
4. **Simplify fresh init path**: Use `Object.fromEntries()` for cleaner
initialization of all-false states.
Performance improvement: Extend mode now checks tools in parallel instead
of serially, reducing init time especially for projects with many tools.
* fix: use change-id as fallback title instead of "Untitled Change"
Fixes#225 by addressing mismatch between proposal template and title extraction:
- Updated proposal template to include `# Change: [description]` header
- Changed extractTitle fallback from "Untitled Change" to change-id
- Updated all extractTitle call sites to pass changeName parameter
This ensures both new and existing proposals display meaningful titles.
* refactor: make title extraction case-insensitive for "Change:"
Makes the extractTitle regex case-insensitive to handle variations like
"# change:" or "# CHANGE:" in addition to "# Change:".
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/.
This commit enhances the validation logic for delta specs:
- Delta section headers are now parsed case-insensitively (e.g., "Added Requirements" and "ADDED Requirements" both work)
- Empty delta sections now produce clear error messages guiding users to add requirement entries
- Specs with no delta headers at all now receive specific error messages
- Added test coverage for case-insensitive delta header parsing
Add comprehensive OpenSpec integration for Crush AI assistant including:
- CrushSlashCommandConfigurator for proposal, apply, and archive commands
- Integration with slash command registry and CLI tools
- Generates .crush/commands/openspec/ with proper frontmatter and workflows
- Available via `openspec init --tools crush`
💘 Generated with Crush
Co-authored-by: Crush <crush@charm.land>
* feat: add Auggie (Augment CLI) support to configuration and documentation
- Added Auggie (Augment CLI) to the AI tools configuration in `config.ts`.
- Updated the slash command registry to include Auggie's configurator.
- Documented Auggie's commands in the README.md for better visibility.
This enhances the integration of Auggie within the existing toolset.
* test: add tests for Auggie command file creation and updates
- Implemented tests to verify the creation of Auggie slash command files with appropriate templates.
- Added checks to ensure existing Auggie command files are refreshed correctly during updates.
- Confirmed that missing command files are not created during the update process.
These changes enhance the test coverage for Auggie's integration and ensure proper functionality of command file management.
* fix: skip metadata when validating requirement SHALL/MUST keywords
Fixes validation incorrectly checking metadata lines instead of requirement text.
The extractRequirementText() function was returning the first non-empty line
after the requirement header, which was often metadata like **ID**: REQ-001
instead of the actual requirement statement.
Changes:
- Updated extractRequirementText() to skip lines matching **Key**: Value pattern
- Skip blank lines between header and requirement text
- Return first substantive text line for SHALL/MUST validation
Added comprehensive tests for:
- Requirements with metadata before SHALL/MUST text
- Requirements with SHALL in text but not header
- Requirements correctly failing without SHALL/MUST
- Requirements without metadata fields
All 20 validation tests pass.
Fixes#159
* Respect --no-validate flag while archiving
Standardize archive command documentation to use `<change-id>` instead of `[change]` to clarify that the change ID must be explicitly passed. Remove OpenCode-specific slash command reference from AGENTS.md to keep it tool-agnostic.
* feat: add argument support to archive slash command
Add $ARGUMENTS placeholder to the /openspec:archive slash command to allow explicit change ID specification, improving safety and matching CLI behavior.
Changes:
- Add $ARGUMENTS to archive command frontmatter in OpenCode configurator
- Update archive command template with argument validation steps
- Add rewriteArchiveFile method to handle managed section updates
- Update AGENTS.md documentation for archive command usage
This change makes it possible for users to run `/openspec:archive <change-id>` instead of relying on context inference, reducing the risk of archiving the wrong change.
* refactor: improve archive slash command argument handling instructions
Update the archive slash command template to provide clearer guidance on how
to handle change IDs from arguments versus conversation context. The new
instructions better distinguish between explicit argument-provided IDs and
contextual references, and provide more explicit failure modes.
This change adds support for factory functions in slash command configuration,
allowing slash commands to be defined as functions that return command objects.
* feat: add non-interactive options to openspec init
- Add --tools, --all-tools, and --skip-tools CLI options
- Enable automated initialization for CI/CD pipelines
- Maintain backward compatibility with interactive mode
- Add comprehensive validation and error handling
- Update cli-init spec with non-interactive requirements
- Add unit and integration tests for new functionality
Closes change proposal: add-non-interactive-init-options
* feat(init): add single --tools flag for non-interactive init
* test(init): verify --tools help lists available ids
* Revert manual spec.md edits
The canonical spec shouldn't be edited directly when a change delta
already captures the update. Archiving that delta will sync the spec.
---------
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
Co-authored-by: Tabish Bidiwale <tabishbidiwale@gmail.com>
Update the tool selection wizard so pressing Enter on a highlighted tool
automatically selects it before proceeding to the review step. This aligns
with common CLI expectations where Enter confirms the highlighted item.
Changes:
- Add logic to select the currently highlighted tool when Enter is pressed
- Update help text to clarify that Enter selects the highlighted tool
- Maintain Space key for toggling multiple selections
This reduces friction during onboarding by matching user expectations,
especially for users who navigate to a tool and press Enter without
first toggling it with Space.
- Use POSIX-style forward slashes in FILE_PATHS for consistent logging
- Normalize backslashes to forward slashes in update command output
- Improves Windows compatibility and log readability
Fixes#132
The FILE_PATHS constant was using hardcoded forward slashes, which caused
path.basename() to fail on Windows. On Windows, path.basename() expects
backslashes as path separators, so it would return the entire string
instead of just the filename.
This broke Codex detection on Windows during init/update because the
resolveAbsolutePath() method would construct incorrect paths, causing
file existence checks to fail.
Changed FILE_PATHS to use path.join() which automatically uses the
correct platform-specific path separators (backslashes on Windows,
forward slashes on Unix).
* feat: update Codex slash commands to use YAML frontmatter and $ARGUMENTS
Updates Codex custom slash command format to match the official Codex implementation:
- Replace simple header format with YAML frontmatter (description + argument-hint fields)
- Switch from positional $1 placeholder to $ARGUMENTS for consistency with GitHub Copilot
- Add updateFullFile method to ensure both frontmatter and body are updated during openspec update
- Align with Codex custom_prompts.rs specification
* docs: update Codex proposal to reflect YAML frontmatter and $ARGUMENTS
Updates the proposal to accurately describe the implemented format:
- YAML frontmatter with description and argument-hint fields
- $ARGUMENTS instead of positional placeholders like $1
- Alignment with GitHub Copilot pattern and official Codex specification
- Clarifies that openspec update refreshes both frontmatter and body
* test: update Codex tests for YAML frontmatter and $ARGUMENTS
Updates test assertions to match the new Codex format:
- YAML frontmatter with description and argument-hint fields
- $ARGUMENTS instead of positional $1 placeholders
- Verifies frontmatter is updated during openspec update
* feat: add GitHub Copilot slash command support
Add GitHub Copilot as a natively supported AI tool with custom slash
commands for OpenSpec workflow operations. This enables teams using
GitHub Copilot to access /openspec-proposal, /openspec-apply, and
/openspec-archive directly from Copilot's chat interface.
Implementation:
- Create GitHubCopilotSlashCommandConfigurator that writes prompts to
.github/prompts/ directory with YAML frontmatter and $ARGUMENTS
placeholder following GitHub Copilot's prompt format
- Register GitHub Copilot in AI_TOOLS configuration and slash
command registry for automatic init/update integration
- Add comprehensive test coverage for prompt generation, updates,
and extend mode detection
- Update documentation (README and CHANGELOG) to include GitHub
Copilot in the slash-command support table
The implementation follows the existing SlashCommandConfigurator
pattern and integrates seamlessly with openspec init and openspec
update commands.
* docs: remove GitHub Copilot from tools list
* Document current cli specs and archive safety
* feat: add Codex slash command support
Add support for generating and updating Codex prompts in `.codex/prompts/` directory:
- Implement CodexSlashCommandConfigurator for managing openspec-*.md prompts
- Update AI_TOOLS configuration to include Codex as an available option
- Add Codex registration in SlashCommandRegistry
- Update documentation to reflect Codex support
- Add comprehensive test coverage for Codex init and update workflows
* feat: complete Codex slash command support implementation
Add comprehensive Codex slash command support with Claude.md integration,
config-driven command management, and full test coverage. Update documentation
and changelog to reflect changes.
* chore: mark all Codex slash command tasks as completed
All tasks for the Codex slash command support feature have been implemented and tested.
* docs: remove Codex-specific note from README
Remove the Codex-specific installation note as it's no longer needed in the main setup instructions. This information is better suited for tool-specific documentation.
* docs(windsurf): propose workflow support
* restore missing opencode spec
* Add Windsurf IDE support with slash commands
* feat(windsurf): add Windsurf workflows support under .windsurf/workflows and simplify templates\n\n- Write workflows to .windsurf/workflows instead of .windsurf/commands\n- Remove YAML frontmatter; add concise intro before managed markers\n- Add init/update tests for Windsurf and marker preservation\n- List Windsurf in README native tools table\n- Normalize registry indentation
* chore(windsurf): remove optional intro content to simplify workflows\n\n- Drop intro hook and headings for Windsurf workflows\n- Keep OPENSPEC markers-only body for safe updates\n- Adjust tests to assert marker-managed content
* feat(windsurf): add required YAML frontmatter to workflows\n\n- Include description and auto_execution_mode: 3 for proposal/apply/archive\n- Keep content minimal; body remains marker-managed
---------
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
Co-authored-by: Tabish Bidiwale <tabishbidiwale@gmail.com>
Implements Kilo Code integration with the following features:
- Added Kilo Code as a selectable AI tool in `openspec init`
- Created KiloCodeSlashCommandConfigurator to generate workflow files
- Generates `.kilocode/workflows/openspec-{proposal,apply,archive}.md`
- Added update support to refresh existing Kilo Code workflows
- Updated README with Kilo Code integration details
- Added comprehensive test coverage for init and update commands
- Updated CHANGELOG with new feature
All tasks from the change proposal are complete.
* feat: implement Phase 1 E2E testing with cross-platform CI matrix
- Add shared runCLI helper in test/helpers/run-cli.ts for spawn testing
- Create test/cli-e2e/basic.test.ts covering help, version, validate flows
- Migrate existing CLI exec tests to use runCLI helper
- Extend CI matrix to bash (Linux/macOS) and pwsh (Windows)
- Update Phase 1 tasks and proposal with implementation status
* fix: correct YAML syntax in CI workflow diagnostics command
* fix: use multiline YAML for diagnostics command
* fix ci
* fix: ci
* fix: update core validation and json converter
* chore(ci): split pr and main workflows
* refactor: simplify CI workflow with unified matrix strategy
- Consolidate test_pr and test_matrix into single test job
- Add proper shell configuration with defaults
- Add timeout protection (15 minutes)
- Simplify required-checks to single job
- Maintain cross-platform testing (bash on Linux/macOS, pwsh on Windows)
* fix: restore lean PR workflow with async main branch matrix
- PRs run only essential tests on ubuntu-latest (fast feedback)
- Main branch runs full cross-platform matrix asynchronously
- Separate required-checks for each workflow type
- Different timeouts: 10min for PR, 15min for matrix
Tabish Bidiwale