Arcgentic

Arcgentic is a harness engineering layer for AI coding agents. It turns ad-hoc prompting into a gated engineering workflow.

中文文档 -> README.zh-CN.md

Arcgentic helps Codex and Claude Code run software work as a disciplined sequence: clarify the idea, plan the work, build it, self-audit it, optionally run a realistic user test, audit it independently, then close only when the evidence is good enough.

It is for people who already use AI coding tools, but do not want every session to depend on memory, vibes, or a lucky prompt.

Where it came from

Arcgentic started as the development discipline behind Moirai, a real agent project where AI coding had to survive 30+ strict development rounds, repeated NEEDS_FIX audits, planned handoffs, role boundaries, self-audit, external audit, and recoverable session state.

This plugin packages the patterns that survived that work so Codex and Claude Code users can apply them to their own complex projects. It is not a new coding agent, and it does not copy Moirai-specific phase numbers, fact shapes, or runtime internals. It is the workflow layer extracted from real agent development.

Harness engineering

Arcgentic sits in the harness layer around a coding agent.

Codex and Claude Code are the agents. Arcgentic is the engineering harness that gives those agents roles, handoffs, stop states, audit gates, and evidence. This is the same direction people describe as moving from vibe coding toward agentic engineering: the important work is not only prompting the model, but building the workflow around the model so its output can be checked, routed, and trusted.

Related reading:

• Martin Fowler / Thoughtworks: Harness engineering for coding agent users
• Andrej Karpathy's broader "vibe coding -> agentic engineering" framing

30-second version

Question	Answer
What is it?	A harness engineering layer for Codex / Claude Code: roles, handoffs, audits, stop states, and pass/fix gates around the coding agent.
What problem does it solve?	AI coding sessions drift: scope changes silently, context gets lost, tests are skipped, and "done" often means "the assistant said it is done."
Who should use it?	Heavy Codex / Claude Code users, agent builders, AI-native teams, and people doing complex multi-round engineering work.
What does it add?	A repeatable gated workflow with automated role dispatch: planning, dev self-audit, optional user testing, external audit, and closeout.
What does it not do?	It does not replace your judgment, your tests, or your review process. It makes those steps harder to skip.

Platform status

Platform	V2 status	Verification
Codex	Complete V2	Verified in a real Codex project workflow, including automatic Orchestrator thread setup and role-thread dispatch.
Claude Code	Complete V2	Verified in a real Claude Code session for single-session-subagent mode via a foreground Agent tier-0 broker dispatch — see tests/dogfood/gate-3-claude-code-native-broker/RESULT.md. That gate covered a single Planner role dispatch, not a full Planner→Developer→Auditor round loop. The SendMessage-based footer-correction retry path and ListAgents were not exercised by this gate (the footer was valid on the first attempt), and multi-session-subthread mode and the hook-backed fallback path remain unverified.

Codex is the best current experience. In the verified Codex path, the current project conversation becomes Orchestrator; Arcgentic then creates or reuses the role threads, names them, sends the right role prompt, waits for their return signal, and dispatches the next role without manual thread switching.

Claude Code support now has dogfood evidence for single-session-subagent mode via a foreground Agent tier-0 broker dispatch, so treat that specific path as a verified real workflow. The SendMessage-based footer-correction retry path and ListAgents were not exercised by that gate, and multi-session-subthread mode and the hook-backed fallback path have not yet been verified in a real Claude Code session — all of these should still be treated as unproven.

Distribution status

Channel	Status	Use it for
GitHub Release	Published v2.2.1	Release notes, source archive, and verification context.
PyPI	Published arcgentic==2.2.1	Python CLI: gates, V2 state helpers, Claude Code broker, and audit tooling.
npm	Published arcgentic@2.2.1	Plugin asset bundle and Codex local install helper.
Claude Code plugin marketplace	Manifest ready	Main Claude Code install path; single-session-subagent mode now has dogfood evidence via a foreground Agent tier-0 broker dispatch, but multi-session-subthread mode and the hook-backed fallback path remain unverified.

Install

Codex local install

git clone https://github.com/Arch1eSUN/Arcgentic.git arcgentic
cd arcgentic
bash scripts/install-codex-local.sh --plugin-root .

Then start in a saved project workspace and ask:

Use Arcgentic to build this idea: <your idea>

npm bundle install

Use this if you want the Arcgentic plugin assets through npm:

npm install -g arcgentic
arcgentic install-codex-local

The npm package is a zero-dependency plugin bundle and Codex local install helper. It includes the skills, agents, scripts, schemas, templates, and platform manifests. The Python CLI is still published separately on PyPI.

Claude Code install

/plugin marketplace add Arch1eSUN/Arcgentic
/plugin install arcgentic@arc-studio

Then start inside your project:

Use Arcgentic to build thi