Arcgentic: A State Machine-Based Strict Round-Driven Development Agent Framework

Title: Arcgentic: A State Machine-Based Strict Round-Driven Development Agent Framework

Arcgentic transforms four roles—planning, development + self-audit, external audit, and reference tracking—into a mechanically enforced state machine-driven workflow, automating the execution of engineering discipline through quality gating and sub-agent scheduling.

Original Author/Maintainer: Arch1eSUN (Arc Studio), Source Platform: GitHub, Version: v0.2.2-alpha.3, License: MIT, Original Link: https://github.com/Arch1eSUN/Arcgentic

Keywords: Agent Framework, State Machine, Development Workflow, Claude Code, Quality Gating, Audit, Sub-Agent, Engineering Discipline

Problem Background

Large language model-assisted development workflows usually have strict "intentions", but execution is often loose. Developers need to "remember to run audit checks", "remember to scan references first", "remember to update technical debt"—as the project progresses, this discipline tends to gradually relax.

Core Insight

Arcgentic's core insight is: Transform discipline into mechanical execution. If a gating check fails, the state machine refuses to proceed. No "remembering to do something"—the system enforces it, blocking progress if not passed.

Core Architecture

Arcgentic adopts a four-layer architecture design:

1. Skills: Markdown documents guiding Claude role thinking (e.g., plan-round, execute-round, etc.);
2. Agents: Platform-independent sub-agent definitions (e.g., orchestrator, auditor, planner, etc.);
3. Scripts: Bash-implemented state machine and gating enforcement (state management, quality gating, tool library);
4. Hooks: Optional commit-level enforcement.

State Machine Design

Core state machine flow: intake → planning → awaiting_dev_start → dev_in_progress → awaiting_audit → audit_in_progress → passed/needs_fix → closed (needs_fix can transition back to fix_in_progress)

Each state transition must be verified via transition.sh: whether the target state is legal, whether the gating script passes, and update the state history.

Key Gating Mechanisms

• Handover Document Gating: Verify that the planning document includes objective statements, scope definitions, sufficient sections, and acceptance criteria;
• Commit Chain Gating: Verify that development outputs form a coherent commit chain, each commit has a clear intent and complies with specifications;
• Adjudication Fact Table Gating: Verify that audit adjudications include an independently verifiable fact table and clear adjudication results.

Four Core Roles

Role	Responsibility	Key Output
Planner	Read scope → Write 16-section handover document	Detailed handoff document
Developer	Execute tasks → Inline self-audit → Generate N commit chain	Specification-compliant commit chain
External Auditor	Read handover + commit chain → Write adjudication	Adjudication document with fact table
Reference Tracker	Daily git fetch → Categorize → Maintain INDEX.md	Updated reference index

Operation Modes

• Single Session Mode: One Claude session loads the orchestrator skill, delegates sub-agents on demand—suitable for individual/small projects;
• Multi-Session Mode: Multiple Claude sessions each load different role skills, using state.yaml as the protocol—suitable for team/long-term projects.

Both modes share state.yaml and gating scripts, and can be switched midway.

Practical Application Value

1. Quality Assurance: Every output undergoes mechanical verification;
2. Knowledge Retention: State files become the carrier of project memory;
3. Team Collaboration: Clear role boundaries and handover protocols;
4. Auditability: Complete historical records and decision traceability;
5. Continuous Improvement: Experience coding mechanism drives team learning.

Cost Discipline Principles

• ❌ No paid API calls in plugin code;
• ❌ No background processes/daemons/cron triggers;
• ❌ No automatic cloud LLM pulls;
• ✅ All LLM inference is done within Claude Code subscription;
• ✅ References are updated only via manual git fetch.

Experience Encoding Protocol

Arcgentic's experience learning mechanism:

1. Observation: The lesson-codifier sub-agent scans the latest N rounds;
2. Pattern Detection: Same issue occurs 3 times → Propose new mandate;
3. Verification: Novel retention type → Declare experience iteration;
4. Encoding: Encode experience into reusable rules.

This mechanism is derived from the experience summary of 30+ strict development rounds in the Moirai project.

Roadmap

• Current Version: v0.2.2-alpha.3 (core state machine, 10 skills, 9 agents, Python CLI, Claude Code/Codex plugins);
• Upcoming Release: v0.3.0 (OpenSpec ingestion layer, Superpowers market integration, GitHub reference discovery, rich execution round fact generation);
• Target Version: v1.0.0 (Stable version released after passing Gate3 in 2-3 non-Moirai projects).

Arcgentic represents an important evolution of LLM-assisted development workflows—from "suggestive" to "enforced". Through the combination of state machines, quality gating, and sub-agent scheduling, it transfers engineering discipline from human memory to system execution. For teams pursuing high-quality, maintainable, and auditable code, Arcgentic provides a set of implementable technical solutions.