From Repository to System

The key move

An agent may need to read many repositories to understand a system while changing only one repository. This is the Read Many / Write One shape. The workspace control repository gives the interactive driver one project root; the managed repositories remain independent checkouts under repos/.

             read
      ┌─────────────────┐
      │  repos/service-a│
      │  repos/service-b│───┐
      │  repos/infra    │   │
      └─────────────────┘   ▼
                       Run: write one target

The distinction keeps the write boundary reviewable. Related repositories can remain independently owned, released, and integrated.

What a workspace adds

The workspace control repository can record repository relationships, paths, Git URLs, shared policies, generated skills, and durable architectural context. It can answer “what else should this Run know about?” without pretending the repositories are one atomic history. ws repo clone and ws repo sync make URL-backed checkouts reproducible while leaving their Git boundaries intact. The current ws discover command filters declared membership; it does not perform semantic search or infer all dependencies.

What it does not add

A workspace does not create an atomic multi-repository transaction. If a change spans multiple repositories, each repository still needs its own Candidate and integration path.

Driver and bounded Run

Start the interactive driver at the workspace root. It uses the generated AGENTS.md and .agents/skills/ to select context and invoke ws run. A caller can provide a direct objective without first creating a separate Task object. The bounded Run starts in an isolated worktree for the one write target; its context repositories are selected snapshots for that Run, with workflow-level checks against mutation rather than an enforceable filesystem read-only boundary.

A practical rule

Start with the narrowest mutation scope that can complete the task. Expand read context when understanding requires it. Expand write scope only when the integration plan explicitly calls for it. If more than one repository must change, create separate Candidates and coordinate their integration.

See Multi-Repo System Context and Read Many / Write One.