Using arcgentic

Overview

arcgentic is an agentic harness for round-driven development. It turns the four-role engineering workflow into a mechanically-enforced state machine where every transition is gated, every artifact is structured, and every lesson is codified.

Announce at start: "I'm using the arcgentic:using-arcgentic skill to navigate the round workflow."

The Iron Rule

BEFORE ANY ACTION IN A ROUND-DRIVEN PROJECT:
1. Read .agentic-rounds/state.yaml (single source of truth)
2. Run scripts/state/pickup.sh — get your role + action
3. Load the role-specific skill if applicable
4. Then act

The Four Roles

Each role has a dedicated skill. In multi-session mode, load only the skill for the role named by state/pickup or by arcgentic session-mode prompt --role.

Two Operating Modes

Mode A — Single-session (orchestrator drives all)

Main session loads arcgentic:orchestrate-round. Acts as orchestrator. Dispatches sub-agents (orchestrator.md → auditor.md → ...) via Claude Code's Task tool when role-switching is needed. State machine advances after each sub-agent's structured output is verified.

Use when: independent developer / small project / no team coordination needed.

Mode B — Multi-session (humans coordinate)

Each role runs in its own Claude session. Each session loads only its role's skill. State.yaml is the inter-session protocol — every session starts by reading it.

Use when: team of humans / different humans want different role contexts / role-specific skill loading must not contaminate other role's contexts.

Both modes share the same state.yaml schema and the same gate scripts. The mode is a project-level decision in project.session_mode; do not ask again per round once it is set.

State Machine

intake → planning → awaiting_dev_start → dev_in_progress → awaiting_audit
                                                                 ↓
                                  closed ← passed ←———— audit_in_progress
                                                                 ↓
                                  awaiting_audit ← fix_in_progress ← needs_fix

Every transition runs scripts/state/transition.sh, which:

1. Verifies the target is in the current state's next list (reject if not)
2. Runs the required gate script (reject if not 0)
3. Updates current_round.state + appends to state_history

Gates:

• planning → awaiting_dev_start requires handoff-doc-gate.sh
• dev_in_progress → awaiting_audit requires round-commit-chain-gate.sh
• fix_in_progress → awaiting_audit requires round-commit-chain-gate.sh
• audit_in_progress → passed | needs_fix requires verdict-fact-table-gate.sh
• passed → closed is owned by arcgentic close-round, which checks verdict completeness and strict audit-check before writing the closed state

What to do RIGHT NOW

The literal first thing to do, every session:

bash $PLUGIN_ROOT/scripts/state/pickup.sh --state-file ./.agentic-rounds/state.yaml

($PLUGIN_ROOT is where this plugin is installed; on Claude Code default: ~/.claude/plugins/arcgentic/)

The pickup output tells you which role + which action. Then load the corresponding skill or follow the handoff doc.

Bootstrap (new project)

If .agentic-rounds/state.yaml doesn't exist:

bash $PLUGIN_ROOT/scripts/state/init.sh \
  --project-root . \
  --project-name "<your-project-name>" \
  --round-naming "<your-naming-pattern, e.g. phase.round[.fix]>"

This creates the state.yaml in intake state. You're ready.

Cost Discipline (load-bearing)

arcgentic never:

• Calls paid APIs from its scripts
• Starts background processes / daemons / cron
• Pulls references automatically (founder/user triggers refresh-references.sh manually)

If a sub-agent dispatched via Task tool tries to break any of these, refuse + report.

When NOT to use arcgentic

• One-off scripts / throwaway prototypes (overhead > value)
• Projects where every change ships without review (no audit role needed)
• Hobby projects without a "PASS gate" notion (the round model assumes that)

Skill priority (when multiple apply)

1. arcgentic:using-arcgentic (this skill) is the orientation skill — always load first in an arcgentic project
2. Then load the role skill matching pickup.sh output
3. arcgentic:pre-round-scan is invoked by role skills as their first action; you don't need to load it manually
4. arcgentic:verify-gates is invoked by the state-machine scripts, not directly by you

See also

• skills/orchestrate-round/SKILL.md — for orchestrator mode
• skills/audit-round/SKILL.md — for auditor role
• skills/close-round/SKILL.md — for PASS-only closeout
• docs/examples/state.example.yaml — schema reference
• schema/state.schema.json — JSON Schema