feat(spec): add XDG global config and config command proposals #376
Conversation
Create two OpenSpec change proposals: 1. add-global-config-dir: Foundation for user-level configuration following XDG Base Directory Specification with cross-platform support 2. add-config-command: User-facing CLI command for viewing and managing global settings Both proposals are minimal and focused on providing a clean, extensible base for OpenSpec settings and future feature flags.
WalkthroughThe changes introduce a global configuration system for OpenSpec with a cross-platform config directory strategy using XDG Base Directory Specification, a new core module for configuration management, and a new CLI command group to interact with global settings. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
openspec/changes/add-global-config-dir/design.md (1)
26-29: Add language specifier to fenced code block.Line 26 is missing a language identifier on the code fence. Per markdown best practices, add a language specifier (e.g.,
bash,shell, ortext) to improve syntax highlighting and clarity.🔎 Proposed fix
-``` +```shell Unix/macOS: $XDG_CONFIG_HOME/openspec/ or ~/.config/openspec/ Windows: %APPDATA%/openspec/</details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between cefb4719aaf4b7702331fce7905eab62bcf29b4d and 780acb0ec02ca2e8b15b267ffb6228da27e2a38b. </details> <details> <summary>📒 Files selected for processing (5)</summary> * `openspec/changes/add-config-command/proposal.md` (1 hunks) * `openspec/changes/add-global-config-dir/design.md` (1 hunks) * `openspec/changes/add-global-config-dir/proposal.md` (1 hunks) * `openspec/changes/add-global-config-dir/specs/global-config/spec.md` (1 hunks) * `openspec/changes/add-global-config-dir/tasks.md` (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>📓 Path-based instructions (4)</summary> <details> <summary>openspec/changes/**/*.md</summary> **📄 CodeRabbit inference engine (openspec/AGENTS.md)** > Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/` Files: - `openspec/changes/add-global-config-dir/design.md` - `openspec/changes/add-global-config-dir/tasks.md` - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` - `openspec/changes/add-global-config-dir/proposal.md` - `openspec/changes/add-config-command/proposal.md` </details> <details> <summary>openspec/changes/*/tasks.md</summary> **📄 CodeRabbit inference engine (openspec/AGENTS.md)** > Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items Files: - `openspec/changes/add-global-config-dir/tasks.md` </details> <details> <summary>openspec/changes/**/specs/**/spec.md</summary> **📄 CodeRabbit inference engine (openspec/AGENTS.md)** > `openspec/changes/**/specs/**/spec.md`: Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files > Include at least one `#### Scenario:` per requirement in spec delta files > Use `#### Scenario: Name` format (4 hashtags) for scenario headers, not bullets or bold text > Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements > When using MODIFIED Requirements, paste the full requirement block including header and all scenarios Files: - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` </details> <details> <summary>openspec/changes/*/proposal.md</summary> **📄 CodeRabbit inference engine (openspec/AGENTS.md)** > Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code) Files: - `openspec/changes/add-global-config-dir/proposal.md` - `openspec/changes/add-config-command/proposal.md` </details> </details><details> <summary>🧠 Learnings (10)</summary> <details> <summary>📓 Common learnings</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal usingproposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use@/openspec/AGENTS.mdto learn how to create and apply change proposals, spec format and conventions, and project structure and guidelinesLearnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensureproposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)</details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Createdesign.mdonly when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity**Applied to files:** - `openspec/changes/add-global-config-dir/design.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal usingproposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/**Applied to files:** - `openspec/changes/add-global-config-dir/design.md` - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` - `openspec/changes/add-config-command/proposal.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensureproposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)**Applied to files:** - `openspec/changes/add-global-config-dir/design.md` - `openspec/changes/add-config-command/proposal.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:02.839Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use@/openspec/AGENTS.mdto learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines**Applied to files:** - `openspec/changes/add-global-config-dir/design.md` - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` - `openspec/changes/add-config-command/proposal.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Checkopenspec/project.mdfor project conventions before creating specs**Applied to files:** - `openspec/changes/add-global-config-dir/design.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files**Applied to files:** - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements**Applied to files:** - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios**Applied to files:** - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : Include at least one#### Scenario:per requirement in spec delta files**Applied to files:** - `openspec/changes/add-global-config-dir/specs/global-config/spec.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>openspec/changes/add-global-config-dir/design.md</summary> 26-26: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (5)</summary><blockquote> <details> <summary>openspec/changes/add-global-config-dir/tasks.md (1)</summary><blockquote> `1-25`: **LGTM!** The tasks file follows the required structure with numbered sections, hierarchical task numbering, and checkbox items for tracking progress. Clear, actionable implementation plan. </blockquote></details> <details> <summary>openspec/changes/add-global-config-dir/specs/global-config/spec.md (1)</summary><blockquote> `1-76`: **LGTM!** Spec correctly uses `## ADDED Requirements` header with five well-defined requirements, each including multiple `#### Scenario:` sections. Clear scenarios cover positive and edge cases (missing files, invalid JSON, platform variations, schema evolution). Aligns well with the tasks and design documents. </blockquote></details> <details> <summary>openspec/changes/add-global-config-dir/design.md (1)</summary><blockquote> `1-104`: **Excellent design rationale.** The design doc thoroughly covers context, goals, decision reasoning, and trade-offs. Path resolution strategy is well-justified (XDG standard vs. alternatives), and the decision to read fresh on each call and defer directory creation to save operations is sensible for short-lived CLI commands. The flat schema with optional fields ensures future extensibility without breaking changes. </blockquote></details> <details> <summary>openspec/changes/add-global-config-dir/proposal.md (1)</summary><blockquote> `1-20`: **LGTM!** Proposal correctly includes all required sections: Why (justifies need for user-level config), What Changes (clear bullets detailing new module, exports, and schema), and Impact (identifies new global-config spec and affected code files). Clean and complete. </blockquote></details> <details> <summary>openspec/changes/add-config-command/proposal.md (1)</summary><blockquote> `1-39`: **LGTM!** Proposal includes all required sections: Why (addresses user need for config interaction), What Changes (detailed subcommand operations with concrete usage examples), and Impact (identifies new cli-config spec, affected code, and dependency on add-global-config-dir). Clear execution order noted for implementation sequencing. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Summary
Created two OpenSpec change proposals for a user-level global configuration system:
Design Highlights
~/.config/openspec/)Next Steps
Review proposals for approval, then implement in order (global-config-dir first, then config command).
🤖 Generated with Claude Code
Summary by CodeRabbit
openspec configsubcommand group with operations: path, list, get, set, and reset for managing global configuration.✏️ Tip: You can customize this high-level summary in your review settings.