docs: expand workspace planning explorations

[TabishB]

Summary

• update the workspace architecture exploration with the current direction: hybrid Model D, linked per-repo changes, stable project identifiers, and informational cross-repo references
• add detailed user journeys for single-repo, monorepo, multi-repo, and team-shared coordination flows
• add a UX simplification follow-up centered on one default path, one escalation path, and progressive disclosure
• add a staged roadmap that reflects real multi-repo demand while keeping the first coordination layer thin

Files

• openspec/explorations/workspace-architecture.md
• openspec/explorations/workspace-user-journeys.md
• openspec/explorations/workspace-ux-simplification.md
• openspec/explorations/workspace-roadmap.md

Notes

• docs only; no tests run

[1code-async]

Task completed.

I'll review this PR by first examining the changes.

---

View full conversation

Powered by 1Code

[coderabbitai]

📝 Walkthrough

Walkthrough

OpenSpec architectural exploration adds finalized design decisions for multi-repo support with Model D (hybrid approach), establishes a phased implementation roadmap spanning nested specs through shared contract governance, documents comprehensive user journeys across single-repo through multi-team scenarios, and defines a simplified progressive-disclosure UX strategy to streamline workspace interactions.

Changes

Cohort / File(s)	Summary
Architectural Decisions openspec/explorations/workspace-architecture.md	Formalizes Model D (hybrid) approach with optional lazy-derived workspace manifests, cross-repo coordination via .openspec.yaml links and initiative records, stable project identifiers for linking, offline-first resolution chains, and informational-only v1 cross-repo references; updates status tracking from TBD to Decided.
Implementation & Roadmap openspec/explorations/workspace-roadmap.md	Defines four-phase staged rollout: Phase 1 introduces nested specs and informational references; Phase 2 adds thin cross-repo coordination with neutral coordination workspaces; Phase 3 hardens shared coordination with committed state/local resolution separation; Phase 4 gates optional shared contract ownership and governance.
User Experience Documentation openspec/explorations/workspace-user-journeys.md, openspec/explorations/workspace-ux-simplification.md	Establishes scope-based mental model with durable object types (Spec, Change, Initiative), defines discovery via project identifiers, documents four end-to-end user journeys (single-repo through multi-team), specifies decision/prompting flows for shared contract ownership, and introduces progressive-disclosure UX strategy with single default path and escalation heuristics for team-scale work.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Four docs hop into the warren,
Design firm, roadmap, journeys sworn—
Workspace architecture's set to bloom,
Progressive UX clears the room,
Multi-repo dreams now have a map! 🗺️✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: expand workspace planning explorations' accurately summarizes the main change: adding multiple new documentation files (user-journeys, UX simplification, and roadmap) that expand the workspace planning exploration.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch TabishB/dynamic-repo-link

---

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]

Actionable comments posted: 1

🧹 Nitpick comments (1)

openspec/explorations/workspace-roadmap.md (1)

130-133: Align Phase 2 resolution bullets with the decided offline-first chain.

Line 130–133 currently lists only explicit input and git-remote matching, but the architecture decision also includes local registry usage and unresolved/non-fatal continuation. Tightening this wording will prevent drift between roadmap and architecture docs.

Proposed doc diff

-4. Resolution through:
-   - explicit input
-   - git remote matching
-5. Partial-resolution support
+4. Offline-first resolution through:
+   - explicit input
+   - saved local OpenSpec registry
+   - git remote matching / parent scan heuristics
+5. Partial-resolution support (unresolved roots are non-fatal for planning)

🤖 Prompt for AI Agents

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

In `@openspec/explorations/workspace-roadmap.md` around lines 130 - 133, Update
the "Resolution through:" bullet list under the Align phase so it matches the
offline-first chain decision: replace the current two bullets ("explicit input"
and "git remote matching") with a complete list that explicitly includes
"explicit input", "git remote matching", "local registry usage" and "unresolved
/ non‑fatal continuation (partial-resolution support)"; ensure the following
item ("Partial-resolution support") remains consistent or is merged into the
bullet list language and adjust wording so the section clearly communicates
offline-first resolution ordering and non-fatal continuation semantics (look for
the "Resolution through:" header and items 4–5 in the same block to make the
edit).

🤖 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/explorations/workspace-user-journeys.md`:
- Around line 327-334: Normalize all example project identifiers to the
canonical lowercase host/org/repo form (e.g., change
`github.com/Fission-AI/web-client`, `github.com/Fission-AI/contracts`,
`Fission-AI/web-client`, and `fission/web-client` to
`github.com/fission-ai/web-client` and `github.com/fission-ai/contracts`) so
casing is consistent; update every example occurrence (including the instances
noted in the comment) to use the lowercase normalized form and ensure any
explanatory text references the normalized host/org/repo pattern.

---

Nitpick comments:
In `@openspec/explorations/workspace-roadmap.md`:
- Around line 130-133: Update the "Resolution through:" bullet list under the
Align phase so it matches the offline-first chain decision: replace the current
two bullets ("explicit input" and "git remote matching") with a complete list
that explicitly includes "explicit input", "git remote matching", "local
registry usage" and "unresolved / non‑fatal continuation (partial-resolution
support)"; ensure the following item ("Partial-resolution support") remains
consistent or is merged into the bullet list language and adjust wording so the
section clearly communicates offline-first resolution ordering and non-fatal
continuation semantics (look for the "Resolution through:" header and items 4–5
in the same block to make the edit).

🪄 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: d773bf9f-4044-4bed-a496-50b0a8be9a54

📥 Commits

Reviewing files that changed from the base of the PR and between a18d992 and 0f89dec.

📒 Files selected for processing (4)

• openspec/explorations/workspace-architecture.md
• openspec/explorations/workspace-roadmap.md
• openspec/explorations/workspace-user-journeys.md
• openspec/explorations/workspace-ux-simplification.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Standardize canonical project ID casing in examples.

Canonical IDs are shown with mixed case (e.g., github.com/Fission-AI/...), while the architecture decision defines normalized host/org/repo. Use one canonical lowercase form in all examples to avoid ambiguity in linking/resolution semantics.

Proposed doc diff

-- `github.com/Fission-AI/web-client`
-- `github.com/Fission-AI/contracts`
+- `github.com/fission-ai/web-client`
+- `github.com/fission-ai/contracts`

-- github.com/Fission-AI/contracts
-- github.com/Fission-AI/billing-service
-- github.com/Fission-AI/web-client
-- github.com/Fission-AI/ios-client
+- github.com/fission-ai/contracts
+- github.com/fission-ai/billing-service
+- github.com/fission-ai/web-client
+- github.com/fission-ai/ios-client

Also applies to: 1155-1159, 1299-1304, 1544-1553, 1617-1618, 1998-1999

🤖 Prompt for AI Agents

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

In `@openspec/explorations/workspace-user-journeys.md` around lines 327 - 334,
Normalize all example project identifiers to the canonical lowercase
host/org/repo form (e.g., change `github.com/Fission-AI/web-client`,
`github.com/Fission-AI/contracts`, `Fission-AI/web-client`, and
`fission/web-client` to `github.com/fission-ai/web-client` and
`github.com/fission-ai/contracts`) so casing is consistent; update every example
occurrence (including the instances noted in the comment) to use the lowercase
normalized form and ensure any explanatory text references the normalized
host/org/repo pattern.