atomk-hermes-skills/skills/devops/kanban-workflow/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
kanban-workflow	Kanban multi-agent workflow: orchestrator decomposition, worker execution, and Codex CLI integration lane.	2.0.0	Hermes Agent	MIT	linux macos windows	hermes tags related_skills kanban multi-agent orchestration worker codex worktrees routing 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

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.