Workflows

Some work is too structured for one agent turn and too branching for a single Task Runner spec. A workflow is an authored Python script that orchestrates many agents through explicit stages, running them in parallel, chaining their output, and checking results before moving on.

You rarely write one by hand: describe the goal in plain English and the agent usually authors the script for you.

Reach for a workflow when the shape of the work matters as much as the work itself:

For a single autonomous run from a spec, use the Task Runner. For ad-hoc parallelism inside a conversation, use Subagents. Workflows are for when you need repeatable structure across many agents.

The fastest way to a workflow is to describe the outcome and let the agent write the script:

"Write a workflow that takes every markdown file in docs/, has one agent summarize each in parallel, then a second agent merges the summaries into a single index."

The agent produces a Python script that composes the stages. Read it, adjust it, and run it. Because it's plain Python, you can version it, share it, and re-run it whenever the inputs change.

session_send delivers a message into another session as its next turn. A coordinator agent can direct peer sessions instead of only opening, reading, or stopping them. This is the primitive underlying the conductor and any cross-session orchestration pattern you build yourself.

The conductor agent handles goals too large for a single session:

1. It decomposes the goal into discrete work items
2. It starts a session for each item
3. It checks acceptance criteria for each completed session
4. It decides the next round based on results: sending follow-ups, retrying, or finishing

The conductor runs on a monitoring loop that survives tab closes and turn caps, so a long multi-session plan keeps going while you're away.

Invoke the conductor from any session by describing a goal that naturally splits into parallel work streams.

Promote a session's workflow definition into the global library for reuse across sessions:

• Manage versions and lineage from Agent Capabilities → Workflows
• Invoke a saved definition with /workflow <name> in any session
• Task Runner plans share the same library, so a plan you've used before is available as a named workflow

Workflows in the library are versioned. You can view revision history and roll back to an earlier version.

A chat turn can run for up to four hours. For work that runs longer, use a monitor loop or Task Runner so Crew can continue between turns. See Configuration for the timeout settings.

An agent can start, revise, inspect, and stop a monitor loop bound to its own session. Plain timer loops (monitor_start) work from dashboard chat, Slack, Discord, and Webex. The goal chip shows the active cadence and budget so a loop that is waiting does not look like an ordinary running turn.

A loop can carry two short rules: what should wake the session and what should remain quiet. A quiet verdict writes a small notice into the chat and spends no model turn. A loop armed with gate=false is never screened because it is meant to act while its subject is quiet.

When a loop supplies no rules, open Quiet check-ins: wake or skip under Settings → Developer → Feature Previews → Decisions (Jev). Enable Also send what a watching loop has found so Jev can skip a turn to let the configured judge inspect watched session text and typed pull request facts. Without that consent, the loop runs as a plain timer.

The operator ceiling monitoring.max_runtime_secs defaults to seven days and can be raised to thirty days. Raising it does not extend a deadline already set on a running loop.

Use monitor_watch when the goal is to reach a review-ready pull request. Provider probes run without an agent turn while nothing actionable changes, then wake the owning session with a bounded summary. Reviews and comments that request a change or ask a question count as actionable, not only failed checks. A merged or closed pull request ends the watch.

Paste the canonical pull request URL into Watch a pull request. Azure DevOps Server and Bitbucket Data Center are not supported. Azure DevOps and private Bitbucket watches must be started from a dashboard conversation because they rely on owner-scoped credentials.

monitor_watch is available from dashboard, Slack, and Discord sessions. Webex sessions can arm a plain timer loop with monitor_start but not a structured pull request watch, because structured wake delivery has no Webex route.

Use monitor_stop to end a structured watch; monitor_inspect reads its current state. Both monitor_stop and monitor_inspect work across pull request watches, workflow watches, and plain timer loops from monitor_start.

A structured watch retires when its subject reaches a terminal state or its budget is exhausted. The interrupt controller can also turn an eligible polling cron into a wake-on-change interrupt, so quiet intervals do not spend agent turns.

Accepted workflow agent calls use the same durable task queue as subagents and Task Runner steps. Queued calls survive a Gateway restart and resume scheduling after startup. Workflow run state and completed agent results remain available from the Workflows surface.

Under the hood, a workflow coordinates the same background agents you can spawn yourself. Each stage can fan out to subagents, wait for their results, and pass a synthesized output to the next stage. The workflow script owns the structure: which stages run, in what order, and what "done" means. Each agent does the work.

The bundled Workflows app provides a dashboard surface to author, validate, and watch workflow runs. It ships disabled and hidden from the main app catalog by default.

Enable it from the CLI:

kirocrew app enable workflows

Once enabled, the app appears in the sidebar at /workflows and lets you validate a workflow script against the sandboxed API before anything runs, then watch each phase and per-agent event as the run progresses. Runnable examples are included to start from.

• Subagents: parallel background agents a workflow coordinates
• Task Runner: single-spec autonomous execution with checkpoints and self-review