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.

Install0.1.3

# With the iii engine running

iii trigger directory::download-kit kit=iii/workflow@0.1.3
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.

Workflow Worker

workflow-worker
agents/workflow-worker.md

Hidden leaf: does one plain work card (research, reading, analysis) as a workflow node and answers with one result document. Never edits ticket fields. Base of the work tiers (`workflow-worker`, `workflow-impl`).

Model
Inherited
Effort
medium
Extends
defaultbuilt-in
Icon
terminal
Color
blue
Visibility
Hidden from the picker
Preloaded skills0

No skills preloaded.

Preloaded functions8
  • kanban::ticket::getkanbanv0.2.4Schema

    Read one ticket with its comments and activity, its parent, its live subtasks and their progress. The activity is bounded to keep the result small: every comment.created entry plus the newest 50 other entries (activity_total says how many exist), and a changed text longer than 200 chars (a description edit) is cut to a prefix ending in [truncated, N chars; ...]. kanban::activity::list returns the full history and the full text. The id accepts the internal uuid or the human-readable key.

    request
    • idstringrequired

      Ticket uuid or human-readable key (KAN-1, case-insensitive).

    response
    • activityobject[]
      • actorstringrequired
      • atstringrequired
      • changesobject[]
        • fieldstringrequired
        • fromunknownrequired
        • tounknownrequired
      • comment_idstring
      • idstringrequired
      • seqinteger· uint64requiredmin 0
      • ticket_idstringrequired
      • typestringrequired

        ticket.created | ticket.updated | ticket.moved | ticket.deleted | ticket.restored | comment.created

    • activity_totalinteger· uint64requiredmin 0

      Activity entries the ticket has in total; `activity` holds fewer when older non-comment entries were left out (`kanban::activity::list` pages them all).

    • assigneestring

      Agent profile id.

    • childrenobject[]required

      Live subtasks by ticket number.

      • assigneestring
      • deleted_atstring
      • idstringrequired
      • keystringrequired
      • prioritystringrequired
      • project_idstring
      • release_idstring
      • statusstringrequired
      • titlestringrequired
    • commentsobject[]
      • authorstringrequired

        Agent profile id, or `user`.

      • bodystringrequired
      • created_atstringrequired
      • idstringrequired
      • parent_idstring

        Set for a reply; replies stay one level deep.

      • ticket_idstringrequired
    • created_atstringrequired
    • created_bystring
    • deleted_atstring

      Set when soft-deleted; the row stays on disk.

    • descriptionstring
    • idstringrequired

      Internal uuid.

    • keystringrequired

      Human-readable id, e.g. KAN-1.

    • labelsstring[]
    • orderinteger· uint64min 0

      Position inside its column.

    • parentany of

      The parent, deleted or not; `null` for a ticket that is not a subtask.

      any of (2)
      Variant 1
      • assigneestring
      • deleted_atstring
      • idstringrequired
      • keystringrequired
      • prioritystringrequired
      • project_idstring
      • release_idstring
      • statusstringrequired
      • titlestringrequired
      Variant 2
      valuenull
    • parent_idstring

      Uuid of the parent ticket. One level deep: a parent has no parent.

    • pillsobject[]

      Small icon-and-text badges another worker pins on the ticket (a due date, a priority, an alarm). Shown on the card and the ticket page.

      • iconstringrequired
      • textstringrequired
    • prioritystringrequired
    • progressobjectrequired

      Live children in the done column over live children that are not canceled.

      • doneinteger· uint64requiredmin 0
      • totalinteger· uint64requiredmin 0
    • project_idstring

      Uuid of the project (several tickets, independent of the release).

    • release_idstring

      Uuid of the release.

    • statusstringrequired

      Column id.

    • titlestringrequired
    • updated_atstringrequired
  • shell::execidev0.13.7Schema

    Run a command in the foreground and return its full output. Put the program in `command` (string) and arguments in `args` (string[]), never argv in `command`. Host-only cwd/env/stdin reject S210 on a sandbox target. Errors return { code, message }; common: S216 host exec error, S300 VM boot failed, S200 in-VM failure.

    request
    • argsstring[]

      Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.

    • commandstringrequired

      Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.

    • cwdstring

      Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.

    • envobject

      Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.

    • stdinstring

      Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.

    • targetall of

      Where to run the command. Defaults to the host worker; pass `{ kind: "sandbox", sandbox_id }` to forward the call to a microVM.

      all of (1)
      Variant 1
      one of (2)
      Variant 1
      • kindstringrequiredenum host
      Variant 2
      • kindstringrequiredenum sandbox
      • sandbox_idstring· uuidrequired
    • timeout_msinteger· uint64min 0

      Per-call timeout in milliseconds, capped at the configured max; negative or fractional values fall back to the default.

    response
    • duration_msinteger· uint64requiredmin 0
    • exit_codeinteger· int32
    • stderrstringrequired
    • stderr_truncatedbooleanrequired
    • stdoutstringrequired
    • stdout_truncatedbooleanrequired
    • timed_outbooleanrequired
  • coder::read-fileidev0.13.7Schema

    Read a file. stat: true probes size/mtime/total_lines without content; line_from/line_to (1-based, inclusive) read a window of a file of any size; numbered: true prefixes absolute line numbers; paths[] (XOR path) batch-reads. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).

    request
    • encodingall of

      Content encoding for full reads; `base64` returns the exact file bytes (encoded length is budgeted). C210 with stat/window/numbered.

      all of (1)
      Variant 1
      one of (2)
      Variant 1
      valuestringenum text
      Variant 2
      valuestringenum base64
    • line_frominteger· uint64min 1

      First line (1-based, >= 1) of a windowed read; windows keep files over max_read_bytes readable slice by slice. `path` mode only.

    • line_tointeger· uint64min 1

      Last line of the window, 1-based inclusive, >= `line_from`; omit to read from `line_from` to EOF. `path` mode only.

    • max_output_bytesinteger· uint64min 0

      Full-read byte budget (returned bytes, clamped to max_read_bytes); over budget fails C218 naming size/total_lines. C210 with a window.

    • numberedboolean

      Prefix each line with its absolute 1-based file line number (`N→`), matching coder::update-file line ops; C210 with `stat`. `path` mode only.

    • pathstring

      Single file to read; XOR with `paths` (C210 if both or neither is set).

    • pathsany of[]

      Batch of files to read in one call (bare path strings or window objects), processed in order against batch_read_budget_bytes; XOR with `path`.

      any of (2)
      Variant 1
      valuestring
      Variant 2
      • line_frominteger· uint64min 1

        First line of the window, 1-based inclusive (>= 1); defaults to 1 when only `line_to` is set.

      • line_tointeger· uint64min 1

        Last line of the window, 1-based inclusive, >= `line_from`; omit to read to EOF.

      • numberedboolean

        Prefix this entry's lines with their absolute 1-based line numbers (`N→`); prefix bytes count toward the batch budget.

      • pathstringrequired

        File to read.

      • statboolean

        Metadata probe for this entry: size/mode/mtime plus total_lines, content null, no budget consumed; C210 with a window or `numbered`.

    • statboolean

      Metadata probe: size/mode/mtime plus total_lines/is_utf8, no content; C210 with line_from/line_to/numbered/max_output_bytes.

    response
    • contentstring

      File content as a UTF-8 string — the whole file, or just the requested window when `line_from`/`line_to` was given (window lines keep their newline terminators). Binary content is returned with invalid bytes replaced by U+FFFD; request `encoding: "base64"` when exact bytes matter (content is then the file's bytes base64-encoded). **Single-path mode only; null when the request used `paths[]`.**

    • is_utf8boolean

      Whether `content` survived UTF-8 conversion without losing bytes. Reflects the RETURNED content only: a clean window inside an otherwise-binary file is still `true`. **Single-path mode only; null when the request used `paths[]`.**

    • lines_returnedinteger· uint64min 0

      Number of lines in `content`. For full reads this equals the file's total line count. **Single-path mode only; null when the request used `paths[]`.**

    • modeinteger· uint32min 0

      Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. **Single-path mode only; null when the request used `paths[]`.**

    • more_linesboolean

      True when the file has content beyond what `content` includes: the window ended before EOF, or the byte budget cut the window short. Always false for full reads. **Single-path mode only; null when the request used `paths[]`.**

    • mtimeinteger· int64

      Last-modified time as a Unix epoch in seconds. **Single-path mode only; null when the request used `paths[]`.**

    • pathstring

      Canonical absolute path of the file read (resolved through the jail). **Single-path mode only; null when the request used `paths[]`.**

    • resultsobject[]

      Per-entry results for a batch `paths[]` request. **Present only when the request used `paths[]`; null in single-path mode.**

      • contentstring

        File content as a UTF-8 string — the whole file or the requested window. Binary bytes are replaced by U+FFFD (`is_utf8: false`). `null` on failure.

      • errorany of

        Structured error — present only when `success: false`.

        any of (2)
        Variant 1
        • codestringrequired

          Stable error code, e.g. "C211". See the README error table.

        • messagestringrequired

          Human/LLM-readable message: problem + actual values + corrective next call.

        Variant 2
        valuenull
      • is_utf8boolean

        Whether `content` survived UTF-8 conversion without losing bytes. `null` on failure.

      • lines_returnedinteger· uint64min 0

        Number of lines returned in `content`. `null` on failure.

      • modeinteger· uint32min 0

        Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. `null` on failure.

      • more_linesboolean

        `true` when the file has content beyond what `content` includes (window ended before EOF, or byte budget cut the window short). `null` on failure.

      • mtimeinteger· int64

        Last-modified time as a Unix epoch in seconds. `null` on failure.

      • pathstringrequired

        Canonical absolute path of the file (resolved through the jail). If resolution failed, this echoes the caller's input verbatim.

      • sizeinteger· uint64min 0

        Size of the FILE in bytes (from metadata). `null` on failure or when the entry budget was exhausted before the file was opened.

      • successbooleanrequired

        `true` when the read succeeded (content/metadata fields are populated); `false` when an error occurred (only `error` is set).

      • total_linesinteger· uint64min 0

        Total lines in the file; present when the stream reached EOF during this entry's read. `null` when not traversed or on failure.

    • revisionstring

      Opaque identity of the file's exact bytes. Present for complete single-path reads only; pass it as `expected_revision` to `coder::create-file` for a conflict-safe whole-file overwrite.

    • sizeinteger· uint64min 0

      Size of the FILE in bytes (from metadata) — not the size of `content`; in windowed mode the two differ. **Single-path mode only; null when the request used `paths[]`.**

    • total_linesinteger· uint64min 0

      Total number of lines in the file. Present only when the read traversed the whole file: always for full reads; for windowed reads only when the stream naturally reached EOF within the byte cap. Never computed by forcing an extra full scan — absent means the file was not fully traversed. **Single-path mode only; null when the request used `paths[]`.**

  • shell::exec_bgidev0.13.7Schema

    Spawn a background job; returns { job_id, argv } immediately. Accepts the shell::exec payload plus optional job_id. Observe shell::on-job-finished with args { job_id } naming a fresh job_id before calling exec_bg with that same ID, or omit job_id to generate one. Duplicate retained IDs reject before execution. Host jobs ignore timeout_ms and use the configured background hard cap; read output with shell::status, list jobs with shell::list. Jobs have no terminal: a command that needs one fails, and a job that stays stopped is killed. Spawn-time failures are plain-string messages; later failures call shell::on-job-finished and appear in shell::status.

    request
    • argsstring[]

      Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.

    • commandstringrequired

      Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.

    • cwdstring

      Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.

    • envobject

      Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.

    • job_idstringmin 1 chars

      Optional non-blank ID for observing shell::on-job-finished before execution. Must be unique among retained jobs in this worker. Omit or pass null to generate a job-UUID automatically.

    • stdinstring

      Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.

    • targetall of

      Where to run: the host (default) or { kind: "sandbox", sandbox_id }.

      all of (1)
      Variant 1
      one of (2)
      Variant 1
      • kindstringrequiredenum host
      Variant 2
      • kindstringrequiredenum sandbox
      • sandbox_idstring· uuidrequired
    • timeout_msinteger· uint64min 0

      Per-call timeout in milliseconds; ignored by host background jobs, forwarded to sandbox targets.

    response
    • argvstring[]required
    • job_idstringrequired
  • shell::statusidev0.13.7Schema

    Fetch the full record (status, exit_code, timing, output) of a background job by job_id. A running host job shows the last 8 KiB of each stream, flagged truncated when there is more. Errors return { code, message }; common: S211 no such job.

    request
    • job_idstringrequired
    response
    • jobobjectrequired
      • argvstring[]required
      • exit_codeinteger· int32
      • finished_at_msinteger· uint64min 0
      • idstringrequired
      • started_at_msinteger· uint64requiredmin 0
      • statusstringrequiredenum running, finished, killed, failed
      • stderrstringrequired
      • stderr_truncatedbooleanrequired
      • stdoutstringrequired
      • stdout_truncatedbooleanrequired
  • shell::killidev0.13.7Schema

    Terminate a running background job by job_id (returned by shell::exec_bg). Errors return { code, message }; common: S211 no such job, S216 kill/signal delivery failure.

    request
    • job_idstringrequired
    response
    • job_idstringrequired
    • killedbooleanrequired
    • reasonstring
    • statusstringrequiredenum running, finished, killed, failed
  • harness::observeharnessv1.9.14Schema

    Observe a function for the current harness session: each time it runs, omit `target` to be notified in this session with what it returned, or name a non-harness `target.function_id` to call with it. Pass the function's `args` when it takes them and `filters` on its `input.<field>` to choose calls. Set `lifecycle.expires_in_ms` on every wake except a timer, to how long the work should take; a one-shot wake without it expires after 10 minutes with a notice. Returns `{ observer_id, once }`; a `note` is advice about the observer, which was created either way. Call-target results are discarded and do not return to this session.

    request
    • actionstring

      User-facing text saying what happened, shown with each delivery.

    • argsobject

      Args for the worker that hosts the function, a JSON object; its description says which it takes: cron `{ "expression" }`, database `{ "db", "table"?, "ops"? }`, `harness::on-timer` `{ "in_ms" }` or `{ "at" }` (epoch ms). Omit for a function that takes none.

    • conditionsobject[]

      Delivery-time gates, in order; each is an iii function answering `{ decision: "allow" | "skip", payload?, reason? }`.

      • configunknown

        Passed to the condition function AS its `condition_config`: give its fields (e.g. `id`, `expect`) directly, not wrapped in `condition_config`.

      • function_idstringrequired
    • filtersobject

      Which calls reach this observer, a JSON object of explicit operators on the call's fields: `{ "input.scope": { "$eq": "run" } }`.

    • function_idstringrequired

      The function to observe: `state::on-changed`, `cron::on-tick`, `harness::on-timer`, `database::on-row-changed`, or any other function. What it returns is the event.

    • labelstring

      A short human label echoed back in the notification text.

    • lifecycleany of

      When the observer stops delivering; top-level `once` is the shorthand.

      any of (2)
      Variant 1
      • expires_in_msinteger· int64

        Relative deadline: the observer stops this many milliseconds after it was created (the only deadline form). Set it on every wake except a timer, to how long the work should take: if nothing fires by then, the session is woken with a notice. A one-shot wake without it expires after 10 minutes.

      • max_firesinteger· uint64min 0

        Lifetime delivery budget; the observer is removed on its Nth delivery.

      • onceboolean

        Remove the observer after its first delivery (same as top-level `once`).

      Variant 2
      valuenull
    • namespacestring

      Where the function is hosted; omitted: this harness's namespace, then `default`, then Compose's.

    • onceboolean

      Remove the observer after its first delivery; defaults to true for a wake (no `target`) and `harness::on-timer`, false for a call target and `cron::on-tick`.

    • targetany of

      The function called with each event: `{ function_id, payload?, event_into? }` — the fixed payload and the JSON pointer where the event is injected into it (default `/event`). Omit it to be notified in this session instead. `harness::spawn` is never a valid target.

      any of (2)
      Variant 1
      • event_intostring

        JSON pointer where the event lands inside the payload (default `/event`).

      • function_idstringrequired
      • payloadunknown

        Payload template; the delivered event is injected into it at `event_into`.

      Variant 2
      valuenull
    response
    • notestring

      Advisory only — the observer was CREATED. Says what applied by default or what looks suspicious in its wiring (e.g. a filter naming a key someone already wrote). Read it and act on it if it applies.

    • observer_idstringrequired
    • oncebooleanrequired

      The effective `once` flag applied (after the per-function default).

  • workflow-result::submitworkflowv0.3.5Schema

    Deliver this workflow node's result: call it once with {"result": <the JSON value your node's output schema requires>}. An error names what to fix: call it again. Once it is accepted, end your turn with one short line, not the JSON. The node is finished once the turn ends: submit last. Only a workflow node's own session can call it.

    request
    • caller_session_idstring

      Stamped from the calling session by the workflow's pre-call hook; a supplied value is overwritten.

    • resultunknownrequired

      The node's result: the JSON value its output schema requires.

    response
    • acceptedbooleanrequired
    • nodestringrequired

      The node uid the result was stored for.

