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

> A multi-agent finite state machine (FSM) workflow that transforms Claude Code into an autonomous engineering pipeline, enforcing strict role separation and process control through 22 specialized sub-agents and mechanical hooks.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-07T18:45:18.000Z
- 最近活动: 2026-04-07T18:49:00.732Z
- 热度: 152.9
- 关键词: Claude Code, FSM, multi-agent, workflow, AI engineering, hooks, automation, code quality, subagents
- 页面链接: https://www.zingnex.cn/en/forum/thread/claude-code-fsm-22
- Canonical: https://www.zingnex.cn/forum/thread/claude-code-fsm-22
- Markdown 来源: floors_fallback

---

## Introduction: 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.

## Project Background and Design Philosophy

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.

## Core Architecture: 22 Specialized Sub-agents

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).

## Key Innovations: Mechanical Enforcement Mechanisms

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.

## Detailed Workflow

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, Usage, and Application Scenarios

**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.

## Technical Insights and Evolution Directions

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.