Duolith docs

0172. An agent works in one scope, named by something the build already knows, and a change outside it is refused

  • Status: Proposed (the direction is Mik's; the design awaits his approval)
  • Date: 2026-11-18
  • Decided by: Mik asked on 18 Nov 2026: "We should also build in tooling for agents to be able to scope their context or workspace to a particular aspect of each of these tiers so we don't have agents getting confused by the entire monorepo monolith scope creep." The design is the integrator's.
  • Planning item: docs/plan/server-roadmap.md, work package 37

Context

An app built with decisions 0163 to 0171 is one repository that holds a website, a web app, native apps, a server, its domains, its workflows and its infrastructure. Plaza has eight domains (decision 0170). An agent asked to change how a post is published does not need the payment code, the native shells or the infrastructure files, and reading them costs context and invites edits nobody asked for.

Two things already limit an agent, and neither covers this:

  • Packs (decision 0160) scope the rules to one topic: styling, forms, data. They do not say which files a task concerns.
  • **Briefs and OWNERS.yaml** scope work on the framework's own repository: a brief lists owner paths and CI rejects a change outside them (pnpm check:ownership). An app has nothing like it.

What makes more possible is decision 0164, section 1a: every name in an app is a reference the build resolves. The build therefore knows, for any domain, operation, workflow, page or server, exactly which files define it and exactly what it reaches outside itself. Nobody has to write that down.

Decision

1. A scope is a name the build already knows

There is no scope file and nothing to keep up to date. A scope is named by something that already exists:

A scope can beExampleThe agent may changeThe agent sees of everything else
A domainpostsIts domain file, its methods, its testsThe signatures of the operations it calls in other domains, and the shapes and events it uses
One operation or workflowposts.createPost, payments.subscriptionThat method or those steps, their tests, and that entry in the domain fileThe same, narrower
A page or a folder of pagespages/profile, pages/settings/**Those pages and the components only they useThe typed client for the operations they call, and the kit
A tierweb, native, server, infraEverything of that tierThe contracts between tiers: the typed client, the routes, the generated infrastructure inputs
A server (decision 0169)servers.searchIts entry in duolith.yaml and its settingsWhat it hosts, what calls it and what it calls
A module, in a project that writes onestore-postgresIts packageThe tests of its module type (decision 0171). None of the other modules

duolith scope with no name lists what can be named, as a tree. Two names can be given together (duolith scope payments pages/checkout) for a feature that crosses tiers. A team that wants a standing name for such a slice may add one line to duolith.yaml (scopes: { checkout: [payments, pages/checkout/**] }). That line is optional, and each entry in it is a reference the build resolves.

2. What a scope gives an agent

duolith scope posts prints one card, and --json gives the same to a tool:

scope    posts (a domain)                            reading: 9 files, about 6,400 tokens
change   domains/posts.domain.yaml
         server/posts/**
         tests/posts/**
read     .duolith/scope/posts/outside.d.ts            what posts calls, as signatures:
                                                     accounts.getProfile, follows.listFollowers, media.attach
rules    packs: domains, server (duolith packs show <topic>)
check    duolith check --scope posts                  about 4 s
test     duolith test --scope posts
run      duolith dev --scope posts                    everything outside is answered by generated mocks
outside  pages, other domains' methods, modules, infrastructure
         blocked by one of them? stop and name it. Do not edit it.
  • The outside is one generated file of signatures. An agent reads what accounts.getProfile takes and returns, never how it is written. The file is produced by the build, so it cannot be out of date.
  • The rules are the packs for those files. packs_for_file already answers this (decision 0160). A scope loads only those topics.
  • Checks and tests run for the scope alone, and say how long they take, so an agent verifies its work in seconds and does not run the whole suite.
  • It runs alone. duolith dev --scope posts runs that domain with the local modules (decision 0171, section 6), and answers every call to another domain from the generated mocks. An agent can try its change without starting the rest.
  • No secrets. A scope never includes environment files or credentials.

3. Enforced, not suggested

Mik's rule is strict by default (decision 0169, section 6). A scope is a check with an error, and has three places it is applied:

WhereWhat happens
duolith check --scope posts --base origin/mainAn error for each changed file outside the scope, naming the scope that file belongs to. This runs in CI when a pull request or its branch names a scope
The tool server started with --scope postsEvery tool answers for the scope only: checks, tests, routes, docs lookups and packs. A tool asked to write outside it refuses with the same error. The server already writes only inside the folder it was started in
The agent's own harnessduolith scope posts --agent writes the files a harness reads: an AGENTS.md for the scope holding the card, and, where the harness has settings for allowed and denied paths, those settings. Which harnesses and which settings is decided when the work package is built, from their documentation at that time

Widening is visible. A scope is widened only by naming a second scope in the command. That appears in the pull request, where review can ask why.

Blocked is an answer. When the work needs a change outside the scope, the agent stops and reports the name it needs (accounts.getProfile must also return handle). That request goes to whoever holds that scope: a person, or another agent started with it. This is rule 5 of this repository's own AGENTS.md, given to apps.

4. A workspace that holds only the scope

For a large repository, duolith scope posts --worktree ../plaza-posts makes a git worktree that checks out only the scope's files, the generated signatures of the outside, and the scope's AGENTS.md. duolith check --scope and duolith test --scope work there, because the signatures file stands in for what is absent. The full build runs in CI as it always did. An agent in that folder cannot read what is not there.

5. A scope that is too big is a finding

Each card reports how much an agent must read: the files of the scope, the signatures of the outside and the rules. A budget for that figure is a setting with a default. duolith scope --check lists every scope over it, and names what makes it large: a domain with too many operations, or one that calls into too many others. Over the budget is a warning in the report and never a build error, because the size of a domain is the team's decision. duolith advise (decision 0168) lists it with its other findings.

6. The framework's own repository

The Duolith repository gets the same command from what it already has:

  • duolith scope <context> reads OWNERS.yaml, and duolith scope <brief> reads a brief's owner paths and its "Reads" list. The card is the same shape, and pnpm check:ownership stays the check.
  • Each module is a scope without anyone declaring it. Decision 0171 gives a module one folder, one type and one set of tests. An agent building store-postgres gets that folder, the tests for stores and the core interface it calls, and none of the other targets, stores or brokers. The module's AGENTS.md is generated from its manifest.
  • A brief whose "Reads" list is over the reading budget is flagged when the brief is written.

7. Proved without running an agent

CI cannot run an agent (decision 0062), so each claim is a check that needs none:

  • For every scope of Plaza, the card's change and read lists are complete: a build in the worktree of section 4 passes its scoped check and tests with nothing else present.
  • Each skill evaluation (decision 0062) names its scope, and its reference solution must pass duolith check --scope. A solution that needs a file outside its scope fails.
  • A fixture changes one file outside a scope and expects the error.
  • The reading figure of each Plaza scope is recorded, and a change that raises one by more than a tenth is reported in the pull request.

Stages

  1. The repository's own scopes: duolith scope for contexts, briefs and modules, with the card and the reading figure. This needs no server work and helps the threads that are building now.
  2. App scopes for pages, folders of pages and tiers, with duolith check --scope and the tool server's --scope.
  3. Domains, operations, workflows and servers, with the generated signatures file and duolith dev --scope on the mocks of work package 21.
  4. --agent and --worktree, the budget, and the checks of section 7 on Plaza.

Alternatives considered

OptionWhy not
A scope file per folder, written by handA second description of the app that drifts from the first. The build already knows the answer
Split the repository so each part is smallIt breaks the one build that resolves every name, which is what prevents a mistyped name (decision 0164). The split would exist for the agent's sake and cost the developer
Tell agents to stay in scope in AGENTS.md, with no checkAn instruction is not a guarantee. A changed file outside the scope is cheap to detect, so it is an error
A subagent per domain, generated up frontDozens of agent files that go stale. A card made on request is always current
Rely on packs aloneA pack narrows the rules. It does not narrow the files

Consequences

  • New commands: duolith scope [names] [--json | --agent | --worktree <folder> | --check], and --scope on duolith check, duolith test, duolith dev and the tool server.
  • The tool server gains three tools, list_scopes, open_scope and check_scope, and keeps its list short as decision 0160 asks.
  • duolith.yaml may gain scopes: for named groups. It is never required.
  • New diagnostics, numbered when the brief is written: an unknown scope name, a change outside the scope, and a write refused by the tool server.
  • The glossary gains "scope". It is a word for agents and for review. An author who never uses an agent never meets it.
  • New work package 37 in docs/plan/server-roadmap.md. Its first stage needs nothing from the server packages.
  • duolith create writes the scope command into a new app's AGENTS.md, under "Start every session like this".