System prompt

5,065 bytes
agents/workflow-worker.md

Workflow Worker

You are one node of a workflow run the workflow kit started. You do exactly the task in your opening message, answer with one result document, and stop. Nobody reads your chat text: the result document is the only thing the orchestrator sees. Write every field of it in English, whatever language the files or the ticket use: it goes on the board.

Decide routine details with the simplest in-scope reversible default and note material assumptions in evidence; do not block on naming, layout or test selection. Scope, acceptance, permission boundaries and human-only questions stay binding.

  1. Read first. When the task carries a Card: block, that is your card and there is no ticket to read. Otherwise, when the task names a ticket, call kanban::ticket::get on it before any other work, even on a retry: comments added since the last attempt steer this one. The description is the brief; comments by authors other than workflow are human notes and count as requirements. If the read fails, answer failed with summary ticket read failed: <error>.
  2. Retry. When the opening message carries loop_previous, it is the verdict that rejected your last attempt: every entry of its reasons must be fixed in this one. own_previous is the result document of that attempt: start from it and keep what the verdict did not reject, instead of redoing the work. A Retry: line in the task carries the reasons of an earlier round. The newest wins.
  3. Scope. Do only what the card's opening sentence and Acceptance ask; its Out of scope bullet is binding. A question only a human can answer is blocked with question, never half the work. A missing input that another ticket produces is failed with summary waiting for <KEY>. A denied call you need is blocked with question: "allow <function id>".
  4. Result document. Deliver it as your opening message says (workflow-result::submit with {"result": <the object>}), then end your turn with one short line; never paste the object into your reply. The object has:
    • status: done, blocked or failed.
    • summary: at most 60 words; say what you did NOT verify.
    • result: the work the card's opening sentence asks for, as text (markdown is fine), shaped by its Result bullet when it has one; empty when not done. In Mode: work, every claim in it cites where the fact comes from, inline: <file>:<line>, a URL you opened, the command and what it printed, or [KEY] for an input the task gives. Cite the original (the code, the project's own documents, official documentation or a specification, a command you ran, the task's input), never a summary of it written elsewhere. Mark a claim you cannot source (unsourced).
    • evidence: one line per check, <check>: <observed>.
    • new_items: work the goal still needs that no ticket covers, {title, card, after}: card is a full card in the run's card format: a one-sentence summary; in a code task, then ## Change with Files, Implement, Tests and Commit bullets; then ## Acceptance with - [ ] items, each with its Verify: call; then ## Scope. after lists titles or ticket keys whose output it needs. Prefer one item over several, and none over a small one: a fix inside your own task is yours to make. A Discover: card's list is its result: give the items it asks for. At most the count the task allows.
    • loose_ends: what you noticed and the goal does not need, one line each, <file>:<line>: <what>. A bug in code this run changed is never a loose end: fix it, or report it as a new item. Neither is a check you could not run (a missing tool, a denied call): say it in summary.
    • question: only when blocked. Put long evidence in a file and give its path.
  5. Rules. Never write tickets or comments: the orchestrator owns the board. Finish before the Deadline in your task; when the work cannot finish by then, answer failed with the reason instead of starting it. A command over ~90 s runs as a long run: follow the recipe in your Functions line, and kill any job of yours still running before you answer. Call shell::exec as {command, args[]}; never put a whole shell line in command. With a Worktree: in your task, work only inside it and never run git push, merge, rebase, reset, checkout, switch, stash, clean, restore, revert, tag, worktree, branch or rm -r. Ignore guidance to use the workflow worker and the claim, done-watch and cron steps in kanban/tickets/*.

Search the registry

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