Proposal: Add workspace control plane proposal

[rajashree-n]

Summary

This PR adds a draft OpenSpec proposal for first-class multi-repo workspace support using a dedicated control-plane pattern.

The new change introduces:

• a checked-in openspec-workspace.yaml manifest as the source of truth for workspace topology
• a new openspec workspace command surface with init, sync, and doctor
• generated workspace router files like .agents.md derived from the manifest
• a dedicated control-plane repo pattern that works across sibling repos without requiring a monorepo

Context

This draft is based on the multi-repo workspace pattern described in my comment on issue #725:
#725 (comment)

Why

OpenSpec is currently project-root centric. That works well for single repos, but it leaves multi-repo teams without a standard way to keep agents grounded across a shared workspace.

This proposal targets a common setup like:

scm/
├── openspec-management/
├── service-auth/
└── service-payments/

The goal is to let teams manage shared specs, schemas, and repo routing from a single control plane while preserving repo-local ownership of existing AGENTS.md files.

What’s Included

• proposal.md
• design.md
• tasks.md
• spec delta for cli-workspace
• spec delta for workspace-manifest

Key Design Choices

• openspec init remains project-scoped
• multi-repo support is introduced as a separate openspec workspace command group
• .agents.md is treated as a generated artifact, not the primary contract
• repo-local AGENTS.md files are referenced, not overwritten
• sibling repo discovery is supported, but discovered entries must be reviewed before writing

Validation

• openspec validate add-workspace-control-plane passed locally

Status

Draft proposal only. No runtime CLI implementation is included in this PR.

Summary by CodeRabbit

• Documentation
  • Added design, proposal, spec, and task docs describing a new workspace control‑plane for multi-repo OpenSpec management.
  • Specified a checked‑in workspace manifest and validation rules, plus router generation and drift detection behaviors.
  • Documented a new CLI surface: openspec workspace with init, sync, and doctor commands and expected workflows.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9db421b8-f273-4ea5-8043-fb6cb3c78b27

📥 Commits

Reviewing files that changed from the base of the PR and between caeebea and c54a1f5.

📒 Files selected for processing (1)

• openspec/changes/add-workspace-control-plane/tasks.md

✅ Files skipped from review due to trivial changes (1)

• openspec/changes/add-workspace-control-plane/tasks.md

---

📝 Walkthrough

Walkthrough

Adds design, proposal, specs, and task documentation for a new first-class multi-repo "workspace" control-plane in OpenSpec, plus a small .openspec.yaml metadata file. No code or public API declarations were changed.

Changes

