npm - sauron-cli - Versions diffs - 1.3.0 → 1.4.1 - Mend

sauron-cli 1.3.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (655) hide show

package/OpenSpec-main/openspec/explorations/workspace-user-journeys.md DELETED Viewed

@@ -1,2259 +0,0 @@
-# Workspace User Journeys
-## Purpose
-This document describes the exact user experience for OpenSpec across:
-1. Single-repo projects
-2. Monorepos
-3. Large monorepos that behave like many repos
-4. True multi-repo initiatives
-It is intentionally UX-first. The goal is to define:
-- Where the user starts
-- What commands they run
-- What the agent sees
-- Where artifacts are stored
-- How OpenSpec decides which specs to read
-- How OpenSpec behaves when roots are missing, ambiguous, or partially available
-This is a proposed UX model, not an implementation spec.
----
-## The Core Mental Model
-Users should not need one mental model for repos and a separate mental model for monorepos.
-OpenSpec should operate on **scopes**.
-A scope is an owned planning and implementation boundary. Depending on the codebase, a scope may be:
-- an entire repo
-- a package or app inside a monorepo
-- a service inside a monorepo
-- a shared contracts area
-- another explicitly owned domain
-The user experience should be:
-- Pick the thing you want to change
-- Confirm which scopes are involved
-- OpenSpec reads only the relevant specs
-- OpenSpec stores each artifact in the owning place
-- If the work spans multiple owning places, OpenSpec creates a neutral coordination workspace
-### Durable Objects
-There are three different durable objects:
-1. **Spec**
-   A canonical behavior contract. Always stored in the owning scope.
-2. **Change**
-   A repo-local or scope-local planning artifact. Stored with the owner of the implementation/spec delta.
-3. **Initiative**
-   A cross-scope coordination artifact. Only needed when work spans multiple owning roots. Stored in a neutral coordination workspace.
-The key rule is:
-> Canonical specs never move into the coordination workspace.
-The workspace coordinates. Owner roots remain canonical.
-### Cross-Boundary Specs
-Some behaviors are true across multiple scopes, apps, or repos:
-- checkout behavior shared by web, iOS, Android, and backend
-- auth/session rules shared by app clients and API services
-- billing rules shared by invoices, payments, and reporting
-- privacy or audit guarantees shared across many systems
-These are not just "references between local specs." They are first-class shared contracts.
-OpenSpec should model them explicitly as:
-1. **Canonical shared contract**
-   A spec that defines what must be true across boundaries.
-2. **Local implementation specs**
-   Per-scope specs describing how each owner satisfies that contract locally.
-3. **Initiative**
-   A change or project to update the contract and its implementations together.
-The first-principles rule is:
-> A cross-boundary spec may have many consumers, but it must still have one canonical owner.
-If there is no owner yet, the shared behavior can live temporarily as an initiative note during exploration, but OpenSpec should not promote it into a canonical spec until ownership is explicit.
----
-## UX Principles
-### 1. Same top-level workflow everywhere
-Users should still recognize the existing OpenSpec workflow:
-- `openspec init`
-- `openspec update`
-- `/opsx:explore`
-- `/opsx:propose`
-- `/opsx:apply`
-- `/opsx:archive`
-The new behavior is that OpenSpec may ask:
-- "Which scope does this affect?"
-- "Does this span multiple owning roots?"
-- "Should I create a coordination workspace?"
-### 2. No required upfront workspace registration
-Users should not have to pre-register all repos or modules just in case.
-OpenSpec should support:
-- ad hoc discovery
-- one-time local linking
-- optional saved workspaces later
-### 3. Cross-root planning must have a neutral home
-If a change spans multiple repos, the planning artifact should not be forced into one repo.
-Instead, OpenSpec should create a neutral coordination workspace for the initiative.
-### 4. Canonical storage follows ownership
-- Shared contract spec lives in the contract-owning scope
-- Web-specific spec lives in the web-owning scope
-- iOS-specific spec lives in the iOS-owning scope
-- Repo-local code tasks live in the repo-local change
-### 5. References are informational
-Cross-scope or cross-repo `references` should initially be documentation-only.
-OpenSpec may surface them to users and agents, but should not require them to resolve or validate across roots in the first version.
-### 6. Shared contracts need explicit ownership
-When the user describes behavior that spans multiple boundaries, OpenSpec should help them decide whether they are creating:
-- a local spec
-- a shared contract
-- an initiative note that is not yet canonical
-If the work is a real long-lived contract, OpenSpec should prompt for a canonical owner rather than burying it in whichever repo the user happened to be standing in.
-### 7. Do not force "shared ownership" as implicit co-ownership
-OpenSpec should help teams create **shared contract ownership**, not ambiguous co-ownership.
-That means:
-- one scope or repo owns the canonical shared contract
-- other scopes consume and reference it
-- coordination workspace can summarize it
-- ownership and review routes stay legible
-### 8. Use the current repo only as a starting point, not as truth
-When a user starts in `web-client` and describes a checkout behavior spanning web, iOS, Android, and backend, OpenSpec should treat the current cwd as a clue about likely consumers, not as proof that `web-client` should own the shared contract.
----
-## Terms
-### Project
-A single OpenSpec root where canonical specs and changes can live.
-In practice a project may be:
-- a repo root with `openspec/`
-- a monorepo root with one `openspec/`
-- a nested owned scope if OpenSpec later supports nested roots
-### Scope
-A logical boundary inside or across projects. Scopes are what users pick during planning.
-Examples:
-- `repo`
-- `contracts/checkout`
-- `apps/web`
-- `services/billing`
-- `mobile/ios`
-### Coordination Workspace
-A neutral directory used only for cross-root coordination. It stores initiative-level planning data and agent workspace instructions.
-Example:
-```text
-~/work/openspec-workspaces/add-3ds/
-  .openspec-workspace/
-    workspace.yaml
-    initiative.md
-    links.yaml
-    agents/
-      claude.md
-      codex.md
-```
-This coordination workspace may exist in two modes:
-1. **Personal coordination workspace**
-   A local directory used by one person for ad hoc or exploratory cross-root planning.
-2. **Shared coordination workspace**
-   A committed coordination repo or shared workspace used by a team or multiple teams.
-The UX should support both without changing the core mental model.
-### Owning Root
-The repo or scope that canonically owns a spec, codebase area, or repo-local change.
-### Shared Contract Owner
-The scope or repo that canonically owns a cross-boundary spec.
-This may be:
-- an existing shared contracts area inside a monorepo
-- an existing backend/API contract owner
-- a dedicated contracts repo
-- a new shared scope created as part of the planning flow
-This should not be an accidental consequence of where the user started the agent.
----
-## Recommended File Shapes
-### Single repo
-```text
-repo/
-  openspec/
-    specs/
-    changes/
-    config.yaml
-```
-### Monorepo
-```text
-monorepo/
-  openspec/
-    specs/
-    changes/
-    config.yaml
-  apps/
-    web/
-    admin/
-  services/
-    billing/
-  packages/
-    contracts/
-```
-Optional scope markers:
-```text
-monorepo/
-  apps/web/openspec.scope.yaml
-  services/billing/openspec.scope.yaml
-  packages/contracts/openspec.scope.yaml
-```
-### Multi-repo with coordination workspace
-```text
-~/work/
-  contracts/
-    openspec/
-  web-client/
-    openspec/
-  ios-client/
-    openspec/
-  openspec-workspaces/
-    add-3ds/
-      .openspec-workspace/
-        workspace.yaml
-        initiative.md
-        links.yaml
-        agents/
-          claude.md
-          codex.md
-```
----
-## Discovery Model
-OpenSpec needs to answer two separate questions:
-1. What scopes are involved?
-2. Where are they on disk right now?
-These are not the same problem.
-### Scope discovery
-OpenSpec discovers candidate scopes from:
-- the current repo root
-- `openspec/specs/**`
-- optional scope marker files
-- previous initiative metadata
-- explicit user selection
-### Root resolution
-For multi-repo work, durable identifiers should not be raw paths.
-Stable project identifiers should look like:
-- `github.com/Fission-AI/web-client`
-- `github.com/Fission-AI/contracts`
-User shorthand may be accepted:
-- `Fission-AI/web-client`
-- `fission/web-client`
-OpenSpec resolves these to local paths using this order:
-1. explicit path passed for this run
-2. saved local OpenSpec registry
-3. local git remote scanning
-4. user prompt
-Relative paths like `../web-client` may be used as temporary hints for a single run, but should not be the durable identifier.
-### Shared manifest vs local overlay
-For team use, OpenSpec should separate:
-1. **Shared coordination state**
-   Stable information that can be committed and shared with teammates.
-2. **Local resolution state**
-   Machine-specific path mappings and local availability.
-#### Shared coordination state should include
-- initiative ID and summary
-- stable project identifiers
-- selected scopes
-- linked repo-local change IDs
-- ownership metadata
-- rollout or sequencing notes
-- unresolved-but-known participating projects
-#### Local resolution state should include
-- local filesystem paths for project identifiers
-- local repo availability
-- local preferred clone among multiple matches
-- machine-specific agent attachment hints
-This separation is critical for a cohesive team story.
-Without it, coordination workspaces become either:
-- too local to share, or
-- polluted with machine-specific paths that break for teammates
----
-## Team Collaboration Model
-This section describes how the same UX should scale from one person to a large org.
-### Smallest unit: one user, one machine
-The user may create a local coordination workspace and keep everything local.
-This is fine for:
-- one-off cross-repo exploration
-- private planning before sharing
-- trying out a multi-repo idea
-### Team unit: shared initiative
-Once cross-repo work becomes collaborative, the coordination workspace should be shareable and committed.
-That means:
-- initiative metadata is committed
-- ownership decisions are committed
-- linked changes are committed
-- local paths are not committed
-### Cross-team unit: sponsored initiative
-When work spans teams, the initiative needs a clear coordination owner even if specs and code remain distributed.
-This is not the same as canonical spec ownership.
-There are now two distinct responsibilities:
-1. **Shared contract owner**
-   Owns the canonical cross-boundary spec.
-2. **Initiative sponsor/driver**
-   Owns the coordination process for the current change.
-These may be the same team, but they do not have to be.
-Examples:
-- Platform team sponsors rollout, auth team owns canonical auth contract
-- Payments team sponsors initiative, contracts repo owns canonical checkout contract
-- Mobile platform team sponsors app-wide migration, backend team owns API contract
-### What we should tell teams
-OpenSpec should communicate this clearly:
-> If the work is collaborative, treat the coordination workspace as a lightweight shared planning repo or committed workspace. Commit stable initiative metadata there, and keep machine-specific repo path mappings local.
-This gives a clean answer to:
-- how do we share the cross-repo plan?
-- how do teammates open the same initiative?
-- how do people with different local clone layouts work on the same initiative?
----
-## Ownership Decision Model
-This section answers a key product question:
-> How should a team or agent decide where a shared cross-boundary spec belongs?
-### First-principles heuristic
-OpenSpec should help teams choose the owner that can most credibly do all of the following:
-1. define the guarantee
-2. review and approve changes to that guarantee
-3. communicate the guarantee to consumers
-4. absorb the coordination cost when the guarantee changes
-The owner is not necessarily:
-- the team that started the change
-- the frontend team
-- the backend team
-- the repo with the most code
-The owner is the boundary where the contract is most stable and most authoritative.
-### Ownership decision questions
-When OpenSpec detects a likely shared contract, it should ask or infer from these questions:
-1. Is this behavior meant to be true across multiple scopes for the long term?
-2. Is it an external contract, an internal product rule, or an implementation detail?
-3. Which team or scope can approve changes to this contract?
-4. Which owner would consumers naturally look to as the source of truth?
-5. Does a shared contract area already exist?
-6. Will this contract likely outlive the current initiative?
-### Recommended outcomes
-#### Outcome A: Existing owner already exists
-Example:
-- `packages/contracts/checkout` already exists in a monorepo
-- `contracts` repo already exists in multi-repo environment
-OpenSpec should default to that existing owner.
-#### Outcome B: Shared contract belongs in an existing domain owner
-Example:
-- an API request/response contract belongs with the API/backend owner
-- a shared auth token contract belongs with the auth platform owner
-OpenSpec should suggest that existing domain owner if there is no dedicated shared area.
-#### Outcome C: A new shared contract scope should be created
-Example:
-- checkout behavior is shared across several clients and services
-- no existing shared owner exists
-- this will likely recur and needs long-term governance
-OpenSpec should help create a new shared contract scope.
-#### Outcome D: Keep it as initiative-only for now
-Example:
-- the team is still exploring
-- the boundary is unclear
-- no one can yet answer who should own the canonical guarantee
-OpenSpec should allow the behavior to remain in initiative notes temporarily and explicitly mark it as non-canonical until ownership is chosen.
-### What OpenSpec should suggest by default
-#### For monorepos
-Default suggestion order:
-1. existing shared contract scope inside the monorepo
-2. existing domain/platform owner
-3. create a new shared scope inside the monorepo
-4. keep as initiative-only until clarified
-#### For multi-repo environments
-Default suggestion order:
-1. existing contracts/shared-specs repo
-2. existing domain/platform repo that already owns the stable contract
-3. create a dedicated shared contracts repo or scope
-4. keep as initiative-only until clarified
-### What OpenSpec should not do
-OpenSpec should not:
-- silently assign ownership to the repo where the user started
-- duplicate the canonical shared spec across all consumers
-- call something canonical when no owner was chosen
-- force teams into a central admin setup before they can plan
----
-## Shared Contract Creation UX
-When the user describes a likely cross-boundary behavior, OpenSpec should treat this as a first-class planning moment.
-### Detection cues
-Signals that a shared contract may be needed:
-- request mentions multiple platforms or repos
-- request mentions "shared", "common", "contract", "same behavior", "consistent across"
-- selected scopes include clients plus backend
-- no existing spec cleanly owns the described behavior
-### Prompt shape
-During `/opsx:propose` or `/opsx:explore`, OpenSpec should ask something like:
-```text
-This looks like behavior shared across multiple scopes:
-- web
-- iOS
-- Android
-- backend
-What kind of artifact is this?
-- A local change within one scope
-- A shared contract that multiple scopes must follow
-- An initiative note for now; ownership is not clear yet
-```
-If the user chooses shared contract:
-```text
-Where should the canonical shared contract live?
-- Existing shared contracts scope
-- Existing domain owner
-- Create a new shared contract scope
-- Decide later and keep this initiative-only for now
-```
-### Creating a new shared contract scope
-If the user chooses "create a new shared contract scope," OpenSpec should guide them.
-#### Monorepo
-Prompt feel:
-```text
-Suggested new shared scopes:
-- openspec/specs/contracts/checkout
-- openspec/specs/shared/checkout
-- packages/contracts/checkout
-Who should own review for this contract?
-```
-OpenSpec then:
-1. creates the canonical shared spec in the chosen shared scope
-2. records selected consumers
-3. generates local references in consumer changes/specs if appropriate
-#### Multi-repo
-Prompt feel:
-```text
-No shared contract owner exists yet.
-Choose where the canonical contract should live:
-- Create it in an existing contracts repo
-- Create a new shared contracts repo later; keep initiative-only for now
-- Assign it to an existing domain owner repo
-```
-OpenSpec should avoid auto-creating a brand-new repo. It can scaffold the plan and record the decision, but repo creation may be organizationally sensitive and usually belongs outside the CLI.
-### Temporary initiative-only mode
-If ownership is unclear, OpenSpec should support:
-- storing the shared behavior in the initiative workspace as a draft note
-- marking it explicitly as non-canonical
-- reminding users to promote it into a canonical shared contract before long-term adoption
-This is important because many teams discover the need for a shared contract while exploring, before they know how to govern it.
----
-## Cohesive UX Across Team Size
-The product should feel like one system, not three separate features.
-### The invariant workflow
-No matter the setting, the user experience should always reduce to this:
-1. Start where you are
-2. Describe the work
-3. Confirm the affected scopes
-4. Let OpenSpec determine whether this is:
-   - local only
-   - multi-scope in one root
-   - cross-root coordination
-5. OpenSpec creates artifacts in the right places
-6. OpenSpec tells the user where to continue planning and where to implement
-### What changes by scale
-#### Solo / single repo
-- entry point: repo root
-- shareability: not relevant
-- local-only storage is fine
-#### Solo / ad hoc multi-repo
-- entry point: local coordination workspace
-- shareability: optional
-- local path mappings are sufficient
-#### Team / collaborative multi-repo
-- entry point: shared coordination repo/workspace
-- shareability: required
-- stable manifest committed, local paths private
-#### Large org / cross-team initiative
-- entry point: shared coordination repo/workspace
-- sponsor/driver is explicit
-- shared contract ownership is explicit
-- some participating teams may only resolve a subset of roots locally
-### What should remain consistent
-These things should not change with org size:
-- canonical specs live with owners
-- local code changes live with owners
-- shared contracts need one canonical owner
-- coordination data is not the canonical spec source
-- local machine paths are never the durable identifier
-- implementation may still happen root-by-root even if planning is coordinated
-If these invariants hold, the UX remains coherent across solo, team, and org-wide usage.
----
-## Agent Access Model
-Cross-root UX only works if the agent can actually see the relevant roots.
-OpenSpec should support three agent capability levels.
-### Level 1: Strong multi-root support
-The tool can explicitly attach multiple directories to one session.
-Desired UX:
-- User opens the coordination workspace
-- OpenSpec tells the user exactly which roots to attach
-- Agent reads from all attached roots
-### Level 2: Single cwd but filesystem access to linked roots
-The tool runs from one working directory but can still read sibling absolute paths if the environment permits it.
-Desired UX:
-- User opens the coordination workspace
-- OpenSpec writes agent-readable absolute paths into the workspace instructions
-- Agent can read those roots directly
-### Level 3: Practically single-root
-The tool can only reliably operate within one repo at a time.
-Desired UX:
-- Coordination workspace is used for planning only
-- OpenSpec guides the user into repo-local implementation sessions afterward
-- `/opsx:apply` runs in each repo separately
-This must be treated as a first-class case, not a fallback afterthought.
----
-## Current OpenSpec Flow To Preserve
-Today the flow is:
-1. User enters a repo
-2. User runs `openspec init`
-3. User opens an agent in that repo
-4. User runs `/opsx:explore` or `/opsx:propose`
-5. OpenSpec stores changes in `openspec/changes/<change>/`
-6. `/opsx:apply` implements within that repo
-That should remain the exact feel for single-repo work.
-The only extension is:
-- if OpenSpec detects a cross-root initiative, it explicitly upgrades the workflow into a coordination workspace flow
----
-## Journey 1: Single Repo, Standard OpenSpec Project
-### Starting state
-The user has one repo:
-```text
-~/work/acme-app/
-```
-They enter the repo:
-```bash
-cd ~/work/acme-app
-```
-They initialize OpenSpec:
-```bash
-openspec init
-```
-OpenSpec creates:
-```text
-openspec/
-  specs/
-  changes/
-  config.yaml
-```
-They open Claude, Codex, Cursor, or another agent inside this repo.
-### Planning
-The user types:
-```text
-/opsx:propose add-dark-mode
-```
-OpenSpec should:
-1. detect a single local project
-2. detect a single default scope: the repo
-3. create one repo-local change
-4. read only local project config and local specs
-5. generate local planning artifacts
-Output feel:
-```text
-Created openspec/changes/add-dark-mode/
-Using scope: repo
-Generated:
-- proposal.md
-- specs/ui/spec.md
-- design.md
-- tasks.md
-Ready for implementation with /opsx:apply
-```
-### Implementation
-The user types:
-```text
-/opsx:apply
-```
-OpenSpec reads:
-- proposal
-- specs
-- design
-- tasks
-Only from this repo.
-### Archival
-The user types:
-```text
-/opsx:archive
-```
-OpenSpec archives the change in this repo, as today.
-### Storage outcome
-- Spec deltas stored in this repo
-- Canonical specs stored in this repo
-- Tasks and design stored in this repo
-- No workspace concept surfaced
-### Edge cases
-- Multiple active changes in repo: prompt user to select one
-- Missing spec directories: proceed if allowed by current schema behavior
-- User runs from subdirectory: OpenSpec should either walk up or clearly tell them to run from repo root
----
-## Journey 2: Monorepo, Small Team, One Obvious Scope
-### Starting state
-The user has:
-```text
-~/work/platform/
-```
-Inside:
-```text
-platform/
-  openspec/
-  apps/web/
-  services/api/
-  packages/ui/
-```
-The user enters the monorepo root and runs their agent there.
-### Planning
-The user types:
-```text
-/opsx:propose add-invoice-filtering
-```
-OpenSpec detects this is still one project root, but there are multiple candidate scopes.
-If the user’s request clearly mentions one area, OpenSpec may infer:
-- `apps/web`
-Otherwise it asks:
-```text
-Which scope does this change affect?
-- apps/web
-- services/api
-- packages/ui
-- shared/contracts
-```
-The user picks `apps/web`.
-### Expected behavior
-OpenSpec should:
-1. create a single monorepo-local change under `openspec/changes/add-invoice-filtering/`
-2. tag that change with `apps/web`
-3. read specs relevant to `apps/web`
-4. avoid pulling unrelated monorepo areas into context
-### Storage outcome
-- One change in monorepo root
-- Scope selection recorded in change metadata
-- Delta specs only generated for the selected area
-### Why this matters
-The user should not feel like they are using a different product because they happen to be in a monorepo.
----
-## Journey 3: Monorepo, Cross-Scope Change
-### Starting state
-Same monorepo:
-```text
-platform/
-  openspec/
-  apps/web/
-  services/api/
-  packages/contracts/
-```
-### Planning
-The user types:
-```text
-/opsx:propose add-3ds-checkout
-```
-OpenSpec detects likely affected scopes:
-- `packages/contracts`
-- `services/api`
-- `apps/web`
-It asks:
-```text
-This appears to affect multiple scopes.
-Which scopes should be included?
-[x] packages/contracts
-[x] services/api
-[x] apps/web
-[ ] apps/admin
-[ ] packages/ui
-```
-### Expected behavior
-OpenSpec creates:
-```text
-platform/openspec/changes/add-3ds-checkout/
-```
-The change includes scope metadata listing all three selected scopes.
-OpenSpec reads:
-- shared contract specs
-- API specs for billing/checkout
-- web checkout specs
-OpenSpec ignores unrelated specs by default.
-### Implementation
-The user runs:
-```text
-/opsx:apply
-```
-OpenSpec should:
-1. show that multiple scopes are affected
-2. sequence tasks accordingly
-3. update one shared task artifact if the monorepo is still treated as one owning root
-### Storage outcome
-- One change at monorepo root
-- Delta specs for multiple scope paths
-- All canonical specs remain inside the monorepo
-### Important note
-This is still not a coordination workspace case, because there is still one owning project root.
----
-## Journey 4: Large Monorepo That Behaves Like Many Repos
-### Why this journey exists
-Some monorepos are operationally equivalent to multi-repo systems:
-- different teams own different areas
-- different release cadences
-- many developers should not edit each other’s planning setup
-- cross-team work is exceptional
-This means OpenSpec cannot assume:
-- one monorepo root automatically equals one planning unit
-### Starting state
-```text
-platform/
-  openspec/
-  apps/web/
-  apps/mobile/
-  services/billing/
-  services/orders/
-  packages/contracts/
-```
-Optional scope markers exist:
-```text
-apps/web/openspec.scope.yaml
-apps/mobile/openspec.scope.yaml
-services/billing/openspec.scope.yaml
-packages/contracts/openspec.scope.yaml
-```
-### Planning a local team change
-The web team enters the monorepo root, or a repo-aware subtool enters the web area.
-The user types:
-```text
-/opsx:propose add-checkout-loading-state
-```
-OpenSpec detects this is limited to `apps/web`.
-The user should experience this exactly like a single-scope change.
-### Planning a cross-team monorepo initiative
-The user types:
-```text
-/opsx:propose add-3ds
-```
-OpenSpec detects:
-- `packages/contracts`
-- `services/billing`
-- `apps/web`
-- possibly `apps/mobile`
-At this point OpenSpec must make a product decision.
-#### Recommended behavior
-If all affected scopes live under one owning root and the user is comfortable with one monorepo-local change, keep using one root-level change.
-If the monorepo is configured or inferred to behave like many owned sub-projects, offer to upgrade to a **coordination-style monorepo initiative**.
-Prompt feel:
-```text
-This monorepo has multiple independently owned scopes.
-How would you like to plan this work?
-- One monorepo change
-- Coordination initiative with linked scope changes
-```
-### Coordination-style monorepo initiative
-If the user chooses the coordination flow, OpenSpec creates:
-1. a neutral initiative workspace
-2. linked scope-local changes inside the monorepo root or scope-owned folders
-This is the same conceptual flow as multi-repo, but all roots happen to be inside one VCS root.
-### Why this matters
-This prevents the UX from hardcoding "monorepo is always simpler."
-That assumption fails for exactly the enterprise-style teams this feature is for.
----
-## Journey 5: Multi-Repo Work Started From Inside One Repo
-### Starting state
-The user is in:
-```text
-~/work/web-client
-```
-They already use OpenSpec there.
-They open Claude in `web-client` and type:
-```text
-/opsx:propose add-3ds
-```
-During exploration or proposal generation, it becomes clear that the work also affects:
-- `contracts`
-- `billing-service`
-- `ios-client`
-### Critical UX requirement
-At this point OpenSpec should not silently create one cross-repo change inside `web-client`.
-That would be misleading, because:
-- the initiative is not owned by `web-client`
-- the agent does not yet have the other roots
-- canonical specs belong in other repos
-### Expected OpenSpec behavior
-OpenSpec interrupts the default single-repo flow and says:
-```text
-This work spans multiple owning roots:
-- github.com/Fission-AI/contracts
-- github.com/Fission-AI/billing-service
-- github.com/Fission-AI/web-client
-- github.com/Fission-AI/ios-client
-For cross-repo work, OpenSpec recommends creating a coordination workspace.
-Suggested location:
-~/work/openspec-workspaces/add-3ds
-Create it now?
-```
-If the user agrees, OpenSpec creates the workspace.
-If the user wants another location, they can choose it.
-### Coordination workspace creation
-Proposed CLI feel:
-```bash
-openspec workspace create add-3ds --at ~/work/openspec-workspaces/add-3ds
-```
-OpenSpec writes:
-```text
-~/work/openspec-workspaces/add-3ds/
-  .openspec-workspace/
-    workspace.yaml
-    initiative.md
-    links.yaml
-    agents/
-      claude.md
-      codex.md
-```
-### Repo resolution
-OpenSpec now resolves local paths for:
-- `github.com/Fission-AI/contracts`
-- `github.com/Fission-AI/billing-service`
-- `github.com/Fission-AI/web-client`
-- `github.com/Fission-AI/ios-client`
-Using:
-1. known local registry
-2. git remote scanning
-3. user confirmation if needed
-### Agent handoff
-OpenSpec then tells the user:
-```text
-Next step:
-1. Open your coding agent in ~/work/openspec-workspaces/add-3ds
-2. Attach these roots if your tool supports multi-root:
-   - /Users/me/work/contracts
-   - /Users/me/work/billing-service
-   - /Users/me/work/web-client
-   - /Users/me/work/ios-client
-OpenSpec has generated workspace instructions at:
-.openspec-workspace/agents/claude.md
-```
-### Planning from the workspace
-The user now starts the agent in the coordination workspace and runs:
-```text
-/opsx:propose add-3ds
-```
-Or OpenSpec may have already scaffolded the initiative and tell the agent to continue it.
-### Storage outcome
-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
-- agent workspace instructions
-Each repo stores its own execution change:
-- `contracts/openspec/changes/add-3ds-contract/`
-- `billing-service/openspec/changes/add-3ds-billing/`
-- `web-client/openspec/changes/add-3ds-web/`
-- `ios-client/openspec/changes/add-3ds-ios/`
-Those repo-local changes are where repo-specific tasks, delta specs, and local implementation state live.
-### Why this matters
-This gives the user a truthful answer to:
-- Where should I stand?
-- Where does the change live?
-- How does the agent see the other repos?
-The answer is:
-- stand in the coordination workspace for cross-repo planning
-- keep canonical changes/specs in their owners
----
-## Journey 6: Multi-Repo Work Started From a Neutral Place
-### Starting state
-The user already knows the work is cross-repo.
-They start in a neutral directory:
-```bash
-cd ~/work
-```
-They run:
-```bash
-openspec workspace create add-3ds --at ~/work/openspec-workspaces/add-3ds
-```
-Or a future higher-level shortcut:
-```bash
-openspec initiative new add-3ds
-```
-### OpenSpec prompts
-OpenSpec asks:
-```text
-Which repos or scopes are involved?
-```
-The user enters:
-- `github.com/Fission-AI/contracts`
-- `github.com/Fission-AI/billing-service`
-- `github.com/Fission-AI/web-client`
-- `github.com/Fission-AI/ios-client`
-OpenSpec resolves local clones and writes the workspace files.
-### Agent setup
-The user opens the coordination workspace in their agent.
-OpenSpec-generated agent instructions contain:
-- initiative summary
-- available roots
-- ownership map
-- guidance that canonical spec edits must be written back to owning roots
-### Planning behavior
-When the user runs:
-```text
-/opsx:explore
-```
-or
-```text
-/opsx:propose add-3ds
-```
-the agent reads:
-- workspace initiative metadata
-- relevant specs from attached roots
-- only for selected repos/scopes
-### Storage outcome
-Same as Journey 5, but the user never had to start from one repo first.
-### Why this journey matters
-Some users will intentionally want the initiative to live outside any single repo from the start.
-OpenSpec should support that directly.
----
-## Journey 6A: Team-Shared Multi-Repo Initiative
-### Starting state
-A team knows the work spans multiple repos and will involve multiple people over several days or weeks.
-They create or choose a shared coordination repo, for example:
-```text
-~/work/openspec-initiatives/
-```
-Or a team-owned repo such as:
-```text
-github.com/Fission-AI/initiatives
-```
-Inside it, OpenSpec creates:
-```text
-initiatives/
-  add-3ds/
-    .openspec-workspace/
-      workspace.yaml
-      initiative.md
-      links.yaml
-      agents/
-        claude.md
-        codex.md
-```
-### What gets committed
-The team commits:
-- initiative summary
-- stable project IDs
-- selected scopes
-- ownership decisions
-- linked repo-local change IDs
-- rollout and status notes
-### What stays local
-Each teammate keeps local path mappings outside the shared repo, for example in OpenSpec local config/data:
-- `github.com/Fission-AI/contracts` -> `/Users/alice/src/contracts`
-- `github.com/Fission-AI/contracts` -> `/home/bob/work/contracts`
-### Teammate workflow
-Each teammate:
-1. clones or pulls the shared coordination repo
-2. runs something like `openspec workspace doctor` or `openspec workspace sync`
-3. resolves any missing project IDs to local clones
-4. opens their agent from the shared coordination workspace
-### Agent startup behavior
-OpenSpec generates agent instructions using:
-- committed shared manifest
-- local path overlay
-This means every teammate sees the same initiative structure, but with their own valid filesystem paths.
-### Why this matters
-This is the team-scale version of "enter the coordination workspace."
-Without this distinction, the phrase sounds cohesive for one person but falls apart for shared planning.
----
-## Journey 6B: Cross-Team Initiative With Explicit Sponsor
-### Starting state
-The work spans:
-- platform/shared contracts
-- backend services
-- multiple clients
-- multiple teams
-### Expected setup
-OpenSpec should support the initiative being created in a shared coordination repo owned by the sponsoring or driving team.
-That sponsor is responsible for:
-- opening the initiative
-- linking participating projects
-- tracking initiative status
-- keeping ownership decisions visible
-But the sponsor does not automatically own:
-- all specs
-- all implementation changes
-- the canonical shared contract
-### Example
-- Payments team sponsors `add-3ds`
-- Contracts repo owns canonical checkout contract
-- Web team owns web implementation change
-- iOS team owns iOS implementation change
-- Billing team owns backend implementation change
-### User experience
-When another team member opens the shared coordination workspace, OpenSpec should make this explicit:
-```text
-Initiative sponsor:
-- payments-platform
-Canonical shared contract owner:
-- contracts
-Participating owners:
-- billing-service
-- web-client
-- ios-client
-```
-### Why this matters
-Without this, "shared ownership" becomes ambiguous and teams do not know whether they are reading:
-- a sponsor-owned plan
-- a canonical contract
-- or just another team’s local interpretation
----
-## Journey 7: Multi-Repo Planning When Only Some Repos Are Cloned
-### Starting state
-The user wants to plan work affecting:
-- contracts
-- billing-service
-- web-client
-- ios-client
-But only has these locally:
-- contracts
-- web-client
-### Expected behavior
-OpenSpec should still allow planning.
-It creates the coordination workspace and records:
-- resolved roots for `contracts` and `web-client`
-- unresolved status for `billing-service` and `ios-client`
-Prompt feel:
-```text
-Resolved locally:
-- contracts
-- web-client
-Not currently available locally:
-- billing-service
-- ios-client
-Planning can continue with partial context.
-Implementation in unresolved roots will remain pending until linked.
-```
-### Agent behavior
-The agent should:
-- use resolved repos for concrete planning
-- mention unresolved repos explicitly
-- avoid pretending it read their specs
-- generate pending placeholders in initiative tracking if needed
-### Storage outcome
-The coordination workspace may contain unresolved links such as:
-```yaml
-projects:
-  - id: github.com/Fission-AI/contracts
-    path: /Users/me/work/contracts
-    status: resolved
-  - id: github.com/Fission-AI/billing-service
-    status: unresolved
-  - id: github.com/Fission-AI/web-client
-    path: /Users/me/work/web-client
-    status: resolved
-  - id: github.com/Fission-AI/ios-client
-    status: unresolved
-```
-### Why this matters
-This keeps planning useful even when the environment is incomplete.
-Blocking planning here would make the feature brittle.
-This also matters for large teams, because not every teammate will have every participating repo cloned or accessible.
----
-## Journey 8: How Specs Are Read During Planning
-This is one of the most important behavioral rules.
-OpenSpec should never blindly read all specs from all roots.
-### Single repo
-Read:
-- local project config
-- local specs relevant to the selected scope
-- local change history only if helpful
-Do not read:
-- unrelated local specs by default
-### Monorepo
-Read:
-- root project config
-- specs for the selected scopes
-- shared contract specs if selected or referenced
-Do not read:
-- unrelated apps/services/packages
-### Multi-repo
-Read:
-- initiative metadata from coordination workspace
-- specs in resolved attached roots
-- only the selected scopes within those roots
-- informational references if the user or agent explicitly chooses to open them
-Do not read:
-- specs from unresolved roots
-- every spec in every repo
-- referenced specs automatically if that would explode context
-### Informational references
-References should appear like:
-```text
-Related references:
-- github.com/Fission-AI/contracts: openspec/specs/checkout/spec.md
-- github.com/Fission-AI/web-client: openspec/specs/checkout/web/spec.md
-```
-The agent can use them as navigation hints.
-They are not validation blockers.
-### Shared contract read order
-When a selected change involves a shared contract, OpenSpec should prefer this read order:
-1. initiative metadata, if present
-2. canonical shared contract
-3. selected consumer/local specs
-4. repo-local change artifacts
-This matters because the shared contract defines the boundary-level truths, while local specs describe how each consumer satisfies them.
----
-## Journey 9: How Artifacts Are Stored
-This must stay simple and deterministic.
-### Rule 1: Canonical specs live with owners
-Examples:
-- Checkout contract spec lives in `contracts`
-- Web checkout behavior lives in `web-client`
-- iOS behavior lives in `ios-client`
-### Rule 2: Repo-local changes live with repo owners
-Examples:
-- `contracts/openspec/changes/add-3ds-contract/`
-- `web-client/openspec/changes/add-3ds-web/`
-These changes are the execution artifacts for each owning repo. They should carry repo-specific tasks, delta specs, and local implementation state.
-### Rule 3: Initiative-level planning lives in the coordination workspace
-Examples:
-- proposal.md
-- design.md
-- initiative summary
-- rollout sequencing
-- cross-repo assumptions
-- ownership, milestones, risks, and dependencies
-- links between repo-local changes
-### Rule 4: Workspace never becomes canonical spec storage
-The coordination workspace may reference specs and summarize them.
-It should not become a second spec source of truth.
-### Rule 5: Shared contracts are canonical only after ownership is explicit
-If a cross-boundary behavior has not yet been assigned a canonical owner, OpenSpec should store it as initiative-level draft material rather than pretending it is already a canonical spec.
-### Rule 6: Shared coordination workspaces store stable collaboration data, not local machine state
-If a coordination workspace is committed for team use, it should contain:
-- stable project IDs
-- linked changes
-- ownership and initiative metadata
-It should not contain:
-- `/Users/...` paths
-- `C:\\...` paths
-- machine-specific attached-root state
-That information belongs in local overlay data.
----
-## Journey 10: `/opsx:apply` In Cross-Root Work
-Implementation UX must remain honest about tool limits.
-### Case A: Agent can work across roots
-The user is in the coordination workspace.
-They run:
-```text
-/opsx:apply
-```
-OpenSpec responds:
-```text
-This initiative has linked changes in:
-- contracts
-- billing-service
-- web-client
-- ios-client
-Choose apply mode:
-- Apply one linked change
-- Apply in suggested sequence
-```
-Recommended default:
-- apply one linked change at a time
-This keeps task state and implementation context manageable.
-### Case B: Agent is practically single-root
-The user is in the coordination workspace and runs:
-```text
-/opsx:apply
-```
-OpenSpec should say:
-```text
-This initiative spans multiple repos.
-Implementation must be run per repo in your current tool.
-Next suggested step:
-- open /Users/me/work/contracts and run /opsx:apply add-3ds-contract
-```
-### Why this matters
-Cross-repo planning and cross-repo implementation are not the same capability.
-The UX must not assume all agents can do both well.
----
-## Journey 10A: Creating A Shared Contract In A Monorepo
-### Starting state
-The user is in a monorepo with:
-```text
-platform/
-  openspec/
-  apps/web/
-  apps/ios/
-  apps/android/
-  services/billing/
-```
-There is no existing canonical `checkout` shared contract.
-### User request
-The user types:
-```text
-/opsx:propose add-3ds-checkout
-```
-The agent discovers the request spans:
-- web
-- iOS
-- Android
-- billing backend
-### Expected prompt
-```text
-This looks like a cross-boundary behavior shared by multiple scopes.
-Should OpenSpec treat this as:
-- A shared contract
-- Independent local changes only
-- An initiative note for now
-```
-The user chooses shared contract.
-OpenSpec then asks:
-```text
-Where should the canonical shared contract live?
-- openspec/specs/contracts/checkout
-- openspec/specs/shared/checkout
-- keep it initiative-only for now
-```
-### Expected storage result
-OpenSpec creates:
-- canonical shared contract in chosen shared scope
-- repo-local change under monorepo root
-- local delta specs for selected consumer scopes as needed
-### Why this matters
-This keeps one source of truth for the cross-boundary behavior, instead of smearing the same logic across web, iOS, Android, and backend specs.
----
-## Journey 10B: Creating A Shared Contract In A Multi-Repo Environment
-### Starting state
-The user is planning a checkout initiative involving:
-- `contracts`
-- `web-client`
-- `ios-client`
-- `android-client`
-- `billing-service`
-There is no existing shared checkout contract.
-### Planning flow
-The user creates or enters a coordination workspace.
-They run:
-```text
-/opsx:propose add-3ds
-```
-OpenSpec detects this likely requires a shared contract.
-### Expected prompt
-```text
-No canonical shared contract owner was found for this behavior.
-Choose how to proceed:
-- Create the canonical contract in an existing contracts repo
-- Assign the contract to an existing domain owner repo
-- Keep it as initiative-only for now
-```
-If the user selects an existing contracts repo, OpenSpec:
-1. creates a repo-local change in that repo for the shared contract
-2. links consumer repo changes to it
-3. records references from consumers to the canonical contract
-If the user keeps it initiative-only, OpenSpec:
-1. stores the draft cross-boundary behavior in initiative notes
-2. marks it as non-canonical
-3. warns that long-term consumer behavior should not depend on this until promoted into an owned shared contract
-### Why this matters
-This avoids a bad default where whichever app team starts the change accidentally becomes the long-term owner of a cross-org contract.
----
-## Journey 11: Archiving Cross-Root Work
-### Single repo or simple monorepo
-Same as today:
-```text
-/opsx:archive
-```
-### Multi-repo initiative
-The user in the coordination workspace runs:
-```text
-/opsx:archive
-```
-OpenSpec checks linked repo changes:
-- archived
-- ready to archive
-- still active
-- unresolved
-Prompt feel:
-```text
-Initiative: add-3ds
-Linked change status:
-- contracts/add-3ds-contract: complete
-- billing-service/add-3ds-billing: complete
-- web-client/add-3ds-web: active
-- ios-client/add-3ds-ios: unresolved
-Archive options:
-- Archive completed linked changes only
-- Mark initiative partially complete
-- Wait until all linked changes are done
-```
-### Recommended behavior
-Allow partial completion states.
-Cross-repo work often lands asynchronously.
----
-## Setup Journeys
-The setup path needs to feel lightweight.
-## Journey 12: Day-Zero Setup For A Single Repo User
-### Steps
-1. `cd repo`
-2. `openspec init`
-3. open agent in repo
-4. run `/opsx:propose`
-No workspace concepts shown.
----
-## Journey 13: Day-Zero Setup For A Monorepo Team
-### Steps
-1. `cd monorepo`
-2. `openspec init`
-3. optionally add scope markers for major owned areas
-4. run `openspec update`
-5. open agent in monorepo root
-During planning, OpenSpec asks for scope selection when needed.
-No separate workspace admin step is required.
----
-## Journey 14: Day-Zero Setup For A Multi-Repo Team
-### Steps
-1. each repo independently runs `openspec init`
-2. user creates a coordination workspace only when cross-repo work arises
-3. user links repo IDs to local clones as needed
-4. user opens the agent in the coordination workspace for planning
-This is important:
-The system should not require a platform team to pre-register every repo before any real work can begin.
----
-## Agent Instruction Requirements
-When OpenSpec creates a coordination workspace, it should generate agent-facing files.
-Minimum contents:
-1. initiative summary
-2. selected scopes
-3. owning roots and resolved paths
-4. unresolved roots
-5. storage rules
-6. implementation limitations for the current tool if known
-### Example `claude.md`
-```md
-You are working on initiative `add-3ds`.
-Resolved roots:
-- /Users/me/work/contracts
-- /Users/me/work/web-client
-Unresolved roots:
-- github.com/Fission-AI/billing-service
-- github.com/Fission-AI/ios-client
-Ownership:
-- contracts owns shared checkout contract
-- web-client owns web checkout behavior
-Rules:
-- Canonical specs must be edited in owning roots
-- Initiative-level notes live in this coordination workspace
-- Cross-repo references are informational only
-```
-This file should be generated for any supported agent integration that benefits from deterministic startup context.
----
-## Scenarios Summary
-### Happy paths
-1. Single repo, one change
-2. Monorepo, one scope
-3. Monorepo, multiple scopes
-4. Large monorepo, coordination-style initiative
-5. Multi-repo, all roots locally available
-6. Multi-repo, partial local availability
-### Important transitions
-1. Single repo request escalates into multi-repo
-2. Monorepo request escalates into coordination-style planning
-3. Planning workspace hands off to repo-local implementation
-4. Partial cross-repo completion at archive time
-5. Initiative-only shared behavior gets promoted into a canonical shared contract
----
-## Edge Cases
-### 1. User starts in the "wrong" repo
-Example:
-- User starts in `web-client`
-- Work actually spans `contracts`, `web-client`, `ios-client`
-Expected behavior:
-- OpenSpec recommends creating a coordination workspace
-- It does not bury the whole initiative inside `web-client`
-### 2. User wants the initiative stored elsewhere
-Expected behavior:
-- allow explicit path selection
-- remember recent workspace locations if useful
-### 3. Two local clones match the same repo identifier
-Expected behavior:
-- prompt user to choose one
-- optionally save preferred mapping locally
-### 4. Repo identifier cannot be resolved
-Expected behavior:
-- store as unresolved
-- allow planning to continue
-- block implementation for that root only
-### 5. Monorepo has no explicit scope metadata
-Expected behavior:
-- infer likely scopes from structure and specs
-- let the user confirm
-- offer to save the selection model later
-### 6. Scope selection is too broad
-Expected behavior:
-- warn user that many scopes will be pulled into planning
-- suggest narrowing
-### 7. Shared contract ownership is ambiguous
-Expected behavior:
-- require one canonical owner
-- other scopes/repos can reference it, not co-own it implicitly
-### 7A. No existing shared owner makes sense
-Expected behavior:
-- let the team keep the behavior as initiative-only temporarily
-- explicitly mark it as draft and non-canonical
-- prompt for promotion later if it starts behaving like a long-lived contract
-### 8. Agent cannot truly work across roots
-Expected behavior:
-- use coordination workspace for planning only
-- guide user into per-root apply flows
-### 9. Workspace goes stale
-Examples:
-- repo moved on disk
-- repo renamed
-- remote URL changed
-Expected behavior:
-- `openspec workspace doctor` or equivalent relinks roots
-- initiative metadata remains stable because identifiers are durable, paths are not
-### 10. One repo is archived or intentionally deferred
-Expected behavior:
-- initiative can remain partially complete
-- not every linked root must land simultaneously
-### 11. Users do not want admin-managed setup in giant monorepos
-Expected behavior:
-- scope discovery should be local and incremental
-- setup should not require one central team to define everything first
-### 12. Users want ad hoc multi-repo work only once
-Expected behavior:
-- allow a one-off coordination workspace
-- do not force long-lived workspace management
-### 13. Teams want to share a coordination workspace
-Expected behavior:
-- support a committed shared coordination repo or workspace
-- keep machine-specific resolution data local
-- let each teammate resolve project IDs independently
-### 14. Cross-team initiatives need different ownership roles
-Expected behavior:
-- distinguish initiative sponsor from canonical shared contract owner
-- make both visible in workspace metadata and agent instructions
----
-## Product Decisions This UX Implies
-If OpenSpec adopts these journeys, several design conclusions follow.
-### 1. Multi-repo planning needs a first-class coordination workspace
-Without this, OpenSpec has no honest answer to where the user should stand or where the cross-repo initiative should live.
-### 2. Repo-local changes and canonical specs should stay in owners
-Without this, OpenSpec creates duplicate or misleading sources of truth.
-### 3. Large monorepos cannot be treated as always-simple single roots
-OpenSpec must support both:
-- one-root monorepo changes
-- coordination-style monorepo initiatives
-### 4. Discovery and resolution are different systems
-OpenSpec must separately handle:
-- identifying scopes
-- resolving local paths for durable project identifiers
-### 5. Agent startup context needs explicit generation
-Cross-root planning only works reliably if OpenSpec writes deterministic workspace context for the agent.
-### 6. References should stay informational in v1
-If OpenSpec validates cross-root references by default, it has effectively shipped a dependency graph system.
-That should be a later, optional capability.
-### 7. Shared contract creation needs a guided ownership flow
-Without this, teams will either:
-- duplicate shared behavior across repos
-- assign ownership accidentally
-- or avoid creating cross-boundary specs altogether
-OpenSpec should help users choose among:
-- existing shared owner
-- existing domain owner
-- new shared contract scope
-- initiative-only draft mode
-### 8. Shared coordination needs a two-layer storage model
-To support teams and orgs cleanly, OpenSpec should distinguish:
-- committed shared initiative metadata
-- local machine-specific path resolution
-Without that split, the UX will either:
-- fail to scale beyond one user, or
-- leak machine-specific state into shared artifacts
----
-## Open Questions
-These journeys intentionally leave some implementation choices open.
-1. Should a coordination workspace always be user-visible on disk, or may it optionally live in global OpenSpec data directories?
-2. Should monorepo coordination-style initiatives reuse the same workspace concept as multi-repo, or use a lighter in-repo variant?
-3. Should OpenSpec support nested `openspec/` roots, or keep one root and model scopes separately?
-4. What is the minimum metadata required to represent selected scopes and linked changes?
-5. What is the exact format split between committed shared workspace state and local overlay state?
-6. Which agents should receive generated workspace instructions, and in what format?
-7. What exact CLI surface should create and manage coordination workspaces?
----
-## Recommended Next Step
-Convert these journeys into a concrete design proposal covering:
-1. coordination workspace file format
-2. scope metadata shape
-3. repo identifier and local resolution model
-4. linked change model
-5. shared manifest vs local overlay model
-6. CLI commands for create, attach, doctor, sync, and archive flows
-7. agent instruction generation for supported tools