| name | arc-agent-driven |
| description | Execute a task list with one fresh subagent per task plus a single task-reviewer each. Use when tasks need isolated contexts to avoid cross-task pollution; for in-session human-checkpoint execution use arc-executing-tasks. |
| category | orchestration |
| status | promoted |
arc-agent-driven
Execute a plan by dispatching a fresh subagent per task, with one task-reviewer after each that returns both verdicts in a single pass: spec compliance and task quality.
Core principle: Fresh subagent per task + one task-reviewer returning both verdicts (spec compliance + task quality) = high quality, fast iteration.
When to Use
- You have a task list (from arc-writing-tasks) whose tasks are mostly independent.
- You want automated execution without a human checkpoint between tasks.
vs. arc-executing-tasks (human-checkpoint mode): fresh subagent per task (no context pollution), one task-reviewer after each, faster iteration.
The Process
- Read tasks, create a task list.
- Per task: dispatch an implementer subagent (answer its questions before and during work); it implements, tests, commits, self-reviews.
- Dispatch one task-reviewer that returns both verdicts (spec compliance + task quality) from a single read of the change.
- If issues: one fix pass addresses spec gaps and quality findings together, then re-review covers both verdicts. Fan out to
arc-dispatching-parallel only when findings are genuinely independent; otherwise a single batch-fix dispatch is the default.
- Both verdicts clean → mark the task complete; move to the next.
- After all tasks: dispatch a final whole-branch code reviewer, then run the completion pipeline — arc-verifying (confirm requirements met and tests pass), then arc-finishing (Step 0 discriminates on
.arcforge-epic).
Max review cycles: 3 per task. If not converging, escalate to a human with a summary of unresolved issues.
Per-Task File Handoff
Hand each subagent a file, not a wall of pasted text. The brief and the review
package live in the self-ignoring .arcforge/sdd/ workspace:
- Before dispatching the implementer, record the current commit as the task
BASE:
git rev-parse HEAD. Optionally assemble the brief with
: "${ARCFORGE_ROOT:=$HOME/.agents/arcforge}"; node "${ARCFORGE_ROOT}/skills/arc-agent-driven/scripts/task-brief.js" --task "<text>" --acceptance "<criteria>" --base <BASE>
(it prints the brief path).
- After the implementer commits, build the review package for the whole task
range — never just the last commit — with
: "${ARCFORGE_ROOT:=$HOME/.agents/arcforge}"; node "${ARCFORGE_ROOT}/skills/arc-agent-driven/scripts/review-package.js" <BASE> HEAD.
It writes the commit list plus git diff --stat and git diff -U10 for
<BASE>..HEAD into one file and prints that file's path.
- Hand the task-reviewer that path as
{DIFF_FILE}. The reviewer reads the
package once; it does not re-run git or crawl the codebase.
Record BASE from before the implementer ran so a multi-commit task stays whole.
HEAD~1 as the base would truncate the package to the final commit.
Durable Progress Ledger
Session todos and terminal narration don't survive a fresh session or a mid-run
compaction, and neither carries a git-verifiable commit range — so you can
re-dispatch an already-completed task (the most expensive failure). Persist
per-task completion to a ledger file.
- Ledger:
.arcforge/sdd/progress.md — the same self-ignoring workspace the
brief and review packages use; a runtime recovery artifact, not tracked.
- At skill start,
cat .arcforge/sdd/progress.md. If it exists, trust it plus
git log and resume AFTER the last task marked complete — do not re-dispatch
tasks it lists.
- After each clean review, append
Task N: complete (commits <base7>..<head7>, review clean) in the same message as your other bookkeeping. Those commits
exist in git even when your context no longer remembers creating them.
git clean -fdx destroys the ledger; reconstruct progress from git log.
Model Selection
Name a model on every dispatch — never rely on inherit. An omitted model
inherits your session's tier, often the most expensive one. The Task/subagent
model parameter overrides the agent's frontmatter default; the sonnet values
below are the mid-tier floor, not a ceiling.
- Transcription implementer →
haiku. A well-formed arc-writing-tasks task
carries "Exact code — Complete code", so it is transcription plus testing — as
are single-file mechanical fixes.
- Prose-plan implementer and the task-reviewer →
sonnet floor. Cheaper
models take 2-3× the turns on multi-step judgment, costing more overall. Scale
the reviewer above the floor only for a large or subtle diff.
- Final whole-branch review →
opus — pinned in agents/code-reviewer.md;
the one architecture-level judgment here.
Headless caveat (arc-looping): the loop path spawns agents through headless
claude -p, which strips agent frontmatter and does NOT honor a model: pin
(${ARCFORGE_ROOT}/scripts/lib/loop-verifier.js) — under arc-looping, pass
--model explicitly on the dispatch, or the intended tier is ignored.
Agents & Templates
Two ways to dispatch each role, depending on platform support.
Pre-built agents (when your platform supplies named subagents — e.g. Claude
Code's agents/) bundle tool isolation and methodology:
| Agent | Role | Model | Access |
|---|
| implementer | TDD implementation | sonnet | Read, Write, Edit, Bash, Grep |
| task-reviewer | Per-task gate: spec compliance + task quality in one pass | sonnet | Read, Grep, Glob, Bash |
Templates (cross-platform fallback — custom prompts, or when named agents
aren't available; they carry the full role prompt):
./implementer-prompt.md./task-reviewer-prompt.md
The workflow — fresh implementer per task, then one task-review returning both
verdicts — is identical however the subagent is launched (Codex or Claude Code).
Red Flags
Never:
- Mark a task complete before both verdicts (spec compliance AND task quality) are clean, or move to the next task while the task-reviewer has open issues on either verdict
- Start implementation on main/master without explicit user consent
- Dispatch multiple implementation subagents in parallel (conflicts)
- Make a subagent read the task file — provide the full text instead
- Coach the reviewer — never tell the task-reviewer to ignore specific issues, and never pre-assign a severity; it categorizes findings by their actual severity, independently
- Let the plan grade its own work — a defect the plan explicitly mandated (a test that asserts nothing, verbatim duplication) is still a finding: reported Important and labeled plan-mandated for the human to decide, never silently accepted
- Hand a reviewer a bare diff and let it re-run git or crawl the codebase — build the review package and give it the file path instead
- Use
HEAD~1 as the review base — it truncates a multi-commit task to its last commit; record the pre-implementer BASE and package BASE..HEAD
- Re-dispatch a task the ledger marks complete — reconcile the ledger against
git log before dispatching anything
Integration
Required workflow skills:
- arc-using-worktrees — REQUIRED: set up an isolated workspace before starting
- arc-writing-tasks — creates the task list this skill executes
- arc-reviewing — code-review template for reviewer subagents
- arc-finishing (Step 0 discriminates on
.arcforge-epic) — complete development after all tasks
Subagents should use arc-tdd for TDD on each task.
Alternative: arc-executing-tasks — human-checkpoint mode instead of automated.
