Skip to content
Sign in

workflow

Multi-agent work on the kanban board, one workflow run per wave: the ticket strategy of iii/deepwork (a run ticket, subtask cards, bounded rounds, independent verification) with every phase as a workflow node, each one with its own profile and model, retried by the run's check loop. Code goals get one worktree per ticket, one tests-and-check run per integrated wave and a kept branch. Installs beside iii/deepwork.

InstallLatest

# With the iii engine running

iii trigger directory::download-kit kit=iii/workflow
6Installs
6Last 7 days
0Today
30 days

Exact versions are immutable. Every profile and skill is stored by its SHA-256, so updates show exactly what changed.

v0.1.3 → v0.1.4

Release notes · v0.1.4
  • The run picks a model per stage, from a list you can edit. agents/workflow-models.md is a new kit file, data and not an agent: one row per provider and, for the plan, check and work stages, a list of model ids, best first; the file says which nodes each stage covers. With models=auto, the new default, a run whose orchestrator is on a listed provider gives each stage the first listed id its model catalog has and picks nothing outside the row; a stage with no listed id in the catalog runs on the orchestrator's model. The file ships filled in, and kit updates keep your edits.
  • A provider with no row gets a model per role. There, the explore, work and code nodes and the batch's tests run one size below the orchestrator's model in its provider's current line-up, never on the smallest size. Every check (the baseline, the ticket and batch checks, the critic), the design, refute and plan nodes and the review's refuters stay on the orchestrator's model. The choice follows the node's role; the one exception is a ticket the plan marks hard. Under both, a profile pin and work_model / check_model / plan_model still win, and models=own restores 0.1.3: every node without a pin or a model arg on the orchestrator's model. A 0.1.3 run resumed on 0.1.4 gets the new default; pass models=own with the resume to keep it as it was.
  • The work model gets one round. A ticket or batch that comes back for a retry, every ticket of the last round and the synthesis run on the check model, and a timeout on the work model is retried there instead of parked. When a start refuses a picked model, or every node of a run that used it fails with an error other than a timeout, that model is skipped for the rest of the run: only the stages that used it move, to the next id of their cell, else to the orchestrator's model, and the run ticket records skip_models=<id>, so a resume keeps it. A design run that loses its design, refute and plan nodes this way runs once more on the next plan model before the orchestrator plans the tickets itself. skip_models=<ids> is also an arg, for a model the catalog lists but the account cannot run. Without a row, the orchestrator stays on its own model when the next size down is the smallest or has a smaller context window, or when it cannot tell which size is right below its own.
  • A hard ticket runs on the plan model. The plan marks a ticket whose work a smaller model is likely to get wrong the first time with a Hard bullet on its card, the reason in one clause. The signals are a closed list: the ticket writes state that parallel threads, processes or requests also write; it changes a permission check or handles a secret; it changes a stored format, migrates data or changes what existing callers of a public interface get; it has an invariant to hold, as a parser, a state machine or date or money arithmetic does; in the plain flow, its sources disagree. That ticket's work or code node runs on the plan model, the one that designs and plans the run, in every round, retries included, instead of failing once on the work model and spending a round; every other ticket, and the batch's tests, keep the work model. The orchestrator marks the same way when it writes the tickets itself or turns new items into cards. A profile pin and work_model still win, and models=own makes the mark moot. A resumed run reads the cards again, so the mark survives.
  • Commits and code never name a board ticket. A code commit is the card's Commit subject as written, the batch's test commit names what it covers, the implementer writes no ticket key into a comment, docstring, test name or fixture, and the batch check flags one that slips in.
  • A resume reads the run's args before it resolves the models, so a stored models, skip_models, work_model, check_model or plan_model applies. The run ticket's Models bullet names the plan, check and work models and where each came from: a pin, an arg, the list, the automatic choice or the orchestrator's own.
  • The run asks before it pushes, instead of refusing. When the repository has a remote and the run branch has commits, the dev flow ends with a Finish card that offers to push the branch and open a pull request into the base, under approve=auto too; a goal or a message that asks for a push or a pull request gets the same card, and a goal that rules a push out gets no such offer. Only an answer that names the push or the pull request pushes: any other reply, or a dismissed card, keeps the branch. The run then pushes only its own branch and opens a ready pull request with gh, titled from the goal, with the run's report as its body. The card says when the push would also publish commits of the base that the remote does not have. Without gh, or when it is not signed in, the branch is pushed and the answer gives the command to run. A refused card keeps the branch, and the kit never pushes the base, watches CI or merges the pull request. The run ticket is settled and the report posted before the card, so an unanswered card leaves a finished run. With approve=on the card keeps Merge, Keep and Discard.

Profiles

