Feature Description

Document and support a first-class architecture pattern for specialist worker lanes under Hermes Kanban orchestration.

The Codex worker lane in #19924 is one concrete example, but the architecture should generalize to other implementation specialists:

• Codex CLI worker
• Claude Code worker
• OpenCode worker
• local coding-model worker
• review/lint/test workers

Motivation

Hermes should remain the top-level orchestrator. Specialist tools should not become parallel orchestrators with their own task lifecycle, status system, or shadow planning board.

The desired hierarchy is:

Hermes Kanban = canonical task lifecycle and logs
Specialist worker = implementation executor for one assigned card
GitHub PR = upstreamable code artifact
Human/review worker = final quality gate before done

This prevents duplicated control planes and makes worker output auditable.

Proposed Architecture

Worker lanes should follow these rules:

1. Hermes Kanban owns lifecycle state.

   • ready → running → blocked/done/cancelled
   • Workers do not own task truth.

2. Code-changing workers should not auto-promote successful exits to done.

   • Success should normally transition to blocked with reason review-required.
   • A separate human/review lane decides whether work becomes done.

3. Worker logs should be stored under the Kanban root.

   • Example: <root>/kanban/logs/t_<id>.log
   • Logs should include command, workspace, exit code, and summary.

4. Workers should be non-interactive and sandboxed.

   • Example policy for CLI coding workers: workspace-write, no approval prompts.
   • Worker environment should be pinned to the card workspace/board.

5. Assignee routing should be explicit.

   • Example assignees: codex, codex-worker, claude-code, opencode.
   • Unknown assignees should not silently invoke arbitrary shell commands.

6. Worker outputs should be reviewable artifacts.

   • Git diff
   • tests run
   • logs
   • status metadata

Phased Build Plan

Phase 1: Codex worker lane

• Land feat: add Codex Kanban worker lane #19924.
• Validate routing, logs, workspace pinning, and review-required status mapping.

Phase 2: Architecture docs

• Add a docs page or contributor guide section explaining worker lane semantics.
• Include expected status transitions and safety rules.

Phase 3: General worker interface

• Factor common runner behavior if/when a second worker lane lands.
• Keep the initial implementation concrete until duplication appears.

Phase 4: Optional dashboard visibility

• Show worker type, log path, exit status, review-required reason, and linked PR.

Alternatives Considered

Parallel worker-specific task systems

Rejected. This creates shadow infrastructure and makes it unclear whether GitHub, a worker CLI, or Hermes owns task state.

Auto-mark successful workers as done

Rejected for code changes. Passing worker execution is not equivalent to reviewed, mergeable work.

Acceptance Criteria

• There is a documented worker lane contract.
• At least one implementation follows it (feat: add Codex Kanban worker lane #19924 or successor).
• Code-changing workers transition successful completion to review-required rather than done.
• Logs and workspace pins are auditable from Kanban metadata.
• The pattern is explicit enough that future Claude/OpenCode/local-model workers can follow it without inventing a parallel lifecycle.