fsm-workflow

FSM Workflow for Claude Code

Discipline is enforced by hooks, not personas. A multi-agent pipeline for Claude Code where 22 subagents operate under strict role separation, context isolation, and nonce-proof reads — so agents can't drift, contradict the spec, or claim work done without proof. Brainstorm → spec → architect → plan → execute → audit → test → close, with mechanical enforcement at every boundary.

Why this beats persona-based agent packages

Most multi-agent packages give you "Senior Developer", "UI Expert", "QA Engineer" — persona prompts that bias the model's output distribution but do nothing mechanical to stop bad behavior. This package replaces persona with enforcement. At a glance:

• Hook enforcement, not prompt hints — workers physically cannot read MAP.md / CLAUDE.md, cannot write the task tracker, cannot force a weaker model. permissionDecision: deny returns from hooks regardless of what the model "wants" to do. Persona is a suggestion; this is a gate.
• Context isolation by construction — workers receive exactly one input: an absolute path to their task file. Everything they need is listed inside it. No ambient context, no drift across compactions, no "I remember the spec said..." hallucinations.
• Single-writer state — only task-planner and session-closer may touch MAP.md. The orchestrator flips status fields; workers never write shared state. This kills the entire class of "helpful" cross-writes that corrupt trackers in loose multi-agent setups.
• Nonce-proof reads — every task file carries a checkpoint hex string. Workers must echo the current nonce in their Registers update. Forgot to read the file? Can't produce the nonce. Task not done. Challenge-response, not vibes.
• Stateless workers — every turn re-reads from disk. Session resume, context compaction, and mid-task recovery are all trivially correct: there is no "memory" to lose.
• Explicit FSM with verifiable transitions — tasks have states (PENDING → IN_PROGRESS → VERIFY → DONE), acceptance criteria that check against disk, and a session that won't close until audit and tests are both clean.
• Parallel waves with dependency cascade — workers run concurrently within a wave. The orchestrator flips status as tasks return and auto-dispatches the next wave when dependencies resolve.
• Coding discipline is a PostToolUse gate — every .py / .ts write runs a discipline check. Violations return as a compact XML block the agent treats like a compiler error: read, fix, retry in-loop.
• One-command install — drop 22 agents, 4 hooks, 1 slash command, and project templates into ~/.claude/ with ./install.sh. Idempotent; re-runnable; backs up your existing settings before touching anything.

Where it isn't better: this is built for multi-file builds with verification loops. For one-shot questions, quick scripts, or creative brainstorming, a single persona agent is simpler and the FSM overhead is absurd. Use the right tool for the task.

How this compares to other Claude Code multi-agent packages

Based on a 2026-04-08 survey of four competing packages (stars as of survey date). Every competitor ships "disciplined" or "orchestrated" in their marketing copy; this table reflects what they actually enforce mechanically versus what they describe in prompts.

Property	This package	wshobson/agents (33k★)	gsd-build/get-shit-done (49k★)	oh-my-claudecode (25k★)	disler/hooks-observability (1.3k★)
Write-authority enforcement (blocks unauthorized agents from writing shared state)	✅ hook returns deny	❌	⚠️ O_EXCL lock (prevents races, not unauth writes)	❌	❌
Context isolation (workers physically cannot read MAP.md / CLAUDE.md)	✅ hook returns deny	❌	❌	❌	❌
Nonce-proof reads (worker must echo checkpoint hex to complete a task)	✅	❌	❌	❌	❌
PostToolUse discipline gate on code (blocks non-compliant .py / .ts writes)	✅ XML violation block	❌	❌ (only validates commit msg)	❌	❌
Stateless workers with single-input contract (re-read from disk every turn)	✅	❌ prompt stacking	⚠️ fresh context per agent	❌	N/A
Hook-enforced role separation	✅	❌ prompt only	❌ prompt only	❌ prompt only	N/A
Agent count / breadth	22	182	24	19	2
Plugin marketplace / skills system	❌	✅ 75 plugins, 147 skills	⚠️ partial	⚠️ 11+ skills	❌
Multi-runtime support (Codex, Gemini, etc.)	❌	❌	✅ 13+ runtimes at install time	⚠️ via tmux	❌
Observability / live tracing	❌	❌	❌	⚠️ hook observers	✅ Vue dashboard + WebSocket + SQLite
Published benchmarks	❌	✅ PluginEval 3-layer framework	❌	⚠️ SWE-bench harness (no results)	❌