PLUGIN·stable

A Claude Code plugin that turns multi-stage agentic work into provable steps.

Multi-stage agentic work as a sequence of provable steps. Iron Rule: real-system evidence on disk, refuses verdicts without proof. 36 skills, 11 agents, 22 commands, 7 hooks.

Install the plugin ↗INSTALL ↓READ THE LAUNCH POST →

withagents.dev/shannon

SKILLS

COMMANDS

10/10

DOCTOR CHECKS

MOCKS TOLERATED

“A successful build proves it compiled. A passing test confirms the mock behaved. Shannon proves the real system did the real thing — and refuses to say 'done' until the evidence is on disk.”

Shannon is a Claude Code plugin for high-stakes multi-stage agentic work — research, planning, implementation, validation, release — where each step must produce evidence a skeptical reviewer can open. Its Iron Rule refuses to emit a verdict without real-system proof on disk: no mocks, no stubs, no test files.

The surface is 36 skills, 11 agents, 22 slash commands, and 7 enforcement hooks. Sub-agents carry their skills inline (embedded at build time), so a spawn can never silently fail to load the skill it needs. A meta-judge generates a weighted rubric YAML before any judge runs, with hidden thresholds, and escalates to multi-round debate on disagreement.

Shannon is self-instrumented. `scripts/doctor.py` is a mechanical contract validator (10/10 checks: manifest validity, surface counts, hook registration, the required-hooks dependency graph, and skill/agent body-reference resolution). `scripts/harness/load_check.py` is a real Agent SDK load probe — it inherits the Claude Code CLI's own auth, queries the running plugin, and asserts every command is addressable.

01. ARCHITECTURE

How it's built

MODULE 00

Plan

/shannon:plan with four modes — linear, converge (iterative critique rounds), tournament (N candidate plans + judge), and deep (tournament feeds converge feeds consensus). Brownfield mode runs codebase + skill inventory first.

MODULE 01

Execute

/shannon:cook spawns an executor with embedded validation; /shannon:autopilot wraps it in a refusal-driven retry loop; /shannon:dispatch fans out sequential / parallel / competitive sub-agents, escalating to a Dynamic Workflow when fan-out outgrows one turn.

MODULE 02

Prove

completion-gate, evidence-gate, and refusal-discipline enforce real-system evidence. doctor.py (mechanical contract) and load_check.py (real SDK load probe) let the plugin observe itself — both PASS at v1.2.0.

02. FEATURES

Iron Rule validation

Real-system evidence on disk for every completion claim. Enforcement hooks refuse to write .test.* / mock / stub files. Compilation success is explicitly not validation.

Embedded sub-agent skills

Each agent's SKILL.md content is inlined into its AGENT.md at build time, so a dispatched sub-agent carries its skill and cannot fail to load it mid-run.

Meta-judge consensus

A rubric YAML with weighted dimensions and hidden thresholds is generated before any judge scores. Non-unanimous verdicts escalate to multi-round debate, never to silent averaging.

Refusal-driven autopilot

/shannon:autopilot wraps /shannon:cook in a retry loop. On REFUSED it parses cited blockers and remediates; it never force-completes. Refusal is a feature, not a bug.

03. QUICK START

// install

# install from the published GitHub repo
/plugin marketplace add krzemienski/shannon
/plugin install shannon@shannon

# activate enforcement in the current project
/shannon:enforce on

# verify the contract (10/10 mechanical checks)
/shannon:doctor

# plan deep (tournament -> converge -> consensus), then execute
/shannon:plan "Add a /health endpoint" --mode deep
/shannon:cook plans/<date>-add-health/

04. INSTALL

01/plugin marketplace add krzemienski/shannon
02/plugin install shannon@shannon
03/shannon:enforce on — activate Shannon's hooks for the current project
04/shannon:doctor — confirm the 10/10 mechanical contract passes
05/shannon:plan "<your feature>" --mode deep — author a tournament+converge plan
06/shannon:cook plans/<date>-<slug>/ — execute end-to-end with Iron-Rule validation

05. FEATURE MATRIX

FEATURE

STATUS / NOTE

Iron Rule — no mocks / stubs / test files

OKEnforced by hooks at write time

Embedded sub-agent skills

OKInlined by build/embed-skills.py

Four planning modes (linear/converge/tournament/deep)

OK/shannon:plan

Refusal-driven autopilot

OKNo force-complete; cites blockers

Meta-judge rubric with hidden thresholds

OKGenerated before any judge runs

Self-instrumented contract check

OKscripts/doctor.py — 10/10

Real Agent SDK load probe

OKscripts/harness/load_check.py — inherits CLI auth

Dynamic Workflows escalation

OKUnbounded fan-out → Workflow pipeline()

06. DOCS

Documentation

Read the Shannon docs

github.com/krzemienski/shannon#readme

06. RESOURCES

v1.2.02026-06-04Second stable release. 36 skills, 11 agents, 22 commands, 7 hooks. DeepPlan + wave-execution (dependency-ordered parallel waves with between-wave synthesis gates); /shannon:plan-deep landed as a true alias of plan --mode deep; the evidence-gated forge pipeline (codebase-analysis → docs-research → planning → oracle plan-review → execute → validation → evidence-indexing → 3-reviewer consensus → 3-oracle quorum → completion-gate); skills10x activation harness with transitive registration. doctor 10/10 PASS.
v1.0.02026-05-31First stable release. 33 skills, 9 agents, 20 commands, 7 hooks. doctor 10/10 PASS; real SDK load probe PASS (all 20 commands addressable). doctor.py now reads version live from the manifest; docs reconciled to disk counts; Dynamic Workflows awareness added to the orchestration cluster.