Skip to content

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:

  • run never imports adapters, cli, docs or definitions.
  • definitions never imports adapters, cli, docs or run. With the first rule, this makes the two contexts know nothing of each other, in both directions.
  • ports never imports adapters, cli or docs.
  • adapters never imports cli or docs.
  • No module outside cli parses command-line arguments. The test fails on a call of ArgumentParser, on a call of parse_args or parse_known_args, and on a read of sys.argv in any other module. The generator in docs reads the parsers that cli builds, and it parses nothing.
  • shared imports 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__.py is in the packages list of pyproject.toml. A package that is not there is missing from the built wheel.
  • The domain module run/domain.py imports no module of the package and no module that does I/O. It imports __future__, collections.abc and typing only, 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 no subprocess, in any form and at any depth, and they use none of os.system, os.popen, os.exec*, os.spawn* and os.posix_spawn*. The other functions of os, such as os.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: F401 comment, 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

Version main