[RFC] Matrix Coder Plugin — OMC-style specialist agent bundle for Hermes

[Interstellar-code]

Matrix Coder Plugin — Specialist agent bundle for Hermes (inspired by OMC + OMX + OmO)

Context

This is a feature request, not a bug — proposing a new plugin in ~/.hermes/hermes-agent/plugins/matrix_coder/.

Clarified intent: Matrix Coder is not a fleet, workflow-engine, or Kanban feature. It should not be framed as an adjunct to those systems. Matrix Coder is a plugin that enables the Hermes agent itself to become a specialist coder: a coding-focused plugin harness with specialist personas, dedicated skills, efficient helper scripts, and deep awareness of Hermes' existing coding capabilities.

The core driving point is that Matrix Coder should make Hermes better at coding-related work by combining four layers inside one plugin:

1. Specialist agent prompts / personas — carefully written role prompts that turn a normal Hermes agent into a better security reviewer, code reviewer, debugger, verifier, simplifier, test engineer, API reviewer, dependency reviewer, architect, or explorer. The premise is simple: when an agent is given a precise specialist persona and operating contract, its coding output becomes more focused, more reliable, and easier to evaluate.
2. Dedicated Matrix Coder skills — a rich skill library inspired by OMC, OMX, and OmO. These skills are the right hand of the plugin: reusable procedures, rubrics, review protocols, evidence standards, output contracts, and coding workflows that specialist personas can load and apply consistently.
3. Built-in helper scripts — small, dedicated scripts that let Matrix Coder automate repetitive or precision-sensitive coding work efficiently instead of making the model manually rederive everything. Examples may include evidence collection, file/module summarization, line-reference extraction, dependency inspection, test discovery, static checks, report formatting, or other deterministic support tasks.
4. The Matrix Coder plugin harness — the Python plugin layer that understands Hermes agent capabilities and coordinates the personas, skills, scripts, and existing Hermes tools. When Hermes runs a coding task, this harness should complement the main agent, use Hermes features effectively, and provide an outstanding coding-focused result without turning into an unrelated orchestration system.

The goal is to give Hermes a coherent specialist-coding system inside one plugin: security review, code review, simplification, API review, performance review, dependency review, debugging, testing, verification, and codebase exploration can all share one consistent specialist harness instead of living as disconnected prompts or ad-hoc inline instructions.

Today, when a Hermes user wants the OMC-equivalent of /security-reviewer src/auth/, they have to do it inline in the parent session or manually load scattered instructions. That works, but it does not feel like a coherent specialist coding system.

This plugin fills that gap by porting the OMC + OMX + OmO pattern — specialist coding personas, reusable skills, efficient helper automation, and shared coding conventions — into Hermes as a first-class plugin.

Core Architecture: Four Complementary Layers

Matrix Coder should be designed as a specialist-coder harness, not as a single prompt or a loose folder of skills. The plugin should combine four complementary layers:

Layer	Purpose	Expected contribution
Specialist personas / prompts	Give Hermes a precise expert identity and operating contract for each coding task.	Better reasoning discipline, clearer scope, more consistent outputs.
Dedicated skills	Provide reusable procedures, rubrics, checklists, evidence rules, and output formats.	Repeatable specialist behavior across reviews, debugging, tests, and refactors.
Built-in scripts	Automate deterministic support work that models should not manually approximate.	Faster evidence gathering, fewer line-reference mistakes, better report quality.
Plugin harness	Coordinate personas, skills, scripts, and Hermes-native tools.	A coherent coding system that complements Hermes instead of replacing it.

The plugin harness should understand what Hermes already provides: file/search/terminal tools, skills, plugin hooks/tools, subagent delegation, provider/model configuration, existing safety gates, and the broader agent loop. Matrix Coder should use those capabilities deliberately so coding tasks feel sharper, more reliable, and more specialized than ordinary inline prompting.

Inspiration: Three Sources Studied

Source 1 — OMC (oh-my-claudecode)

oh-my-claudecode (35,447 stars, MIT, daily commits) ships 19 specialist agent prompts that share:

• A common severity rubric (CRITICAL/HIGH/MEDIUM/LOW)
• A common investigation protocol (scope → investigate → verify → report)
• A common output format (findings table with file:line, severity, confidence, fix)
• A common failure-mode catalog (style-first review, missing evidence, severity inflation)
• A team staged pipeline (plan → prd → exec → verify → fix) for multi-specialist flows
• A two-lane review pattern (code-reviewer + architect in parallel) for depth
• A persistence loop (Ralph) for iterative fix cycles
• A discovery-before-filtering methodology that separates investigation from verdict

Source 2 — OMX (oh-my-codex)

oh-my-codex (MIT, same author as OMC) is the Codex CLI equivalent, with improvements:

10 agents unique to OMX: api-reviewer (API contracts, backward compat), performance-reviewer (hotspots, N+1, complexity), quality-reviewer (logic defects, SOLID, anti-patterns), dependency-expert (CVE check, license audit), quality-strategist (release readiness gates), explore-harness (codebase investigation), information-architect, product-analyst, product-manager, and prometheus-strict (triple-critique adversarial review: collector → adversary → synthesizer).

Structural improvements from OMX:

1. XML-tagged prompt structure — <identity> / <constraints> / <explore> / <execution_loop> / <success_criteria> / <verification_loop> / <style> / <output_contract>. Survives context compaction better than freeform markdown.
2. Boundary tables — Each agent has explicit "You Own vs Others Own" table preventing scope creep in multi-agent dispatch.
3. Deprecation pattern — Hard-deprecated standalone skills. Single routing node ($code-review) dispatches to review lanes; sub-skills not meant for direct invocation.

Source 3 — OmO (oh-my-openagent)

oh-my-openagent (60,487 stars, SUL-1.0, daily active, default branch dev, formerly oh-my-opencode) is a multi-harness agent OS — the most architecturally sophisticated of the three. Published as npm oh-my-opencode (dual-published as oh-my-openagent during rename transition). Maintained by Jobdori, an AI assistant on a heavily customized OpenClaw fork.

OmO is fundamentally different from OMC/OMX in two ways:

A. It's not just prompts — it's a full runtime plugin.
OMC and OMX are static SKILL.md files loaded by an agent. OmO is a TypeScript plugin with 54-61 lifecycle hooks, 20-39 tools (config-gated), 5 built-in MCPs, Team Mode with 8 parallel members, and a custom CLI (bunx omo install).

B. Dynamic agent prompt composition at runtime.
Instead of loading a static SKILL.md for each specialist, OmO builds agent prompts dynamically by composing typed sections at runtime via the dynamic-agent-prompt-builder.ts system. The builder assembles:

• Identity section (who the agent is)
• Delegation table (what categories/skills exist)
• Tool selection table (what tools are available)
• Policy sections (ultrawork instructions, anti-patterns, hard blocks)
• Core sections (explore, librarian, oracle, parallel delegation, category-skills guide)
• Per-provider variants (Anthropic, OpenAI, Google, Kimi categories)

This produces model-optimized prompts — the same logical agent gets different context depending on whether it's running on Opus, GPT-5.5, Kimi K2.6, or Gemini.

Key Concepts from OmO

