Workflows — configure the harness

Three files

File	What it holds
.agentry/process.json	Your board: which kinds of item it has, where each lives, what each column means, which rules hold. The board, lane and merge commands need it.
.agentry/workflow.json	How the harness works the repo: the gate, how much checking a lane gets, what it writes on the board, the commit rules. Optional; with none, every key is absent.
.agentry/config.json	Settings: the push policy, how many builders at once, memory priming. Read from the project first, then ~/.agentry/config.json.

The files load strictly. An unknown key, a wrong type or an empty list is refused (exit 2), naming the key and the nearest known one, so a typo never loosens a check. A key in the wrong file is refused with the file it belongs in. agentry board explain prints every value in effect and where it came from (preset or set); agentry board check runs the rules.

How /agentry:init learns them

• A new repo. It copies the templates: a board in docs/work/ (milestones, sprints, tasks, questions, decisions, epics, debt) and a process.json for it, then runs agentry board check.
• A repo with a board. agentry board scan finds its tables and contract blocks. Each table becomes a kind: columns become fields, typed from their cells; status words are mapped to phases (it asks only about a word it cannot place); files named after items become own files. It turns on each rule whose fields exist, and redrafts until agentry board explain finds every kind with its items.
• The lanes. Then workflow.json, one step at a time: the gate from your workflow doc, gate script, CI config or package.json, as argv; the conductor prompt; the push policy; your own merge and session skills as checks; guard.allow; cleanup.disposable from your .gitignore; the lifecycle writes, asked once; debt kinds under exec.kinds; decision drafts; commit rules from agentry board commits --learn.
• Nothing unchecked, nothing committed. Each change goes through a draft that agentry board explain must load before the real file is written, and the diff is yours to review.

Presets

exec.preset sets five keys at once. A key you give yourself wins over the preset; gate.roles wins role by role.

Key	lean · standard (default) · strict
exec.verify	flagged · all · all
exec.noteRounds	0 · 1 · 3
exec.final	never · after-fix · always
exec.rebase	gate · recheck · recheck
gate.roles	build pick, verify none, merge pick · the same · build and merge full, verify none

workflow.json: the lane

Key	Default	What it does
exec.preset	standard	Fills the keys in the table above.
exec.verify	from the preset	Which items get an independent verifier: all, flagged (only an item whose flag is set; the gate stands in for the rest) or none. A flagged item always gets one. flagged needs a flag field on every kind exec runs.
exec.noteRounds	from the preset	How many fix rounds a PASS WITH NOTES may send back, 0 to 3. Read live, so a raised value applies to running lanes.
exec.final	from the preset	When a fresh final verifier follows a recheck: never, after-fix (unless the recheck passed every note on a tip moved only by fix commits) or always.
exec.rebase	from the preset	What checks a rebase that cleared a land conflict: recheck (a fresh verifier reads the range-diff) or gate.
exec.flagField	flag	The field verify reads to tell a flagged item.
exec.idleMinutes	20	Quiet minutes before a building lane shows as idle; at least 5.
exec.kinds	none	Kinds exec and merge run beside the lifecycle's (debt, chores): each { on, write }, as lifecycle but with no handoff. Their items take a light contract: an Owns line and an Acceptance line. Needs a lifecycle.
models.build	none	The model a builder dispatch names: a name ("sonnet") or { default, paths }, where the first paths entry whose when.any glob matches an owned file wins. A contract's **Model:** bullet wins over it.
models.verify	none	default, ui (a UI-shaped task) and flagged (a flagged task): the verifier's model, each a name or by path.
briefs.build · briefs.verify	none	Up to 20 one-line policy lines printed in every builder or verifier brief, under "Repo policy".

workflow.json: the gate

The gate is your repo's own checks. Each tier is argv, run with no shell in the git root of the tree under test; its exit code is the verdict, and a run that leaves files changed counts as red. With no gate, a lane still gets a verifier: nothing else would check the work.

Key	Default	What it does
gate.tiers	required in a gate	The tiers in precedence order, each { name, command, when }. Every tier but the last has a when; the last is the fallback. full may name only the last.
gate.tiers[].when.only	—	Globs: the tier applies when every changed file matches one.
gate.tiers[].when.any	—	Globs: it applies when some changed file matches one.
gate.tiers[].when.flag	—	true: it applies when the item's flag is set.
gate.roles.build	pick	The tier a lane's gate runs: pick (the first tier whose when holds, else the last), full (the last) or a tier's name.
gate.roles.verify	none	The tier run while a verifier is out; none leaves the gate to after the verdict.
gate.roles.merge	pick	The tier the land runs on main. It skips it only on a green record of the same tier and argv on the lane's tip.
gate.checklist	[]	Manual checks the land waits on, each { name, text, when }, recorded with agentry lane merge <id> --check <name>=pass.
gate.after	[]	Globs of files allowed to change after the gate ran green (a changelog written at merge).
gate.concurrency	1	How many lane gates run at once in this checkout; the rest queue for a slot.
gate.flaky	[]	Test names known to fail under load. A red whose output fails only in these is run again alone, once; both runs are recorded.
gate.flakyLogs	[]	Globs of step logs read for failing test names when the gate's own output has only a summary.
gate.note	—	Free text.

