Portable workspaces

For a guided first task, Start here or choose a workflow. This page is the detailed reference.

A workspace is an adopter-owned Git repository that holds the shared, cross-repository memory for a product made of several independent repositories. It is deliberately separate from every member repository: the workspace owns the shared records, while each member keeps its own method, instructions and history. A workspace is plain files checked by a deterministic validator — not a scheduler, a service, an authentication layer or a live ownership register.

Use a workspace when one product spans more than one repository and the shared picture — outcomes, decisions, work, knowledge and executed runs — does not belong inside any single member. Stay with a single plan/ queue when one repository is the whole product; adding a workspace then adds a second place to look for no benefit.

What a workspace contains

An adopter creates the workspace deliberately (the workspace-setup command). It owns README.md, AGENTS.md and .docflow_workspace/ with workspace.yaml, CONVENTIONS.md, INDEX.md, the record folders and curated agents, profiles and integrations directories. Independent checkouts may live in ignored repos/, at sibling paths or at explicitly registered absolute paths. Private local state lives under /.docflow_workspace/local/. Ignore that local directory and the optional /repos/ checkout directory in the workspace Git home; neither is canonical.

graph LR WS[".docflow_workspace
workspace home"] WS --- REG["workspace.yaml
registry"] WS --- IDEAS["ideas/"] WS --- DEC["decisions/"] WS --- WORK["work/"] WS --- KNOW["knowledge/"] WS --- RUNS["runs/"] WS --- MAND["mandates/"] WS -->|registers| A["docflow member
native ADR catalogue + plan/ queue"] WS -->|registers| B["non-docflow member
native AGENTS.md + own workflow"] WS -.->|identity only| C["remote-only reference"]

When to use a workspace

Greenfield multi-repository product. You are starting a product that will span several repositories and want one shared record from day one.
Existing repositories that already work together. You have a handful of repositories with their own conventions and no shared cross-repository view.
A single docflow repository outgrowing itself. One repository holds the decisions today; a second is about to appear.
A federation that needs a home. You already federate ADR catalogues across repositories and want ideas, work, deliveries and runs in one place.

A workspace does not replace native repositories. It records shared outcomes and observed delivery; each member still runs its own workflow and completes its own work.

Kinds of items and their workflows

The workspace holds six kinds of item. Each is a Markdown file with a JSON-compatible front matter block, and each has an identity {home, id}; references are durable and source-bound.

Kind	What it is for	States
Idea	A candidate outcome not yet agreed. Sets priority only.	backlog → selected / rejected / discarded
Decision	An accepted shared choice. Acceptance records agreement, not execution.	proposed → accepted / rejected / superseded
Work	A unit of cross-repository work, with deliveries and testable criteria.	planned → active → review → done / cancelled
Knowledge	A sourced observation or reference, including external and derived documents.	no lifecycle; has `review_when`
Run	One executed assignment: a dispatched attempt, or an imported historical record.	running → succeeded / failed / stopped / unknown
Mandate note	The committed operator note that authorises a decision acceptance or a grant.	immutable record

stateDiagram-v2 direction LR state "Idea" as I { [*] --> backlog backlog --> selected backlog --> rejected backlog --> discarded selected --> backlog selected --> rejected selected --> discarded rejected --> backlog discarded --> backlog } state "Decision" as D { [*] --> proposed proposed --> accepted proposed --> rejected proposed --> superseded accepted --> superseded rejected --> superseded } state "Work" as W { [*] --> planned planned --> active active --> review review --> active review --> done planned --> cancelled active --> cancelled review --> cancelled } state "Run" as R { [*] --> running running --> succeeded running --> failed running --> stopped running --> unknown unknown --> succeeded unknown --> failed unknown --> stopped }

Work and deliveries. Work owns one or more deliveries, each with a testable criterion. A delivery is observed from the member’s own native evidence: a merge, a required check, a plan/todo→plan/done move, a branch head. Work reaches done only when every required delivery records its native completion with passed evidence, and every criterion has passed evidence. Completing work leaves the still-current agreement accepted.

Runs, dispatched and imported. A dispatched run carries a brief bound to an exact grant revision, then a receipt with the exact commands, exit codes, source revisions, evidence, blockers and next action. An imported run has no brief and no grant: it backfills execution that happened under a native mandate, is read-only, and can never satisfy a dispatch, an active work-state check or a claim overlap.

Mandate notes. Authority is never a chat message. An accepted decision or a grant cites a committed mandate note under .docflow_workspace/mandates/<date>-<slug>.md by workspace home, path and full Git revision; the cited revision must contain the note.

The five commands

graph TD SETUP["workspace-setup
create or adopt the home"] STATUS["workspace-status
read-only briefing"] SCOPE["workspace-scope
ideas, decisions, work,
deliveries, criteria, grants"] DISPATCH["workspace-dispatch
check authority, write a brief"] SYNC["workspace-sync
reconcile receipts, refresh INDEX"] SETUP --> STATUS --> SCOPE --> DISPATCH --> SYNC SYNC -.->|next briefing| STATUS

workspace-setup creates or deliberately adopts the workspace home and registry. It establishes the home; scope, dispatch and sync maintain their own canonical records within it.
workspace-status gives a read-only briefing and fresh-session recovery: priorities, owners, current authority, delivery progress, blockers and next actions. It never writes.
workspace-scope records ideas, accepts decisions, records work with deliveries and criteria, and records grants and recommendations from a committed mandate note. It is disjoint from the repository new-plan skill.
workspace-dispatch checks the current grant, native claim, dependencies and resources, writes a bounded brief, and hands it to a native host.
workspace-sync reconciles returned receipts and observes member state read-only, updating delivery observations and criteria evidence only from checked native evidence, then refreshes INDEX.md. It works whether or not this workspace dispatched the work.

Selection and agreement grant no execution authority. A prepared pull request or an unmerged plan item never marks a delivery complete.

Member repositories

A workspace registers three kinds of member. Membership grants no authority; it only declares where native truth lives.

docflow members keep a native ADR catalogue, CONVENTIONS.md, a plan/ queue and their own completion event. The workspace references their decisions and deliveries; it never copies or rewrites their queue.
non-docflow members keep their own AGENTS.md/README.md and native workflow. The workspace contract preserves those instructions untouched and only references the member by identity and revision.
remote-only reference members exist only as identity, aliases and a remote URL with role: reference. They have no local path or instructions; references to them are identity-only and actions stay non-mutating (read/test/report).

Use cases

1. Greenfield product across repositories

Create the workspace home with workspace-setup, choosing the product identifier and the repository paths.
Register the first members in workspace.yaml (delivery role, local path, instructions file).
Run workspace-status to confirm the registry validates and reports no work yet.
Record the first idea with workspace-scope, select it, and accept the shared decision that follows.
Record work with its deliveries and criteria, then workspace-dispatch the first brief. Reconcile it with workspace-sync.

2. Retrofit existing repositories

Clone the existing repositories as independent checkouts under /repos/ (never submodules, never a copied queue).
Run workspace-setup and register each repository with its real path and instructions file; keep every native workflow untouched.
Run workspace-status and fix any registry diagnostics; confirm each native AGENTS.md is read explicitly.
Capture the cross-repository outcomes that are currently only in people’s heads as ideas and decisions with workspace-scope.
Import any already-executed history as read-only imported runs, then dispatch new work.

3. Migrating a single docflow repository to a workspace

Keep the existing repository’s ADR catalogue, its plan queue and its completion event exactly as they are.
Create the workspace home and register the repository as a docflow member.
Reference the repository’s existing decisions from the workspace rather than copying them; the native catalogue stays authoritative.
Move only the genuinely cross-repository outcomes into the workspace.
Continue to run new-adr, new-plan and ship-item inside the member; use workspace-sync to observe the merges and plan moves.

4. Other cases

Mixed docflow and non-docflow product. Register both member kinds; the workspace holds one shared outcome graph while each member keeps its own method. Non-docflow instructions are preserved by the contract.
Remote-only references. Register a repository you consume but never check out with role: reference and a remote URL. Cite it by identity; do not attempt a local revision check.
A federation becoming a workspace. When several repositories already federate ADR catalogues, create a workspace home and register the members; the workspace adds ideas, work, deliveries and runs around the existing catalogues without rewriting them.

Authority and verification limits

The validator (node validate.mjs <workspace-root> --at <UTC-time>) checks supplied records for consistency; it does not authenticate an approver, prove that an external action happened, or enforce live host permissions. A structurally valid planned workspace can pass and still have no execution authority. Native-host, consumer and operator qualification remain separate from a green package check.

Ready to start? Follow the step-by-step workflow guides for existing, mixed and new setups. See the methodology for the repository conventions and Examples for worked skill-by-skill flows.