Concept	What it does	Relevance to Matrix Coder
11 Agents	Sisyphus (orchestrator), Hephaestus (deep worker), Prometheus (planner), Oracle, Librarian, Explore, Atlas, Metis, Momus, Multimodal-Looker, Sisyphus-Junior	Shows what a mature agent catalog looks like — not just reviewers but researchers, planners, and critics
Category-Based Model Routing	Agent says visual-engineering / deep / quick / ultrabrain; system picks the right model per provider	Far more flexible than fixed model-per-agent — could adopt for Hermes dispatch
Team Mode	Lead + up to 8 parallel members via team_* tools, tmux visualization, hyperplan (5 hostile critics), security-research (3 hunters + 2 PoC engineers)	A richer multi-agent parallel pattern than OMC's sequential team pipeline
IntentGate	Classifies user intent (ultrawork/search/analyze/team) before dispatching	Could replace or augment the meta-skill routing decision tree
Hashline Edit	LINE#ID content hashes validate every edit — zero stale-line errors	Useful for the simplify-slop and debug-isolate specialists
Package Layering	Core → MCP → Skills → Adapters → Platform → Web. Pure TypeScript core extracted for multi-harness reuse	The right architecture for Matrix Coder's shared _lib/ — avoid duplication across specialist files
Ulw Loop / Ralph Loop	Self-referential loop with evidence audit, backed by .omo/ulw-loop/. Doesn't stop until 100% done.	A pattern for the "fix loop" phase — specialist identifies issue, loop prevents unblocking until fixed
OpenClaw	Bidirectional external integration — Discord/Telegram/HTTP/shell	Shows how OmO extends beyond CLI into chat platforms, which Matrix Coder could do via Hermes gateway

Proposed Plugin: matrix_coder

Name rationale: "Matrix" = a structured array of specialist roles. Coder = the work domain. This plugin is the specialist coder layer: a plugin harness that makes Hermes better at coding by giving it specialist personas, dedicated coding skills, deterministic helper scripts, and shared operating standards. It is not a fleet, workflow-engine, or Kanban feature.

Location

~/.hermes/hermes-agent/plugins/matrix_coder/.

Layout

The layout should reflect the four-layer architecture: personas, skills, scripts, and the plugin harness.

plugins/matrix_coder/
├── plugin.py                       # register(ctx): tools, skills, hooks, harness entrypoints
├── plugin.yaml                     # manifest: name, kind, description, capabilities
├── README.md                       # user-facing overview and conversational invocation examples
├── pyproject.toml                  # optional plugin-local package metadata if needed
├── matrix_coder/
│   ├── __init__.py
│   ├── harness.py                  # main Matrix Coder coordinator / dispatcher
│   ├── registry.py                 # specialist + skill + script registry helpers
│   ├── config.py                   # plugin config loading and defaults
│   ├── models.py                   # typed request/result objects
│   ├── prompts.py                  # prompt assembly helpers for personas + skills
│   ├── hermes_bridge.py            # thin adapter over Hermes tools/delegate/skill APIs
│   └── reporting.py                # shared report formatting / JSON output
├── personas/                       # specialist agent prompts / role contracts
│   ├── _base/
│   │   ├── specialist-contract.md  # common identity, evidence, scope, output rules
│   │   ├── severity-rubric.md
│   │   ├── evidence-protocol.md
│   │   └── boundary-table.md
│   ├── security-reviewer.md
│   ├── code-reviewer.md
│   ├── api-reviewer.md
│   ├── performance-reviewer.md
│   ├── dependency-reviewer.md
│   ├── quality-reviewer.md
│   ├── debugger.md
│   ├── test-engineer.md
│   ├── verifier.md
│   ├── simplifier.md
│   ├── explorer.md
│   └── architect.md
├── skills/                         # plugin-scoped Hermes skills
│   ├── matrix-coder/               # meta-skill: choose and run the right specialist
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── routing-decision-tree.md
│   ├── review-security/
│   │   ├── SKILL.md
│   │   └── references/
│   ├── review-code/
│   │   ├── SKILL.md
│   │   └── references/
│   ├── review-api/
│   │   └── SKILL.md
│   ├── review-performance/
│   │   └── SKILL.md
│   ├── review-quality/
│   │   └── SKILL.md
│   ├── review-deps/
│   │   └── SKILL.md
│   ├── debug-isolate/
│   │   └── SKILL.md
│   ├── test-add/
│   │   └── SKILL.md
│   ├── verify-evidence/
│   │   └── SKILL.md
│   ├── simplify-slop/
│   │   └── SKILL.md
│   ├── explore-codebase/
│   │   └── SKILL.md
│   └── _lib/                       # shared skill references, not directly invoked
│       ├── output-format.md
│       ├── prompt-structure.md
│       ├── coding-quality-rubric.md
│       ├── test-strategy.md
│       ├── failure-modes.md
│       └── mental-execution-pattern.md
├── scripts/                        # deterministic helper automation
│   ├── collect_context.py          # summarize target files/modules for a specialist
│   ├── extract_line_refs.py        # stable file:line evidence extraction
│   ├── discover_tests.py           # map source files to likely tests
│   ├── inspect_dependencies.py     # dependency/package metadata inspection
│   ├── static_probe.py             # lightweight static checks / grep-like probes
│   ├── summarize_diff.py           # compact diff summary for review mode
│   └── format_report.py            # normalize markdown/json specialist reports
├── tools/                          # optional plugin tools exposed to Hermes
│   ├── run_specialist.py           # tool handler for programmatic specialist dispatch
│   └── list_specialists.py         # tool handler for available personas/skills
├── templates/
│   ├── specialist-report.md
│   ├── findings-table.md
│   └── json-result.schema.json
├── examples/
│   ├── ad-hoc-security-review.md
│   ├── debug-isolation.md
│   └── simplify-slop-pass.md
└── tests/
    ├── test_plugin_registration.py
    ├── test_skill_registration.py
    ├── test_specialist_dispatch.py
    ├── test_scripts.py
    └── fixtures/

Layout Principles

• Personas are not skills. Personas define specialist identity, boundaries, and output discipline. Skills define reusable procedures and workflows those personas can apply.
• Skills are the operational right hand. They hold rubrics, checklists, evidence rules, and task-specific procedures inspired by OMC, OMX, and OmO.
• Scripts handle deterministic work. Anything that can be computed reliably should be done by a helper script rather than approximated by the model.
• The harness coordinates, not replaces Hermes. matrix_coder/harness.py should understand Hermes tools, skill loading, plugin hooks/tools, delegation, and provider/model config so Matrix Coder complements the Hermes agent loop.
• Model dispatch uses Hermes config. Matrix Coder should infer specialist execution choices from the active Hermes provider/model/delegation setup instead of keeping its own hardcoded model catalog.
• Shared _lib/ content should be loaded progressively. Keep the default prompt small; load deeper references only when a specialist needs them.
• The first implementation should stay plugin-native. Avoid adding core Hermes APIs until the plugin proves which seams are truly needed.

register(ctx) behavior

def register(ctx):
    # 1. Register all sub-skills (review-security, review-code, review-api, ...)
    for skill_dir in SKILLS_DIRS:
        ctx.register_skill(name=f"matrix:{skill_dir.name}", path=skill_dir / "SKILL.md")

    # 2. Register the meta-skill (intent → specialist routing)
    ctx.register_skill(name="matrix:meta", path=SKILLS_DIR / "matrix-coder" / "SKILL.md")

    # 3. Register sub-agent role configs (for delegate_task dispatch)
    for agent_yaml in AGENT_CONFIGS:
        ctx.register_agent_role(name=f"matrix:{agent_yaml.stem}", config_path=agent_yaml)

    # 4. Register any agent-facing plugin tool/hook needed by the harness.

Prompt Structure (OMX-style XML tags + OmO-inspired category routing)

All specialist prompts use OMX's XML-tagged template, with an OmO-inspired category_routing section:

<identity>
Role description and identity.
</identity>

<category_routing>
For delegation, use categories:
- deep: {role} analysis
- quick: Single-file changes
</category_routing>

<constraints>
<scope_guard>
Boundary table: What you own vs what others own.
</scope_guard>
<ask_gate>
Output style rules and update semantics.
</ask_gate>
</constraints>

<explore>
Step-by-step investigation protocol.
</explore>

<execution_loop>
<success_criteria>
Definition of done.
</success_criteria>
<verification_loop>
When to deepen effort vs. when to stop.
</verification_loop>
</execution_loop>

<style>
<output_contract>
Default output shape: outcome-first, evidence-dense.
Include: result, evidence, validation status, stop condition.

## {Specialist} Summary

