arc-agent-driven
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
When to Use
digraph when_to_use {
"Have task list?" [shape=diamond];
"Tasks mostly independent?" [shape=diamond];
"Want automated execution?" [shape=diamond];
"arc-agent-driven" [shape=box];
"arc-executing-tasks" [shape=box];
"Use writing-tasks first" [shape=box];
"Have task list?" -> "Tasks mostly independent?" [label="yes"];
"Have task list?" -> "Use writing-tasks first" [label="no"];
"Tasks mostly independent?" -> "Want automated execution?" [label="yes"];
"Tasks mostly independent?" -> "arc-executing-tasks" [label="no - need human checkpoints"];
"Want automated execution?" -> "arc-agent-driven" [label="yes"];
"Want automated execution?" -> "arc-executing-tasks" [label="no - want control"];
}
vs. arc-executing-tasks:
- Fresh subagent per task (no context pollution)
- Two-stage review after each task
- Faster iteration (no human-in-loop between tasks)
The Process
digraph process {
rankdir=TB;
subgraph cluster_per_task {
label="Per Task";
"Dispatch implementer subagent" [shape=box];
"Implementer asks questions?" [shape=diamond];
"Answer questions" [shape=box];
"Implementer implements, tests, commits, self-reviews" [shape=box];
"Dispatch spec reviewer subagent" [shape=box];
"Spec compliant?" [shape=diamond];
"Implementer fixes spec gaps" [shape=box];
"Dispatch code quality reviewer subagent" [shape=box];
"Quality approved?" [shape=diamond];
"Implementer fixes quality issues" [shape=box];
"Mark task complete" [shape=box];
}
"Read tasks, create TodoWrite" [shape=box];
"More tasks?" [shape=diamond];
"Multiple independent issues?" [shape=diamond];
"Use arc-dispatching-parallel for fixes" [shape=box];
"Dispatch final code reviewer" [shape=box];
"Use arc-finishing or arc-finishing-epic" [shape=box style=filled fillcolor=lightgreen];
"Read tasks, create TodoWrite" -> "Dispatch implementer subagent";
"Dispatch implementer subagent" -> "Implementer asks questions?";
"Implementer asks questions?" -> "Answer questions" [label="yes"];
"Answer questions" -> "Dispatch implementer subagent";
"Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
"Implementer implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent";
"Dispatch spec reviewer subagent" -> "Spec compliant?";
"Spec compliant?" -> "Implementer fixes spec gaps" [label="no"];
"Implementer fixes spec gaps" -> "Dispatch spec reviewer subagent";
"Spec compliant?" -> "Dispatch code quality reviewer subagent" [label="yes"];
"Dispatch code quality reviewer subagent" -> "Quality approved?";
"Quality approved?" -> "Multiple independent issues?" [label="no"];
"Multiple independent issues?" -> "Use arc-dispatching-parallel for fixes" [label="yes"];
"Multiple independent issues?" -> "Implementer fixes quality issues" [label="no"];
"Use arc-dispatching-parallel for fixes" -> "Dispatch code quality reviewer subagent";
"Implementer fixes quality issues" -> "Dispatch code quality reviewer subagent";
"Quality approved?" -> "Mark task complete" [label="yes"];
"Mark task complete" -> "More tasks?";
"More tasks?" -> "Dispatch implementer subagent" [label="yes"];
"More tasks?" -> "Dispatch final code reviewer" [label="no"];
"Dispatch final code reviewer" -> "Use arc-finishing or arc-finishing-epic";
}
Max review cycles: 3 per reviewer. If not converging, escalate to human with summary of unresolved issues.
Agents & Templates
Dispatch these agents via the Agent tool (preferred) or use templates for custom prompts:
Agents (recommended — includes tool isolation and methodology):
implementer— TDD implementation with full write accessspec-reviewer— Spec compliance verification (read-only)quality-reviewer— Code quality assessment (read-only + test runner)
Templates (for custom prompts or when agents aren't available):
./implementer-prompt.md- Implementer prompt with placeholders./spec-reviewer-prompt.md- Spec compliance review prompt./code-quality-reviewer-prompt.md- Code quality review prompt (references arc-requesting-review)
Example Workflow
You: I'm using arc-agent-driven to execute these tasks.
[Read task file: docs/tasks/sync-command-tasks.md]
[Create TodoWrite with all 5 tasks]
Task 1: Add SyncResult dataclass
[Dispatch implementer subagent with full task text + context]
Implementer: "Before I begin - should SyncResult be in models.py or a new file?"
You: "In models.py with other dataclasses"
Implementer:
- Implemented SyncResult dataclass
- Added tests, 3/3 passing
- Self-review: All good
- Committed: abc1234 "feat(models): add SyncResult dataclass"
[Dispatch spec compliance reviewer]
Spec reviewer: ✅ Spec compliant - all fields present, nothing extra
[Dispatch code quality reviewer]
Code reviewer: Strengths: Clean, typed. Issues: None. Approved.
[Mark Task 1 complete]
Task 2: Add sync CLI command
...
[After all tasks]
[Dispatch final code reviewer for entire implementation]
Final reviewer: All requirements met, architecture solid
Done! Completion pipeline:
1. Run arc-verifying — confirm all requirements met and tests pass
2. Use arc-finishing (regular branch) or arc-finishing-epic (worktree) to decide merge/PR/keep/discard
Available Agents
The full agent roster for arc-agent-driven workflows:
| Agent | Role | Model | Access |
|---|---|---|---|
| implementer | TDD implementation | sonnet | Read, Write, Edit, Bash, Grep |
| spec-reviewer | Spec compliance check | sonnet | Read, Grep, Glob |
| quality-reviewer | Code quality review | sonnet | Read, Grep, Glob, Bash |
| planner | Architecture analysis | opus | Read, Grep, Glob (read-only) |
| debugger | Bug investigation | sonnet | Read, Grep, Glob, Bash |
| verifier | Independent verification | sonnet | Read, Grep, Glob, Bash |
Subagents Should Use
- arc-tdd - Implementer follows TDD for each task
Advantages
vs. Manual execution:
- Subagents follow TDD naturally
- Fresh context per task (no confusion)
- Subagent can ask questions (before AND during work)
vs. arc-executing-tasks:
- Same session (no handoff)
- Continuous progress (no waiting)
- Review checkpoints automatic
Quality gates:
- Self-review catches issues before handoff
- Two-stage review: spec compliance, then code quality
- Review loops ensure fixes actually work
Red Flags
Never:
- Skip reviews (spec compliance OR code quality)
- Proceed with unfixed issues
- Start implementation on main/master branch without explicit user consent
- Dispatch multiple implementation subagents in parallel (conflicts)
- Make subagent read task file (provide full text instead)
- Skip scene-setting context
- Ignore subagent questions
- Accept "close enough" on spec compliance
- Skip review loops
- Let implementer self-review replace actual review
- Start code quality review before spec compliance ✅
- Move to next task while either review has open issues
If subagent asks questions:
- Answer clearly and completely
- Provide additional context if needed
- Don't rush them into implementation
If reviewer finds issues:
- Implementer fixes them
- Reviewer reviews again
- Repeat until approved
Integration
Required workflow skills:
- arc-using-worktrees — REQUIRED: Set up isolated workspace before starting
- arc-writing-tasks - Creates the task list this skill executes
- arc-requesting-review - Code review template for reviewer subagents
- arc-finishing or arc-finishing-epic - Complete development after all tasks
Subagents should use:
- arc-tdd - TDD for each task
Alternative workflow:
- arc-executing-tasks - Use for human checkpoint mode instead of automated
Converted and distributed by TomeVault — claim your Tome and manage your conversions.