Workspaces and federation, Guild Stack

A Guild Stack workspace is an umbrella repo that contains project repos. The contract is simple: the workspace coordinates, each project owns its own knowledge, and queries read through child wikis in place instead of copying their pages upward.

Run /guild:init at the umbrella root when you want Guild Stack to detect the children and write the federation manifest. Run /guild:init inside a child repo when that repo needs its own .guild/ memory, runs, plans, and wiki.

Workspace recallsplit_workspace_federation

Workspace

cross-project wikishared canon
federation planchild targets
merged resultssource tagged

Child projects

plugin wikiproject canon
website wikiproject canon
benchmark wikiproject canon

Read through the workspace manifest. Child page bodies remain in their owning repositories.

Workspace federation is read-through: the umbrella wiki holds cross-project facts, child wikis stay canonical for their repos, and results are merged with source tags.

Source-backed contract

This page follows docs/v2/model.md, workspace-federation.md, knowledge-memory.md, config-surfaces.md, and architecture/modules/workspace.md.

Contract	What it means	Proof surface
Two levels only	Guild Stack treats this shape as a workspace root plus immediate child projects.	`guild.workspace.v1` detects depth-1 children.
Query, do not copy	Workspace recall fans out to child `.guild/wiki/**` stores and source-tags hits.	`workspace.json` query recipe and `wiki_search({ cwd })` steps.
Root owns cross-project facts	The umbrella wiki stores decisions, boundaries, ownership, and release relationships that bind more than one repo.	Root `.guild/wiki/` and `.guild/workspace-knowledge/`.
Projects own project facts	A child repo’s wiki remains canonical for facts about that repo alone.	Child `.guild/wiki/**`.
Workspace writes stay root-side	Detection, impact, and upstream candidates write under the workspace `.guild/`, never into a child `.guild/`.	`workspace.json`, `workspace/impact-index.json`, `runs/<id>/upstream-candidates.json`.

Root vs project ownership

Use the workspace root for coordination facts. Use the project root for work that belongs to one repo.

Surface	Workspace root owns	Project root owns
Wiki	Cross-repo decisions, boundaries, ownership, shared goals, release relationships.	Repo-specific standards, decisions, context, product facts, sources.
Runs	Workspace-scoped orchestration and cross-project initiative evidence.	The run evidence for work performed in that repo.
Initiatives	Opt-in goals spanning more than one project.	Opt-in goals scoped to the repo.
Knowledge promotion	Upstream candidates by reference, then human-gated `guild:wiki-ingest` or `guild:decisions`.	Project-local candidates, decisions, and wiki pages.
Config	Workspace defaults and root-only `workspace.mode`.	Project overrides, local settings, and repo-specific behavior.

For Power Users, this keeps multi-repo work inspectable without flattening repo ownership. Beginner Users can start at the umbrella and still keep each project independent. Harness Developers should treat the boundary as a file contract: root-side workflows may reference child artifacts, but child .guild/ writes belong to the child repo.

Query-not-copy in practice

Federated recall has three rules:

Rule	Operational behavior
Read-through only	The workspace asks each child wiki what it knows by calling the wiki query surface with that child’s `cwd`.
Never copy up	The root may keep a coordination interpretation, such as “plugin owns dispatch,” but not the child page body.
Read-only into children	Deleting or rebuilding the workspace `.guild/` loses zero child-project knowledge.

The workspace can hold its own coordination store:

.guild/
├── workspace.json                         # guild.workspace.v1 manifest
├── workspace/
│   ├── workspace.yaml                     # human descriptor
│   ├── children.yaml                      # operator-curated child notes
│   ├── relationships.yaml                 # operator-curated relationships
│   └── impact-index.json                  # root-side impact projection
├── workspace-knowledge/
│   ├── ownership.yaml
│   ├── boundaries.yaml
│   ├── cross-repo-deps.yaml
│   ├── shared-goals.yaml
│   ├── release-relationships.yaml
│   └── decisions/<slug>.md
└── wiki/                                  # cross-project canon only

