Add RFC 0001 draft for OpenSpec workspaces #342
Conversation
WalkthroughTwo RFC documents establish the OpenSpec Workspaces design: the main RFC specifies a user-scoped workspace store, multi-repo coordination through context manifests, drift detection, and CLI command behaviors; the appendix provides supporting analysis, design decisions, research findings, Q&A sections, and migration strategies. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI
participant Manifest as Context Manifest<br/>(.openspec-context.json)
participant Store as Workspace Store<br/>(~/.config/openspec)
participant Repo as Repo Specs
User->>CLI: openspec context
CLI->>Manifest: check if exists/valid
alt Manifest missing or drift detected
CLI->>Repo: read current specs
CLI->>Store: fetch workspace metadata
CLI->>Manifest: refresh with latest state
Manifest->>Manifest: update schemaVersion, repoId, workspaceId
end
CLI->>User: display context info
User->>CLI: openspec change apply <changeId>
CLI->>Store: retrieve change from workspace
CLI->>CLI: verify drift (sourceHash vs current state)
alt Verification succeeds
CLI->>Repo: apply changes to specs
CLI->>Manifest: update activeChangeId, status
CLI->>User: ✓ Change applied
else Drift detected
CLI->>User: ✗ Drift detected, resolve manually
end
sequenceDiagram
participant Dev as Developer
participant CLI
participant WS as Workspace Index<br/>(index.json)
participant Manifest as Per-Repo Manifest
Dev->>CLI: openspec attach --workspace <wsId>
CLI->>WS: load or create workspace entry
CLI->>Manifest: generate .openspec-context.json
Manifest->>Manifest: set workspaceId, repoId, status=attached
CLI->>Dev: ✓ Attached to workspace
Dev->>CLI: openspec change propose --title "Fix spec"
CLI->>WS: create new changeId in workspace
CLI->>CLI: capture current specs as sourceHash
WS->>WS: store change metadata and diff
CLI->>Dev: ✓ Change stored in workspace
Dev->>CLI: openspec change show <changeId>
CLI->>WS: retrieve change details
CLI->>Dev: display changes, tasks, context
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Tip 📝 Customizable high-level summaries are now available in beta!You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.
Example instruction:
Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later. 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: 4
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
rfcs/0001-openspec-workspaces-appendix.md(1 hunks)rfcs/0001-openspec-workspaces.md(1 hunks)
🧰 Additional context used
🧠 Learnings (9)
📓 Common learnings
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 using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/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.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
📚 Learning: 2025-11-25T01:08:02.839Z
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.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
rfcs/0001-openspec-workspaces-appendix.mdrfcs/0001-openspec-workspaces.md
📚 Learning: 2025-11-25T01:08:19.004Z
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 using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
rfcs/0001-openspec-workspaces-appendix.mdrfcs/0001-openspec-workspaces.md
📚 Learning: 2025-11-25T01:08:19.004Z
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 : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
rfcs/0001-openspec-workspaces-appendix.mdrfcs/0001-openspec-workspaces.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
rfcs/0001-openspec-workspaces-appendix.mdrfcs/0001-openspec-workspaces.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
rfcs/0001-openspec-workspaces-appendix.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
rfcs/0001-openspec-workspaces.md
📚 Learning: 2025-11-25T01:08:19.004Z
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 Requirements` headers in spec delta files
Applied to files:
rfcs/0001-openspec-workspaces.md
📚 Learning: 2025-11-25T01:08:19.004Z
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 Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
rfcs/0001-openspec-workspaces.md
🪛 LanguageTool
rfcs/0001-openspec-workspaces-appendix.md
[style] ~44-~44: To elevate your writing, try using a synonym here.
Context: ... The tightly-coupled structure makes it hard to customize the planning process or ad...
(HARD_TO)
[style] ~314-~314: To elevate your writing, try using a synonym here.
Context: ... | | In one "primary" repo | Arbitrary, hard to discover | | In centralized `.opensp...
(HARD_TO)
🪛 markdownlint-cli2 (0.18.1)
rfcs/0001-openspec-workspaces.md
81-81: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
185-185: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
311-311: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🔇 Additional comments (9)
rfcs/0001-openspec-workspaces.md (3)
83-92: Clear and forward-thinking customization framing.This section effectively explains the value of workspaces as a customization unit without overcommitting on implementation details. The hooks concept is grounded with practical examples, and deferring richer automation to future versions is sensible.
112-131: Clear and practical agent integration model.The four-step workflow balances CLI-first interactions with file-based fallbacks. Acknowledging non-CLI agents shows pragmatism about real-world constraints.
274-312: Well-structured user flows with appropriate sequence diagrams.Flows C and D clearly show the interactions between CLI, workspace, and repo during proposal creation and application. The notes summarizing agent/user handoffs are helpful.
rfcs/0001-openspec-workspaces-appendix.md (6)
21-60: Excellent foundational narrative for appendix.Executive summary and background clearly establish the two-concern split and its benefits. The "Why Split" rationale (specs are code, changes are ephemeral, cross-repo neutral ground) is principled and persuasive.
63-149: Comprehensive and well-reasoned key decisions.Nine decisions are documented with clear rationale and trade-offs. The decision to defer complex concerns (cross-repo specs, branch mapping, auto-sync) while shipping V1 with pragmatic mode 3 (Manual) for agent integration shows good scope management.
152-172: Solid cross-platform storage research.The comparison table and recommendation clearly justify the XDG-style choice. The note about visibility trade-offs shows thought about practical developer experience.
174-275: Comprehensive Q&A with realistic trade-offs.19 questions address major design concerns in a developer-friendly format. Appropriately acknowledges deferred concerns (structured task storage, work logs, branch mapping) while explaining pragmatic V1 choices. The note on agent forgetfulness (lines 256-260) shows realistic problem-solving rather than false promises.
278-358: Thoughtful risk analysis with realistic mitigations.Five risk categories are documented with candid trade-offs. The high-risk item (agent context accessibility) is well-mitigated with pragmatic hybrid modes. Deferring complex concerns (auto PR orchestration, team sync, structured task storage) while shipping V1 shows good judgment about scope vs. value.
360-420: Well-structured alternatives and forward-looking roadmap.Four alternatives are evaluated with fair pros/cons and clear rejection criteria. Future Considerations appropriately defers team sync, CI/CD, structured tasks, and cross-repo specs while showing a realistic agent integration evolution (prompting → verification → SDK → work logs).
|
Full disclaimer, there might be some AI slop in here, will tighten this up, just keen to start discussing this. |
Adds the initial RFC 0001 draft describing OpenSpec workspaces and off-repo change storage. Includes the appendix with research, decisions, and new customization hooks context.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.