/using-arcgentic

name: using-arcgentic
description: Entry skill for the arcgentic plugin — establishes the four-role workflow (planning / dev+self-audit / external-audit / reference-tracking), the round state machine, and when to switch roles or dispatch sub-agents. Use when starting any session in a project that has .agentic-rounds/state.yaml present, OR when the user mentions arcgentic / round-driven development / external audit / four-role workflow.

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

| Role | When | Skill | State | |------|------|-------|-------| | **planner** | Round intake → handoff doc | `arcgentic:plan-round` | `intake`, `planning` | | **developer** | Handoff → commit chain | `arcgentic:execute-round` | `dev_in_progress`, `fix_in_progress` | | **auditor** | Commits → verdict | `arcgentic:audit-round` | `awaiting_audit`, `audit_in_progress` | | **closeout** | PASS verdict → anchored close | `arcgentic:close-round` | `passed` | | **ref-tracker** | Daily git fetch + categorize | `arcgentic:track-refs` | (continuous) |

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