Workflows

A workflow is the orchestration layer: an ordered, declarative plan that routes one request through several agents — some in sequence, some in parallel — and defines what "done" means. Workflows are the core differentiator: the engine produces a deterministic execution plan from YAML, with no model calls and no orchestration server.

On-disk layout

kits/<kit>/workflows/<name>.yaml     one single file per workflow

Workflow reference

name: feature-development # required, kebab-case
description: Full feature implementation workflow # required, <= 500 chars
version: 1 # required, positive integer
tags: # optional, defaults to []
  - feature
steps: # optional, defaults to []
  - agent: tech-lead # sequential step
  - parallel: # concurrent group (never empty)
      - agent: backend-architect
        skills: # optional per-step skills
          - postgres
      - agent: frontend-specialist
  - agent: test-automator
  - agent: security-auditor
  - agent: code-reviewer
  - agent: shipper

Step shapes (a step is exactly one of these, and the loader says so in its error):

• Agent step: { agent: <name>, skills?: [<skill>, ...] } — runs next in order; the named skills are preserved into the plan for that step.
• Parallel group: { parallel: [agent step, ...] } — at least one agent; all members run concurrently after the previous step.

Validation happens in layers:

1. Schema (load time): shapes, names, unknown keys.
2. Loader (cross-artifact): every referenced agent and skill must exist — unknown workflow agents/skills are errors, as are duplicate artifact names.
3. Quality (agentkrew validate): circular references in the kit reference graph are reported deterministically.

From YAML to an execution plan

The engine compiles steps into a plan whose JSON form mirrors the YAML structure:

{
  "workflow": "feature-development",
  "steps": [
    { "agent": "tech-lead" },
    {
      "parallel": [
        "backend-architect",
        "frontend-specialist",
        "database-specialist"
      ]
    },
    { "agent": "test-automator" },
    { "agent": "security-auditor" },
    { "agent": "code-reviewer" },
    { "agent": "shipper" }
  ]
}

Same kit version + same configuration → same plan, byte for byte. Per-step skills travel with their step rather than being flattened away.

How workflows run in a runtime

No supported runtime has a native "workflow" object, so the adapter renders the plan where the runtime can execute it:

• The plan is embedded verbatim in every generated command and workflow file ("Step 1: tech-lead / Step 2 (parallel): …"), so the session executes it as ordinary agent delegation — sequential steps in order, parallel groups spawned together.
• Each workflow also renders as a standalone invocable entry: .claude/skills/workflow-<name>/SKILL.md (/workflow-<name>), .opencode/commands/workflow-<name>.md (/workflow-<name>), or .agents/skills/workflow-<name>/SKILL.md on Codex ($workflow-<name>).
• The engine itself never calls a model — orchestration happens inside your runtime session, driven by the embedded plan.

Inspecting workflows

agentkrew list workflows --installed
agentkrew info feature-development --installed        # step count
agentkrew info feature-development --installed --json # full steps

--json prints the parsed steps structure exactly as the engine sees it.

Shipped workflows

Engineer Kit (3):

Cross-kit workflows (3, in kits/cross-kit): product-launch, feature-launch, and marketing-campaign sequence Engineer and Marketing agents in one plan (for example: plan → competitive analysis → brand → parallel build → verify → content → SEO → launch). The cross-kit kit declares requires: [engineer, marketing], so installing it pulls both kits; both teams read the same AGENTKREW.md.

agentkrew list workflows --installed is the live source of truth.

Creating a custom workflow

1. Source checkout (contributor): create kits/<kit>/workflows/<name>.yaml following the reference above. Every referenced agent must exist in the kit (or a required kit) — the loader rejects dangling references. Validate with agentkrew validate --kit <kit>.
2. Installed project: workflows are a source-level concept; in an installed project, add the equivalent plan as a command or workflow-shaped prompt file for your runtime (see commands), then verify with agentkrew validate --installed.

Keep workflows deterministic: name the steps, do not embed prompts, and let agents own the thinking. See customization for the full authoring workflow.