---
name: kanban-workflow
description: "Kanban multi-agent workflow: orchestrator decomposition, worker execution, and Codex CLI integration lane."
version: 2.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [kanban, multi-agent, orchestration, worker, codex, worktrees, routing]
    related_skills: [development-workflow, hermes-agent]
---

# Kanban Multi-Agent Workflow

Three roles in a Kanban-driven multi-agent system: **orchestrator** (decompose & route), **worker** (execute & hand off), and **Codex lane** (bounded implementation help inside a worker's run).

The core worker lifecycle (`kanban_show` → work → `kanban_heartbeat` → `kanban_complete`/`kanban_block`) is auto-injected into every worker's system prompt as `KANBAN_GUIDANCE`. This skill provides the deeper detail for each role.

## Section 1: Orchestrator Playbook

### When to Use the Board (vs. just doing the work)
- Multiple specialists needed
- Work should survive crash/restart
- Human-in-the-loop needed
- Parallel subtasks
- Review/iteration expected
- Audit trail matters

Otherwise: use `delegate_task` or answer directly.

### Step 0: Discover Available Profiles
Before fanning out, discover what profiles exist (`hermes profile list`). The dispatcher silently fails to spawn unknown names.

### Decomposition Playbook
1. **Understand the goal** — ask clarifying questions if ambiguous
2. **Sketch the task graph** — extract lanes, map to profiles, decide dependencies
3. **Create tasks and link** — use `parents=[...]` for dependencies; independent lanes run in parallel
4. **Complete your own task** — summarize what you created
5. **Report back** — plain prose with actual profile names

### Anti-Temptation Rules
- Do NOT execute the work yourself
- Split multi-lane requests before creating cards
- Run independent lanes in parallel (no parent links)
- Never create dependent work as independent ready cards
- If no specialist fits, ask the user — don't invent profile names

### Goal-Mode Cards
For open-ended tasks, pass `goal_mode=True` to wrap workers in a Ralph-style goal loop. Write body as explicit acceptance criteria.

### Recovering Stuck Workers
**Reclaim** — abort and reset to ready. **Reassign** — switch profile. **Change model** — edit profile config.

See `references/kanban-orchestrator.md` for full decomposition examples, pitfalls, and notification routing.

---

## Section 2: Worker Pitfalls & Examples

### Workspace Handling
| Kind | Behavior |
|------|----------|
| `scratch` | Fresh tmp dir, read/write freely, GC'd on archive |
| `dir:<path>` | Shared persistent directory, other runs will read |
| `worktree` | Git worktree, commit work here |

### Good Handoff Shapes
- **Coding task:** `kanban_complete(summary="...", metadata={"changed_files": [...], "tests_run": N, ...})`
- **Research task:** `kanban_complete(summary="...", metadata={"sources_read": N, "recommendation": "..."})`
- **Review task:** `kanban_complete(summary="...", metadata={"pr_number": N, "approved": False, "findings": [...]})`

### Block Reasons That Get Answered Fast
Good: one sentence naming the specific decision. Bad: `"stuck"`. Leave longer context as a comment.

### Claiming Created Cards
Only list ids from successful `kanban_create` return values. Phantom ids block completion. The prose-scan also catches `t_<hex>` references that don't resolve.

### DO NOT
- Call `delegate_task` as substitute for `kanban_create`
- Call `clarify` (headless, no user to answer) — use `kanban_comment` + `kanban_block`
- Modify files outside `$HERMES_KANBAN_WORKSPACE`
- Complete a task you didn't finish — block it instead

See `references/kanban-worker.md` for retry diagnostics, heartbeat patterns, and CLI fallback reference.

---

## Section 3: Codex Lane (Worker + Codex CLI)

Use when: task is coding/refactor with clear acceptance criteria, a bounded diff can be evaluated, repo can be isolated in a worktree.

### Ownership Rules
1. Hermes owns the Kanban lifecycle — Codex must never call `kanban_complete`
2. Hermes owns final acceptance — Codex output is untrusted until reviewed
3. Hermes owns test execution — Codex tests are advisory
4. Hermes owns safety — reject if Codex changes safety boundaries
5. Hermes owns cleanup — kill stuck processes and remove worktrees

### Required Worktree Pattern
```bash
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"
git worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
```

### Mode Selection
- `codex exec --full-auto` for bounded one-shot edits
- Codex `/goal` for broader multi-step work

### Prompt Construction
Every Codex prompt must include: task_id, acceptance criteria, repo/worktree/branch paths, ownership statement, required output format, prohibited actions, verification commands.

### Reconciliation Checklist
- [ ] `git diff --stat` reviewed by Hermes
- [ ] No secrets/credentials/unrelated data
- [ ] PMB safety constraints preserved (when applicable)
- [ ] Hermes ran canonical tests independently
- [ ] Accepted commits applied to Hermes-owned branch
- [ ] Temporary processes and worktrees cleaned up

### Metadata Schema
Include `metadata.codex_lane` with: `used`, `mode`, `worktree`, `branch`, `result`, `accepted_commits`, `rejected_reason`.

See `references/kanban-codex-lane.md` for full prompt template, monitoring patterns, and PMB safety constraints.