grimoire-rs/hex

Tiered architecture-decision orchestrator — evaluates trade-offs and produces ADRs or system designs through discover, research, design, and adversarial-review phases. Use for architecture decisions, ADRs, system design, trade-off analysis between approaches, one-way-door decisions, C4-level design, or NFR evaluation (scalability, availability, latency, security, cost, operability). Tier (low|medium|high|xhigh|max, auto by default) scales research-axis count and selection, whether the design is delegated to an architect worker, and review breadth.

Shared reference library for the hex swarm-orchestration bundle - worker role registry, model capability matrix, swarm protocol vocabulary, and the .agents/memory/hex.md memory spec. Not invoked directly; the hex-plan, hex-execute, hex-review, hex-architect, and hex-init skills link into it.

Use when the user says "let's just discuss this, don't edit anything yet", wants to think a fuzzy problem out loud, or asks to talk something through before a plan or ADR starts. Pre-plan discussion mode — answers first, then fires an automatic entry recon wave, elaborates the ask in dependency-batched questions, pushes back with a structured grill, and captures what was settled in a discussion artifact.

Tiered multi-agent execution orchestrator — implements an approved hex-plan artifact (or a free-text task) through contract-first TDD (stub, specify, implement, bounded review-fix loop), then commits. Runs file-disjoint work packages in parallel git worktrees and merges onto a feature branch in serialized topological order. Use to execute, implement, build, or run an approved plan, resume an interrupted execution, or turn a design into tested, reviewed, committed code. Tier (low|medium|high|xhigh|max, auto by default) scales review breadth, review-fix loop rounds, and the cross-model code-diff gate.

Use when a review-approved feature branch is ready to land and the user asks to finalize it, tidy the commit series, or get the pull request ready to merge. Explicit invocation only — the merge itself stays the human's.

Initialize or reconfigure a project for the hex swarm - audits project context (CLAUDE.md/AGENTS.md) for the knowledge the orchestrators need (how to verify, spec/plan conventions), provisions what is missing into project context, optionally seeds default templates, and bootstraps the AI-maintained swarm memory at .agents/memory/hex.md (cached pointers, orchestration preferences, perspectives of interest). Re-entrant - run again anytime to re-audit pointers or change the setup.

Use when a settled goal — a discussion, ADR, plan, spec, PR, issue, or existing goal file — should run to completion unattended, and the user wants its goal file plus one paste-ready autonomous-loop prompt for a coding-agent client.

Tiered multi-agent planning orchestrator — decomposes a feature, issue, or PR into a contract-first TDD plan through discover, research, design, decompose, and adversarial-review phases. Use for multi-step feature planning, task decomposition, swarm planning, multi-perspective research, meta-plan preview, or ADR scaffolding. Tier (low|medium|high|xhigh|max, auto by default) scales research depth, whether an architect designs, and review breadth.

Use when the user asks to run a retrospective over recorded agent friction, consolidate the retro inbox into ledger findings and proposed skill or project-config edits, or import a handwritten friction log; also run at a goal loop's retro checkpoints.

Tiered adversarial review orchestrator for a working tree, branch diff, pull request, or plan/markdown artifact before it lands on main — a staged reviewer panel (spec, quality, security, performance, docs), root-cause analysis, and an optional cross-model adversarial gate scale with diff size via tier (low|medium|high|xhigh|max, auto by default). Use for pre-merge checks, code review, branch or PR review, diff review, plan or ADR review, adversarial review, root-cause analysis, or any "review this before I merge" request. Never edits the code or diff under review, and never commits — its writes are the plan's Status block, an append-only convergence check, and — on an approved, converged fold — the resolved spec file and a fold receipt; the fix loop is /hex-execute's job.