improve-agent-architecture

name	improve-agent-architecture
description	Audit any Hermes agent setup — crons, profiles, A2A meshes, workflows — and propose improvements in a visual HTML report.
version	1.2.0
metadata	{"hermes":{"tags":["agents","architecture","audit","crons","a2a","orchestration","hermes"],"related_skills":["hermes-agent","improve-codebase-architecture"]}}

Improve Agent Architecture

Audit a Hermes agent setup. Map what the user built, find where it will fail or already fails silently, propose fixes in one visual HTML report.

Vocabulary

lane (one autonomous path: cron job, A2A peer, spawned profile) · contract (prompt + gates + done-condition; self-report is not satisfaction) · gate (check before a state transition) · seam (handoff between lanes) · latch (persistent flag gating behavior) · probe (cheap liveness/auth check before spending turns) · ghost architecture (documented but not running) · silent-failure window (lane dead → anyone notices) · single point of model failure

Process

1. Inventory — documented vs running

Read first: ~/.hermes/config.yaml, profiles under ~/.hermes/profiles/, skills referenced by cron prompts, ~/.hermes/scripts/ helpers, AGENTS.md files.

Then probe everything. Docs describe aspiration.

hermes cron list                 # per-job last_status, model pins, deliver targets
hermes cron runs <job_id>        # real error strings for every non-ok job
hermes gateway list / port scan  # is every documented peer actually up?
ls ~/.hermes/*/state/            # latches, freeze flags
hermes doctor                    # provider/auth health

Also check: session transcripts for manual rescues of the system (those are friction), queue depth on whatever backing system the workflow uses (GitHub, Linear, files), and whether "ok" runs produced real side effects.

Every intended-vs-actual mismatch is a finding. Worst are ghost architecture.

2. Review — AI engineer's lens

Ask, in order of severity:

1. What dies when the provider/account dies? Auth, credits, and rate limits have different owners and different fixes.
2. Which lanes fail repeatedly? Did anyone learn within a day?
3. Which latches are stale — reason resolved, no release mechanism?
4. Which contracts are shallow — done-condition is "agent says so", not a runnable gate?
5. Which seams are fictional — documented handoffs that always ride fallback?
6. Prompt quality: model+effort pinned? Never-do list stated? Output packet defined? Ambiguity becomes variance at 3am.
7. Deliver design: deliver=local everywhere makes "no news" span healthy to dead.
8. Doc drift: paused jobs listed as active, mesh described as primary when it's fallback.
9. Redundancy: superseded-but-enabled lanes fail the deletion test.

Compress findings to root causes. Ten failures usually trace to two or three causes.

3. Report — visual HTML

Load /stop-slop before writing prose.

Write per HTML-REPORT.md: stat tiles → task-flow pipeline strip → orchestrator decision ladder → blast-radius rows (root cause → arrows → victims) → fix cards with red/green before-after panels → do-first card. Prose is captions only. Open it, give the path, ask which fix to explore.

4. Grilling loop

Run /grilling on the chosen fix. Inline side effects:

• New mechanism named? Add it to the fleet's SKILL.md.
• Fix touches a lane contract? Update every place it's stated (skill table, cron prompt, script) in one change.
• User rejects with a load-bearing reason? Record it so future audits don't re-suggest.

Fix patterns

1. Probe + circuit breaker — auth ping before agent work; on failure latch provider_down, skip cheaply, alert once, retry hourly.
2. Self-expiring latches — TTL or machine-checked unblock condition evaluated each tick against live queue truth.
3. Mesh honesty — probe peers, log which path each task took, or demote the edge in docs.
4. Provider diversity on cheap lanes — premium pins stay where they earn it; low-judgment lanes ride a second provider.
5. Failure digest — daily roll-up only when ≥1 lane failed; silence caps at 24h.
6. Contract tightening — runnable gates instead of self-report; regenerate doc tables from live state.
7. Pruning — delete superseded lanes; disabled-and-forgotten rots.

Pitfalls

• Auditing from docs. Cron runs history describes truth.
• Reading last_status: ok as healthy. Blind hunts pass too.
• Lumping failures together. Read the error strings.
• Proposing topology redesigns when the gap is observability.
• Fixing the incident, not the class. One probe beats six re-auths.
• Breaking quiet-by-default. Alerts fire only on factory-down or P0 signals.