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