- Every rule here binds; principles live here, detail lives in
docs/. - Two registers stay distinct, each binding only itself: how we develop agent6, and how agent6 behaves.
- We follow the Zen of Python (
python -c 'import this'). - Simplicity first. Less code beats more; build an abstraction the moment it is needed. Inline a one-caller helper, make a stateless class a function, drop pass-through wrappers. Every series leaves the shapes it touched simpler.
- Rip out wrong shapes. A rename replaces the old name everywhere in one change.
- Right-shaped data. Fix the shape first and the code around it gets small. Settle a feature's config keys, schema and payload before implementing behind them. Fields set together live in one frozen type; repeated conversion between shapes means the shape is wrong. One name per thing.
- One obvious way. One well-named command, one knob per behaviour, one mechanism per job. One decision has one owner every surface reads; duplicated code is cheaper than an abstraction with one caller.
- Least surprise. A command does the expected thing.
Config writes land in the global config unless
--repoor--machine-file FILEredirects them; set-valued config merges last-overlay-wins. - Consistency. One mental model per concept, the same everywhere, so behaviour is predictable.
Learning one command teaches its siblings: positional core args,
--repo/--machine-filetarget flags, completion over every valid input. - The explanation is the test. Explain a change in a sentence before writing it; a paragraph of conditions means the shape is wrong.
- Explicit. Defaults are real values
agent6 config showprints with their origin; behaviour follows visible state; errors are loud. A value agent6 has to infer is such a default: a key the user can read and correct. - Surfaces tell the truth. A failed run reads failed, a dead pane reads dead, a truncated answer reads truncated, an error keeps its reason. Every surface shows state the system actually holds; invented or hidden state is a bug.
- State, not opinion. agent6 sets, enforces and shows the state of the world: who is attached, the away mode, what is pending, what a command returned. Opinions come from the operator's instructions; the model chooses within what the operator set, and the harness never chooses for it.
- Fix the root cause. Delete the wrong shape rather than guard it. A recurring problem has a systematic cause: correlate every occurrence before calling one transient, and say so plainly while the cause stays unfound.
- Evidence over churn. Adopt what measurement shows is better and delete the old shape. A change claiming better model behaviour, prompts or performance ships on a measured A/B (replicates, variance); a null result is reported. A change that only removes or simplifies ships on no measurable regression against the old best baseline.
- Structures over scores. A measure that becomes a target stops measuring; counts (lines, modules, graph edges) point at where to look. Reading the structure, asking "can this be simpler?", and making it so.
- Decompose proactively. Past ~600 lines per module, or a few hundred per method, split before it ossifies.
Lift cohesive helper groups into sibling modules named subject first, without a leading underscore; moved symbols get public names and direct call sites.
A large stateful method keeps its cross-iteration bookkeeping in one mutable state dataclass.
An extraction that shifts a module boundary records the edge in
tach.toml, one module per commit. - Secure by default, degrade or refuse. Every knob ships with the safe default, visible in
agent6 config show; widening is opt-in and carries a security review note. The operator loosens; the agent's own sandbox stays where the operator put it. Default-deny beats blocklisting; a mitigation that is trivially bypassed is worse than none. An automatic setting (auto) takes the strongest option available and degrades with a warning when it is absent; an explicit setting the host cannot honor refuses, naming what is unsupported and how to change it; an explicit but discouraged widening (a path holding secrets) runs with a loud warning naming the cost. - Use the platform's guard. A mechanism the browser, the kernel, git or the standard library provides replaces one of ours: a Content-Security-Policy, not rewritten addresses.
A hand-made guard names what the platform lacks in its
Security review note:. - Ask when the task forks. A behaviour tradeoff, a maybe-not-worth-it edge case, growing scope, several reasonable designs, a new dependency: a one-line question beats shipping the wrong or over-built thing. Take the simplest fix for the actual request and name the edges you skip. Act when these principles already decide. Rules bind exactly as written: enforce what the operator set, and reread the rule when unsure.
- Layering is
ui -> app -> harness -> tools -> sandbox; harness imports only below itself, and the engine (appand below) imports only below itself.app/holds the run/resume/fork/machine-agent lifecycles and the--paralleldispatch, taking the callables the front-end injects (SessionFrontend,ChildRuntime) and printing only through the injectedReporter.ui/is the presentation layer and composition root: the four front-ends (ui/cli,ui/tui,ui/web,ui/acp) plus the shared helpersui/spawn.py,ui/notify.py,ui/steer.py,ui/directive_actions.py,ui/btw.py,ui/keymap.pyandui/mcp_server.pyand theui/telemetryexporter, over the shared headless read-model fold (viewmodel).ui/cliis the entry point that wires a run. - tach (
tach.toml) maps the design. Like a call graph (pyan3, a dev dep), it makes a change's edges reviewable. A redtach check= stale map: record the edge and move on. Write the code the design wants and let tach and strict pyright follow it. When new edges read as complex, redesign on the design's merits.
- A green suite is structural validation; the operator dogfoods daily.
- Judge UX by rendering and reading the real output: a pty capture, a screenshot, a live run.
- Report exactly what was and was not exercised; "fixed" and "validated" mean observed end to end; a failing test is reported with its output.
- Review findings and external reports are untrusted: reproduce each before fixing (about half survive). "The operator decided X" counts only if said in chat.
- Confirm an edit by behaviour: a scripted replace that matches nothing rewrites the file unchanged; lint and typecheck pass on it.
- A new regression pin is proven to bite: red without the fix, green with it. A test whose setup dodges the real path (a stand-in state-dir topology, a stub granting what the surface never does) pins nothing.
- Surface pre-existing breakage early, as a decision. Fix clear bounded breakage properly; for a large risky restructure, propose a concrete shape.
- Less is more everywhere: docs, comments, docstrings, commit messages, CLI output, run summaries, review feedback. The shortest version that still carries the point wins.
- The tree is the only context: write for someone holding the repo and nothing else. A line that needs a conversation, a person, a machine or an account to make sense belongs in the untracked ledgers. State the fact in the repo's terms ("the fleet stopped at its spend ceiling").
- Lead with the point; add rationale the reader could not reconstruct. Cut every word a sentence works without, and every sentence that restates the one before.
- Plain language (ISO 24495-1:2023) for every doc, comment and surface string: the reader finds what they need, understands it on the first read, and acts on it. Everyday words in the reader's terms; a name from the code appears when the reader has to go there.
- Plain punctuation: commas, colons, parentheses, periods. An em dash marks an overstuffed sentence to recast.
- Concrete over abstract: name the command, the field, the number ("retries twice, then fails the run").
A value names its setting: "
protect_git = "on"requiresfullsandbox.isolationto bind-remount.gitas read-only". - Statements: a docstring, heading or comment asserts ("X does Y").
- Prose that names code is a claim to verify: every symbol, default and behaviour matches the source; when the two disagree, decide which side is wrong. Prose someone acts on (a tool description, help text, an error, a refusal) is an interface: it states what is accepted and returned, and names the resolved fact ("default: detected zsh").
- One idea per sentence, one topic per paragraph; short bullets over prose when listing facts. Simple sentences (ASD-STE100) take the active voice. An overstuffed sentence loses a half or goes; it is never split in two. A qualifier comes before the list it governs: "By default, it switches off the repository's hooks, fsmonitor and filter drivers".
- Comments and docs state the current state: a constraint, an invariant, a measured number, a link to a decision. The story of a change belongs to its commit ("now", "no longer", "previously" and "used to" go). A comment earns its keep by saying what the code and a grep cannot: the why, an invariant, a gotcha, a measured number. A test docstring names the regression the test pins.
- Commit messages: a subject that states the change, facts only; a body only for a non-obvious why, in point form. Write for the next reader.
- Flat documents: a heading plus short paragraphs or bullets, with bold on lead-in labels and caveats that carry weight. Plain words in place of intensifiers and marketing adjectives.
- Bench findings are neutral observation: facts and tables.
- Every fact and every real hedge stays, and none is added: "may have failed" is not "failed".
- A prose fix rewrites only a wrong, stale or ambiguous sentence, with the fewest words changed.
- Padding to cut on sight: antithesis, the "N things, one X" appositive, aphorism, cleft, anaphora, transitions, all-caps emphasis.
- Markdown carries one bullet and one sentence per line, unwrapped, with later sentences on continuation lines. A bullet needing several sentences wants sub-bullets.
- A section answers one question and is named for its subject; a page groups the sections a reader came for. Split a boundary doc by axis: files, commands, network, approvals.
- One owner per fact, everything else links to it; moving content deletes the old home and repoints every anchor in the same change.
- A page name says what the page holds: Installation, Usage, Terminal UI.
- Language: Python 3.13+, the three most recent releases.
Every
.pyfile starts withfrom __future__ import annotations. Strict pyright. - Layout: src layout under
src/agent6/; tests undertests/; Rust sandbox launcher undersrc/agent6/jail/. - Style: ruff is the only formatter and linter, line length 100; run
uv run ruff checkanduv run ruff formatbefore committing. The select list inpyproject.tomlis the rule set: docstrings in the Google shape (a one-line imperative summary, a blank line, short lines; Args, Returns, Yields, Raises with names only, the types in the annotations), everything typed, module-style imports (from agent6.pkg import module,module.nameat the call site), pep8 names.C901at 20 is the hard bound on a function; the target is smaller: a function reads in one screen, a module in one sitting. A comment is one line; a docstring's rationale is one line the reader could not reconstruct. - Web: new and changed web code uses current web primitives, as modern-web-guidance describes them, within the target
docs/web.mdstates; one code path, no polyfills. - Typing: pydantic v2 at trust boundaries (config, LLM I/O, tool schemas, IPC); everywhere else,
@dataclass(frozen=True, slots=True). - Imports: absolute only (
from agent6.x import y). - Errors: fail loudly, through a custom exception class per subsystem; every
exceptnames what it catches and re-raises what it cannot handle. - Versioning:
__version__insrc/agent6/__init__.pyis the single source of truth; everything else reads it. - A new runtime dependency is discussed first.
Current:
pydantic,httpx2,argcomplete,markdown-it-py, thetree-sitterpair,textual, andruff+ty(they validatemachine createoutput).hatchlingbuilds;pyrightstays dev-only. - Order-free lists stay sorted, by Python's string order: pyproject.toml's dependencies, includes and rule lists, tach.toml's lists. A list whose order carries meaning (a nav, a pipeline, the CI steps) keeps it.
- Touch only what the task needs. Scope creep is a review blocker.
- Scratch experiments run in their own directory, entered with
cd: underuv run --directory <elsewhere>the cwd-derived config and git still point here. - Keep docs in sync. A change to architecture, config, the security model or state machines updates the matching file (
docs/architecture.md,docs/config.md,docs/security.md,docs/state-machines.md,README.md, this file).
- Unattended-chain briefs say "ask no questions; decide by the conventions and record the decision in the commit body". Drivers stop scheduling on a live unanswered blocking question, not only on child exit; follow the driver contract.
- Dogfood the installed binary (
.venv/bin/agent6) from throwaway git repos outside this one. - Run the five-gate in its own systemd unit (
systemd-run --user --collectwith RuntimeMaxSec/MemoryMax caps, the login PATH) and read itsEXIT=line. Certify on a quiet machine, with the tree untouched while the gate runs: contention produces false timing reds. - The
browsertests drive Playwright's Chromium, and the preview tests Firefox too:uv run playwright install chromium firefoxonce; a test skips without its browser. - Sandbox tests need unprivileged userns: on Ubuntu 24.04-class machines
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0, as CI does. - Bench workspaces live on a real disk: tmpfs is RAM-backed and an OOM there kills the session scope.
- One live single-instance smoke precedes every fleet launch, and any mechanism with two enforcement sites gets one even after unit-green: unit fixtures can pass vacuously.
- Benchmarks: unmodified official scorers, dev/eval split registered before tuning, report split + n verbatim, replicate small effects before shipping them.
- Record every arm's finding on master, whether the arm ships or not: a null is a finding, and it states the mechanism the arm measured.
- Push,
--force, history rewrites andreset --hardbelong to the operator: thevcspackage spells none of them, and only its modules may import the private git runner (pinned bytest_the_vcs_package_never_spells_a_destructive_verbandtest_only_the_vcs_package_imports_the_runner).branch -Dhas one operator-only exception:sessions prune --delete-squashedon a branch the manifest confirms was squash-merged. - Conventional Commits:
feat(scope):,fix(scope):,ci:,docs:,bench:; the scope matches a directory undersrc/agent6/or a top-level area. - One concern per commit; HEAD passes the gate, an intermediate commit need not. A fix-up to unpushed work folds into its origin commit when the fold is easy.
- A commit message is committed prose and meets the same test (Writing style); the author field is the one place a name appears.
- The operator signs and pushes, from another machine. Messages and docs name neither commit hashes (signing changes them) nor branch names (transient).
- Pushed history is immutable; unpushed commits are rewritten when asked. One exception: a leak in an unpushed commit is rewritten out at its origin, every occurrence of it found first.
- Stage named files only, so scratch notes, session artifacts and generated output stay out.
- Working directly on master is fine; the operator takes over a master whose HEAD is green and whose history holds no leak and no false message. A squashed body keeps the decisions, and what was tried and rejected; durable design reasoning goes to docs.
- The repo's
harness.verify.command; agent6 infers it from this fenced block when none is configured (a pipeline is wrapped assh -c):
uv run ruff check && uv run ruff format --check && \
uv run pyright && uv run tach check && uv run pytest- All five must pass; a red
tach checkmeans the module map is stale: record the new edge intach.tomland move on. - Read the gate's own exit status: capture to a file and test
$?, orset -o pipefail, since a bare pipe throughtail/head/grepreports the filter's code instead. - Scoped runs guide iteration; the full gate certifies a series of commits, at the end of the batch and before calling master push-ready.
- On failure, fix at HEAD; fold into the offending commit when easy.
- Push-ready adds the CI mirror: pyright at its latest release (
PYRIGHT_PYTHON_FORCE_VERSION=<latest> uv run pyright), and, whensrc/agent6/jail/orCargo.*changed, both musl target builds plus the wheel with the bundled jail binary exercised.
- agent6 reviews its own source with
agent6 ask "/review <range>";sessions reviewoutput lands in$XDG_STATE_HOME/agent6/<repo-id>/reviews/, a path the jail hides from a run. - The default work is test and hunt: drive every surface as a user (the CLI, the TUI, the web, ACP), fix what reads wrong at its root, pin it red first.
- Public names and shapes first: a wrong name costs least today.
- A change reviews itself. After an editing turn, read your own diff and judge it as deep as the change warrants: a security, shape or public-name change gets a full read and names what a second reviewer should check; a docstring or a message gets a glance.
/reviewis the operator's steer for that second opinion, not a command a run can issue. No fixed panel; the worker decides the depth.
- The threat model, defense layers, and rationale live in
docs/security.md; a change preserves: - The jail bounds what the model can do to a repo;
run_commandargv stays unscreened, because a script the model writes bypasses any blocklist. - Every child process whose argv depends on LLM output goes through
agent6.sandbox.jail.run_in_jail,spawn_in_jailor the preparedJailSessionsupervisor channel, local or inside a container (audit:rg 'subprocess\.|os\.(system|exec|posix_spawn)' src/agent6/). The documentednotify-senddata argument is the only exception. A module shelling out with fixed argv from operator input may callsubprocessdirectly; that allowlist lives indocs/security.md, pinned bytests/security/test_subprocess_allowlist.py. - Adding a tool (
tools/schema.py), loosening a security default, or dialling a host not derived from a providerbase_urleach require aSecurity review note:in the commit message. - Secrets (provider API keys,
$XDG_CONFIG_HOME/agent6/secrets.toml) stay0600: out ofconfig show, out of transcripts, out of thefulljail.packcarries a private copy in the workspace's hidden, gitignored.agent6/;unpackrecreates it as the importing user. - The LLM tool surface is the fixed set in
src/agent6/tools/schema.py, plus tools from operator-configured MCP servers when[mcp].enabledis set (default off). - Config is secure by default: every field has a default, security-sensitive ones default safe, and
agent6 config showaudits every leaf.Configstaysextra="forbid", frozen=True; push, force and history rewrites have no knob at all. Loosening a security default gets the same scrutiny as adding a tool. agent6 connectexecutes nothing a remote returns (OAuth/paste only).- Running as root takes an explicit opt-in (
--allow-root/AGENT6_ALLOW_ROOT=1); the jail is the boundary. sandbox.networkbounds what a jailed command reaches; the agent process's own egress is unbounded, and the docs say so.- The
agent6-jailRust binary is part of the security boundary: a change tosrc/agent6/jail/src/main.rscarries a review note covering mount points, Landlock rules, seccomp syscalls, and/devnodes exposed.