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 be | Example | The agent may change | The agent sees of everything else |
|---|---|---|---|
| A domain | posts | Its domain file, its methods, its tests | The signatures of the operations it calls in other domains, and the shapes and events it uses |
| One operation or workflow | posts.createPost, payments.subscription | That method or those steps, their tests, and that entry in the domain file | The same, narrower |
| A page or a folder of pages | pages/profile, pages/settings/** | Those pages and the components only they use | The typed client for the operations they call, and the kit |
| A tier | web, native, server, infra | Everything of that tier | The contracts between tiers: the typed client, the routes, the generated infrastructure inputs |
| A server (decision 0169) | servers.search | Its entry in duolith.yaml and its settings | What it hosts, what calls it and what it calls |
| A module, in a project that writes one | store-postgres | Its package | The 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.getProfiletakes 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_filealready 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 postsruns 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:
| Where | What happens |
|---|---|
duolith check --scope posts --base origin/main | An 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 posts | Every 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 harness | duolith 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>readsOWNERS.yaml, andduolith scope <brief>reads a brief's owner paths and its "Reads" list. The card is the same shape, andpnpm check:ownershipstays 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-postgresgets that folder, the tests for stores and the core interface it calls, and none of the other targets, stores or brokers. The module'sAGENTS.mdis 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
changeandreadlists 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
- The repository's own scopes:
duolith scopefor contexts, briefs and modules, with the card and the reading figure. This needs no server work and helps the threads that are building now. - App scopes for pages, folders of pages and tiers, with
duolith check --scopeand the tool server's--scope. - Domains, operations, workflows and servers, with the generated signatures file and
duolith dev --scopeon the mocks of work package 21. --agentand--worktree, the budget, and the checks of section 7 on Plaza.
Alternatives considered
| Option | Why not |
|---|---|
| A scope file per folder, written by hand | A second description of the app that drifts from the first. The build already knows the answer |
| Split the repository so each part is small | It 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 check | An 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 front | Dozens of agent files that go stale. A card made on request is always current |
| Rely on packs alone | A pack narrows the rules. It does not narrow the files |
Consequences
- New commands:
duolith scope [names] [--json | --agent | --worktree <folder> | --check], and--scopeonduolith check,duolith test,duolith devand the tool server. - The tool server gains three tools,
list_scopes,open_scopeandcheck_scope, and keeps its list short as decision 0160 asks. duolith.yamlmay gainscopes: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 createwrites the scope command into a new app'sAGENTS.md, under "Start every session like this".