**Target:** {file or directory}
**Verdict:** PASS | FAIL | NEEDS_DISCUSSION

### Findings
[severity × confidence × file:line × category × issue × recommendation]

### Phased Roadmap (Epic)

This issue is the **epic**. Implementation is split across six child issues, each independently shippable. Detailed execution plans are drafted just-in-time per phase.

- [x] Phase 0 — Scaffold & contracts + walking-skeleton smoke test (#112) — *complete, reviewed; pending commit/merge*
- [x] Phase 1 — Spine: harness + `_base` + **2 roles** (`review`, `executor`) + trigger invocation + intake gate (#113) — *complete, reviewed (APPROVE); in PR #119*
- [x] Phase 1.5 — Remaining 6 specialist roles + 4 review lenses (#118) — *complete, reviewed (APPROVE); in PR #119*
- [x] Phase 2 — Observability: Kanban audit mirror (#114) — *complete, reviewed (APPROVE); in PR #119*
- [x] Phase 3 (v1) — Workflow skills as personas: Ralph · autopilot · ultrawork · ultraqa (#115) — *complete, reviewed; loop hardening deferred to testing; in PR #119*
- [x] Phase 4 — Domain packs (text composition, `@domain` token) (#116) — *complete, reviewed; in PR #119*
- [ ] Phase 5 — Implicit routing / IntentGate (#117)

Dependency order:

0 ──> 1 ──> 1.5
│
├──> 2 (kanban)
├──> 3 (workflows — needs 1, better after 2)
├──> 4 (domain packs)
└──> 5 (implicit — needs 1, better after 4)

Phase 0 + 1 = usable MVP (2 roles proving the spine). Phase 1.5 fills out the roster. Phases 2/3/4 build on the role core; Phase 5 lands last.

### Cross-cutting (applies to every phase)

- [ ] Testing strategy — unit + end-to-end (persona injection, output normalization, single-writer / disjoint-file assignment)
- [ ] Config schema for dispatch-category → Hermes model mapping
- [ ] Observability of the intake gate's own decisions (audit a wrong `direct` verdict)
- [ ] Uninstall / disable behavior — disabling MC must not leave any MC hook (persona injection / output-normalize / optional file-claim backstop) registered
- [ ] Persona-contract versioning
- [ ] Licensing: confirm OmO (SUL-1.0) is ideas-only vs vendored text; add `NOTICES`/`THIRD_PARTY_LICENSES` + segregation if text is copied (repo is MIT)

### Advisory review

A code-verified opus critic pass was run on the epic + all phases (see the "Advisory Plan Review" comments on each issue). Key corrections already folded in: persona binding is text composition (no subagent persona API); per-role write-blocking is dropped in favor of **single-writer-per-file** (advisory roles + orchestration-time disjoint file assignment / worktree isolation); Phase 1 re-cut to 2 roles + Phase 1.5; Phase-2 spike removed (code already supports never-claimed-card completion); Phase-4 "dynamic composition" is text-level only.

## Open Questions (low-confidence findings surfaced)
### Positive Observations
### Recommendation
</output_contract>
</style>

Specialist Sub-Skills

Matrix Coder exposes one consolidated specialist catalog rather than separate phase-by-phase skill lists. Specialists are personas, not hardcoded agents: at dispatch the harness composes a role contract (+ optional domain pack) into the subagent's context and re-injects it per turn via the pre_llm_call hook. Same agent, different persona. Note (advisory review): there is no Hermes API to load a system prompt/persona onto a subagent — delegate_task has no persona param and the child prompt is hardcoded — so persona binding is text composition (context + pre_llm_call), not a structural attachment. The 8 roles are an MC concept and do not map to the subagent role field ({leaf, orchestrator}). Phase 1 ships the full role core; domain packs follow in Phase 2.

Two-axis model

• Roles = activity contracts (distinct inputs, rubric, output shape, allowed tools). Fixed core of 8 — this is where the quality lift lives.
• Domain packs = composable context layers (frontend, backend, etc.) loaded onto any role. Avoids the N×M persona explosion of treating every stack/activity pair as its own agent.

This consolidates the 16 ported review-fragments (from OMC/OMX/OmO) into 8 roles: the six review-* entries collapse into one review role with a selectable lens; architect + adversarial planning + release-strategy merge into plan; and a new executor role is added — the table as ported was entirely read-only (every entry disallowed Write/Edit), so nothing could actually implement. executor edits files by default; the others are analysis/review by default. These read/write labels are advisory persona guidance, not a hook-enforced per-role block (see Concurrency rule below). The new executor role is what makes Matrix Coder a coder rather than a review panel.

Axis 1 — Role core (Phase 1)

Role	Primary purpose	Tools	Edits files? (advisory)	Inspiration	Dispatch category
explore	Map files, flows, and risks before other roles act.	file, search, terminal	✗	OmO Explore	quick, explore
plan	Break work into dependency-aware tasks + acceptance criteria; system-design review (boundaries, interfaces, tradeoffs); adversarial critique (collector → adversary → synthesizer); release readiness / go-no-go.	file, search, terminal	✗	OMC + OMX + OmO Prometheus	deep, planning
executor	Implement to spec: surgical edits, follow the plan, keep changes minimal and reversible.	file, search, terminal	✓	Matrix Coder (new)	deep / quick, implement
review	Code review with a selectable lens: security · code · api · performance · quality · deps. One contract, lens-specific rubric.	file, search, terminal	✗	OMC + OMX	deep, review (+ lens)
debug	Isolate root cause and propose a fix strategy via focused probes, failing tests, traces, minimal repro.	file, search, terminal	only when explicitly fixing	OMC + OmO Hephaestus	deep, debug
test	Add or strengthen tests around behavior, regressions, or newly changed code.	file, search, terminal	when explicitly asked	OMC	quick, test
verify	Verify claims, fixes, file references, test evidence, and completion status. No fixing.	file, terminal	✗	OMC	quick, verify
simplify	Behavior-preserving reduction of overbuilt or AI-sloppy code.	file, search, terminal	when explicitly asked	OMC	quick, refactor

Concurrency rule (the real guardrail). The hard invariant is single-writer-per-file: no file is edited by more than one agent at a time. MC enforces this at orchestration time — when it fans specialists out in parallel it assigns disjoint file sets, and for write-heavy parallel work it can use worktree isolation (one worktree per writer) so there is no shared-file contention. Read-only/analysis roles may share read access freely. A role's read-vs-write nature is advisory (stated in the persona, reinforced by intake/orchestration), not a per-role pre_tool_call hard block — so MC does not need to map tool-call → agent → role at the hook layer (this removes the former Phase-1 role-isolation spike). An optional path-claim backstop hook may be added later if a hard stop is wanted, but it is keyed on file path, not role.

Axis 2 — Domain context packs (Phase 2, composable onto any role)

frontend · backend-api · data-db · infra-cli · plugin-skill-authoring. A request like "API coder" resolves to a role (executor / review / test) + the backend-api pack — no separate persona required.

Each role shares Matrix Coder's common _base/ persona contract, severity rubric, evidence protocol, output format, and progressive skill-loading rules. Domain packs add stack-specific conventions only; they do not change a role's operating contract.

Workflow / Orchestration Skills

Beyond the specialist roles (the who), Matrix Coder ships workflow skills (the how) that orchestrate roles in loops and fan-outs. This is the "system feel" of OMC/OMX/OmO — not isolated prompts. Adapted from OMC (MIT, per-skill attribution).

Skill	Drives
Ralph loop	repeat executor → verify until verification passes (bounded, explicit stop criteria)
autopilot	full chain plan → executor → test → review → verify from one ask
ultrawork	parallel fan-out of roles across files / topics
ultraqa	test → verify → fix cycle until the goal is met

Workflows emit the shared output contract and, when Kanban observability is present, write parent + iteration/branch cards for live Switch UI monitoring. Shipped in Phase 3.

Dynamic Model Dispatch Using Hermes Configuration

Matrix Coder should not maintain a separate hardcoded model catalog or require distributed specialist-to-model mappings. The plugin should use the existing Hermes agent configuration as the source of truth for providers, models, fallback chains, reasoning settings, and delegation behavior. At runtime, Matrix Coder should inspect the active Hermes configuration and dynamically choose the best available execution path for each specialist dispatch: deeper review/debug/architecture tasks should route to the strongest configured coding-capable model or delegated subagent path, while quicker verification/simplification/dependency checks can use cheaper or faster configured options when available. This dynamic mapping must live inside the Matrix Coder harness, be robust across providers, inherit Hermes' existing model/provider/delegation settings where possible, and avoid forcing users to duplicate model config under Matrix Coder-specific category maps. The specialist can still declare intent metadata such as deep, quick, review, security, or debug, but those labels should guide the harness' runtime selection against Hermes' current configuration rather than statically naming a provider or model.

Deprecation Pattern (OMX-inherited)

The meta-skill (matrix:meta) is the single routing node for all review types. It dispatches to the right specialist based on intent. Sub-skills are not meant to be invoked directly unless you bypass the meta-skill. Fewer entry points = less duplication.

Sub-Skill Output Format (shared across all specialists)

## {Specialist} Summary

**Target:** {file or directory}
**Mode:** {ad-hoc | workflow-dispatched}
**Verdict:** PASS | FAIL | NEEDS_DISCUSSION

### Findings
| # | Severity | Confidence | File:Line | Category | Issue | Recommendation |
|---|----------|------------|-----------|----------|-------|----------------|
| 1 | CRITICAL | HIGH | src/auth/login.ts:42 | injection | SQL string concat | Use parameterized query |
| 2 | MEDIUM   | MEDIUM   | src/api/users.ts:88 | error-handling | Empty catch block | Log error, return 500 |

### Open Questions (low-confidence findings — surfaced, not blocking)
### Positive Observations
### Recommendation

Invocation Model

Matrix Coder should be invoked through the Hermes agent experience, not through a separate command interface. The primary path is conversational: the user asks Hermes for a coding task, the Matrix Coder meta-skill or harness selects the appropriate specialist persona and supporting skills, and the plugin coordinates any helper scripts or delegated specialist execution internally. Direct qualified skill usage may remain available for explicit expert selection, but the plugin should not require or expose a separate external invocation workflow.

All invocation paths should return the same matrix:_lib/output-format.md shape.

Non-Goals: Fleet, Workflow Engine, and Kanban Coupling

Matrix Coder should not be designed around a2a_fleet, workflow-engine, or kanban. Those systems may exist elsewhere in Hermes, but they are not the conceptual center of this feature.

Matrix Coder's center is the Hermes coding experience itself: when Hermes is asked to code, review, debug, simplify, test, or verify, this plugin gives it a specialist-coder harness with multiple expert capabilities and one consistent evidence/output discipline.

Other systems can choose to call Matrix Coder later if useful, but Matrix Coder should stand on its own as the plugin that makes Hermes a better specialist coder.

Clarification — Kanban observability is in scope. "No Kanban coupling" means MC does not use Kanban as a control/orchestration engine: it does not schedule, dependency-gate, or execute specialists via the Kanban dispatcher, and it is not a Kanban feature. MC may, however, use Kanban as an observability / audit mirror — writing a parent card per invocation and a child card per specialist dispatch (status running → done/blocked) so delegations are traceable and visible live on the Switch UI. Cards mirror MC's own execution; they never drive it. (See the Kanban Integration comment for the audit-mirror design and the dispatcher-double-execution constraint.)

Intent-Gated Dispatch (Phase 3, OmO's IntentGate pattern)

OMC/OMX route based on explicit user commands (/security-reviewer). OmO routes based on intent classification first:

User: "find security holes in src/auth/"
→ IntentGate classifies: [ultrawork, security]
→ Routes to: matrix:review-security
→ with category: deep (since it's a security audit, not a quick check)

This means the user doesn't need to know the specialist names. The meta-skill plus IntentGate routes naturally.

Open Questions

• Should role configs be stored in the plugin's agents/ dir, or in the profile's ~/.hermes/profiles/<name>/agents/ for per-profile customization? Initial proposal: plugin's directory, with override mechanism via profile-level matrix_coder_overrides.yaml.
• Should category → model mappings live in the Hermes config.yaml, or in a separate matrix_coder/categories.yaml? Initial proposal: inside config.yaml under matrix_coder.categories, to keep model routing visible alongside other config.
• Does the plugin need its own SQLite for tracking dispatches (rate limiting, history)? Initial answer: no, defer until Phase 2.

Related

• oh-my-claudecode — source pattern 1 (MIT, attribution required)
• oh-my-codex — source pattern 2 (MIT, attribution required)
• oh-my-openagent — source pattern 3 (SUL-1.0, 60K stars, daily active, multi-harness agent OS, attribution for structural patterns)

Attribution

This proposal and any shipped prompts adapt oh-my-claudecode (MIT, Yeachan Heo), oh-my-codex (MIT, Yeachan Heo), and oh-my-openagent (SUL-1.0, code-yeongyu / Sisyphus Labs).

• Direct prompt porting (Phase 1): OMC agent prompts (security-reviewer, code-reviewer, verifier, ai-slop-cleaner, test-engineer, debugger, planner, architect) and OMX agent prompts (api-reviewer, performance-reviewer, quality-reviewer, dependency-expert, explore-harness, prometheus-strict, quality-strategist) are MIT-licensed and will be ported with attribution in each shipped SKILL.md.
• Structural patterns (not direct copies): OmO's intent/category routing concept, IntentGate dispatch pattern, dynamic prompt composition concept, and package layering architecture inform the plugin design but are structural patterns, not direct text porting. Attribution here is design provenance.
• Prompt structure: The XML-tagged template format, boundary tables, and deprecation pattern are derived from OMX's structural conventions, not direct text copies.

[Interstellar-code]

Matrix Coder — Runtime Architecture

The Layout section already captures the file structure. This comment captures the runtime architecture: how a coding request flows through the plugin, how a specialist persona is composed from the two axes, and where Hermes-native capabilities bind in.

The guiding principle is one coherent coding harness: a single dispatcher resolves a role (+ optional domain pack), composes a persona prompt from shared _base/ contracts, binds the allowed tool surface, picks a model via Hermes config, runs the specialist on a Hermes subagent, and returns a result in a shared output contract. Specialists are personas, not hardcoded agents — the same subagent takes a different persona per dispatch.

Dispatch flow

flowchart TD
    H[Hermes agent — coding intent] --> ENTRY["matrix_coder.register(ctx)<br/>registers tools · skills · hooks"]
    ENTRY --> HAR["harness.py<br/>coordinator / dispatcher"]
    HAR --> GATE{"IntentGate<br/>(Phase 3 — explicit role before then)"}
    GATE -->|"role + lens + domain"| REG["registry.py<br/>resolve role · skills · scripts"]
    HAR --> CFG["config.py<br/>dispatch category → Hermes model"]
    HAR --> MOD["models.py<br/>typed request / result"]

    REG --> PR["prompts.py — persona assembly"]
    subgraph COMPOSE["Persona composition — two axes"]
      direction LR
      B["_base/ contract<br/>identity · severity · evidence · boundary · output"]
      ROLE["role persona (1 of 8)<br/>explore · plan · executor · review<br/>debug · test · verify · simplify"]
      DOM["domain pack — optional<br/>frontend · backend-api · data-db<br/>infra-cli · plugin-skill-authoring"]
      SK["specialist sub-skills"]
    end
    PR --> B
    PR --> ROLE
    PR --> DOM
    PR --> SK

    COMPOSE --> BRIDGE["hermes_bridge.py<br/>subagent delegate · skill loading<br/>sets active-role state"]
    CFG --> BRIDGE
    BRIDGE --> SUB[["Hermes subagent<br/>runs the composed specialist"]]
    SUB -->|"tool call"| GUARD{"pre_tool_call hook<br/>active role read-only?"}
    GUARD -->|"yes — review / verify / explore / plan"| BLOCK["block Write/Edit<br/>action=block"]
    GUARD -->|"no — executor (always); debug/test/simplify (when fixing)"| TOOLS[("Hermes-native tools<br/>file · search · terminal<br/>+ deterministic helper scripts")]
    BLOCK -.->|"vetoed"| SUB
    TOOLS --> SUB
    SUB --> REP["reporting.py<br/>shared output contract (Findings / Open Questions / Recommendation)"]
    REP --> H

Loading

Hook bindings (see the Hooks Architecture comment): persona is injected each turn via pre_llm_call; the read-only guardrail above is enforced by pre_tool_call (action=block); the final reply is normalized by transform_llm_output. The bridge does not enforce allow/deny by string-matching — it sets active-role state and the pre_tool_call hook does the hard block.

Layer responsibilities

Layer	Module(s)	Responsibility
Entry / harness	plugin.py, harness.py	register(ctx) wires tools/skills/hooks; harness is the single coordinator that owns a dispatch.
Resolution	registry.py, config.py, models.py	Resolve which role/lens/domain/skills/scripts apply; map dispatch category → Hermes model; typed request/result objects.
Persona assembly	prompts.py, personas/	Compose one prompt from _base/ contract + role persona + optional domain pack + sub-skills. Two-axis composition lives here.
Execution bridge	hermes_bridge.py	Thin adapter over Hermes file/search/terminal tools, skill loading, hooks, and subagent delegation; enforces per-role tool allow/deny.
Reporting	reporting.py	Normalize every specialist's output into the shared contract so results are comparable and chainable.

Two-axis composition (the core idea)

composed persona  =  _base contract            (shared: identity, evidence, severity, output)
                  +  role persona              (1 of 8 — defines the operating contract)
                  +  domain pack   [optional]  (stack conventions; does NOT change the contract)
                  +  sub-skills                (rubrics / protocols the role loads progressively)

• Roles are the fixed core (8). They define what the contract is and which tools are allowed. Only executor carries Write/Edit by default.
• Domain packs are composable context. "API coder" = a role (executor / review / test) + the backend-api pack — no new persona. This is what avoids the N×M explosion.

Tool surface & guardrails

• Tool allow/deny is enforced at the bridge, per role — e.g. review / verify / explore / plan cannot Write/Edit; executor can; debug / test / simplify can only when explicitly fixing/asked.
• Model selection is dispatch-category based, resolved from Hermes config — the persona references a category (deep, quick, …), never a hardcoded model.
• Helper scripts are deterministic support (evidence collection, line-reference extraction, test discovery, report formatting) — invoked by roles, not a substitute for the model's reasoning.

Chaining (typical flow)

explore → plan → executor → review(+lens) → test → verify
                      ↘ (on failure)
                   debug / simplify

Each step emits the shared output contract, so a later role consumes an earlier role's result without bespoke glue.

Phasing

• Phase 1 — all 8 roles as static persona files + _base/ contracts + harness/bridge/reporting; explicit role selection.
• Phase 2 — domain packs; richer runtime prompt composition if the Hermes plugin API supports it; optional plugin-local SQLite for dispatch history.
• Phase 3 — IntentGate auto-routing (category/role inference from the request).

---

Corrections (advisory review, code-verified):

• Persona is not "loaded onto" the subagent — delegate_task has no persona/system_prompt param and the child prompt is hardcoded (tools/delegate_tool.py:569-643, 2660). MC binds persona by composing it into the child context at dispatch and re-injecting via pre_llm_call. The "bridge sets active-role state" only feeds MC's own hooks; nothing else reads it.
• The pre_tool_call guardrail node is best-effort (hooks fail-open) — not an absolute block.
• transform_llm_output fires on EVERY parent turn — the normalize handler must no-op unless an MC dispatch is active.

---

Design change: the pre_tool_call guardrail node is no longer a per-role read-only block. The real guarantee is single-writer-per-file (orchestration-time disjoint file assignment / worktree isolation). Roles' read/write nature is advisory. Any future hook backstop is keyed on file path, not role.

[Interstellar-code]

Matrix Coder — End-User Flow

The previous comment covered the runtime architecture (how a dispatch flows through the plugin internals). This one covers the user architecture: how a person actually invokes and experiences Matrix Coder.

Mental model

Matrix Coder is invisible plumbing, not a destination. The user keeps talking to Hermes the way they already do — there is no separate UI, no board, no fleet to configure (see Non-Goals). What changes is that Hermes can now become the right specialist for a coding request instead of answering as a generalist. The user asks for coding work; Matrix Coder loads the matching role persona (+ domain pack) behind the scenes and Hermes responds with focused, contract-shaped output.

Three invocation modes

Mode	How the user triggers it	When	Example
Implicit (Phase 3)	Plain natural language; IntentGate infers role/lens/domain.	Default once IntentGate ships.	"Is this auth code safe?" → review + security lens
Explicit	User names the activity or uses a light keyword.	Phase 1 default; always available as override.	"review this for performance", "debug why the worker hangs", "matrix: simplify this module"
Chained	User asks for an end-to-end coding task; harness sequences roles.	Larger tasks.	"implement X with tests and review it" → plan → executor → test → review → verify

Explicit always wins over implicit — if the user names a role/lens, IntentGate does not override it.

All modes pass through the Stage-0 Intake / Right-Size Gate first (see the Invocation & Intake Gate comment). On invocation Matrix Coder self-assesses the request: if Hermes can handle it directly it recommends so and lets the user decide; otherwise it silent-proceeds to the routed role. The gate decides whether to use Matrix Coder; the modes below decide how the role is chosen.

Typical session (sequence)

sequenceDiagram
    actor U as User
    participant H as Hermes
    participant MC as Matrix Coder
    participant S as Specialist persona

    U->>H: "Review this PR for security and performance"
    H->>MC: coding intent
    MC->>MC: resolve role=review, lens=[security, performance]
    MC->>MC: compose persona (_base + review + lens + domain pack)
    MC->>S: dispatch on Hermes subagent (tools: file/search/terminal, no write)
    S-->>MC: Findings / Open Questions / Recommendation (shared contract)
    MC-->>H: normalized result
    H-->>U: focused review, severity-tagged, evidence-backed

    U->>H: "Fix the high-severity one"
    H->>MC: coding intent (follow-up)
    MC->>S: dispatch role=executor (write/edit allowed) + debug if needed
    S-->>MC: patch + rationale
    MC-->>H: result
    H-->>U: change applied, with what/why

Loading

What the user gets back

Every specialist returns the same output contract, so the experience is consistent regardless of role:

• Findings — severity-tagged, each with a file:line reference and evidence.
• Open Questions — low-confidence items surfaced, not hidden.
• Positive Observations — what is already correct (so review is not pure negativity).
• Recommendation — a clear next action or go/no-go.

executor additionally returns the applied change + rationale; verify returns a pass/fail evidence ledger.

What the user explicitly does NOT do

• No fleet, workflow-engine, or kanban interaction — Matrix Coder is a coding harness, not an orchestration surface.
• No manual model selection — the user never picks Opus vs Sonnet; the dispatch category resolves the model from Hermes config.
• No persona/prompt wrangling — the user states intent in plain language; persona composition is internal.
• No new install ritual per task — the plugin is registered once via register(ctx); specialists load on demand.

Example prompts → resolved persona

User says	Role	Lens / domain	Write?
"any security holes here?"	review	security	no
"this endpoint is slow"	debug → review	performance + backend-api	only when fixing
"map how auth flows through this repo"	explore	—	no
"break this feature into tasks"	plan	—	no
"build the CSV export and test it"	plan → executor → test	backend-api	yes
"is this overengineered?"	simplify	—	when asked
"did the fix actually work?"	verify	—	no

Progressive disclosure

A first-time user just talks normally and gets better coding answers. A power user can steer explicitly (name the role, pin a lens, request a chain). Both use the same surface — the depth is opt-in, never required.

[Interstellar-code]

Matrix Coder — Hooks Architecture (planning input)

Hooks were missing from the original proposal. Homework done against the Hermes core; this section defines the hook surface Matrix Coder will register and why. To be folded into planning.

How Hermes plugin hooks work (verified)

• Registration is in code, inside register(ctx): ctx.register_hook("<event>", handler) — hermes_cli/plugins.py:937. The plugin.yaml hooks: field is documentation/listing only; it does not auto-wire anything.
• Handlers are synchronous plain callables taking **kwargs. async def handlers are never awaited (silently broken) — the bridge hook path must stay sync. Dispatch site: hermes_cli/plugins.py:1556.
• Fail-open + isolated: each handler runs in its own try/except; exceptions log at WARNING and are swallowed — a buggy hook never halts the agent loop.
• Multiple plugins per event, fired in FIFO registration order. No priority mechanism.
• 19 hook events total. Three power tiers: veto (2), mutate (5), observer (12).

Hooks Matrix Coder will register

Hook	Tier	Matrix Coder use	Core fire site
pre_tool_call	veto	Enforce per-role tool allow/deny. When the active role is review / verify / explore / plan, hard-block Write/Edit via {"action":"block","message":...}. Makes the "Disallowed" column real enforcement, not just prompt text.	hermes_cli/plugins.py:1668
pre_llm_call	mutate	Inject the active persona contract (role _base + lens + domain pack) and coding standards as ephemeral turn context. All hook returns are joined, so MC composes cleanly alongside other plugins.	agent/conversation_loop.py:679
transform_llm_output	mutate	Normalize specialist output into the shared contract (Findings / Open Questions / Positive / Recommendation) before it reaches the user.	agent/conversation_loop.py:4450
transform_tool_result	mutate	Augment/condense tool results for the active specialist (e.g. attach file:line evidence, trim noise).	model_tools.py:873
post_tool_call	observer	Evidence collection / dispatch telemetry (no mutation).	model_tools.py:852
subagent_stop	observer	Capture specialist dispatch outcome (role, status, duration) for chaining + reporting.	tools/delegate_tool.py:2268
on_session_start / on_session_reset	observer	Init / clear per-session MC state: active role, lens, domain pack, dispatch history.	agent/conversation_loop.py:305; plugins.py

Enforcement model — guardrails become real

The role catalog's Disallowed: Write/Edit column is enforced at runtime, not merely requested in the prompt:

role dispatched  -->  MC sets active-role state (on_session_start / per-dispatch)
user/model tries Write or Edit
        |
   pre_tool_call hook fires
        |
   active role in {review, verify, explore, plan}?
        |-- yes --> return {"action":"block","message":"<role> is read-only; use executor to apply changes"}
        |-- no  --> allow (executor: always; debug/test/simplify: only when explicitly fixing/asked)

This gives a defense-in-depth pair: the persona prompt discourages writes, and the pre_tool_call hook hard-stops them. A review persona literally cannot mutate the tree.

Constraints to design around

• Sync only — no async in any MC hook handler; long work must be delegated to a subagent, not awaited in the hook.
• No ordering guarantee vs other plugins — MC's pre_tool_call block must be self-sufficient (don't assume MC runs before/after security-guidance or mcp_lazy, which also register pre_tool_call).
• Fail-open — if MC's enforcement hook raises, the block is lost and the action proceeds. Keep the handler trivial and defensive (**_kwargs, no exceptions on the hot path).
• pre_llm_call is ephemeral — injected context is never persisted and never enters the system prompt; persona must be re-injected each turn.

Two parallel hook systems (note)

Plugin hooks (ctx.register_hook, sync) are distinct from the gateway's filesystem HookRegistry (gateway/hooks.py, supports async def handle). Matrix Coder uses the plugin system exclusively.

---

Corrections (advisory review, code-verified):

• The read-only guard is best-effort defense-in-depth, NOT a hard guarantee. Hooks are fail-open — each callback runs in a swallowed try/except (hermes_cli/plugins.py:1566-1575) and the pre_tool_call enforcement site proceeds on error (model_tools.py:785-799). If MC's handler raises or is not registered in the child process, Write/Edit proceeds. Keep the handler trivial/defensive; add a test asserting a raising guard does NOT block.
• Per-agent role isolation is an open spike. Hooks DO fire inside subagent turns (good), but subagents share parent_session_id (tools/delegate_tool.py:1129). Active-role state must be keyed per-agent/dispatch, not per-session, or a child review role blocks the parent's writes. Confirm pre_tool_call kwargs (task_id/tool_call_id) can disambiguate the active role before relying on hook enforcement. UNCLEAR in code today.
• First-block-wins across plugins: security-guidance/mcp_lazy also register pre_tool_call; any one block wins in FIFO order, so MC does not control which block message shows.

---

Design change — per-role write-block dropped. The hard read-only guard (and its call→agent→role mapping / fail-open concern) is replaced by a simpler invariant: single-writer-per-file, enforced at orchestration time (disjoint file assignment across parallel specialists; worktree isolation for parallel writers). A role's read/write nature is now advisory persona guidance, not a pre_tool_call hard block. pre_tool_call may host an optional path-claim backstop later, keyed on file path (not role) — which sidesteps the per-agent identity problem entirely. The Phase-1 role-isolation spike is therefore dropped.

[Interstellar-code]

Matrix Coder — Invocation & Intake Gate (Stage 0)

Adds the entry contract that sits in front of every specialist dispatch. Feeds planning; this is Phase 1, not deferred — it is the front door.

Invocation

Matrix Coder is invoked explicitly — by a trigger term (e.g. matrix ...) or a dedicated Hermes command. No silent auto-invocation in Phase 1. (Phase 3 adds implicit intent-based invocation; see hook note below.)

Stage 0 — Intake / Right-Size Gate

The moment Matrix Coder is invoked, it self-assesses the request before dispatching any specialist. The bias is to avoid overhead: if Hermes can do the task directly, the gate says so and lets the user decide. This makes Matrix Coder self-policing — it knows when not to be used.

trigger term / explicit command
        |
   [Stage 0] Intake Gate   (cheap — quick dispatch category)
        |
   verdict?
     |-- direct  --> "Efficient for Hermes to handle this directly (reason).
     |                Invoke Matrix Coder anyway, or let Hermes do it?"   --> user decides
     |-- matrix  --> SILENT-PROCEED: route to role(+lens)(+domain), dispatch Stage 1

Default: silent-proceed. The gate only interrupts the user to recommend direct. On a matrix verdict it routes and dispatches without an extra confirmation prompt — friction only where it adds value. The gate never auto-declines and never auto-skips silently on a direct verdict; the explicit trigger keeps the user in control.

Two cheapest-first layers:

1. Deterministic pre-filter (in harness.py, optional) — obvious cases skip the LLM entirely: single file, under a small line threshold, no logic/security/architecture signal → direct candidate. Free, instant.
2. XML-contracted triage persona (quick category) — handles the gray zone. Rubric + policy + output live in its XML template (below).

Intake gate XML contract

<intake_gate>
  <identity>Right-size the request before specialist dispatch. Bias toward NOT adding overhead.</identity>
  <assess>
    <dimension name="clarity">Ask unambiguous and fully specified?</dimension>
    <dimension name="scope">How many files / surfaces change?</dimension>
    <dimension name="complexity">Mechanical edit vs logic / architecture / security reasoning?</dimension>
    <dimension name="risk">Reversibility, blast radius, security / data impact.</dimension>
    <dimension name="verifiability">Is success obvious without specialist evidence?</dimension>
  </assess>
  <decision_policy>
    <recommend_direct when="clear AND single-surface AND mechanical AND low-risk">
      Hermes should do this directly; Matrix Coder adds overhead without quality gain.
    </recommend_direct>
    <recommend_matrix when="ambiguous OR multi-file OR logic/security/architecture OR high-risk OR needs evidence">
      Route to role(s) with one-line justification.
    </recommend_matrix>
    <never>Auto-skip OR auto-decline silently. On a direct verdict, always surface the recommendation; user decides.</never>
  </decision_policy>
  <output_contract>
    <verdict>direct | matrix</verdict>
    <reason>one line</reason>
    <proposed_route>role (+ lens) (+ domain) — only if matrix</proposed_route>
    <question>Efficient for Hermes to handle this directly. Invoke Matrix Coder anyway, or let Hermes do it?</question>
    <on_matrix>silent-proceed — route and dispatch without asking</on_matrix>
  </output_contract>
</intake_gate>

Gate vs IntentGate

Two different questions, composed:

• Intake gate (Phase 1) — should we use Matrix Coder at all? (direct vs matrix)
• IntentGate (Phase 3) — which role? (intent → role/lens/domain)

Intake runs first. If matrix, IntentGate (or the explicit role the user named) picks the specialist.

Do hooks come into this? — mostly no

The intake gate is harness control flow off the explicit entry (the trigger term / command runs the MC entry tool, which runs Stage 0 then Stage 1). For Phase 1 it needs no hook — invocation is a direct tool/command call, not an interception of the ambient agent loop.

One hook becomes relevant only for the Phase-3 implicit path: if Matrix Coder should auto-offer right-sizing when the user never typed a trigger (plain "fix this bug" in normal chat), pre_llm_call is the natural carrier — detect coding intent and inject the intake recommendation as ephemeral turn context. That is a Phase-3 enhancement, explicitly out of scope for Phase 1.

Note the separation of concerns:

• pre_llm_call — (Phase 3 only) inject the intake gate on implicit coding intent.
• pre_tool_call — the role write/edit guardrail (Hooks Architecture comment). Unrelated to intake; do not conflate. The guardrail polices an already-dispatched specialist; the intake gate decides whether to dispatch at all.

So: link to pre_llm_call is optional and Phase-3 only. Phase-1 intake is pure harness logic + the XML persona contract above.

---

Correction (advisory review): the deterministic pre-filter must NOT short-circuit to direct on size/line-count alone — a 3-line change to auth, a migration, or a config file is small but high-risk. The pre-filter may only route to direct when low-risk signals ALSO hold; encode a denylist of sensitive path patterns (auth, migrations, secrets, security, CI/deploy config) that always go to the triage persona.

[Interstellar-code]

Matrix Coder ↔ Hermes Kanban Integration (audit / traceability layer)

Code exploration done (codegraph + source read) and cross-checked against prior memory of the Kanban system. This defines how Matrix Coder records delegations as Kanban tasks for audit, traceability, and live monitoring on the Switch UI — without coupling MC's control flow to Kanban.

Verified architecture (Hermes Kanban)

• Single shared data layer: hermes_cli/kanban_db.py. Plugins import it directly — no HTTP, no gateway, no subprocess. connect() (kanban_db.py:1253) → SQLite at ~/.hermes/kanban.db (WAL, BEGIN IMMEDIATE). Task create/complete is a sub-millisecond local write.
• Task model — kanban_db.py:631. Relevant fields for us: id, title, body, assignee, status, priority, created_by, tenant, session_id, skills, result, idempotency_key, metadata (via run), parent/child links.
• Statuses (kanban_db.py:100): triage · todo · scheduled · ready · running · blocked · review · done · archived. Dashboard columns = first 8.
• Hierarchy: task_links(parent_id, child_id) (kanban_db.py:899). kb.create_task(..., parents=[id]), kb.link_tasks(), kb.child_ids(). Board returns progress {done/total} + link_counts rollups per card.
• Switch UI is live: dashboard WebSocket /api/plugins/kanban/events?since=&board=&token= (plugin_api.py:2143) polls task_events every ~300ms and streams new rows to the browser. Every status transition appends a task_events row → card updates within ~300ms. No gateway needed.
• Completion carries findings: complete_task(conn, id, summary=..., metadata={...}, created_cards=[...]) (kanban_db.py:3076) — summary + structured metadata show in the task drawer; created_cards is an audit of what the task spawned.

Integration model: parent = invocation, child = dispatch

MC invoked (intake verdict = matrix)
   └─ parent task  "matrix_coder: <goal>"        status=running
        ├─ child  "[review:security] <topic>"    running → done (summary+metadata)
        ├─ child  "[debug] <topic>"              running → done
        └─ child  "[executor] <topic>"           running → blocked (reason) / done
   parent completed last with synthesis summary + metadata{findings, child_ids}

• One MC invocation = one parent card. One specialist dispatch = one child card.
• Per-specialist result → complete_task(child, summary=recommendation, metadata=findings); the parent gets the synthesis on complete_task(parent, ...).
• idempotency_key = "mc:<invocation_id>" (parent) and "mc:<invocation_id>:<specialist>" (child) → retry-safe, no duplicate cards (kanban_db.py:1856).
• session_id = HERMES_SESSION_ID + tenant = "matrix_coder" → board filtering / namespace isolation.

CRITICAL constraint — audit mirror, NOT a control plane

The Kanban dispatcher claims ready tasks and executes them via the assigned profile (claim_task, CAS on status=ready). Matrix Coder runs its own specialists through the harness/subagent path — it must not let the dispatcher pick up and re-run the same work. Therefore MC-created cards are audit-only:

• Create children with initial_status="running", NOT ready — the dispatcher only claims ready, so running cards are never double-executed.
• No dispatcher-actionable assignee — set created_by="matrix_coder"; leave assignee unset (or a non-profile sentinel) so nothing routes it to a worker.
• Do not use parents=[...] dependency-gating for control — child auto-promotion (todo→ready when parents done) is a dispatcher execution feature; we use links purely for the visual tree, and since children are created running they never enter the ready claim path.
• MC owns every transition explicitly: create(running) → complete_task / block_task. The card mirrors MC's real execution; it never drives it.

Impl note to verify at build: confirm complete_task / block_task behave on a card that has no active dispatcher-opened run (MC-managed cards aren't claimed). If they require an expected_run_id, MC either opens a synthetic run or uses the direct status setter — flag for Phase-2 spike.

Anti-pattern (do NOT repeat)

The retired Swarm board wrote raw SQL to kanban.db — bypassed run-closing/event semantics, wrote an invalid queued status, had a SQL-injection-prone quoter, and an unauthenticated write route. Matrix Coder must only go through hermes_cli.kanban_db functions, never raw SQL. (Confirmed prior finding; the direct-SQL bridge is exactly what the unified-kanban plan retired.)

Which activities create Kanban tasks (resolves the open question)

Tie creation to the Stage-0 Intake Gate verdict — coarse-grained, topic-level only:

Activity	Kanban task?
Intake verdict = direct (Hermes handles it)	No — that is the "not every micro-step" line
The intake gate / right-size assessment itself	No
MC invocation, verdict = matrix	Yes — parent card (the unit of audit)
Each specialist dispatch within it	Yes — child card
Internal tool calls, helper-script runs, lens sub-passes	No — these are run detail, not topics
Single-specialist quick invocation	One card (collapse parent/child — no empty hierarchy)

Rule of thumb: a Kanban card represents a delegated topic a human would want to audit, not an implementation step.

Minimal API surface (direct Python, matches kanban_swarm.py)

from hermes_cli import kanban_db as kb
import os

conn = kb.connect()
parent = kb.create_task(conn,
    title=f"matrix_coder: {goal[:80]}", body=spec_md,
    created_by="matrix_coder", tenant="matrix_coder",
    session_id=os.environ.get("HERMES_SESSION_ID"),
    initial_status="running", priority=5,
    idempotency_key=f"mc:{invocation_id}")
conn.close()

# per specialist dispatch
conn = kb.connect()
child = kb.create_task(conn,
    title=f"[{specialist}] {topic[:60]}", body=ctx_md,
    created_by="matrix_coder", parents=[parent], tenant="matrix_coder",
    session_id=os.environ.get("HERMES_SESSION_ID"),
    initial_status="running", skills=[specialist_skill],
    idempotency_key=f"mc:{invocation_id}:{specialist}")
conn.close()

# on specialist finish
conn = kb.connect()
kb.complete_task(conn, child, summary=recommendation, metadata=findings)  # or kb.block_task(conn, child, reason)
conn.close()

# on invocation finish
conn = kb.connect()
kb.complete_task(conn, parent, summary=synthesis,
    metadata={"specialists": names, "child_ids": child_ids, "findings": all_findings},
    created_cards=child_ids)
conn.close()

add_comment(conn, parent, author="matrix_coder", body=...) (kanban_db.py:2207) can stream interim findings onto the parent thread.

Worker-context nuance

If MC itself runs inside a dispatcher-spawned worker (HERMES_KANBAN_TASK set), prefer the agent tools in tools/kanban_tools.py (kanban_create/kanban_comment/kanban_complete) — they enforce task ownership and stamp worker_session_id. As a standalone plugin (the normal case), direct kb.* calls are correct.

Nothing new in core is required

Parent/child hierarchy, idempotent create, session/tenant filtering, metadata findings, created_cards audit, and the live WebSocket UI all already exist. Phase-2 work is the MC bridge module (hermes_bridge.py / a small kanban_audit.py) wiring dispatch lifecycle → kb.* calls, plus the audit-mirror status discipline above.

Non-Goals reconciliation

This does not contradict the Non-Goals. MC uses Kanban as an observability/audit mirror (write cards, read status for the UI), not as a control/orchestration engine — it does not schedule, gate, or execute specialists via Kanban, and does not become a Kanban feature. The body Non-Goals wording will be tightened to: no Kanban coupling for control flow; Kanban for traceability/observability is in scope.

---

Correction (advisory review, code-verified): the Phase-2 spike is unnecessary — already supported. complete_task handles a never-claimed card via the expected_run_id is None branch (hermes_cli/kanban_db.py:3144-3161, status ∈ running/ready/blocked, synthesizes a zero-duration run); block_task likewise (:3570-3596). Just call them with the default expected_run_id=None. Also add a test asserting an MC running card with no run/claim is never claimed by claim_task nor promoted to ready by the stale-claim reaper.

[Interstellar-code]

Advisory Plan Review — opus critic (code-verified, pre-implementation)

Cross-cutting findings on the epic. Per-phase findings are on #112–#117. Severity: BLOCKER > HIGH > MED > LOW > NIT.

• [HIGH] "Persona loaded onto subagent" is not a real API. delegate_task's schema (tools/delegate_tool.py:2660) has no persona/system_prompt/skills param; the child system prompt is hardcoded by _build_child_system_prompt() (:569-643, only goal/context/workspace/orchestrator-note). A persona can only reach the subagent via (a) the goal/context strings, or (b) per-turn pre_llm_call injection. The "bridge sets active-role state" is not a binding — nothing reads it except MC's own hooks. → Pick ONE mechanism and write it into Phase 1: persona composed into context at dispatch AND/OR re-injected via pre_llm_call. Drop "loaded onto subagent."

• [HIGH] Fail-open hooks make the read-only guardrail best-effort, not "literally cannot mutate." Hook callbacks run in try/except that swallows exceptions at WARNING (hermes_cli/plugins.py:1566-1575); the pre_tool_call enforcement site also try/excepts and proceeds on error (model_tools.py:785-799). If MC's guard raises or isn't registered in the child process, Write/Edit proceeds silently. → Downgrade the claim to "defense-in-depth, best-effort." Keep the handler trivial/defensive. Add Phase-1 tests: raising guard does NOT block (documents reality) + healthy guard blocks.

• [HIGH] Hooks fire inside subagent turns (good) — but active-role state must be keyed per-agent, not per-session. Subagents run in-process via child.run_conversation() (run_agent.py:4360-4370), so the guard fires for parent AND every child. Subagents share parent_session_id (tools/delegate_tool.py:1129); pre_tool_call gets task_id/tool_call_id but session is shared. If state is session-keyed, a child review role blocks the parent's writes (over-block) or vice-versa. → Spike before committing to hook-based enforcement: confirm the hook kwargs can disambiguate parent vs child vs active role. UNCLEAR in code today — gating risk for Phase 1.

• [MED] First-block-wins across plugins means MC doesn't control the block message. security-guidance + mcp_lazy also register pre_tool_call; any one block wins in FIFO order. Safe (any block stops the action) but MC's role-specific message isn't guaranteed. → Stop assuming MC controls the message; note in Phase 1.

• [MED] SUL-1.0 (OmO) vendored into an MIT repo is the real licensing gap. Repo is MIT (LICENSE:1, Nous Research). SUL-1.0 is source-available, not OSI-open — restricts commercial/hosted use, requires full license text + notice. Per-file headers alone don't satisfy it. → Before Phase 0: determine whether OmO text is copied vs only ideas/structure reused. If text: add THIRD_PARTY_LICENSES/NOTICES, segregate OmO files, confirm the product use case is permitted. If ideas only: attribution is courtesy — say so.

• [MED] Phase 1 is overloaded (all 8 roles + _base + harness + bridge + reporting + 3 hooks + intake gate = ~the whole architecture). The risky unproven bits are hook-fired persona injection + per-dispatch read-only guard — provable with ONE read-only role (review) + ONE write role (executor). → Re-cut Phase 1 to harness + _base + 2 roles + 3 hooks + intake gate; defer the other 6 personas to a Phase 1.5 (content, not architecture).

• [LOW] Cross-cutting gaps unaddressed: testing strategy, config schema for dispatch-category→model, observability of the intake gate's own decisions (auditing a wrong direct verdict), uninstall/disable behavior (does disabling MC leave the guard registered?), persona-contract versioning. → Add a "Cross-cutting" checklist to the epic.

Verification log (code claims checked)

• pre_tool_call block veto → CONFIRMED (plugins.py get_pre_tool_call_block_message; model_tools.py:785-799).
• Hooks sync-only, async never awaited → CONFIRMED (plugins.py:1561).
• Hooks fail-open/isolated → CONFIRMED (plugins.py:1566-1575; model_tools.py:785).
• Multi-plugin FIFO, no priority → CONFIRMED (plugins.py:957).
• pre_llm_call ephemeral + all-returns-joined → CONFIRMED (conversation_loop.py:691-699,968).
• transform_llm_output first-non-empty-wins → CONFIRMED (conversation_loop.py:4459-4463).
• Dispatcher claims only status=ready → CONFIRMED (kanban_db.py:2544).
• create_task defaults running/no-assignee; running ∉ claimable → CONFIRMED (kanban_db.py:101,1742-1791). Reaper resets to ready only for cards with claim_expires/worker_pid (MC cards lack these).
• complete_task/block_task on never-claimed card (the Phase-2 spike) → CONFIRMED RESOLVED, spike unnecessary (kanban_db.py:3144-3161,3570-3596, expected_run_id is None branch).
• WebSocket live path, token in ?token= URL → CONFIRMED (plugin_api.py:2145-2149; security note :31).
• Direct kb.* import from a plugin → CONFIRMED (matches kanban_swarm.py).
• register(ctx) exposes register_tool(+schema)/register_command/register_hook/register_skill → CONFIRMED (plugins.py:318,413,936,960). Plugin skills are explicit-load, NOT in system-prompt <available_skills>.
• "Persona loaded onto subagent" → REFUTED (no persona param; delegate_tool.py:2660, :569-643).
• Subagent role enum = MC's 8 roles → REFUTED (enum is only {leaf, orchestrator}).
• Per-dispatch role isolation via hook kwargs → UNCLEAR (shared parent_session_id; needs spike).
• SUL-1.0 compliance → UNCLEAR (depends on copied-text vs ideas).