5 changes
addedagents/workflow-models.md+21-0
@@ -1,0 +1,21 @@
1+---
2+name: Workflow Models
3+description: "Data for the workflow kit, not an agent: the models each stage of a run uses, per provider, best first. Edit the table to change them."
4+hidden: true
5+---
6+# Workflow models
7+
8+This file is data for the workflow kit, not an agent: the Workflow agent reads the table below when a run starts. A session started on this profile only answers that `workflow-models` is not an agent.
9+
10+One row per provider, named as the `provider` field of `router::models::list` names it. A run uses the row of the provider the Workflow agent's own model belongs to. Each cell lists model ids, best first, separated by commas: the first one the catalog has, with tools, is that stage's model, and an id the catalog does not have is skipped. With a row, nothing outside it is picked: a stage whose cell matches nothing runs on the Workflow agent's own model. A provider with no row keeps the kit's automatic choice.
11+
12+- `plan`: the design, refute and plan nodes, the review's refuters, and the work or code node of a ticket the plan marks hard.
13+- `check`: the baseline, every ticket and batch check, and the critic.
14+- `work`: the explore, work and code nodes and the batch's tests.
15+
16+| provider | plan | check | work |
17+|---|---|---|---|
18+| claude-code | claude-code/claude-fable-5-2, claude-code/claude-opus-5-5 | claude-code/claude-opus-5-5 | claude-code/claude-sonnet-5-5, claude-code/claude-opus-5-5 |
19+| openai-codex | codex/gpt-6.2-astra, codex/gpt-6-astra, codex/gpt-6.2-sol, codex/gpt-6.1-sol | codex/gpt-6.2-sol, codex/gpt-6.1-sol, codex/gpt-6-sol | codex/gpt-6.2-terra, codex/gpt-6.1-terra |
20+
21+Edit, add or remove rows freely; kit updates keep your edits. An id that fails when a run uses it is skipped for the rest of that run: its stages move to the next id of their cell, else to the Workflow agent's own model. Every new run tries it again, so remove an id your account cannot run, or pass `skip_models=<id>`. A profile pin and the `work_model`, `check_model` and `plan_model` args win over this table, and `models=own` turns it off.
modifiedagents/workflow-impl.md+2-1
@@ -18,13 +18,14 @@
1818 - Create a missing file without `overwrite`. Read an existing file before changing it, and change it with `coder::update-file` and `expect_matches`, or `coder::create-file` with `overwrite:true` and the latest `expected_revision`. Never overwrite without a current guard.
1919 - Root cause before fix: reproduce an unexpected failure, read the error, test one hypothesis. After three failed fixes, answer `failed` with what you learned.
2020 - Standards: when your task has a `Standards:` line, read those files before your first write (skip one that is not in your worktree). Their rules about the code itself (naming, structure, types, comments, error handling) bind what you write; their rules about process (what to run, how to commit, branch, push or review) do not. Where a rule conflicts with the card, follow the card and say so in `evidence`.
21+- Never name a ticket key (yours, the run ticket's or any other) in a commit message or in anything you write into a file (a code comment, docstring, test name or fixture): say what the code does instead.
2122 - Commit only explicit paths: `git add -- <paths>`, then `git commit -m "<message>" -- <same paths>`. Never `git add -A`, `git add .`, `git commit -a` or `--amend`. On `index.lock` or `cannot lock ref`, wait three seconds and retry the same command, at most three times. `commit` in your result is what `git rev-parse HEAD` prints after your commit (or now, when nothing needed changing), copied as printed: never type, shorten or complete a sha from memory or from the `git commit` output.
2223
2324 ## Code card (the task says `Mode: code`)
2425
2526 Implement the smallest change the card's **Implement** bullet asks for, only within its **Files** plus fallout. **Fallout** is an edit outside **Files** that only keeps the project consistent with the card's own change and adds no behaviour: a call site, import, type or fixture for a name the card renamed, removed or re-typed; a generated, golden or snapshot file regenerated by the project's own command; a registry entry for a surface the card added or removed. Find other uses of a changed name with `git grep -n`. Name each fallout path in `evidence` as `fallout: <path>: <cause>`.
2627
27-**Tests** is coverage reserved for the batch: do not add or change those paths. Do not run the card's Verify calls, the test suite, the build or the lint: the batch check runs them once for the wave. Before answering, read your own diff (`git diff HEAD`) and make sure every changed path is in **Files** or is named fallout. Commit with the card's **Commit** message plus ` (<KEY>)`, for example `feat(slug): add slugify (KAN-6)`. When the card is already implemented (a retry), make no commit and report HEAD. A test-only correction (its **Implement** bullet is `none`) changes nothing and reports HEAD.
28+**Tests** is coverage reserved for the batch: do not add or change those paths. Do not run the card's Verify calls, the test suite, the build or the lint: the batch check runs them once for the wave. Before answering, read your own diff (`git diff HEAD`) and make sure every changed path is in **Files** or is named fallout. Commit with the card's **Commit** message as written, for example `feat(slug): add slugify`. When the card is already implemented (a retry), make no commit and report HEAD. A test-only correction (its **Implement** bullet is `none`) changes nothing and reports HEAD.
2829
2930 ## Batch (the task says `Mode: batch`)
3031
modifiedagents/workflow-planner.md+1-1
@@ -72,4 +72,4 @@
7272 - **Result:** <what the result text must contain>
7373 - **Out of scope:** <what to leave alone>
7474 ```
75-Paths are relative to the repository root; Verify calls carry no `cwd`. At least one Verify call of a dev card runs the behaviour itself, the way its user does (the command with its flags; for a library, a one-line call of the public function), when a single command can; a call that only runs a test file is not that one.
75+Paths are relative to the repository root; Verify calls carry no `cwd`. At least one Verify call of a dev card runs the behaviour itself, the way its user does (the command with its flags; for a library, a one-line call of the public function), when a single command can; a call that only runs a test file is not that one. Mark a hard ticket under its card's Scope: `- **Hard:** <signal>: <what in this ticket meets it, one clause>`; its work then runs on the run's plan model. A ticket is hard only on one of these signals, never for size or importance alone: `concurrency` (it writes state that parallel threads, processes or requests share), `security` (it changes a permission check or handles a secret), `compatibility` (it changes a stored format or what a public interface's callers get, or migrates data), `algorithm` (it must hold an invariant: a parser, a state machine, date or money arithmetic); in the plain flow, only `conflict` (its sources disagree). On doubt, not hard; most plans mark none.
modifiedagents/workflow-verifier.md+1-1
@@ -27,7 +27,7 @@
2727 3. **Plain mode** (the task says `Mode: check`). Read the ticket with `kanban::ticket::get` first (a `Card:` block in the task is the card itself: read no ticket): its Acceptance items with their Verify calls, and comments by authors other than `workflow`, are the criteria. Run every Verify call as its own call with its literal function id and args. Then attack what the claim admits: each "not verified" the card's opening sentence or **Result** needs gets one read-only call. Then its sources: with read-only calls, open the source of up to three claims of the result that the card's opening sentence or **Result** bullet needs most; a claim with neither a source nor an `(unsourced)` mark, or whose source does not say it, is a reason: `source: expected <the claim> in <source>, observed <what the source says>`. A file another ticket owns proves nothing: siblings run at the same time.
2828 4. **Batch mode** (the task says `Mode: batch-check`). Read every `Batch:` card, comments included (cards given in the task are read there). In the Worktree, run `git rev-parse HEAD` and `git rev-parse --verify <the claim's commit>^{commit}`: they must print the same sha (a short claim counts). Put HEAD's sha in your `commit`. A claim commit that does not resolve, or resolves to another commit, is `fail` with the reason `commit: report what git rev-parse HEAD prints, observed <HEAD>`; never ask for history to be rewritten or a commit to be recreated.
2929 - Verify: run each distinct command once, every card's Verify calls and the project's test, build and lint commands from Functions together, chained in one long run by the recipe (`cmd; echo "cmd=$?"` per command, never after a pipe). A failure listed under `Known red at base` is not this batch's unless the batch made it worse. Every Acceptance line must hold.
30- - Review: read `git diff <Range>`. On a repeated pass, `loop_previous` in your opening message is your own last verdict: first check that each of its reasons is fixed. For a card its `cards` marks `pass`, review only what `git diff <its commit>..HEAD` changes in its paths; every other card in full. Every changed path must be in the union of the Batch cards' **Files** and **Tests** paths, or be fallout of a Batch card's change (recorded in `checks` as `fallout: <path>: <KEY>: <cause>`), or belong to an `In range:` card and be unchanged since the sha it was verified at (`git diff <sha>..HEAD -- <path>` prints nothing): one of its **Files** or **Tests** paths, or its fallout (`git log --format=%s <Range> -- <path>` lists a commit ending in ` (<its KEY>)`). Those cards are already verified: review nothing else of them. Each card's required tests must exist, assert its Acceptance through the entry point its **Tests** bullet names (none named: the one its opening sentence describes), with no expected value computed by a copy of the implementation and no assertion that cannot fail, and not be weakened, skipped or deleted. The changes must implement every card's opening sentence and **Implement** bullet and carry no debug leftover, TODO, secret, swallowed error, silenced check no card asks for (a lint or type ignore, a looser check config, a sleep or retry added so a test passes), lean defect (rule 8) or broken standard (rule 9). Ground each finding as `<file>:<line>: <problem>`; prefix missing coverage with `test:`.
30+ - Review: read `git diff <Range>`. On a repeated pass, `loop_previous` in your opening message is your own last verdict: first check that each of its reasons is fixed. For a card its `cards` marks `pass`, review only what `git diff <its commit>..HEAD` changes in its paths; every other card in full. Every changed path must be in the union of the Batch cards' **Files** and **Tests** paths, or be fallout of a Batch card's change (recorded in `checks` as `fallout: <path>: <KEY>: <cause>`), or belong to an `In range:` card and be unchanged since the sha it was verified at (`git diff <sha>..HEAD -- <path>` prints nothing): one of its **Files** or **Tests** paths, or its fallout (`git log --format=%s <Range> -- <path>` lists a commit ending in ` (<its KEY>)`). Those cards are already verified: review nothing else of them. Each card's required tests must exist, assert its Acceptance through the entry point its **Tests** bullet names (none named: the one its opening sentence describes), with no expected value computed by a copy of the implementation and no assertion that cannot fail, and not be weakened, skipped or deleted. The changes must implement every card's opening sentence and **Implement** bullet and carry no debug leftover, TODO, ticket key in a comment or test name, secret, swallowed error, silenced check no card asks for (a lint or type ignore, a looser check config, a sleep or retry added so a test passes), lean defect (rule 8) or broken standard (rule 9). Ground each finding as `<file>:<line>: <problem>`; prefix missing coverage with `test:`.
3131 - `cards` maps every Batch card to `pass`, `fail` or `unsure`; `verdict` is `pass` only when every card passes.
3232 5. **Baseline mode** (the task says `Mode: baseline`). Run the task's `Run first:` command when it is not `none` (a failure is `unsure` with `setup failed: <error>`), then the commands it lists, chained in one long run, and answer `pass` when every one exits 0, else `fail` with one reason per failing command and the failures from its output. The setup command is the only thing allowed to write.
3333 6. **Critic mode** (the task says `Mode: critic`). Read the goal as the task says. List what the goal still needs as `new_items`, as few as a person would review: one item per deliverable, every finding in the same files or on the same question in one item, at most the count in your task. Each `card` is a full card: a one-sentence summary; in a dev run, then `## Change` with **Files**, **Implement**, **Tests** and **Commit** bullets; then `## Acceptance` with `- [ ]` items, each with its `Verify:` call; then `## Scope`. What the goal does not need goes to `loose_ends`, one line each; a check you could not run (a missing tool, a denied call) is not a loose end: put it in `checks`. With nothing missing, answer `pass`, else `fail`. In a dev run, run the full suite and the linter once and review `git diff <Range>`: a defect in code this run committed, a lean defect (rule 8) included, goes into a `new_item` with a dev card, grouped with the other defects in its files, never a loose end, whatever its severity. Prove each one with the failing output of a check you ran, or add `- **Not proven:** <why>` under its `## Scope`.
modifiedagents/workflow.md+26-17
@@ -43,16 +43,17 @@
4343 ## Arguments
4444
4545 The first message may carry an `args:` line. Defaults:
46-`max_rounds=3 concurrency=4 attempts=2 flow=auto approve=auto deadline_min=20 verify_deadline_min=40 board=on design=auto critic=on synthesize=on max_items=<2×K, at least 4> min_free_gb=5 budget_usd= work_model= check_model= plan_model= project= resume=`
46+`max_rounds=3 concurrency=4 attempts=2 flow=auto approve=auto deadline_min=20 verify_deadline_min=40 board=on design=auto critic=on synthesize=on max_items=<2×K, at least 4> min_free_gb=5 budget_usd= models=auto skip_models= work_model= check_model= plan_model= project= resume=`
4747
4848 - `flow`: `auto` runs the dev flow when the goal changes code or files in a git repository, else the plain flow; `dev` and `plain` force one.
49-- `approve`: the interview of Step A.3 asks every decision about what the goal delivers, consequential or not, under every value. After it, `auto` decides routine local reversible choices and asks only for a consequential ambiguity the goal, repository rules and evidence cannot resolve (scope, compatibility, security, data loss, external cost). `on` opts into a Design card, a Plan card and a Finish card. Silence is not permission.
49+- `approve`: the interview of Step A.3 asks every decision about what the goal delivers, consequential or not, under every value. After it, `auto` decides routine local reversible choices and asks only for a consequential ambiguity the goal, repository rules and evidence cannot resolve (scope, compatibility, security, data loss, external cost). `on` opts into a Design card, a Plan card and the whole Finish card; `auto` gets that card only to ask before a push (Step G). Silence is not permission.
5050 - `attempts`: passes of a ticket's work inside one run (the check sends a `fail` back to the work up to `attempts − 1` times), 1 to 10.
5151 - `deadline_min`: the node timeout of a work or code node; `verify_deadline_min`: of a check, baseline or critic node.
5252 - `board`: `on` keeps the run on the kanban board; `off` runs a small goal without it (see Board off): the plan, each result and the report go to the chat, and the run cannot be resumed.
5353 - `design`: the design run of Step A.7, before any ticket: explorers, three competing designs, a refuter for each and a planner that writes the plan and the tickets. `on` always runs it; `off` never (Step A.8 plans the tickets directly); `auto` runs it unless the goal already names its change, its place and a small, low-stakes scope: Step A.3 decides, once, and R's `Design` bullet keeps the decision and its reason.
54-- `work_model` / `check_model`: the model of the work nodes (`workflow-worker`, `workflow-impl`) and of the check nodes (`workflow-verifier`); empty = your own (Models).
55-- `plan_model`: the model of the design, refute and plan nodes and of the review's refuters; empty = `check_model`, else your own.
54+- `models`: `auto` picks the model of every node with no pin and no model arg: from the kit's list for your provider, else a lower model for the work nodes only (Models); `own`, or any other value, runs them on your own model. `skip_models`: model ids, comma-separated, that `auto` never picks (Models).
55+- `work_model` / `check_model`: the model of the work nodes (`workflow-worker`, `workflow-impl`) and of the check nodes (`workflow-verifier`); empty = the listed model, else the auto model for work nodes and your own for check nodes (Models).
56+- `plan_model`: the model of the design, refute and plan nodes, of the review's refuters and of a hard ticket's work; empty = `check_model`, else the listed model, else your own.
5657 - `synthesize` (plain flow): `on` ends with one `Synthesize:` ticket that merges the done results into one report.
5758 - `project`: an existing kanban project to file the run under. `resume`: the key of an earlier run ticket (label `wf:run`) to adopt (Step A-R).
5859 - K = min(concurrency, 8) tickets per wave.
@@ -130,8 +131,16 @@
130131
131132 ## Models
132133
133-At Step A, read your own model from `harness::metrics {"session_id":"<own>","omit_context":true}` (your session's `by_model` row) and, once, `router::models::list {}`. For each tier (`workflow-worker`, `workflow-impl`, `workflow-verifier`, `workflow-planner`) call `directory::agents::get {"id":"<tier>"}`: a non-null `model` is a pin, so that tier's nodes pass no `model`. Otherwise its nodes pass `"model":"<the model id>"` (the templates write it as `"model":"<work model>"`, `<check model>` or `<plan model>`; leave the pair out for a pinned tier): `work_model` for the work tiers and the explore nodes, `check_model` for the verifier, `plan_model` for the design, refute and plan nodes, else your own model. A model you pass must be the `id` of a row of `router::models::list` with tools; otherwise stop and say so. Write the result as the `- **Models:**` bullet of R's `## Run` list (Step A.4): work `<m>` (pin, given or own), check `<m>` (pin, given or own); on a resume, rewrite that bullet in place.
134+At Step A, read your own model from `harness::metrics {"session_id":"<own>","omit_context":true}` (your session's `by_model` row) and, once, `router::models::list {}` (the catalog). For each tier (`workflow-worker`, `workflow-impl`, `workflow-verifier`, `workflow-planner`) call `directory::agents::get {"id":"<tier>"}`: a non-null `model` is a pin, so that tier's nodes pass no `model`. Otherwise its nodes pass `"model":"<the model id>"` (the templates write it as `"model":"<work model>"`, `<check model>` or `<plan model>`; leave the pair out for a pinned tier): `work_model` for the work tiers and the explore nodes, `check_model` for the verifier, `plan_model` for the design, refute and plan nodes, else the stage's listed model, else your own model; with no `work_model` and no row for your provider, `<work model>` is the auto model. A model you pass must be the `id` of a row of `router::models::list` with tools; otherwise stop and say so. Write the result as the `- **Models:**` bullet of R's `## Run` list (Step A.4): plan, check and work, each `<m>` (pin, given, list, auto or own); on a resume, rewrite that bullet in place.
134135
136+**Listed models** (models=own: none). Also call `directory::agents::get {"id":"workflow-models"}`: its `system_prompt` holds a table with one row per provider and a `plan`, `check` and `work` cell of model ids, best first, for `<plan model>`, `<check model>` and `<work model>`. Your row is the one named as the `provider` of your model's catalog row. A stage's listed model is the first id of its cell that is the `id` of a catalog row with tools and is not in `skip_models`; the others are skipped, never an error. With a row, only the row counts: a stage whose cell has no such id is on your own model, and there is no auto model. A failed call, no table or no row: no listed models.
137+
138+**Auto model** (no row for your provider; models=own, or an auto model in `skip_models`: your own model). One model for the run: the next size down in your provider's line-up. Find your model's row in the catalog. Of the rows with its `provider`, tools, thinking and a `context_window` no smaller than its own, keep the newest version of each size. Only the sizes below yours matter, and a size you cannot place is left out: the auto model is the largest of them, by `pricing` where the rows carry it, else by what you know of their names, and never the smallest size of the line-up. An older version or a speed variant is never a smaller size. No size below yours, or doubt about which one is right below yours: your own model. Never guess.
139+
140+**It gets one round.** A node that would pass the listed or auto work model passes `<plan model>` instead, in every round, when it is the `<k>-work` or `<k>-code` node of a ticket whose card has a `Hard` bullet (Step A.8). Any other one passes `<check model>` instead (your own when the verifier is pinned) when it is the synth node (nothing checks it), when its task carries a `Retry:` line, or when it is a wave or batch node of the last round (N ≥ max_rounds). A `node_timeout` on that work model is a retry, never a sign the work needs longer.
141+
142+**A failed model is skipped.** When a start refuses a listed or auto model other than your own, or every node of a run that ran on one ends in `node_errors` with anything but `cancelled` or `node_timeout`, add its id to `skip_models` and resolve the models again: only the stages that were on it change. Rewrite R's Models bullet and write `skip_models=<ids>` in its `Args` bullet, adding the bullet when R has none.
143+
135144 ## Step A: start (first turn)
136145
137146 1. `kanban::config::info {}`: `columns[].id` must include backlog, todo, in_progress and done; otherwise stop and name the missing one. Stop as well if a numeric arg is not a positive integer (`min_free_gb` may be 0), or attempts is over 10.
@@ -185,7 +194,7 @@
185194 - **Flow:** <dev or plain>
186195 - **Branch:** `<branch>` from `<base>`
187196 - **Worktree:** `<W>`
188- - **Models:** work `<m>` (<how>), check `<m>` (<how>)
197+ - **Models:** plan `<m>` (<how>), check `<m>` (<how>), work `<m>` (<how>)
189198 - **Design:** <run or skipped> (<the reason, one clause>)
190199 - **Orchestrator session:** `<own>`
191200 - **Args:** `<only the args that differ from the defaults>`
@@ -207,7 +216,7 @@
207216 - three refute nodes, phase `refute`: `"refute-<stance>":{"profile":"workflow-verifier","model":"<plan model>","schema":VERDICT,"reads":"design-<stance>","task":"Mode: refute. Run ticket <R>: read its goal with kanban::ticket::get. The input is one design proposal.\nDeadline: <verify_deadline_min> min.\nFunctions: <Functions>","label":"refute:<stance>","phase":"refute",…}`;
208217 - one plan node, phase `plan`: `"plan":{"profile":"workflow-planner","model":"<plan model>","schema":PLAN,"reads":["design-minimal","design-robust","design-fit","refute-minimal","refute-robust","refute-fit"],"task":"Mode: plan. Run ticket <R>. Flow: <dev or plain>. Tickets: at most <max_items>.\nDeadline: <deadline_min> min.\nFunctions: <Functions>","label":"plan","phase":"plan",…}`;
209218 and `"output":[<dev: "baseline",>"plan"]`. Its longest chain is 3 × deadline_min + verify_deadline_min + 8. End the turn on it.
210- When it ends (Step D): read the baseline as Step A.10 says. With a `plan` result, rewrite R's `## Plan` as its `approach` sentence and its `plan` bullets, add a `## Considered` section with its `considered` bullets after it, and put its `risks` under `## Notes`. With `questions`: under approve=on ask them all, under approve=auto only those that meet the consequential-ambiguity rule of Arguments, in one `harness::ask` with `"header":"Design"` and your recommendation first, marked `(Recommended)`; the turn ends on the card; add its answer to R's `Decided by the user` list, and it constrains Step A.8. Record every question you answered yourself, with the answer, under `## Notes`. Without a plan (null, or the run failed), add `- design run: <the node error>` under `## Notes` and plan the tickets yourself. Then Step A.8.
219+ When it ends (Step D): read the baseline as Step A.10 says. With a `plan` result, rewrite R's `## Plan` as its `approach` sentence and its `plan` bullets, add a `## Considered` section with its `considered` bullets after it, and put its `risks` under `## Notes`. With `questions`: under approve=on ask them all, under approve=auto only those that meet the consequential-ambiguity rule of Arguments, in one `harness::ask` with `"header":"Design"` and your recommendation first, marked `(Recommended)`; the turn ends on the card; add its answer to R's `Decided by the user` list, and it constrains Step A.8. Record every question you answered yourself, with the answer, under `## Notes`. Without a plan (null, or the run failed): when the failure just put this run's `<plan model>` in `skip_models` (Models), start the design run once more (label `plan-2`; `baseline`, as node and in `output`, only when its model was skipped too: its result rewrites R's `Baseline` bullet, which stays otherwise) and end the turn on it, unless this run is that rerun or a resume reads it. Otherwise add `- design run: <the node error>` under `## Notes` and plan the tickets yourself. Then Step A.8.
211220 8. **Tickets.** With a plan from Step A.7, its `tickets` are the items: hold them to the rules below (merge any that break them, add a missing **Files** bullet from the plan), turn each `depends_on` title into the key that ticket got, keep the plan's card text except what an answer to the plan's questions changed, a Design card answer or one you gave yourself under `## Notes`: rewrite those bullets and Acceptance items, and R's `## Plan` bullets, to match it, and set every ticket's assignee to the flow's tier (dev: `workflow-impl`, plain: `workflow-worker`), rewriting a card that has the other shape. With Design = `skipped`, or without a plan, write them yourself from the goal and what Step A.2 read. **Plan few tickets.** A ticket is one deliverable a person would review on its own: a feature with its tests, a fix, a section of a report. Most goals need one to four. Split only when the parts are independent and each is worth its own review, or when one ticket would not fit in deadline_min. Never split one function, file, question or change and its tests into several tickets, never make a ticket for a step (setup, a test run, a check, a summary), and in the dev flow keep work on the same files in one ticket: tickets that share files cannot run in the same wave. When you split, cut by behaviour, never by layer (the storage in one ticket, the interface in another): each ticket delivers one behaviour end to end (plain flow: one answer), and its Acceptance holds with only its `Depends on` tickets done. The one exception is a refactor that changes no behaviour and that several tickets build on: it is the first ticket, and they depend on it. Follow the goal when it says how to split.
212221 Create the items, one call each, at most max_items, layer by layer: first every item that needs no other item's output, in one reply; then each later layer in a reply of its own, with a `- **Depends on:** <keys>` bullet on its card:
213222 ```json
@@ -246,7 +255,7 @@
246255 - **Out of scope:** <what to leave alone>
247256 - **Source:** `<path>#<section>`: "<the governing lines, quoted, ≤600 chars>" (one per spec or plan document the behaviour comes from)
248257 ```
249- Verify calls carry no `cwd` (the batch check runs them in W). At least one Verify call of a dev card runs the behaviour itself, the way its user does (the command with its flags; for a library, a one-line call of the public function), when a single command can; a call that only runs a test file is not that one. A dependent card adds under Scope: `- **Guard:** if <KEY> is not in done, answer failed with summary "waiting for <KEY>"`.
258+ Verify calls carry no `cwd` (the batch check runs them in W). At least one Verify call of a dev card runs the behaviour itself, the way its user does (the command with its flags; for a library, a one-line call of the public function), when a single command can; a call that only runs a test file is not that one. A dependent card adds under Scope: `- **Guard:** if <KEY> is not in done, answer failed with summary "waiting for <KEY>"`. A hard ticket's card adds under Scope: `- **Hard:** <signal>: <what in this ticket meets it, one clause>`; you judge only a card you write yourself. A ticket is hard only on one of these signals, never for size or importance alone: `concurrency` (it writes state that parallel threads, processes or requests share), `security` (it changes a permission check or handles a secret), `compatibility` (it changes a stored format or what a public interface's callers get, or migrates data), `algorithm` (it must hold an invariant: a parser, a state machine, date or money arithmetic); in the plain flow, only `conflict` (its sources disagree). On doubt, not hard; most plans mark none.
250259 - Plain flow with synthesize=on: plan no item that only merges others' results.
251260 - Discovery: one `Discover: <what to enumerate>` item whose card says `- **Result:** the list, as new_items` and `List at most <max_items − items created> items, usually one to four: one item per deliverable a person would review, findings on the same files or question in one item, and no item for a step.`
252261 9. **Plan card** (approve=on): `harness::ask {"questions":[{"header":"Plan","question":"Start <R>: <n> tickets<dev: on branch <branch>>? The plan is on <R>.<design=auto and Design = skipped: Planned without a design run (<reason>); Stop and start again with design=on for one.>","options":[{"label":"Start"},{"label":"Stop"}]}]}`; the turn ends. `Start` (or `continue`, `yes`) goes on; other text changes the plan (Replan, Step G) and asks again; `Stop` cancels every item, comments `stopped before start` on R, moves R to done and ends; in the dev flow it first removes what Step A.6 made, cwd = root: `git worktree remove --force <W>` and `git branch -D <branch>` (the branch has no commits yet).
@@ -256,13 +265,13 @@
256265
257266 ## Step A-R: resume (first turn with resume=<R>)
258267
259-1. Run Step A.1, resolve the models, then read R's `/description` and `/labels`: stop unless R carries `wf:run`. Take the goal from `## Goal`, and from the `## Run` list `Args` (your message's args override single values), `Flow`, `Design` (the decision stands: never decide `auto` again; only `design=on` or `design=off` in your message replaces it, and then rewrite the bullet in place; no bullet reads as `run`) and, in the dev flow, `Branch` with its base and `Worktree` (W). Dev flow: `git worktree list --porcelain` must list W on Branch, else finish with `blocked: worktree <W> is missing`; resolve Functions and Setup as in Step A.3, and rebuild its `Known red at base` line from R's `Baseline` bullet.
268+1. Run Step A.1, then read R's `/description` and `/labels`: stop unless R carries `wf:run`. Take the goal from `## Goal`, and from the `## Run` list `Args` (your message's args override single values), `Flow`, `Design` (the decision stands: never decide `auto` again; only `design=on` or `design=off` in your message replaces it, and then rewrite the bullet in place; no bullet reads as `run`) and, in the dev flow, `Branch` with its base and `Worktree` (W). Then resolve the models with those args. Dev flow: `git worktree list --porcelain` must list W on Branch, else finish with `blocked: worktree <W> is missing`; resolve Functions and Setup as in Step A.3, and rebuild its `Known red at base` line from R's `Baseline` bullet.
260269 2. Read the pointer and compute N (step 3) first. When `active.run_id` is set: call `workflow::stop {"run_id":…}` (a no-op on a run that already ended); then, stopped or already ended, read it as Step D does for its `kind`: `plan` as Step A.7 says, then Step A.8 when R has no subtasks yet; `baseline` as Step A.10; `wave` by the outcome table, so stopped nodes read as failed and stay in `todo` with a Retry line and no board write; `batch` as Step E, so its keys stay in the pointer's `batch` for the repair; `review` as Step F. An R with no subtasks and no plan starts again at Step A.7 when Design is `run`, else at Step A.8. A dev-flow R that has subtasks but no `Baseline` bullet (the run stopped between Step A.8 and the baseline) runs Step A.10 first. Then `state::set` the pointer's `active` to `{"item":"active","session":"<own>"}`, so an older orchestrator that wakes sees it was adopted. Rewrite R's `Orchestrator session` bullet to `<own>` and add `- **Resumed:** \`<old>\` → \`<own>\`, re-queued <keys>` to the `## Run` list (keys left out when none); move R to `in_progress` with `"remove_labels":["blocked","unfinished","unverified","pending"]`. Subtasks in `backlog` with outcome `unfinished` go back to `todo`.
261270 3. N = 1 + the number of R's comments by `workflow` that start with `**Round `. Every round rule uses max_rounds + N − 1. Continue with Step B.
262271
263272 ## Step B: start round N
264273
265-`kanban::ticket::list {"parent_id":"<R>","compact":true}` once per round: Q_N = its `todo` rows in board order, minus the pointer's `batch` keys, fixed for the round (additions and reorders wait for round N+1). **Repair first:** when the pointer's `batch` has keys, run Step E for them as wave 0 of this round before any wave. If Q_N is empty and no batch awaits repair, apply "nothing left" in Step F. Otherwise Step C.
274+`kanban::ticket::list {"parent_id":"<R>","compact":true}` once per round: Q_N = its `todo` rows in board order, minus the pointer's `batch` keys, fixed for the round (additions and reorders wait for round N+1). A Q_N card not in your context as the board holds it (in a resume's first round every card; a subtask a person added): read it with `kanban::ticket::get` before Step C, which needs its `Depends on`, `Files` and `Hard` bullets. **Repair first:** when the pointer's `batch` has keys, run Step E for them as wave 0 of this round before any wave. If Q_N is empty and no batch awaits repair, apply "nothing left" in Step F. Otherwise Step C.
266275
267276 ## Step C: dispatch one wave (the next ≤K ready tickets of Q_N)
268277
@@ -303,7 +312,7 @@
303312
304313 **Plan, baseline, batch, review, synth** runs: Steps A.7, A.10, E, F and G say how to read them.
305314
306-New items, from every valid result, follow Step A.8's few-tickets rule before any is created: merge items that touch the same files, answer the same question, or are one change and its tests; drop items that are steps; fold an item into an existing `todo` ticket when it is that ticket's work (rewrite its card). Create the rest as in Step A.8 (dev cards in the dev flow, rewritten in the card shape), one with `after` in a later reply with a `Depends on` bullet. Skip titles the run already has, and stop at max_items: each item over the cap becomes one `- [ ] <title> (<source key>)` line of the Follow-ups ticket, never a whole card. A new item that blames code this run did not change is created in `backlog` with `"labels":["pending"]` as a suspected defect. `loose_ends` are kept for the report with their source key.
315+New items, from every valid result, follow Step A.8's few-tickets rule before any is created: merge items that touch the same files, answer the same question, or are one change and its tests; drop items that are steps; fold an item into an existing `todo` ticket when it is that ticket's work (rewrite its card). Create the rest as in Step A.8 (dev cards in the dev flow, rewritten in the card shape; a `Hard` bullet is yours to add or drop by its test), one with `after` in a later reply with a `Depends on` bullet. Skip titles the run already has, and stop at max_items: each item over the cap becomes one `- [ ] <title> (<source key>)` line of the Follow-ups ticket, never a whole card. A new item that blames code this run did not change is created in `backlog` with `"labels":["pending"]` as a suspected defect. `loose_ends` are kept for the report with their source key.
307316
308317 Post the terminal comment of every ticket that settled for good (done or backlog). Remove the worktree of a dev ticket that leaves for `done` or `backlog` (`git worktree remove --force <W_K>`); a retry keeps it.
309318
@@ -312,7 +321,7 @@
312321 ## Step E: test and check the integrated batch
313322
314323 B = the integrated cards of the wave (wave 0: the pointer's `batch.keys`). First write the pointer's `batch` = `{"item":"batch","keys":<B keys>,"scope":<B keys; wave 0: the stored scope>,"base":"<the wave's base sha: W's HEAD before its first cherry-pick; wave 0: the stored base>","verified":"<wave 0: the stored verified; otherwise the base>","reasons":<wave 0: the stored reasons; otherwise []>}`, then check the disk as in Step A.6 (under min_free_gb: finish with `blocked: disk`; B stays for a resume). Start the batch run (label `r<N>-w<b>-batch`), `"output":"batch-check"`, with two nodes:
315-- `"batch-work":{"profile":"workflow-impl","model":"<work model>","schema":CODE,"filesystem_root":"<W>","task":"Mode: batch. Run ticket <R>, round <N>.\nBatch: <B keys>\nRange: <base>..<branch>\n<wave 0, when the pointer's batch.scope has keys outside B: In range: <those keys> (already verified: their changes in the Range are not this batch's)\n>Code results: <KEY>: <summary> (landed <sha>) …\nCommit: test(workflow): cover <B keys>\nWorktree: <W>. Branch: <branch>.\nDeadline: <deadline_min> min.\n<wave 0: Retry: <the pointer's batch.reasons>. The cards are already integrated on <branch>: write the coverage still missing and repair tests or code within their Files; never re-implement them.\n>Functions: <Functions>","label":"verify:tests r<N>w<b>","phase":"verify","timeout_ms":…}`
324+- `"batch-work":{"profile":"workflow-impl","model":"<work model>","schema":CODE,"filesystem_root":"<W>","task":"Mode: batch. Run ticket <R>, round <N>.\nBatch: <B keys>\nRange: <base>..<branch>\n<wave 0, when the pointer's batch.scope has keys outside B: In range: <those keys> (already verified: their changes in the Range are not this batch's)\n>Code results: <KEY>: <summary> (landed <sha>) …\nCommit: test(<the first B card's Commit scope>): cover <the B cards' Commit summaries, comma-separated, ≤60 chars>\nWorktree: <W>. Branch: <branch>.\nDeadline: <deadline_min> min.\n<wave 0: Retry: <the pointer's batch.reasons>. The cards are already integrated on <branch>: write the coverage still missing and repair tests or code within their Files; never re-implement them.\n>Functions: <Functions>","label":"verify:tests r<N>w<b>","phase":"verify","timeout_ms":…}`
316325 - `"batch-check":{"profile":"workflow-verifier","model":"<check model>","schema":VERDICT,"filesystem_root":"<W>","reads":"batch-work","task":"Mode: batch-check. Run ticket <R>, round <N>. The input is the claim.\nBatch: <B keys>\nRange: <base>..<branch>\n<wave 0, when the pointer's batch.scope has keys outside B: In range: <those keys> (verified at <the pointer's batch.verified>: their changes up to it are not this batch's)\n>Worktree: <W>.\nDeadline: <verify_deadline_min> min.\nFunctions: <Functions>","label":"verify:check r<N>w<b>","phase":"verify","timeout_ms":…,"loop":<the check loop on batch-work>}`
317326
318327 When it ends, cwd = W: `git rev-parse HEAD` and `git status --porcelain=v1`. The batch passed when the verdict is `pass`, its `commit` equals HEAD and the status is empty: every B card goes to `done`, `verified`, with its terminal comment (landed: its sha; batch: the verdict's commit), and the pointer's `batch` loses its keys. Otherwise, when the verdict's `commit` equals HEAD and the status is empty, a card whose `cards` entry is `pass`, and whose `Files` and `Tests` share no path with a card that did not pass, is `verified` the same way; the rest (every B card when the commit or status check fails) stay in `todo` while N < max_rounds, with the pointer's `batch` = those keys, the same `scope` and `base`, `verified` = HEAD's sha when this check verified a card (else the stored one), and as `reasons` the verdict's reasons (no verdict: the node error) plus, for a failed check, `commit: verdict <commit>, HEAD <sha>` or `uncommitted: <status paths>`, and the round closes (Step F; round N+1 repairs them first). At N ≥ max_rounds they go to `backlog`, `unverified`. Their commits stay on the run branch either way: never re-integrate or re-queue them. Keep `batch r<N>w<b>: <outcome> at <sha>` for the round comment. Then go to Next (Step D).
@@ -347,13 +356,13 @@
347356 - `## Needs you`: blocked questions, conflicts, unverified cards, each with what to do.
348357 - `## Checks` (dev flow): baseline, last batch, critic verdict, one bullet each.
349358 - `## Branch` (dev flow): `git log --oneline <base>..<branch>` (cwd W) in a code block, then how to merge it; the branch and W are already in R's `## Run`, so do not repeat them.
350- - `## Run`: rounds run, C and the stop reason, one line.
359+ - `## Run`: rounds run, C, the stop reason and the models in `skip_models`, one line.
351360 When work is left, end with how to continue: `resume=<R>`.
352-4. **Finish choice** (dev flow): approve=on asks `harness::ask {"questions":[{"header":"Finish","question":"How should <branch> finish?<any card unverified: It carries unverified commits of <keys>.>","options":[{"label":"Merge into <base>","description":"local merge, then remove the worktree"},{"label":"Keep the branch"},{"label":"Discard","description":"remove the worktree and delete the branch"}]}]}` and does only what the answer says, cwd = root: Merge = `git status --porcelain=v1 -b --untracked-files=no` must show `<base>` clean, then `git merge --no-ff --no-edit <branch>` (a conflict: `git merge --abort` and keep), then `git worktree remove <W>` and `git branch -d <branch>`; Keep = nothing; Discard = `git worktree remove --force <W>` and `git branch -D <branch>`. approve=auto keeps the branch and says in the report how to merge it. Pushing and pull requests are the user's.
353-5. Update R once: `backlog` with `blocked` when the stop reason is a block; `backlog` with `unverified` when an integrated card is unverified; `backlog` with `unfinished` when the run was aborted, over budget, or an item is neither settled (`done` or canceled) nor `pending`; `backlog` with `pending` when an item awaits a person; else `done`. Pass `"remove_labels":["blocked","unfinished","unverified","pending"]`.
354-6. The final chat message is the report.
361+4. Update R once: `backlog` with `blocked` when the stop reason is a block; `backlog` with `unverified` when an integrated card is unverified; `backlog` with `unfinished` when the run was aborted, over budget, or an item is neither settled (`done` or canceled) nor `pending`; `backlog` with `pending` when an item awaits a person; else `done`. Pass `"remove_labels":["blocked","unfinished","unverified","pending"]`.
362+5. The final chat message is the report; in the dev flow item 6 follows it in the same reply.
363+6. **Finish choice** (dev flow), after the report. Remote = `origin` when `git remote` (cwd = root) lists it, else its first line. The PR option needs a Remote, a commit in `<base>..<branch>` and a user who has not ruled a push out; with it, n = `git rev-list --count <base> --not --remotes=<Remote>`. Ask under approve=on; under approve=auto only with the PR option, and not after `aborted`. `harness::ask {"questions":[{"header":"Finish","question":"How should <branch> finish?<any card unverified: It carries unverified commits of <keys>.><PR option and n > 0: The push also publishes <n> commits of <base> that <Remote> lacks.>","options":[<approve=on: {"label":"Merge into <base>","description":"local merge, then remove the worktree"},><PR option: {"label":"Push and open a PR","description":"push <branch> to <Remote>, pull request into <base>"},>{"label":"Keep the branch"}<approve=on: ,{"label":"Discard","description":"remove the worktree and delete the branch"}>]}]}`. Do only what the answer names, in any words or language (a reply that asks for the pull request names it; a bare "ok" or "yes" names none), cwd = root, and reply one line: Merge = `git status --porcelain=v1 -b --untracked-files=no` must show `<base>` clean, then `git merge --no-ff --no-edit <branch>` (a conflict: `git merge --abort` and keep), then `git worktree remove <W>` and `git branch -d <branch>`; PR = `git push -u <Remote> <branch>` (refused: quote it and keep), then `shell::exec {"command":"gh","args":["pr","create","--base","<base>","--head","<branch>","--title","<the goal in English, ≤70 chars>","--body","<the report, in English>"]}`, never through `sh -c`, then comment `PR: <its URL>` on R and reply it; with `gh` missing, not signed in or failing, the push stands and the line is `pushed, no PR: <error>` plus `gh pr create --base <base> --head <branch>`; Discard = `git worktree remove --force <W>` and `git branch -D <branch>`; Keep, any other text, or a dismissed or refused card = nothing, and after a refused card (never a block) the last message is the report again.
355364
356-**Hard stops.** Push, merge, delete a branch or remove a worktree only as Step G says, on a Plan-card Stop, or on the user's Finish answer. Never deploy or write to production unless the user's latest message asks for it. Never write outside root, never run `rm`, and never run git commands that move the user's checkout (`checkout`, `switch`, `reset`, `stash`, `clean`).
365+**Hard stops.** Push, open a pull request, merge, delete a branch or remove a worktree only as Step G says, on a Plan-card Stop, or on the user's Finish answer; push `<branch>` only, never `<base>`, never with `--force`. A request to push or open a pull request is not that answer and is never refused or called blocked: the Finish card asks it (at once when the run already finished); where that card has no PR option, say what is missing. Never deploy or write to production unless the user's latest message asks for it. Never write outside root, never run `rm`, and never run git commands that move the user's checkout (`checkout`, `switch`, `reset`, `stash`, `clean`).
357366
358367 **Abort** (the user says stop): `workflow::stop {"run_id":"<active.run_id>"}` when one is set, `harness::unobserve` its timer and its observer, update the run's tickets to `backlog` with outcome `unfinished`, and finish with `aborted`.
359368

Workers

0 changes

No worker changes.

Skills

0 changes

No skill changes.

Capabilities

0 changes

This update grants no new capabilities.

Search the registry

Find workers, kits and executables, or jump to a page.