Add devops/kanban-workflow
This commit is contained in:
@@ -0,0 +1,125 @@
|
|||||||
|
---
|
||||||
|
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.
|
||||||
Reference in New Issue
Block a user