workflow.json: the board and the land

Key	Default	What it does
lifecycle.kind	none: nothing is written	The kind whose board cells the harness writes as work moves.
lifecycle.on	—	Your status word for each event: dispatched, built, failed (a verifier's FAIL), merged (the only one that may set a done status) and cut (a lane retired on a decision).
lifecycle.write	—	Where each value goes: status, verdict, commit, and handoff as parent.file:<section>.
lifecycle.handoff	—	The one-line handoff template, filling {id}, {sha} and {summary}. Tried against done-has-handoff at load.
extensions.merge.checks	—	Your own skills (.claude/skills/<name>) the land waits on, each recorded like a checklist item.
extensions.start.checks · extensions.close.checks	—	Skills /agentry:start and /agentry:close run and record. A failed close check is named in the handoff; it refuses nothing.
conductor.prompt	—	Your conductor prompt, from the git root; the conductor reads it first and follows it.
conductor.rules	—	The heading in that prompt where a standing rule you state is appended once you confirm it.
commits.subjectMax	—	The longest subject a builder's commit may have, in characters.
commits.subjectPattern	—	A regular expression every subject must match.
commits.forbid	—	Regular expressions no message may match, per line (an attribution trailer). A commit that breaks a rule goes back to the builder once; the land refuses it.
guard.allow	—	Globs of main-checkout files you may edit by hand while lanes run, unless a running lane owns them.
cleanup.disposable	—	Globs of ignored files (build output, caches) lane merge --cleanup discards without asking. Any other ignored file still stops it.
worktrees.keep	—	Names or globs of worktrees kept on purpose: shown as kept, never as drift.
drafts.<kind>.map	derived from the decision kind	How an answered question fills a decision draft: {answer}, {why}, {question}, {unpicked}. A draft is written only on your approval.
locks	none	Named locks shared by every worktree, { "editor": 1 }: agentry run --lock and agentry lock take wait for a slot.

process.json: the board

Key	Default	What it does
version	required: 1	The file format.
name	required	Shown in the board header.
root	required	The board's folder, from the git root; every path below is relative to it.
kinds	required	Your kinds by your own names, each with label, at (a table under a heading, or one file per item), id, fields (column, type, refs, role), status (your words mapped to planned, active, done, dropped, parked, or derived from children), and optionally file, contract and create.
rules	required	The rules turned on, from a fixed catalog of 17: ids-unique, status-known, refs-resolve, deps-done, ready-has-contract, done-has-evidence and the rest. agentry board explain lists them all, on and off.
status.now	—	The kind that is current, such as sprint, for the Now row of agentry board status.
status.note	.agentry/NOTE.md	The hand-written note /agentry:start shows, with its age.
status.file · status.next	—	A status file kept by hand and its heading; status nudges once when an id listed there is already done.
status.prime · status.lines	—	Still accepted at load; nothing in 0.3 acts on them. The session-start hook they fed was removed.

config.json: settings

Key	Default	What it does
merge.push	ask	What /agentry:merge does once a task lands: ask (push only on your yes), auto or never.
lanes.maxWriters	3	How many builder lanes may write at once; /agentry:exec refuses one more.
mode	none	A working mode's name, printed by /agentry:start.
memory.prime	conductor	Who gets ranked facts: off, conductor (the session start) or all (every lane brief too).
memory.primeLimit	5	The most facts one prime carries.

/agentry:config shows the effective settings and sets one, written to the project file.

Examples

Four complete setups, each with a small board, that load clean and pass agentry board check as they are. Copy the files into .agentry/ and the board into its root; each folder's README says where.

• solo-fast — one developer: the lean preset, one gate tier, push never.
• careful-team — the strict preset, a docs tier and a full tier, a UI checklist item, commit rules, push on ask.
• learned-board — an existing board as init learns it: tickets in iterations, upper-case states, linked specs as contracts.
• debt-only — upkeep with no sprints: one debt kind run by its own lanes.

The solo developer's workflow.json, as it ships:

{
  "lifecycle": {
    "kind": "task",
    "on": {
      "dispatched": "doing",
      "built": "verify",
      "failed": "doing",
      "merged": "done"
    },
    "write": {
      "status": "status",
      "verdict": "verdict",
      "commit": "commit"
    }
  },
  "exec": {
    "preset": "lean"
  },
  "gate": {
    "tiers": [
      {
        "name": "full",
        "command": ["npm", "test"]
      }
    ]
  },
  "cleanup": {
    "disposable": ["node_modules", "dist"]
  }
}

Next: Lanes, where these keys take effect.