Kanban Workflows

Overview

Use this umbrella for Hermes Kanban work regardless of whether the current agent is acting as the orchestrator or as a worker. The old orchestrator/worker split encoded two roles of the same class-level workflow; keeping them together makes it easier to load the right lifecycle and avoid role confusion.

When to Use

• The user asks to coordinate a multi-step effort through Kanban.
• You are operating under a Kanban orchestrator profile.
• You are a worker assigned a Kanban ticket and need lifecycle/pitfall guidance.
• Work requires decomposition, ticket updates, acceptance criteria, or handoff notes.

Don't use this for a normal one-agent todo list; use the session todo tool unless a real Kanban board/workflow is in scope.

Route before creating work

Do not use delegate_task for work whose result must outlive the parent process. Do not use Kanban for a quick lookup or one-agent session todo.

Retry-safe task creation

Confirm the installed Kanban tool schema or documented CLI/API supports the fields below before dispatch. This skill does not add runtime capabilities; do not invent equivalent flags or silently omit a required safety constraint. If a required capability is missing, keep the work undispatched and report the compatibility blocker to its owner.

• Discover real profile names before assignment; never invent an assignee.
• Supply a stable idempotency_key for any task creation that may be retried. Reuse the same key after transport uncertainty so the kernel returns the existing non-archived task instead of creating a duplicate.
• Set max_runtime_seconds for bounded workers.
• Agent tool-created tasks use configured kanban.failure_limit; operators using the CLI/API may additionally set per-task max_retries. After repeated failure, block for review or reassign; never respawn the same unchanged task indefinitely.
• Create parent cards first and pass parents=[...] when creating children. Do not create children as ready and link them afterward.

Workspace durability

Never place the only copy of an irreplaceable result in a scratch workspace.

Structured handoff metadata

Every completion or review-required block must name:

• artifact paths or URLs;
• files changed;
• commands/tests and actual outcomes;
• decisions and unresolved risks;
• parent inputs consumed and child tasks created;
• the exact next action.

For code changes requiring human review, comment the structured handoff and block with a review-required: reason instead of marking terminal completion.

Routed HITL notification gate

Any transition to blocked with review-required or needs_input is a human-in-the-loop (HITL) routing event, not a silent terminal state. These labels describe workflow reasons; they do not imply additional runtime statuses, commands or notification features.

The assigning/orchestrating profile must immediately:

1. persist the worker's structured handoff on the card;
2. deliver a user-visible notice to the originating chat or explicitly agreed notification destination, naming the board, task/run, completed evidence, blocker, gate owner and exact supported audit command;
3. present selectable approve/reject/revise choices for a human-owned gate when the interface supports them, otherwise request an explicit recorded approve/reject/revise response;
4. keep the card blocked until the recorded owner processes the gate.

Use only an authorized notification route. If delivery or owner routing is unavailable, record and surface that blocker through the available authorized channel; do not claim that the gate was surfaced or release the card. A terminal-event subscription is transport assistance, not proof of notice. The assigning profile remains responsible for delivery and must not leave the user to discover blocked work through /agents or manual CLI inspection.

Record one explicit gate owner and its admitted authority in the task/handoff:

• Technical review delegated to the assigning profile: notify the requesting user immediately. Only within explicitly granted review authority may the profile inspect the artifact, rerun evidence and accept or request bounded repair. Review ownership does not itself authorize a commit, merge, VM start, paid/model/network call, deployment, publication or any other owner-controlled action beyond existing permission and admission gates.
• User or designated human approver: notify and remain paused. Proceed only according to that owner's recorded approve, reject or revise decision and only within the resulting approved scope.
• Another profile/role: notify the requesting user, route the task to the recorded owner through an authorized channel and remain blocked until a verifiable decision returns.

When technical review discovers a new authority, product or safety decision, route ownership to the responsible human approver and keep the card blocked. If that owner is not established, ask rather than assume permission. Reuse the same task ID and idempotent operation when applying the decision; do not create duplicate retry cards merely to clear a gate.

Orchestrator Mode

The orchestrator owns the user outcome, causal diagnosis, routing and integration — not only queue administration.

1. Preserve the goal: keep the accepted user outcome, current blocker and each task's contribution in the existing task body with scope and acceptance evidence.
2. Choose meaningful work units: use bounded, independently useful tasks, not a ticket for every procedural operation. Supporting machinery needs a concrete outcome/safety justification; agent-created dependencies alone do not establish necessity.
3. Review relevance before dispatch: verify original evidence and actual interfaces, then assess whether the proposed work removes the blocker. Do not delegate an incomplete diagnosis as an instruction to build more infrastructure.
4. Continue within authority: resolve technical issues within existing permission, preserve valid work and surface real new gates. Do not invent substitute work when the critical path is permission-blocked or fragment one coherent approval into routine micro-handoffs.
5. Verify the outcome: independently check artifacts and actual results; distinguish a completed child, a removed parent blocker and delivery of the user outcome.

Keep one implementation owner per overlapping source cluster; do not secretly duplicate worker changes. This does not excuse the parent from necessary diagnosis or substantive review. Existing safety, retry and HITL rules remain unchanged.

Worker Mode

The worker's job is to complete the assigned ticket and make the next state obvious.

1. Read the parent user outcome as well as the ticket, original evidence and acceptance criteria.
2. Resolve discoverable facts; ask only for a consequential missing decision. If the task does not advance the parent outcome, report that mismatch before expanding it.
3. Keep changes within scope and use existing tools/evidence where sufficient. Report adjacent work; do not silently create a new infrastructure project or grant yourself follow-up authority.
4. Report what changed for the parent blocker, with actual verification and remaining limits. Files touched and local tests are supporting evidence, not the user outcome by themselves.
5. Preserve valid successes and hand off the exact remainder. A child completion must not imply full project completion.

Status Update Template

Status: in_progress | blocked | ready_for_review | done
User outcome: <accepted parent goal; do not substitute the ticket title>
Contribution: <current blocker removed or advanced, with remaining gap>
Changes/verification: <scoped changes, actual results and evidence handles>
Blocker/next action: <remaining fact, permission or work; explicit owner>

The template is a reporting format, not a promise that every label is a native board status. Review-required work remains blocked until its gate is processed; use only supported runtime transitions.

Common Pitfalls

1. Role bleed. Orchestrators duplicate worker implementation or avoid substantive review; workers redesign the plan. Preserve ownership without abandoning diagnosis or outcome verification.
2. Ticket vagueness. A ticket without an artifact and verification step is not ready.
3. Silent blockers. Report blocked status with the exact missing input or failing command.
4. Unverified done. A task is not done just because files changed.
5. Board drift. Keep ticket state synchronized with actual work so other agents do not duplicate effort.
6. Duplicate cards after uncertain create. Reuse a stable idempotency key.
7. Infinite respawn. Respect runtime/retry circuit breakers and block for review.
8. Ephemeral-only handoff. Move durable artifacts out of scratch before completion.

Verification Checklist

• Every active ticket has an owner, artifact, and verification step.
• Blockers are explicit and routed to the right owner.
• Review/input gates have recorded ownership, user-visible notice and a verifiable decision before work resumes.
• Completed work was checked by command output or artifact inspection.
• Child completion, parent blocker removal and delivery of the user outcome are distinguished.
• Handoffs are detailed enough for continuation without transcript archaeology.