Child projects keep their own matching .guild/wiki/**, .guild/runs/**, .guild/initiatives/**, and .guild/indexes/**. Federation reads those stores; it does not absorb them.

The federation manifest

/guild:init at a workspace root writes <workspace-root>/.guild/workspace.json with schema guild.workspace.v1.

Manifest field	Role
`schema_version`	Identifies the manifest contract.
`is_workspace`	Records that this root classified as a workspace.
`detected_at`	Timestamp for the projection.
`detection`	Depth, rule, and mode used by detection.
`root_wiki`	Whether the root itself has top-level code that merits a root wiki.
`sub_guilds[]`	Immediate child registry with federation flags.
`query_recipe`	The executable read-through plan for child wiki queries.

The manifest is a derived projection, not the source of truth. Refreshing it is safe, and deleting it loses no child knowledge. Two related controls are read with defaults by lifecycle code: workspace_knowledge defaults to on, and learn_fanout defaults to auto. A freshly written manifest normally does not emit those keys.

Detection and init

Guild Stack classifies a directory as a workspace when at least one immediate child directory contains .git/ or .guild/. Detection is depth 1 by design: a child that is itself a workspace is registered as a leaf and reached through its own manifest.

Where you run `/guild:init`	What Guild does
Project root	Scaffolds project `.guild/`, builds the cheap codebase map, and prepares project-local memory.
Workspace root	Writes `guild.workspace.v1`, registers child repos, offers init for un-onboarded children, and avoids building a monolithic union wiki.

workspace.mode can force detection on or off, but it is root-local and non-inheritable. A child project does not inherit the parent workspace’s mode.

Settings inheritance

Workspace configuration composes through the same closed-key settings system as a project. Higher layers win, and CLI flags win over everything:

built-in defaults
  < workspace .guild/settings.json
  < workspace .guild/settings.local.json
  < project .guild/settings.json
  < project .guild/settings.local.json
  < rigor-profile expansion
  < CLI flags

Nested settings deep-merge rather than replace. config show --sources shows which layer won each key. workspace.mode does not inherit, and initiative_default only inherits workspace-to-child when it names a workspace-scoped initiative; child runs are never silently attached to a project-scoped parent initiative.

Cross-project impact and promotion

The workspace module also has two root-side workflows that matter during real multi-repo work:

Workflow	Contract	Writes
Transitive impact	`guild.workspace_impact.v1` computes affected children and the root verdict: `PASS`, `PASS_WITH_EXCEPTION`, or `FAIL`.	`.guild/workspace/impact-index.json`
Upstream promotion	`guild.upstream_candidates.v1` stages cross-cutting candidates by reference for a human gate.	`.guild/runs/<run-id>/upstream-candidates.json`

Both preserve the same boundary: they write under the workspace root and never mutate a child project’s .guild/. Promotion is staged only. Wiki candidates still go through guild:wiki-ingest; decision candidates still go through guild:decisions.

Workspace-scoped initiatives

Use a workspace-scoped initiative when the goal genuinely spans member projects. The initiative can group child runs by reference, and recall can query each member wiki in place. One-off runs and project-scoped initiatives remain valid.

Harness reference map

Public extension points are the files and commands you can rely on:

Public surface	Purpose
`/guild:init`	Detect workspace/project shape and scaffold the correct `.guild/` surface.
`/guild:learn`	At a workspace root, plan or fan out child learning under each child’s policy.
`.guild/workspace.json`	Federation manifest and read-through query recipe.
`.guild/settings.json`	Closed-key workspace and project behavior settings.
`.guild/wiki/**`	Canonical knowledge at the owning level.

Implementation internals are module workflows such as workspace/detect, workspace/write-manifest, workspace/federated-query, workspace/promote-upstream, and workspace-impact-detector. They exist to produce the contracts above; docs and operators should depend on the contracts, not the internal file layout.