Claude Code FSM Workflow: An Automated Engineering Pipeline with 22 Collaborative Agents

This article introduces the claude-code-fsm-workflow project, which transforms Claude Code into a complete automated engineering pipeline via a finite state machine (FSM) architecture, enabling end-to-end automation from requirement analysis to code delivery. Its core features include 22 specialized sub-agents working collaboratively, and enforcing role separation and process control through mechanical hooks to address issues in AI agent collaboration such as off-topic deviations, repeated context reading, and code contradictions.

This workflow was designed and validated by developers running a Telegram bot cluster on Google Compute Engine. Core issues: AI agents tend to deviate from topics in long conversations, repeatedly read context, and write contradictory code; traditional soft constraints have limited effectiveness. Design philosophy: Adopt mechanical enforcement—ensure rule execution via system-level hooks instead of relying on agents' self-discipline.

The workflow breaks down software development into 22 independent sub-agents, categorized into 5 types:

• Planning phase: spec-writer (convert requirements to technical specifications), research-scout (investigate codebase and prior art), architect (generate build checklist), task-planner (break down atomic tasks and generate MAP.md);
• Execution phase: fsm-executor (execute coding tasks by dependency), fsm-integrator (cross-task integration), dispatcher (schedule sequence and parallelism);
• Quality assurance: code-auditor (static analysis), bug-scanner (defect scanning), dep-checker (dependency verification), code-fixer (mechanical repair), debugger (complex debugging), test-runner (test execution);
• Exploration and verification: explore-scout (parallel code reading), explore-superscout (in-depth analysis), file-lister (file system interaction), mock-server (simulate services), mockup-verifier (prototype validation);
• Session management: session-closer (clean task state), session-handoff (state transfer), doc-writer (generate documentation), code-reviewer (code review).

1. Strict role separation: Enforced via hook scripts (e.g., block-map-writes.sh, block-worker-reads.sh): orchestrators do not write code, workers do not modify task maps, auditors do not fix bugs;
2. Stateless workers: Each poll reads all information from disk with no conversation memory, eliminating information drift;
3. Random number verification for reading: Task files include a nonce; workers must echo the nonce to prove reading, preventing dependency hallucination or outdated information;
4. Discipline access system: .py/.ts file writes require checking via discipline-gate.sh; if coding standards are violated, the write is blocked and an error is returned, and agents automatically correct the issue.

The workflow consists of 10 steps:

1. Brainstorming: Developers discuss requirements with the orchestrator and call spec-writer or research-scout;
2. Trigger build: Developers say "build it" and the scheduler starts the pipeline;
3. Parallel reconnaissance: explore-scout and others read the codebase in parallel to generate analysis reports;
4. Architecture synthesis: The architect generates a structured build checklist;
5. Atomic task planning: task-planner generates MAP.md, including task descriptions, input/output files, dependencies, and nonce;
6. Wave execution: fsm-executor and integrator execute tasks in waves by dependency, and the orchestrator updates the MAP.md state;
7. Parallel audit: code-auditor, bug-scanner, and dep-checker perform parallel reviews;
8. Repair loop: code-fixer and debugger iteratively handle issues until passing checks;
9. Test verification: test-runner executes the test suite;
10. Session cleanup: session-closer resets MAP.md and deletes temporary files.

Installation methods:

• Manual installation: Run install.sh (idempotent, verifies dependencies, backs up settings, copies files, sets permissions, etc.);
• Delegated installation: Paste the content of INSTALL_FOR_CLAUDE.md into Claude Code and let another instance complete the installation. Usage steps: cd to the project directory → run claude → execute /init-workflow to initialize the project. Application scenarios: Incremental development for large codebases, projects with strict quality requirements, team collaboration environments, repeatable process scenarios, long-cycle projects.

This project demonstrates the shift of AI-assisted programming from single-agent conversational to multi-agent pipeline-based. Core insights:

• Mechanical enforcement is better than soft constraints: system-level execution is more reliable than agent self-awareness;
• Externalized state is better than internal: disk-stored state avoids context loss and enables cross-session persistence;
• Role specialization is better than all-in-one: task decomposition reduces cognitive load and improves reliability. It has reference value for teams to enhance the efficiency of AI-assisted development.