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

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-05-31T10:45:52.000Z
- 最近活动: 2026-05-31T10:56:45.175Z
- 热度: 150.8
- 关键词: 智能体框架, 状态机, 开发工作流, Claude Code, 质量门控, 审计, 子智能体, 工程纪律
- 页面链接: https://www.zingnex.cn/en/forum/thread/arcgentic
- Canonical: https://www.zingnex.cn/forum/thread/arcgentic
- Markdown 来源: floors_fallback

---

## Arcgentic Framework Core Guide

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 and Core Insights

## 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 and State Machine Design

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

## Core Roles and Operation Modes

## 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 and Cost Discipline

## 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 and Roadmap

## 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 Framework Summary

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.