P04 — Multi-Repo System Context

Problem

Related repositories are often treated as unrelated projects, so agents and humans repeatedly reconstruct their relationships.

Context

A workspace control repository contains the manifest for services, infrastructure, clients, documentation, or tools that evolve together but retain separate histories. Their checkouts conventionally live below ignored repos/.

Pattern

Record each repository’s stable name, workspace-relative path, Git url, role, and relationships in the control-repository manifest. This is a useful first System Resource catalog, but it is narrower than the full System/Layer/Resource model. In the current CLI, ws discover filters declared membership; it does not semantically infer related repositories. Use ws repo clone to materialize a URL-backed checkout, ws repo add to register an existing checkout, and ws repo sync [name] to materialize a missing one. Keep each repository’s lifecycle independent; do not use submodules by default.

Diagram

workspace system map
 ├─ client ──calls──→ api
 ├─ api ──deploys──→ infra
 └─ docs ──explains──→ all

Example

repositories:
  - name: api
    path: repos/api
    url: https://github.com/example/api.git
    role: service
  - name: infra
    path: repos/infra
    url: https://github.com/example/infra.git
    role: deployment
    relates_to: [api]

The root AGENTS.md and .agents/skills/ generated by ws generate teach an interactive driver how to use this map. A bounded Run can read several mapped repositories while writing only its declared target.

Trade-offs

System context improves orientation and discovery. The reference CLI has a declaration-only System/Layer/Resource registry and ws discover/ws validate surface. A caller-owned resolver may later provide on-demand semantic context selection; that is a proposed interface, not a current command. Relationships need owners and can drift from reality.

Failure modes

The map becomes a second stale source of truth, a URL points at the wrong remote, or the layout implies an atomic release process that does not exist.

Extension points

Use a manifest, graph, catalog service, or generated dependency map.

When not to use

Do not model relationships that are not useful to engineering decisions.