* chore(nix): improve flake with dynamic version and source filtering
- Read version dynamically from package.json instead of hardcoding
- Add lib.fileset source filtering to exclude node_modules and build artifacts
- Update update-flake.sh to support dynamic version pattern
- Add hash change detection to skip unnecessary rebuilds
- Improve error handling with automatic rollback on failure
- Update specs to reflect dynamic version behavior
* chore(ci): bump Nix actions to latest versions
- nix-installer-action: v13 → v21
- magic-nix-cache-action: v8 → v13
- Update validation message for unchanged flake.nix
* chore: add changeset for Nix improvements
* fix(nix): make update-flake.sh portable to macOS
- Fix grep pattern on line 37 to include opening parenthesis
- Replace GNU grep -oP with portable sed alternatives (lines 53, 68, 70)
- Ensures script works on both Linux and macOS (BSD sed/grep)
* fix(nix): properly check build verification exit status
Fix logic bug where build failures were incorrectly reported as success.
The script now:
- Captures build exit code and output separately
- Fails fast if build returns non-zero exit code
- Only checks for 'dirty tree' warning if build succeeded
This addresses CodeRabbit review feedback on line 101-107.
---------
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
* chore: add proposal for PostHog analytics integration
Introduces the proposal artifact for adding opt-in telemetry to OpenSpec
using PostHog. Covers command tracking, feature adoption metrics, and
privacy-respecting consent management.
* feat: add optional anonymous usage statistics
Introduces privacy-first usage analytics to help understand how OpenSpec
is being used. Key privacy protections:
- Only tracks command names and version (no arguments, paths, or content)
- Opt-out via OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1
- Auto-disabled in CI environments
- No IP address collection (explicitly disabled)
- Anonymous ID is a random UUID with no PII
Uses PostHog with a reverse proxy to avoid ad blockers. First-run shows
a one-line notice informing users about the collection.
* docs: make telemetry section collapsible and concise
* added CLI completions support for: bash, fish and powershell
* Add bash/fish/powershell completions
* Archive extend-shell-completions
* Archive extend-shell-completions
* Fix canWriteFile control flow and add tests
* Fix bash completion fallback and security escaping
- Add _init_completion fallback for systems without bash-completion
- Fix command injection escaping in Fish/PowerShell generators
- Add Bash command name escaping for security
- Add comprehensive security tests for all generators
- Fix test placement issues in bash/powershell test files
* refactor: extract completion templates and standardize naming
Extract static template literals from generators into separate template files.
Standardize naming to {SHELL}_STATIC_HELPERS and {SHELL}_DYNAMIC_HELPERS.
- Create bash/fish/powershell/zsh template files
- Rename constants: BASH_HELPERS → BASH_DYNAMIC_HELPERS,
FISH_HELPER_FUNCTIONS → FISH_STATIC_HELPERS,
POWERSHELL_HELPERS → POWERSHELL_DYNAMIC_HELPERS
- Update generator imports
- Remove ~99 lines of boilerplate from generators
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: update spec to reflect multi-shell support
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: add all shells to zsh completion suggestions
* feat: add --yes flag to completion uninstall
* fix: remove bash-completion dependency from fallback
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: use printf instead of echo for Fish tab output
Fish's echo doesn't interpret escape sequences, so \t outputs
literally instead of as a tab character. Use printf for proper
tab-separated completion output.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: make UX messages shell-aware
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: add Homebrew paths for bash-completion detection
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: support both PowerShell Core and Windows PS 5.1
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: preserve colon handling in bash completion
Add -n : option to _init_completion to prevent colons from being
treated as word separators. This is important for spec/change IDs
that may contain colons.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: update completion tests to match implementation changes
Updated bash-generator test to expect `-n :` flag in _init_completion call.
Updated powershell-installer tests to match refactored implementation that
supports both PowerShell Core and Windows PowerShell 5.1.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
* feat: change the frontmatter of the Codebuddy Slash Commands
* fix: fix the issue mentioned by coderabbitai
* feat: change the init.test
* feat: change the init.test
---------
Co-authored-by: neroyang <neroyang@tencent.com>
Archives two changes that were missing complete requirement content in their
spec deltas, which would have caused data loss during archival:
1. add-antigravity-support: Adds Antigravity IDE support to cli-init and
cli-update with proper workflow file generation in `.agent/workflows/`
2. fix-cline-workflows-implementation: Corrects Cline paths from `.clinerules/`
to `.clinerules/workflows/` to match Cline's official workflow conventions
Both deltas were fixed to include all 15 slash command scenarios (14 existing +
1 new Antigravity) to prevent loss of existing requirements when archived.
* proposal: add artifact workflow CLI commands (Slice 4)
Add CLI commands for artifact workflow operations:
- `openspec status --change <id>` - Show artifact completion state
- `openspec next --change <id>` - Show ready artifacts
- `openspec instructions <artifact> --change <id>` - Get enriched template
- `openspec templates --change <id>` - Show template paths
- `openspec new change <name>` - Create new change
Commands are top-level for fluid UX and implemented in isolation
for easy removal (experimental feature).
* fix: remove --change from templates command
Templates are schema-level, not change-level. The command now uses
--schema instead of --change for consistency with how templates
are actually resolved.
* rename: cli-workflow -> cli-artifact-workflow
More specific capability name that clarifies which workflow the CLI
commands are for.
* feat: implement artifact workflow CLI commands (Slice 4)
Add experimental CLI commands for artifact-based workflow management:
- `openspec status --change <id>` - display artifact completion status
- `openspec next --change <id>` - show artifacts ready to create
- `openspec instructions <artifact> --change <id>` - output enriched template
- `openspec templates [--schema <name>]` - show resolved template paths
- `openspec new change <name>` - create new change directory
Features:
- JSON output support (--json flag) for all commands
- Color-coded status indicators (green/yellow/red)
- Progress spinners during loading
- --no-color and NO_COLOR env support
- --schema option for custom schema selection
- Comprehensive error handling with helpful messages
All commands are isolated in src/commands/artifact-workflow.ts for easy
removal if the feature doesn't work out. Help text marks them as experimental.
* fix: update specs glob to match nested directory structure
The schema used specs/*.md but specs are stored as specs/<capability>/spec.md.
Updated to specs/**/*.md so openspec status/next correctly detect spec completion.
* test: update test to match new specs glob pattern
* chore: archive add-artifact-workflow-cli change
- Move change to archive/2025-12-28-add-artifact-workflow-cli
- Create cli-artifact-workflow spec
* feat: unify change state model for scaffolded changes
- Update artifact workflow commands to work with scaffolded changes
- Add draft changes section to dashboard view
- Fix completed changes to require tasks.total > 0
- Archive unify-change-state-model change
* fix: validate change name format to prevent path traversal
Add validation in validateChangeExists() to ensure --change parameter
is a valid kebab-case ID before constructing file paths. This prevents
path traversal attacks like --change "../foo" or --change "/etc/passwd".
- Reuses existing validateChangeName() from change-utils.ts
- Adds 3 tests for path traversal, absolute paths, and slashes
* feat: add instruction loader for template loading and change context
Add the instruction-loader module that provides:
- loadTemplate: Load templates from schema directories
- loadChangeContext: Combine artifact graph with completion state
- generateInstructions: Enrich templates with change-specific context
- formatChangeStatus: Format change status as readable output
This is Slice 3 of the artifact-graph system, building on the graph
operations (Slice 1) and change creation utilities (Slice 2).
* chore: archive add-instruction-loader change
- Move change to archive as 2025-12-28-add-instruction-loader
- Create instruction-loader spec with 4 requirements
* docs: add purpose description to instruction-loader spec
* feat: restructure schemas as directories with templates
Move built-in schemas from embedded TypeScript objects to a file-based
directory structure. This enables co-located templates alongside schemas.
Changes:
- Remove builtin-schemas.ts (replaced by file-based schemas)
- Add schemas/ directory at package root with spec-driven and tdd schemas
- Update resolveSchema() to load from directory structure
- Resolution checks user dir → package dir
* chore: archive restructure-schema-directories change
* docs: update artifact_poc.md for directory-based schema structure
Update documentation to reflect the new schema structure where schemas
are directories containing schema.yaml and co-located templates/ rather
than single .yaml files with separate template directories.
* proposal: add artifact graph core query system
Add OpenSpec change proposal for Slice 1 of the artifact POC - the core
"What's Ready?" query system. This implements:
- ArtifactGraph class for DAG-based dependency modeling
- Filesystem-based state detection (file existence = completion)
- Topological sort for build order calculation
- Ready/blocked artifact queries
This is a parallel module that will coexist with the current system.
* docs: specify Zod for schema validation in artifact graph proposal
- Add decision section for Zod schema validation in design.md
- Update data structures to show Zod schemas with z.infer<> types
- Update tasks to specify Zod usage for type definitions and parsing
* docs: add 2-level schema resolution and built-in schemas
- Add decision for global → built-in schema resolution pattern
- Add resolver.ts for schema lookup logic
- Add built-in schemas directory (spec-driven.yaml, tdd.yaml)
- Add schema resolution tests
- Follows ESLint/Prettier/Git patterns (defaults baked in package)
* experiment: add vertical slice version of artifact graph change
Creates add-artifact-graph-core-v2 with requirements organized as
vertical slices - each requirement file contains its spec, design
decisions, and tasks bundled together for comparison.
* feat(core): add getGlobalDataDir for XDG-compliant data directory
Add getGlobalDataDir() function following XDG Base Directory Specification
for storing user data like schema overrides:
- XDG_DATA_HOME takes precedence on all platforms
- Unix/macOS fallback: ~/.local/share/openspec/
- Windows fallback: %LOCALAPPDATA%/openspec/
* feat(artifact-graph): add core dependency graph module
Implement Slice 1 ("What's Ready?") of the artifact graph system:
- types.ts: Zod schemas for artifact definitions with derived TypeScript types
- schema.ts: YAML parsing with validation for duplicates, invalid refs, cycles
- graph.ts: ArtifactGraph class with Kahn's algorithm for topological sort
- state.ts: Filesystem-based completion detection with glob pattern support
- resolver.ts: Two-level schema resolution (global override → built-in)
- builtin-schemas.ts: spec-driven and tdd workflow definitions
Key design decisions:
- Filesystem as database (stateless, git-friendly)
- Cycle errors show full path (e.g., "A → B → C → A")
- Deterministic ordering via sorted queues
* test(artifact-graph): add comprehensive test suite
52 tests covering all artifact-graph functionality:
- schema.test.ts: Parsing, validation errors, cycle detection
- graph.test.ts: Build order, ready artifacts, blocked queries
- state.test.ts: File existence, glob patterns, missing directories
- resolver.test.ts: Schema resolution with global overrides
* docs(openspec): archive add-artifact-graph-core change
Archive completed change proposal and create artifact-graph spec with
6 requirements covering schema loading, build order, state detection,
ready queries, completion checks, and blocked queries.
* chore: remove experimental artifact-graph-core-v2 folder
Clean up experimental vertical slice proposal that is no longer needed.
* feat(artifact-graph): validate global schema overrides
Global schema overrides are now validated through the same pipeline as
built-in schemas, catching invalid schemas, cyclic dependencies, and
invalid requires references at load time. Added SchemaLoadError for
better error context with file paths.
* test(artifact-graph): add workflow integration tests
Add end-to-end integration tests that exercise the full artifact-graph
pipeline: resolveSchema → ArtifactGraph → detectCompleted → queries.
Tests cover:
- Complete spec-driven and tdd workflow progressions
- Out-of-order file creation handling
- Glob pattern matching with multiple files
- Build order consistency
- Edge cases (empty/missing directories, non-matching files)
* refactor(artifact-graph): adopt zod v4 error message format
Update custom error messages from string format to zod v4 object format
using `{ error: 'message' }` convention.
* fix(test): prevent hanging vitest threads after test runs
- Add teardownTimeout (3s) to vitest config for forced cleanup
- Add global teardown function to vitest.setup.ts
- Call child.unref() to prevent child processes from blocking event loop
- Explicitly destroy stdio streams on process close/error
* 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
* 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.
* 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>
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/.
Tabish Bidiwale