docs: clarify initiative-first workspace model#969
Conversation
|
Task completed. I'll review this PR by examining the changes in detail. Powered by 1Code |
📝 WalkthroughWalkthroughReplaces change-scoped cross-repo linking with an initiative-first model: a coordination workspace stores initiative-level artifacts (proposal, design, metadata, links), while repo-local changes become execution artifacts that link back to initiatives. Terminology, workflows, and roadmap steps updated to reflect this split between planning and execution. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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. 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: 2
🧹 Nitpick comments (1)
openspec/explorations/workspace-architecture.md (1)
809-816: Add an explicit AGENTS alignment checkpoint in the implementation path.Given this is a planning-model shift, include a step to validate artifact names/flow against
openspec/AGENTS.mdconventions before rollout.Based on learnings: Always open
@/openspec/AGENTS.mdwhen the request mentions planning/proposals or architecture shifts.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/explorations/workspace-architecture.md` around lines 809 - 816, Add an explicit AGENTS alignment checkpoint into the implementation steps so each rollout step validates artifact names and workflow against the conventions in "@/openspec/AGENTS.md": update the plan around "Define initiative artifacts", "Extend change metadata", and "Build initiative and link views" to include a pre-rollout verification task that opens and checks AGENTS.md, ensuring initiative formats, `references` usage, linked change naming, and multi-root derivation conform to AGENTS conventions before proceeding.
🤖 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-architecture.md`:
- Around line 732-742: Label this YAML snippet as a proposed/target state rather
than current behavior by adding a clear indicator (e.g., a top-level key or a
comment) that marks it as "target" or "proposed" so implementers know
`initiative` is future metadata; update the snippet surrounding text or the YAML
itself to include that marker and mention `initiative` as a proposed field so
readers understand this example is not yet supported by the current schema
(refer to the `initiative` key and the `schema: spec-driven` example block).
In `@openspec/explorations/workspace-user-journeys.md`:
- Around line 1237-1244: The document inconsistently references two artifact
shapes (proposal.md/design.md vs. initiative.md); pick one canonical artifact
model or explicitly define both modes and their mapping. Update all occurrences
(e.g., the list containing proposal.md, design.md, initiative summary and other
places that mention initiative.md) so they consistently use the chosen canonical
names, and add a short section that maps fields between proposal.md/design.md
and initiative.md if you keep both modes, including examples of required files
and where ownership/milestones/risks/dependencies should live.
---
Nitpick comments:
In `@openspec/explorations/workspace-architecture.md`:
- Around line 809-816: Add an explicit AGENTS alignment checkpoint into the
implementation steps so each rollout step validates artifact names and workflow
against the conventions in "@/openspec/AGENTS.md": update the plan around
"Define initiative artifacts", "Extend change metadata", and "Build initiative
and link views" to include a pre-rollout verification task that opens and checks
AGENTS.md, ensuring initiative formats, `references` usage, linked change
naming, and multi-root derivation conform to AGENTS conventions before
proceeding.
🪄 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: 7bcdae4f-b777-470c-9498-8fda6c91252e
📒 Files selected for processing (2)
openspec/explorations/workspace-architecture.mdopenspec/explorations/workspace-user-journeys.md
| ```yaml | ||
| # billing-service/openspec/changes/add-3ds/.openspec.yaml | ||
| schema: spec-driven | ||
| created: 2026-04-12 | ||
| initiative: add-3ds | ||
| links: | ||
| - project: github.com/fission/web-client | ||
| change: add-3ds-checkout | ||
| - project: github.com/fission/ios-client | ||
| change: add-3ds-checkout | ||
| ``` |
There was a problem hiding this comment.
Clarify this YAML as “target state,” not current behavior.
This example introduces initiative, but current metadata schema (in src/core/artifact-graph/types.ts) does not yet include it. Please label this snippet as proposed/future to avoid implementer confusion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/explorations/workspace-architecture.md` around lines 732 - 742,
Label this YAML snippet as a proposed/target state rather than current behavior
by adding a clear indicator (e.g., a top-level key or a comment) that marks it
as "target" or "proposed" so implementers know `initiative` is future metadata;
update the snippet surrounding text or the YAML itself to include that marker
and mention `initiative` as a proposed field so readers understand this example
is not yet supported by the current schema (refer to the `initiative` key and
the `schema: spec-driven` example block).
| The coordination workspace stores the **initiative-level planning object**: | ||
|
|
||
| - proposal.md | ||
| - design.md | ||
| - initiative summary | ||
| - cross-repo scope map | ||
| - ownership, milestones, risks, and dependencies | ||
| - links to repo-local changes |
There was a problem hiding this comment.
Unify initiative artifact shape across this doc.
These updated sections use proposal.md/design.md, but other journey file-shape examples still describe initiative.md as the primary artifact. Please standardize one canonical structure (or explicitly define both modes) to avoid conflicting implementation guidance.
Also applies to: 1668-1674
🤖 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 1237 - 1244,
The document inconsistently references two artifact shapes
(proposal.md/design.md vs. initiative.md); pick one canonical artifact model or
explicitly define both modes and their mapping. Update all occurrences (e.g.,
the list containing proposal.md, design.md, initiative summary and other places
that mention initiative.md) so they consistently use the chosen canonical names,
and add a short section that maps fields between proposal.md/design.md and
initiative.md if you keep both modes, including examples of required files and
where ownership/milestones/risks/dependencies should live.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
openspec/explorations/explore-workflow-ux.md (1)
36-40: Add explicit “when to use initiative-first” criteriaThe doc now introduces both change-linked and initiative-first exploration, but the switch condition is still implicit. Add a short rule-of-thumb (e.g., cross-team/cross-repo/coordination-heavy) near these lines to reduce operator ambiguity.
Also applies to: 46-47, 99-101
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/explorations/explore-workflow-ux.md` around lines 36 - 40, Add a concise "When to use initiative-first" rule-of-thumb under the "How do explorations relate to changes or initiatives?" section: insert a short bullet like "Use initiative-first for cross-team, cross-repo, or coordination-heavy work" next to the existing bullets, and replicate the same sentence or equivalent brief guideline in the two other places called out (around the content at lines 46-47 and 99-101) so the criterion is explicit and consistent across the document.openspec/explorations/workspace-roadmap.md (1)
128-130: Phase 2 bullets 2 and 3 read as overlappingLine 129 and Line 130 both describe project-ID-based linking. Consider merging into one bullet to reduce ambiguity about whether these are distinct deliverables.
🤖 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 128 - 130, Phase 2 bullets 2 ("Linked per-repo changes using stable project identifiers") and 3 ("Explicit repo linking via project IDs") are duplicate; merge them into a single bullet that combines both concepts (e.g., "Linked per-repo changes and explicit repo linking using stable project/project IDs") to remove ambiguity and ensure it's clear there is one deliverable around project-ID-based linking rather than two separate ones.
🤖 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-roadmap.md`:
- Around line 316-320: Reorder the bullet list so the container/capability
appears before the artifact it hosts: move "thin coordination workspace / repo
for multi-repo planning" (current item referring to the coordination
workspace/repo) to come before "initiative artifact for shared planning" so the
sequence is: coordination workspace/repo first, then initiative artifact,
followed by linked change metadata, team-shared coordination hardening, and
optional shared contract maturity features; update the list order in the
workspace-roadmap document accordingly.
---
Nitpick comments:
In `@openspec/explorations/explore-workflow-ux.md`:
- Around line 36-40: Add a concise "When to use initiative-first" rule-of-thumb
under the "How do explorations relate to changes or initiatives?" section:
insert a short bullet like "Use initiative-first for cross-team, cross-repo, or
coordination-heavy work" next to the existing bullets, and replicate the same
sentence or equivalent brief guideline in the two other places called out
(around the content at lines 46-47 and 99-101) so the criterion is explicit and
consistent across the document.
In `@openspec/explorations/workspace-roadmap.md`:
- Around line 128-130: Phase 2 bullets 2 ("Linked per-repo changes using stable
project identifiers") and 3 ("Explicit repo linking via project IDs") are
duplicate; merge them into a single bullet that combines both concepts (e.g.,
"Linked per-repo changes and explicit repo linking using stable project/project
IDs") to remove ambiguity and ensure it's clear there is one deliverable around
project-ID-based linking rather than two separate ones.
🪄 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: 71e9f984-2284-42d0-8e77-638f1b302afd
📒 Files selected for processing (2)
openspec/explorations/explore-workflow-ux.mdopenspec/explorations/workspace-roadmap.md
| 3. initiative artifact for shared planning | ||
| 4. linked change metadata across repos | ||
| 5. thin coordination workspace / repo for multi-repo planning | ||
| 6. team-shared coordination hardening | ||
| 7. optional shared contract maturity features |
There was a problem hiding this comment.
Reorder deliverables to respect dependency flow
Line 316 introduces the initiative artifact before Line 318 introduces the coordination workspace/repo that hosts it. Consider swapping these so container/capability comes before hosted artifact to avoid sequencing confusion in implementation planning.
Suggested reorder
-3. initiative artifact for shared planning
-4. linked change metadata across repos
-5. thin coordination workspace / repo for multi-repo planning
+3. thin coordination workspace / repo for multi-repo planning
+4. initiative artifact for shared planning
+5. linked change metadata across repos📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 3. initiative artifact for shared planning | |
| 4. linked change metadata across repos | |
| 5. thin coordination workspace / repo for multi-repo planning | |
| 6. team-shared coordination hardening | |
| 7. optional shared contract maturity features | |
| 3. thin coordination workspace / repo for multi-repo planning | |
| 4. initiative artifact for shared planning | |
| 5. linked change metadata across repos | |
| 6. team-shared coordination hardening | |
| 7. optional shared contract maturity features |
🤖 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 316 - 320, Reorder
the bullet list so the container/capability appears before the artifact it
hosts: move "thin coordination workspace / repo for multi-repo planning"
(current item referring to the coordination workspace/repo) to come before
"initiative artifact for shared planning" so the sequence is: coordination
workspace/repo first, then initiative artifact, followed by linked change
metadata, team-shared coordination hardening, and optional shared contract
maturity features; update the list order in the workspace-roadmap document
accordingly.
2 participants
Summary
Why
Changes currently bundle proposal, design, tasks, delta specs, and metadata. That works well for repo-local work, but gets awkward for cross-team and cross-repo planning because one repo-local change ends up trying to act as both the shared plan and the local execution artifact.
This exploration update makes the split explicit:
Summary by CodeRabbit