[codex] Complete workspace foundation and setup specs#1029
Merged
alfred-openspec merged 4 commits intomainfrom May 1, 2026
Merged
[codex] Complete workspace foundation and setup specs#1029alfred-openspec merged 4 commits intomainfrom
alfred-openspec merged 4 commits intomainfrom
Conversation
Contributor
📝 WalkthroughWalkthroughAdds workspace foundation code (path helpers, name validators, zod-backed YAML schemas, serializers, read/write I/O, discovery, and registry listing), extends global data-dir resolver and core exports, introduces CLI design/specs/tasks/docs for workspace setup/link/relink/list/doctor flows, and adds comprehensive foundation tests. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant CLI as CLI (openspec)
participant FS as Filesystem
participant WorkspaceMeta as .openspec-workspace
participant Registry as Managed Registry
User->>CLI: run `openspec workspace setup` (interactive)
CLI->>FS: validate chosen path(s) exist
CLI->>WorkspaceMeta: write `workspace.yaml` (shared state)
CLI->>WorkspaceMeta: write `local.yaml` (machine-local paths)
CLI->>Registry: create/update `registry.yaml` in managed workspaces
Registry-->>CLI: confirm registration
CLI-->>User: print summary and next commands
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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. Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@openspec/changes/workspace-create-and-register-repos/specs/cli-artifact-workflow/spec.md`:
- Around line 6-10: In the "Preparing workspace planning before a change"
scenario update the command list to use the agreed name "doctor" instead of
"check": replace the token "check" with "doctor" so the sentence reads "setup,
list, link, relink, and doctor" (ensure any normative language referencing the
CLI commands in the same scenario or nearby paragraphs uses the same "doctor"
identifier and not "check" to avoid conflicting contract language).
In
`@openspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.md`:
- Around line 80-104: The spec is missing behavior for the zero-known-workspaces
case; add a new Scenario (e.g., "No known workspaces") under "Global Workspace
Commands" that defines what should happen when commands that require a workspace
(like workspace link, workspace relink, workspace doctor) run but the local
registry has no workspaces: state whether the command should fail with a clear
message and suggested next steps (e.g., instruct to run `workspace init` or
`workspace create` or pass `--workspace` after registering one), and clarify
interactive vs non-interactive behavior for this case and the exact error text
or suggestion to display so implementers can rely on a deterministic response.
In `@openspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.md`:
- Around line 145-146: The checklist currently lists commands "setup", "list",
"create", "add-repo", and "doctor" in a way that implies "create" and "add-repo"
are still part of the expected flow; update the sentence to explicitly mark
"create" and "add-repo" as deprecated (e.g., append "(deprecated)" or
"—deprecated" after each) or remove them from the flow and replace with the
current command names so the handoff guide cannot be misread; edit the line that
mentions these commands to either remove the deprecated names or annotate them
as deprecated and optionally add the preferred replacements.
In `@openspec/changes/workspace-reimplementation-roadmap/README.md`:
- Around line 45-47: Replace the non-product term "working-set entries" in the
descriptions for workspace-create-and-register-repos and
workspace-open-agent-context with the approved product-language term "workspace
components" (or explicitly "visible repositories, monorepo modules, and
planning-only code areas") and remove any usage of "working set"/"entry" to keep
wording consistent across the spec; update the two sentences so they read e.g.
workspace-create-and-register-repos creates the workspace and makes workspace
components (repos, monorepo modules, planning-only code areas) visible before a
change exists, and workspace-open-agent-context gives the agent the workspace
root, workspace components, active changes, and selected change scope.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c8584450-21b6-425c-bf19-84b0f077628f
📒 Files selected for processing (13)
openspec/changes/workspace-create-and-register-repos/design.mdopenspec/changes/workspace-create-and-register-repos/proposal.mdopenspec/changes/workspace-create-and-register-repos/specs/cli-artifact-workflow/spec.mdopenspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.mdopenspec/changes/workspace-create-and-register-repos/tasks.mdopenspec/changes/workspace-foundation/design.mdopenspec/changes/workspace-foundation/proposal.mdopenspec/changes/workspace-foundation/specs/openspec-conventions/spec.mdopenspec/changes/workspace-foundation/specs/workspace-foundation/spec.mdopenspec/changes/workspace-foundation/tasks.mdopenspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.mdopenspec/changes/workspace-reimplementation-roadmap/README.mdopenspec/config.yaml
TabishB
changed the title
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
openspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.md (1)
60-79: ⚡ Quick winClarify stale-entry output vs required “linked repos/folders” fields.
Line 63 requires listing links for each workspace, but stale entries (missing workspace path) may not be readable. Add explicit stale-output semantics (e.g.,
stale: true, links omitted/null) to avoid implementation drift.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.md` around lines 60 - 79, Update the spec for the "workspace list" (and alias "workspace ls") output to explicitly handle stale registry entries: when a registered workspace path is not readable/present, emit a clear indicator (e.g., "stale": true) and either omit the "links" field or set it to null, instead of attempting to read or populate linked repos/folders; ensure non-stale workspaces continue to include "name", "path" and a populated "links" list.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@openspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.md`:
- Around line 93-104: Add a new scenario to the spec that defines the behavior
when exactly one known workspace exists: state that for commands workspace link,
workspace relink, and workspace doctor (reference those command names) when
exactly one registry entry is present and --workspace is omitted the CLI SHALL
automatically select that single known workspace (no interactive picker) and
proceed deterministically; include an explicit THEN that the command uses that
workspace's name and path and an optional NOTE that users may still pass
--workspace <name> to override.
---
Nitpick comments:
In
`@openspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.md`:
- Around line 60-79: Update the spec for the "workspace list" (and alias
"workspace ls") output to explicitly handle stale registry entries: when a
registered workspace path is not readable/present, emit a clear indicator (e.g.,
"stale": true) and either omit the "links" field or set it to null, instead of
attempting to read or populate linked repos/folders; ensure non-stale workspaces
continue to include "name", "path" and a populated "links" list.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 807b053e-c87b-4e14-a691-d49d34d8fd97
📒 Files selected for processing (4)
openspec/changes/workspace-create-and-register-repos/specs/cli-artifact-workflow/spec.mdopenspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.mdopenspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.mdopenspec/changes/workspace-reimplementation-roadmap/README.md
✅ Files skipped from review due to trivial changes (1)
- openspec/changes/workspace-reimplementation-roadmap/README.md
🚧 Files skipped from review as they are similar to previous changes (2)
- openspec/changes/workspace-create-and-register-repos/specs/cli-artifact-workflow/spec.md
- openspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.md
Comment on lines
+93
to
+104
| #### Scenario: Picking from multiple workspaces | ||
| - **GIVEN** multiple known workspaces exist | ||
| - **WHEN** an interactive command needs one workspace and none is specified | ||
| - **THEN** OpenSpec SHALL show a workspace picker | ||
| - **AND** the picker SHALL include workspace names and paths | ||
|
|
||
| #### Scenario: Ambiguous non-interactive workspace selection | ||
| - **GIVEN** multiple known workspaces exist | ||
| - **WHEN** a non-interactive command needs one workspace and none is specified | ||
| - **THEN** OpenSpec SHALL fail with a clear message | ||
| - **AND** it SHALL suggest passing `--workspace <name>` | ||
|
|
Contributor
There was a problem hiding this comment.
Define behavior for the “exactly one known workspace” case.
Selection is specified for current workspace, multiple-known, and zero-known cases, but not for one-known outside any workspace. Please add a scenario so workspace link/relink/doctor are deterministic when one registry entry exists and --workspace is omitted.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@openspec/changes/workspace-create-and-register-repos/specs/workspace-links/spec.md`
around lines 93 - 104, Add a new scenario to the spec that defines the behavior
when exactly one known workspace exists: state that for commands workspace link,
workspace relink, and workspace doctor (reference those command names) when
exactly one registry entry is present and --workspace is omitted the CLI SHALL
automatically select that single known workspace (no interactive picker) and
proceed deterministically; include an explicit THEN that the command uses that
workspace's name and path and an optional NOTE that users may still pass
--workspace <name> to override.
alfred-openspec
approved these changes
May 1, 2026
Collaborator
alfred-openspec
left a comment
alfred-openspec
left a comment
There was a problem hiding this comment.
Looks good. Checks are green and the remaining CodeRabbit notes are non-blocking spec follow-ups.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
workspace-foundationimplementation with.openspec-workspacepath helpers, workspace root detection, typed shared/local/registry state parsing, write helpers, and managed workspace location helpersworkspace-create-and-register-reposworkspace-foundationtasks complete after validationVerification
pnpm exec vitest run test/core/global-config.test.ts test/core/workspace/foundation.test.tspnpm run buildpnpm run lintnode bin/openspec.js validate workspace-foundation --strictnode bin/openspec.js validate workspace-create-and-register-repos --strictSummary by CodeRabbit
New Features
Documentation
Behavior
Tests