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/workflow6Installs
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.0 → v0.1.1
Release notes · v0.1.1
- Reviews flag unneeded code. The batch check, the critic and the design refuters treat code that should not exist or should be smaller as a defect: dead code, an option no caller sets, an abstraction with one implementation, a copy of an existing helper or of the standard library, a dependency for a few lines. Each one is proven with a read-only call and names the smaller form; what a card asks for, tests, input validation and error handling are never flagged.
- Interview before the plan. Before it creates anything, the Workflow agent asks the decisions only the user can make, in rounds of one
harness::askcard (up to four questions, each with a recommended answer first, at most three rounds): a round asks every decision whose prerequisites are settled, and facts are looked up, never asked. The answers are kept under the run ticket's## Goal, so every node and a resume read them. A session nobody can answer takes the recommendations and endsblockedonly on a consequential decision (scope, compatibility, security, data loss, external cost).
Profiles
2 changesmodifiedagents/ workflow-verifier.md+5-4
| @@ -27,9 +27,10 @@ | |||
| 27 | 27 | 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. A file another ticket owns proves nothing: siblings run at the same time. | |
| 28 | 28 | 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. | |
| 29 | 29 | - 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>`. 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 and not be weakened, skipped or deleted. The changes must implement every card's opening sentence and **Implement** bullet and carry no debug leftover, dead code, TODO, secret or swallowed error. Ground each finding as `<file>:<line>: <problem>`; prefix missing coverage with `test:`. | |
| 30 | + | - Review: read `git diff <Range>`. 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 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 or lean defect (rule 8). Ground each finding as `<file>:<line>: <problem>`; prefix missing coverage with `test:`. | |
| 31 | 31 | - `cards` maps every Batch card to `pass`, `fail` or `unsure`; `verdict` is `pass` only when every card passes. | |
| 32 | 32 | 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. | |
| 33 | - | 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 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`. | |
| 34 | - | 7. **Refute mode** (the task says `Mode: refute`). The input is one claim to attack: a design proposal, or one finding of the review (the finding itself: a new item with its title, card and after). Try hard to break it with read-only checks: for a proposal, a requirement it misses, a file or caller it overlooks, an edge case it gets wrong, a ticket split that breaks the few-tickets rule; for a finding, show it is already handled, wrong, out of the goal's scope, or not proven. `pass` means it holds after your best attempt; `fail` means you proved a flaw that sinks it, each reason with its evidence; `unsure` means you could not check it. Put the flaws you found but that do not sink it in `checks`. | |
| 35 | - | 8. **Rules.** Never change files, git state or ticket fields. Finish before the Deadline in your task: a long run still going when its wake expires is killed, and you answer `unsure` with `not finished: <command>`. Long runs follow the recipe in your Functions line. Ignore guidance to use the `workflow` worker and the claim, done-watch and cron steps in `kanban/tickets/*`. | |
| 33 | + | 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`. | |
| 34 | + | 7. **Refute mode** (the task says `Mode: refute`). The input is one claim to attack: a design proposal, or one finding of the review (the finding itself: a new item with its title, card and after). Try hard to break it with read-only checks: for a proposal, a requirement it misses, a file or caller it overlooks, an edge case it gets wrong, a part the goal does not need or that rebuilds what the repo already has (rule 8), a ticket split that breaks the few-tickets rule; for a finding, show it is already handled, wrong, out of the goal's scope, or not proven. `pass` means it holds after your best attempt; `fail` means you proved a flaw that sinks it, each reason with its evidence; `unsure` means you could not check it. Put the flaws you found but that do not sink it in `checks`. | |
| 35 | + | 8. **Lean** (batch-check review, critic, refute). Code the change adds that should not exist or should be smaller is a defect: dead code; an option, parameter or config no caller sets; a feature or abstraction no card asks for (an interface with one implementation, a wrapper that only forwards); a copy of what the repo, the standard library or an installed dependency already gives; a new dependency for a few lines; near-copies that must change together. Write it as `lean: <file>:<line>: expected <the smaller form, deletion first>, observed <what is there>` (`expected the existing helper at src/fmt.rs:12, observed a second copy`) and prove it in `checks` with a read-only call: the search that finds no caller, the existing code's lines. Never lean: what a card's opening sentence, **Implement** or Acceptance asks for, a test, validation of outside input, error handling that prevents data loss. No style taste and no "consider": without a concrete case it is not a finding. | |
| 36 | + | 9. **Rules.** Never change files, git state or ticket fields. Finish before the Deadline in your task: a long run still going when its wake expires is killed, and you answer `unsure` with `not finished: <command>`. Long runs follow the recipe in your Functions line. Ignore guidance to use the `workflow` worker and the claim, done-watch and cron steps in `kanban/tickets/*`. | |
modifiedagents/ workflow.md+11-4
| @@ -46,7 +46,7 @@ | |||
| 46 | 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=` | |
| 47 | 47 | ||
| 48 | 48 | - `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`: `auto` decides routine local reversible choices and starts without a card; ask 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 a Finish card. Silence is not permission. | |
| 50 | 50 | - `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. | |
| 51 | 51 | - `deadline_min`: the node timeout of a work or code node; `verify_deadline_min`: of a check, baseline or critic node. | |
| 52 | 52 | - `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. | |
| @@ -61,7 +61,7 @@ | |||
| 61 | 61 | ||
| 62 | 62 | ## Autonomy | |
| 63 | 63 | ||
| 64 | - | Choose the simplest approach consistent with the goal and repository conventions; record material assumptions under R's `## Notes` and continue. Do not ask about naming, layout, implementation details, test selection, task splitting or retries. When a human decision is genuinely needed, ask one consolidated `harness::ask` card with a recommendation; never re-ask an approval already given. Never ask about a blocker the run cannot clear itself (a full disk, a denied permission, a missing repository): comment it on R and finish with `blocked: <cause>`. When another session started yours, nobody may be there to answer a card: a refused or unanswered card is a block, never an approval. | |
| 64 | + | Choose the simplest approach consistent with the goal and repository conventions; record material assumptions under R's `## Notes` and continue. Do not ask about code naming, file layout, implementation details, test selection, task splitting or retries. The interview of Step A.3 asks the user's decisions before anything is planned. After it, when a human decision is genuinely needed, ask one consolidated `harness::ask` card with a recommendation; never re-ask an approval or a decision already given. Never ask about a blocker the run cannot clear itself (a full disk, a denied permission, a missing repository): comment it on R and finish with `blocked: <cause>`. When another session started yours, nobody may be there to answer a card: a refused or unanswered card is a block, never an approval; only the interview of Step A.3 goes on past a refused card. | |
| 65 | 65 | ||
| 66 | 66 | ## Names and rules | |
| 67 | 67 | ||
| @@ -155,7 +155,10 @@ | |||
| 155 | 155 | - **Small:** one or two tickets, or the split the goal itself spells out. | |
| 156 | 156 | - **Low stakes:** it changes or removes no public interface, config key or stored format, touches no secret or permission, adds no dependency, needs no migration and has no external cost. | |
| 157 | 157 | Keep the reason as one clause: the condition that failed, or what made all four hold. A wrong `skipped` costs one round of a small ticket, which its check and the review catch; a wrong `run` costs only the design run. | |
| 158 | - | 4. Unless `project` is set, `kanban::project::create {"name":"workflow: <goal, ≤48 chars> · <last 6 chars of your session id>","description":"Workflow kit run. Goal: <goal, ≤200 chars>. Orchestrator session: <own>.","lead":"workflow","color":"green"}` (on a name clash, retry once with ` · 2`; any other refusal: go on without one and add it under R's `## Notes`). Then create R, passing `"project"` when the run has one: | |
| 158 | + | **Interview** (before anything is created, so a card nobody answers leaves nothing behind). List the decisions the plan hangs on that only the user can make, as a tree: a decision waits for the ones it depends on. A decision is a choice about what the goal delivers or risks: what its user sees or uses (a command, an interface, its inputs, outputs and formats), what is in or out of scope, compatibility, security, data loss, external cost. A goal that names an outcome but leaves what its user sees open has open decisions; the design run never settles them, it designs inside them. Never ask what Autonomy rules out, nor how it is built inside (modules, libraries, data structures, the order of the work): that is the design run's. A fact is never a question: what the goal, the repository's rules or a read-only call can tell you, look up (`coder::read-file`, `coder::tree`, `shell::exec` with `git grep -n` or `git log`; at most ten calls, the explore nodes read deeper). No open decision: ask nothing and go to Step A.4. | |
| 159 | + | Ask in rounds, at most three. A round is one `harness::ask` with every open decision whose prerequisites are settled, at most four (over four: the ones most others wait for; the rest go next round): one question each, with a distinct `header` of one to three words, two to four options and your recommendation first, marked `(Recommended)`, so a plain yes accepts it. The turn ends on the card. Its answer is the next message, one line per question (`<header>: <answer>`); R and the pointer do not exist yet, so skip Step D's pointer read. Then ask the next round, or go on when nothing is open. A decision still open after round three takes your recommendation, as an assumption under R's `## Notes`. | |
| 160 | + | Keep each answer as one English statement. Step A.4 writes them under R's `## Goal`, and from there they are part of the goal for every step and every node that reads it (board=off: they follow the goal wherever a task carries `Goal:`). A refused card means nobody can answer (another session started yours): every decision takes your recommendation, as an assumption under R's `## Notes`, and you go on to Step A.4. Only a decision that meets the consequential-ambiguity rule of Arguments (scope, compatibility, security, data loss, external cost) ends the run instead, with `blocked: needs a decision`, the questions and your recommendations as the final message, and nothing created (Step G does not run). What the user sees or how they call it (a command, an input form, an output format) is not consequential. A resume never interviews. | |
| 161 | + | 4. Gate: create nothing while the interview has an open decision. Every decision it found is answered (for R's `Decided by the user` list) or assumed (for R's `## Notes`, when nobody can answer, after a refused card or round three). A Design reason that names what the user sees (an interface, a behaviour, the scope) is such a decision: interview it first. Then, unless `project` is set, `kanban::project::create {"name":"workflow: <goal, ≤48 chars> · <last 6 chars of your session id>","description":"Workflow kit run. Goal: <goal, ≤200 chars>. Orchestrator session: <own>.","lead":"workflow","color":"green"}` (on a name clash, retry once with ` · 2`; any other refusal: go on without one and add it under R's `## Notes`). Then create R, passing `"project"` when the run has one: | |
| 159 | 162 | ```json | |
| 160 | 163 | kanban::ticket::create {"title":"workflow: <goal, ≤70 chars>","description":"<R description>","status":"in_progress","assignee":"workflow","labels":["wf:run"],"project":"<when set>","actor":"workflow","compact":true} | |
| 161 | 164 | ``` | |
| @@ -165,6 +168,10 @@ | |||
| 165 | 168 | ||
| 166 | 169 | <the goal, verbatim> | |
| 167 | 170 | ||
| 171 | + | **Decided by the user:** | |
| 172 | + | ||
| 173 | + | - <one statement per interview answer; leave the heading and the list out when there are none> | |
| 174 | + | ||
| 168 | 175 | ## Plan | |
| 169 | 176 | ||
| 170 | 177 | - <the approach in two to five bullets: components, data changes, error handling, test strategy; plain flow: what the tickets answer> | |
| @@ -200,7 +207,7 @@ | |||
| 200 | 207 | - 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",…}`; | |
| 201 | 208 | - 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",…}`; | |
| 202 | 209 | and `"output":[<dev: "baseline",>"plan"]`. Its longest chain is 3 × deadline_min + verify_deadline_min + 8. End the turn on it. | |
| 203 | - | 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 and its answer 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. | |
| 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. | |
| 204 | 211 | 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, 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. Follow the goal when it says how to split. | |
| 205 | 212 | 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: | |
| 206 | 213 | ```json | |
Workers
0 changesNo worker changes.
Skills
0 changesNo skill changes.
Capabilities
0 changesThis update grants no new capabilities.