Cohort / File(s)	Summary
Change Metadata openspec/changes/add-workspace-control-plane/.openspec.yaml	New per-change metadata file with schema: spec-driven and created timestamp.
Design & Proposal openspec/changes/add-workspace-control-plane/design.md, openspec/changes/add-workspace-control-plane/proposal.md	Adds design and proposal documents defining a checked-in openspec-workspace.yaml manifest, control-plane scaffolding expectations, generated-router ownership rules, and CLI surface (`workspace init
CLI & Manifest Specs openspec/changes/add-workspace-control-plane/specs/cli-workspace/spec.md, openspec/changes/add-workspace-control-plane/specs/workspace-manifest/spec.md	Formalizes CLI requirements and manifest schema: discovery with user review, path normalization, validation rules (duplicate names/paths, missing control-plane), and router-generation behavior (.agents.md handling).
Tasks / Roadmap openspec/changes/add-workspace-control-plane/tasks.md	Task checklist for implementing workspace commands, manifest read/write/validation, discovery, scaffold behavior, router generation, drift detection, diagnostics, and tests.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as "openspec CLI"
    participant Manifest as "openspec-workspace.yaml"
    participant RepoFS as "Sibling Repos / Filesystem"
    participant Generator as "Router Generator"

    User->>CLI: run `openspec workspace init` (root)
    CLI->>RepoFS: discover candidate repos + instruction files
    RepoFS-->>CLI: list of candidates
    CLI->>User: present discovered entries for review
    User-->>CLI: confirm selections
    CLI->>Manifest: write `openspec-workspace.yaml` (normalized paths)
    CLI->>RepoFS: scaffold control-plane repo files if missing
    User->>CLI: run `openspec workspace sync`
    CLI->>Manifest: read manifest
    CLI->>Generator: generate routers (.agents.md) per manifest config
    Generator->>RepoFS: write generated router files (unless repo-local preserved)
    CLI->>User: report summary & drift info

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• feat: add per-change schema metadata (.openspec.yaml) #443 — Overlaps on adding per-change .openspec.yaml metadata support and schema-aware handling for change files.

Suggested reviewers

• TabishB

Poem

🐰 I hopped from repo to root with cheer,
A workspace map now drawn so clear,
Init, sync, doctor — tools in paw,
Manifests stitch the paths we saw,
Together we keep agents near. 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Proposal: Add workspace control plane proposal' accurately describes the main change: adding a comprehensive proposal for multi-repo workspace control-plane support with manifest, CLI commands, and specifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

openspec/changes/add-workspace-control-plane/tasks.md (1)

17-17: Clarify scope of instruction file detection.

The phrasing "such as AGENTS.md" suggests support for multiple instruction file formats, but the design and specs consistently reference only AGENTS.md. If other formats are intended, they should be documented in the design/specs; otherwise, consider simplifying to "Detect candidate AGENTS.md instruction files".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@openspec/changes/add-workspace-control-plane/tasks.md` at line 17, Update the
checklist entry text in tasks.md to clarify scope: replace the ambiguous item
"Detect candidate instruction files such as `AGENTS.md`" with a specific
form—either "Detect candidate `AGENTS.md` instruction files" if only AGENTS.md
is supported, or enumerate the supported filenames/formats (e.g., `AGENTS.md`,
`INSTRUCTIONS.md`) if multiple are intended; adjust the string in the checklist
line so the wording in the document matches the actual supported formats
referenced by the design/specs.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@openspec/changes/add-workspace-control-plane/tasks.md`:
- Line 17: Update the checklist entry text in tasks.md to clarify scope: replace
the ambiguous item "Detect candidate instruction files such as `AGENTS.md`" with
a specific form—either "Detect candidate `AGENTS.md` instruction files" if only
AGENTS.md is supported, or enumerate the supported filenames/formats (e.g.,
`AGENTS.md`, `INSTRUCTIONS.md`) if multiple are intended; adjust the string in
the checklist line so the wording in the document matches the actual supported
formats referenced by the design/specs.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 85ab990f-78d5-4082-a663-75310442c6af

📥 Commits

Reviewing files that changed from the base of the PR and between 9b5007d and caeebea.

📒 Files selected for processing (6)

• openspec/changes/add-workspace-control-plane/.openspec.yaml
• openspec/changes/add-workspace-control-plane/design.md
• openspec/changes/add-workspace-control-plane/proposal.md
• openspec/changes/add-workspace-control-plane/specs/cli-workspace/spec.md
• openspec/changes/add-workspace-control-plane/specs/workspace-manifest/spec.md
• openspec/changes/add-workspace-control-plane/tasks.md

[alfred-openspec]

Thanks for putting this together. It's a thoughtful draft and it points at a real gap, but I don't think we should merge this shape as written.

The main mismatch is that it makes a checked-in, path-based workspace manifest and control-plane repo the primary abstraction. Our current workspace direction has shifted toward initiative-first coordination, repo-local changes as the execution units, stable project identifiers instead of sibling-relative paths, and workspace state that is optional/lazy rather than required up front.

So I'd treat this PR as a useful exploration signal, not the proposal we merge. The pieces worth carrying forward are the generated router idea, the explicit review-before-write discovery flow, and possibly workspace sync / workspace doctor, but they should sit inside the thinner coordination-workspace model rather than a mandatory openspec-workspace.yaml control plane.

[alfred-openspec]

Did a deeper pass against the current workspace exploration docs and I still think the main issue is architectural, not editorial.

openspec/explorations/workspace-architecture.md now sets three constraints this proposal fights: initiative-first planning for cross-repo work, stable project identifiers instead of sibling-relative paths, and workspace state that is optional/lazy rather than required up front.

So I'd keep this PR as a useful exploration signal, but I would not merge a mandatory openspec-workspace.yaml + control-plane-repo model as the primary shape. The reusable pieces are the review-before-write discovery flow, generated routing as a derived output, and possibly workspace sync / workspace doctor, but they should hang off the thinner coordination-workspace model rather than define it.