gregoryho/arc-agent-driven

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 access
• spec-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