The layout of the repository¶
- NAME
- delegate-layout — the layout of the repository and the dependency rule of the package
The repository holds three things: two skills that an agent reads, one Python package that holds every command, and the docs. This page gives the place of each part at a high level, and the rule for the direction of imports in the package. It describes the repository as it is today. For the reasons behind the shape, see why the code has this shape.
The top level¶
| Path | What it holds |
|---|---|
skills/agent-delegation/ |
The protocol skill: the roles, the brief template, blind verification, fix-ups and hotspots, in words that an agent reads. |
skills/agent-definitions/ |
The definitions skill: the rules of the renderer and the validator, and the neutrality allowlist. |
plugins/claude-code/ |
The Claude Code plugin. It shows the progress of a run from delegate status --json: a status line entry, a warning band, toasts, and the pane of the /delegate command, which gives the plan index and, when the blocker of a row is not the row above, after <id>. .claude-plugin/marketplace.json at the top level lists it, so the repository is a plugin marketplace. |
src/delegate/ |
The Python package. It holds the commands delegate, agent-definitions and verifier-brief. |
tests/ |
The pytest suite of the package and of the docs, with the recorded harness streams in tests/fixtures/. |
docs/ |
The source of the docs site. docs/adr/ holds the decision records, and docs/agents/ holds the agent rules of this repository. The site excludes both. |
examples/ |
A sample declaration, and the sample repository of the tutorial. |
scripts/ |
The release script. |
pyproject.toml, package.nix, flake.nix |
The package build for pip and for Nix. Nix is optional. |
zensical.toml, overrides/, includes/ |
The configuration, the theme and the generated abbreviations of the docs site. |
design/ |
The design handoff of the terminal output and the docs theme: the frames, and their tokens, components and copy in design/docs/. |
The package¶
The modules of src/delegate/ fall into seven groups. Each group does one job.
| Group | Modules | Job |
|---|---|---|
| Definitions | definitions/declaration.py, definitions/guard.py, definitions/render.py, definitions/validate.py, definitions/bootstrap.py, definitions/templates/ |
Load a declaration, make the guards of the agents, render an agent pair for each harness, validate the rendered files, and bootstrap a repository. |
| Run | run/domain.py, run/workflow.py, run/engine.py, run/context.py, run/errors.py, run/chain.py, run/gate_run.py, run/step_pause.py, run/step_scans.py, run/retry.py, run/time_limits.py, run/vcs_access.py, run/plan_review.py, run/dry_run.py, run/guards.py, run/journal.py, run/run_state.py, run/lock.py, run/reports.py, run/runs.py, run/index.py, run/host.py, run/state_location.py, run/progress.py, run/fleet.py, run/fleet_rules.py, run/fleet_model.py, run/fleet_hosts.py, run/fleet_view.py, run/user_config.py, run/last_answers.py, run/brief.py, run/status.py, run/status_model.py, run/status_table.py, run/status_picker.py, run/watch.py, run/live.py, run/feed_text.py, run/clock.py, run/output.py, run/pause.py, run/stop.py, run/quality.py, run/agents.py, run/probe.py, run/probe_memory.py, run/events.py, run/clean.py, run/cleanup.py |
Hold the rules of a run, check a workflow and its quality, check a plan change and review it for a resume and for the dry run, build its tickets, hold the run context and the errors of a run, run the gates of a step, check the verification at the end of a chain, find the pause point of a step, scan the events of a step, plan a retry, keep the time limits, give the engine its calls of the version-control port, hold the guards, write the journal, fold it into the one run state, build the verifier brief from the ticket, the diff and the gates and never from the report, find a run by its full or its short id, find the active runs, list the runs of this machine, register a run in the run index, name the host, find the state location of a repository, read the progress that the journal gives, keep the rules of the fleet, read the configuration file of the user and keep the last answers of the other hosts, report the state of a run, draw the live view of delegate watch and the text of its feed, read the time and wait through one clock, give the colour roles, the glyphs and the columns of the terminal output, keep the result of a denied guard probe, ask a run to pause, and stop a run now. |
| Adapters | adapters/__init__.py, adapters/streams.py, adapters/process.py, adapters/claude_code.py, adapters/opencode.py, adapters/git.py, adapters/shell.py, adapters/run_index.py, adapters/ssh_hosts.py, adapters/environment.py, adapters/skill_text.py |
Implement the ports. Each harness adapter drives one harness through its headless command line. The git backend implements the version-control port. The shell backend implements the gate port. adapters/run_index.py implements the run index port with a directory that it is given; cli/machine_settings.py chooses the directory (#323, #333). adapters/ssh_hosts.py implements the host reader port with ssh. adapters/environment.py makes the environment of each process of a run, and adapters/skill_text.py gives the text of the skills of an agent for the prompt of a new session. The package also holds the registry of harness adapters by name. adapters/process.py starts the process of a harness, writes its event stream, and ends a session that stays idle after a valid report. |
| Ports | ports/harness.py, ports/vcs.py, ports/gates.py, ports/index.py, ports/hosts.py |
The interfaces that the engine drives. The harness port runs one agent: the request, the result, the end states, and the error. The request of an agent session of a ticket names the scratch directory of the session, which the engine makes in the directory of the run for a specialist and a fix-up specialist, and in the temp directory of the host for a verifier (#294): it is the last entry of added_directories, and the value of TMPDIR in environment (#227). It also seals an agent and judges a command against the guard of the sealed agent: seal(agent, source, into) writes the seal of the agent into a directory (the claude-code adapter writes a plugin, and the opencode adapter writes <agent>.json, an OpenCode configuration with the agent as an entry of agent) and gives a frozen SealedAgent (the agent name, the handle that the harness gets for the session, the seal directory, and the files of the seal with the SHA-256 of each), or None when the harness finds no agent file. permits(sealed, command) gives None when the guard of the sealed agent permits the command, else the reason of the denial. The handle of a claude-code seal is <plugin>:<agent>, and the handle of an opencode seal is the agent name. The setup check of the dry run uses these two operations and knows no harness. The version-control port keeps the work of a run: the branches, the commits, the worktrees, the rebase, and the verifier copy. The gate port runs one gate command in a worktree and gives its exit status and its output. The index port records a run in the run index and lists the records. The host port is the host reader: it reads the live runs of one other host. |
| Shared | shared/tiers.py, shared/tiers.toml, shared/version.py, shared/yamlio.py |
The tier table, which both contexts read. The data file is beside the module that loads it, and the build ships it as package data. shared/version.py reads the version of the package from pyproject.toml, and shared/yamlio.py is the one place that loads and dumps YAML. |
| Docs tooling | docs/reference.py, docs/figures.py, docs/neutrality.py |
The generator of the reference sections, the terminal figures of the docs (frames as SVG files), and the neutrality check. This package reads the code of the other layers, and no layer but the command line imports it. |
| Command line | cli/delegate.py, cli/agent_definitions.py, cli/brief.py, cli/run_command.py, cli/pause.py, cli/stop.py, cli/status.py, cli/runs.py, cli/watch.py, cli/clean.py, cli/docs_command.py, cli/setup_check.py, cli/machine_settings.py, cli/location.py, cli/opencode_override.py, cli/stop_signals.py, cli/title.py, cli/screen.py, cli/epilog.py |
The command-line drivers. A driver parses its arguments, makes the adapters (the git backend, the shell backend and the harness adapter), calls a use case, and prints the result. cli/delegate.py is the delegate command, and it passes each subcommand to the driver of that subcommand. cli/agent_definitions.py and cli/brief.py are the standalone commands agent-definitions and verifier-brief. No module outside cli/ parses command-line arguments. cli/machine_settings.py reads the configuration file, the state root and the run index of the machine for delegate run, delegate runs and delegate clean. cli/location.py looks up the state location for a command and prints its note one time. cli/opencode_override.py holds the two flags of the OpenCode column override and the tier table with the override applied, and imports no definitions module. cli/stop_signals.py makes SIGTERM and SIGHUP end a command as Ctrl-C does. cli/title.py sets the title of the terminal. cli/screen.py draws a live view in place on the terminal, for delegate watch and delegate runs --watch. cli/epilog.py ends the help of each command with the address of the docs site and of its reference page. |
The state root of a machine¶
The state root of a machine holds the state of each run of the machine, outside each repository: DELEGATE_STATE_ROOT, or else $XDG_STATE_HOME/delegate (~/.local/state/delegate). It has these entries:
| Path | What it holds |
|---|---|
<name>-<key>/ |
The state directory of one repository: its runs, journals, worktrees and locks. See where the engine writes. |
index/ |
The run index of this machine, one <run id>.json for each run, when no setting names a shared directory (#323). See the run index. |
last-answers/ |
The store of last answers: one <host>.json for each other host that delegate runs read, with the newest document of the host. See the store of last answers. |
The configuration file of the user, $XDG_CONFIG_HOME/delegate/config.toml (~/.config/delegate/config.toml), is not in the state root. See the configuration file. Do not edit, copy or delete a file in index/ or in last-answers/: delegate clean forgets the record of a run.
The dependency rule¶
Dependencies point inward. Run and Definitions are the two bounded contexts, and they hold the domain. They know nothing of each other: the tier table is the one thing that they share. The ports are the interfaces that the domain drives. The adapters implement the ports, and the command line drives the domain and picks the adapters. The docs tooling stands outside and reads them all.
flowchart LR
cli[Command line] --> run[Run]
cli --> definitions[Definitions]
cli --> adapters
cli --> docs
cli --> shared
docs[Docs tooling] --> run
docs --> definitions
docs --> cli
adapters[Adapters] --> ports[Ports]
run --> ports
run --> shared[Shared tier table]
definitions --> shared
Ten rules follow, and tests/test_architecture.py holds them:
runnever importsadapters,cli,docsordefinitions.definitionsnever importsadapters,cli,docsorrun. With the first rule, this makes the two contexts know nothing of each other, in both directions.portsnever importsadapters,cliordocs.adaptersnever importscliordocs.- No module outside
cliparses command-line arguments. The test fails on a call ofArgumentParser, on a call ofparse_argsorparse_known_args, and on a read ofsys.argvin any other module. The generator indocsreads the parsers thatclibuilds, and it parses nothing. sharedimports no other layer of the package. It holds the tier table, so both contexts, the adapters and the command line may import it.- Every directory of
src/delegate/that holds an__init__.pyis in thepackageslist ofpyproject.toml. A package that is not there is missing from the built wheel. - The domain module
run/domain.pyimports no module of the package and no module that does I/O. It imports__future__,collections.abcandtypingonly, so it has no git, no harness, no file system and no subprocess. The test reads the imports of the module and fails on any other. A test plants an import in a temporary copy of the package and checks that the rule fails. - The files of
run/start no process. They import nosubprocess, in any form and at any depth, and they use none ofos.system,os.popen,os.exec*,os.spawn*andos.posix_spawn*. The other functions ofos, such asos.getpid, are allowed. All the process work of the run context goes through a port: git through the version-control port, the agent through the harness port, and a gate command through the gate port. The guards and the brief generator read the repository through the version-control port, as the engine does. The test reads imports and names, and never the arguments of a call, so a command in a constant or in a variable does not get round it. Only the adapters start a process. - A moved name has one address, so no file of the package keeps an import for compatibility. The test fails on a
noqa: F401comment, the mark of a re-export.
A layer is a subpackage of src/delegate/: run/, definitions/, shared/, docs/, ports/, adapters/ and cli/. The package top holds only __init__.py, and the test fails on any other flat module. The test reads the imports with the ast module of the standard library, so it runs no code of the package. A test plants each violation in a temporary copy of the package, and checks that the rule fails on it.
The composition point is the command-line driver. delegate run reads the name of the adapter from the workflow, looks it up in adapters, and passes the adapter to the engine. The engine never chooses an adapter. The commands verifier-brief, delegate pause, delegate status and delegate watch make the git backend in the same way, and pass it to the use case of the same name in run/: cli/brief.py calls the brief generator in run/brief.py, cli/status.py calls report in run/status.py, cli/watch.py calls follow in run/watch.py, and cli/pause.py calls request_pause in run/pause.py. cli/runs.py calls fleet_of in run/fleet.py with the state root of the machine and the stream reader of the adapter of each run. On a terminal, cli/watch.py gives follow the live view of run/live.py, with the stream reader of the adapter of the run, as cli/status.py does. Both commands read the time, and follow and its sinks wait, only through the clock of the commands in run/clock.py: the system clock, or the clock that a test gives with clock.use. The delegate docs command is in cli/docs_command.py, and it calls the generator in docs/reference.py.
The domain module¶
run/domain.py holds the rules of a run as functions of plain values: strings, numbers and lists. The engine reads and writes the world, and asks the module what the rules say.
| Rule | Functions |
|---|---|
| The modes, and the tier of each role in a mode | MODES, role_tier |
| The limits of a mode: the fix-up rounds and the continuations | fixup_round_limit, continuation_limit, may_continue |
| The dependency order of the tickets | dependency_order |
| The skip rule: a ticket with a blocker that is not built is skipped | skip_reason, unbuilt_blockers, unreached_reason |
| The start of a ticket in a chain, and where its own work begins | chain_predecessor, work_starts_at, starts_from_run_branch |
| The handling of a verdict: the rounds, and the reason a step fails | is_accepted, verification_rounds, rounds_used_up_reason, rejection_reason, chain_rejection_reason, unverified_chain_reason, unfinished_reason |
| The rules of a plan change on a resume: the built part, the new and changed tickets, and the later tickets to review | PLAN_RULES, check_plan_change, unreviewed |
| The progress and the ETA of a run | chain_units, percent_complete, seconds_to_end |
tests/test_run_domain.py calls these functions with plain values. It needs no repository and no harness.
The version-control port¶
Git is an outside system, so it belongs behind a driven port, an interface that the engine drives and an adapter implements. The port is ports/vcs.py, and the git backend is adapters/git.py. The command-line driver makes the backend and gives it to the engine, as it gives the harness adapter. The run context keeps the work of a run through the port. The engine makes the run branch and the worktrees, keeps the file watcher off in them, rebases a ticket branch onto the run branch, reads the commit ranges, makes the verifier copy, and moves the run branch. When a run ends built, the engine removes the worktrees and deletes the ticket branches that the run branch holds (see the clean-up). The run context starts no process itself, and a test checks that.
The port speaks the language of the domain. It names no git command and no flag, and a test checks that. Each operation has a test in tests/test_vcs_git.py, which runs the git backend on a real temporary repository and calls the port only.
| Operation | What it does |
|---|---|
repository_root, shared_data_directory, repository_paths |
Find the top of the checkout, and the directory that the checkout and all its worktrees share. repository_paths gives the two from one look-up, so each command finds them one time and passes them on (#239). In it, the file delegate/state-root names the state directory, which is outside it by default, and the runs from before #200 are in delegate/. See where the engine writes. |
branch_exists, create_branch, branch_tip |
Look for a branch, make the run branch or a ticket branch, and read its newest commit. |
delete_branch |
Delete a ticket branch when the run branch holds its newest commit, with the safe delete of git, and keep it when the run branch does not hold it. The clean-up of a run uses it. |
commit_of, head_commit, commits_since |
Name a commit, and list the commits that a branch holds beyond another. |
ensure_worktree, remove_worktree |
Make the worktree of a ticket, or reuse one that a killed run left, and remove it. |
rebase_onto |
Put the commits of a ticket branch on top of the run branch. A conflict or a refusal gives a result, and the worktree keeps the state from before. |
changed_paths, diff_text, uncommitted_changes |
List the paths that differ between two commits, read the text of those changes for the brief, and list the paths that a worktree changed and did not commit. The hotspot guard and the worktree check of a verifier use them. |
hooks_directory, use_hooks_directory, worktree_environment |
Find the hooks that a checkout reads from its own configuration, keep a hooks directory for a worktree alone, and give the environment entries that make the settings of the worktree hold for a process of its ticket. The push guard uses them. |
is_ancestor, fast_forward_branch |
Ask whether a commit holds another, and move the run branch to a verified commit by fast-forward only. The engine gives the tip that its check of the run branch read, and the move fails when the run branch is no longer there. |
make_scratch_repository |
Make a new repository with one commit, for the guard probe. |
make_verifier_copy, stop_file_watcher |
Make a new verifier copy for each round of verification (#349), and stop the background watcher of the file system before a directory goes. |
The git backend keeps one rule for every worktree and every copy that it makes: core.fsmonitor is off. With the setting on, git starts a daemon for each repository it touches, and the daemon outlives its directory. A worktree gets the setting in its own file, delegate.config in its git directory. The backend writes no includeIf section to the configuration of the repository, because Claude Code refuses an agent spawn with worktree isolation in a repository that holds one (#221). It gives the entries that include the file through the environment (GIT_CONFIG_COUNT, GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n>, with a gitdir: condition), so only the processes that the engine starts for the worktree read it. A copy gets the setting in its own repository, and the git commands of the backend run with core.fsmonitor=false. The entries need git 2.31 or later, and the backend was tested with 2.54.0. So the configuration of the user and of the main checkout stays as it was, and the backend sets no extensions.worktreeConfig. See the push guard.
Each git command of the backend reads no stdin (it gets the null device), and it runs with GIT_TERMINAL_PROMPT=0, so git asks for no credential on a terminal (#295). Before, a command got the stdin of the engine, and a hook, a signing program or a filter that waited on it stopped a run with no message. Each command also has a time limit: 10 minutes, and 30 minutes for the clone of the verifier copy. A command that reaches its limit raises VcsError with the operation, the directory and timed out after N seconds, and the engine treats it as each other VcsError. The command that stops the file watcher keeps its own limit of 30 seconds.
The gate port¶
A gate is a command that the workflow names for a ticket, such as a test command. The engine runs it in the worktree of a ticket, and it needs two things: the exit status and the output. The port is ports/gates.py. It holds the GateRunner interface, with one method, run(command, worktree, log, timeout, environment), and the GateResult that the method gives: the exit status, the output, and whether the gate is green. environment holds the entries of the worktree that the runner adds over the environment of the command (#221). log is the path of a log file that the engine makes for each gate run: the runner appends the output to it while the command runs, so delegate status and delegate watch see a long gate as active. The shell backend is adapters/shell.py, and it runs the command with bash -c. The command-line driver makes the backend and gives it to run_workflow, as it gives the harness adapter and the git backend. tests/test_gates_shell.py runs the backend on real directories, and tests/test_run_gate_port.py checks what the engine asks of the port.
Where to change what¶
- A new harness: an adapter module in
adapters/, besideclaude_code.py, a contract test intests/, and recorded streams intests/fixtures/. See how to add a harness adapter. - A new flag, exit code, guard command or finding code: change the code, then run
delegate docs. Seedelegate docs. - A new decision: an ADR in
docs/adr/, and a line in the decision records. - The gates and the hotspots of this repository:
docs/agents/delegation.md.