Subagent-Driven Development

Create and execute plan by dispatching Gemini CLI as worker per task, with Claude orchestrating, reviewing, and committing.

Core principle: Gemini implements + Claude reviews/commits = high quality, fast iteration, token savings.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Claude (Orchestrator)                │
│  - Planning & Architecture                              │
│  - Task decomposition                                   │
│  - Context preparation                                  │
│  - Code review & quality gates                          │
│  - Decision making                                      │
│  - All git commits                                      │
└─────────────────┬───────────────────────────────────────┘
                  │
                  │ Bash: gemini --prompt "..." --approval-mode auto_edit
                  ▼
┌─────────────────────────────────────────────────────────┐
│                  Gemini CLI (Worker)                    │
│  - Code implementation                                  │
│  - Test writing                                         │
│  - File modifications                                   │
│  - Running builds/tests                                 │
│  - NO git commits (Claude handles)                      │
└─────────────────────────────────────────────────────────┘

Benefits:

• •Same session (no context switch)
• •Fresh Gemini instance per task (no context pollution)
• •Code review by Claude after each task (catch issues early)
• •Faster iteration (no human-in-loop between tasks)
• •Significant token savings (Gemini for grunt work, Claude for thinking)

Gemini CLI Reference

Non-Interactive Dispatch

# Basic task execution (auto-approve file edits only)
gemini --prompt "TASK_PROMPT" --approval-mode auto_edit

# With output capture for review
gemini --prompt "TASK_PROMPT" --approval-mode auto_edit 2>&1 | tee /tmp/gemini-output.txt

Prompt Template (HEREDOC)

gemini --prompt "$(cat <<'EOF'
You are implementing [Task N: task name].

## Context
[Minimal context - file paths, what exists, constraints]

## Your Job
1. Implement exactly what the task specifies
2. Write tests if required
3. Verify implementation works
4. DO NOT commit - Claude will review and commit

## Files to Modify
- path/to/file1.ts
- path/to/file2.ts

## Constraints
- Do not modify other files
- Follow existing patterns
- [Other constraints]

## Report Back
What you implemented, what you tested, test results, files changed
EOF
)" --approval-mode auto_edit

Parallel Execution

# Run multiple independent tasks in parallel
gemini --prompt "Task 1 prompt..." --approval-mode auto_edit &
gemini --prompt "Task 2 prompt..." --approval-mode auto_edit &
gemini --prompt "Task 3 prompt..." --approval-mode auto_edit &
wait  # Wait for all to complete

Key Flags

Supported Types of Execution

Sequential Execution

When tasks are related and need to be executed in order.

Dispatch one Gemini worker per task. Let it work sequentially. Claude reviews and commits after each task.

When to use:

• •Tasks are tightly coupled
• •Tasks should be executed in order

Parallel Execution

When tasks are independent (different files, different subsystems).

Dispatch multiple Gemini workers in parallel. Claude batches commits after all complete.

When to use:

• •Tasks are mostly independent
• •Overall review can be done after all tasks complete

Sequential Execution Process

1. Load Plan

Read plan file, create TodoWrite with all tasks.

2. Prepare Context (Claude)

Before dispatching to Gemini, Claude prepares:

• •Minimal, focused context (< 500 tokens)
• •Specific file paths and line numbers
• •Clear acceptance criteria
• •Constraints and boundaries

3. Execute Task with Gemini

Dispatch to Gemini CLI:

gemini --prompt "$(cat <<'EOF'
You are implementing Task N: [task name] from [plan-file].

## Context
[Relevant context prepared by Claude]

## Your Job
1. Implement exactly what the task specifies
2. Write tests (following TDD if task says to)
3. Verify implementation works
4. DO NOT commit - Claude will review and commit

Work from: [directory]

## Report
What you implemented, what you tested, test results, files changed
EOF
)" --approval-mode auto_edit

Gemini reports back with summary of work.

4. Review Work (Claude)

Claude reviews the changes:

Use code-reviewer agent or review directly:

• •Check implementation matches requirements
• •Verify code quality and patterns
• •Security review if needed
• •Check test coverage

Task tool (code-reviewer):
  Review changes made by Gemini for Task N
  WHAT_WAS_IMPLEMENTED: [from Gemini's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]

Code reviewer returns: Strengths, Issues (Critical/Important/Minor), Assessment

5. Fix Issues if Needed

If issues found:

• •Fix Critical issues immediately
• •Fix Important issues before next task
• •Note Minor issues

Dispatch follow-up Gemini worker:

gemini --prompt "$(cat <<'EOF'
Fix issues from code review:
- [Issue 1]
- [Issue 2]

Files to modify: [files]
Do NOT commit.
EOF
)" --approval-mode auto_edit

6. Commit (Claude)

After review passes, Claude commits the changes:

git add [specific files]
git commit -m "feat: [task description]"

7. Mark Complete, Next Task

• •Mark task as completed in TodoWrite
• •Move to next task
• •Repeat steps 2-7

8. Final Review

After all tasks complete, Claude does final review:

• •Reviews entire implementation
• •Checks all plan requirements met
• •Validates overall architecture

9. Complete Development

After final review passes:

• •Announce: "I'm using the finishing-a-development-branch skill to complete this work."
• •REQUIRED SUB-SKILL: Use superpowers:finishing-a-development-branch
• •Follow that skill to verify tests, present options, execute choice

Example Workflow

Claude: I'm using Subagent-Driven Development to execute this plan.

[Load plan, create TodoWrite]

Task 1: Hook installation script

[Prepare context for Gemini]
[Dispatch Gemini worker]
Gemini: Implemented install-hook with tests, 5/5 passing

[Claude reviews changes]
Claude: Code looks good. Committing.
[git add && git commit]

[Mark Task 1 complete]

Task 2: Recovery modes

[Prepare context for Gemini]
[Dispatch Gemini worker]
Gemini: Added verify/repair, 8/8 tests passing

[Claude reviews]
Claude: Missing progress reporting. Dispatching fix.

[Dispatch fix to Gemini]
Gemini: Added progress every 100 conversations

[Claude reviews fix, commits]

[Mark Task 2 complete]

...

[After all tasks]
[Claude final review]
Claude: All requirements met, architecture solid

Done!

Red Flags

Never:

• •Skip code review between tasks
• •Proceed with unfixed Critical issues
• •Let Gemini commit (Claude handles all commits)
• •Dispatch multiple Gemini workers editing same files (conflicts)
• •Implement without reading plan task

If Gemini fails task:

• •Dispatch new Gemini worker with specific fix instructions
• •Don't try to fix manually in Claude session (context pollution)

Parallel Execution Process

Load plan, review critically, execute independent tasks in parallel, Claude reviews and commits after batch.

Core principle: Batch execution with Claude checkpoints.

Announce at start: "I'm using Subagent-Driven Development to implement this plan."

Step 1: Load and Review Plan

1. •Read plan file
2. •Review critically - identify any questions or concerns
3. •If concerns: Raise them with your human partner
4. •If no concerns: Create TodoWrite and proceed

Step 2: Identify Independent Tasks

Group tasks that can run in parallel:

• •Different files
• •Different subsystems
• •No dependencies between them

Step 3: Prepare Context for Each

Claude prepares minimal context for each Gemini worker.

Step 4: Execute Batch in Parallel

# Dispatch all independent tasks
gemini --prompt "Task 1..." --approval-mode auto_edit &
gemini --prompt "Task 2..." --approval-mode auto_edit &
gemini --prompt "Task 3..." --approval-mode auto_edit &
wait

Step 5: Review All Changes (Claude)

When Gemini workers complete:

• •Review each set of changes
• •Check for conflicts between changes
• •Run full test suite
• •Identify issues

Step 6: Batch Commit (Claude)

After review passes:

git add [all changed files]
git commit -m "feat: [batch description]"

Step 7: Report

• •Show what was implemented
• •Show verification output
• •Say: "Ready for feedback."

Step 8: Continue

Based on feedback:

• •Apply changes if needed
• •Execute next batch
• •Repeat until complete

Step 9: Complete Development

After all tasks complete and verified:

• •Announce: "I'm using the finishing-a-development-branch skill to complete this work."
• •REQUIRED SUB-SKILL: Use superpowers:finishing-a-development-branch

Parallel Investigation Process

Special case for investigating multiple unrelated failures.

1. Identify Independent Domains

Group failures by what's broken:

• •File A tests: Tool approval flow
• •File B tests: Batch completion behavior
• •File C tests: Abort functionality

2. Create Focused Gemini Prompts

Each Gemini worker gets:

• •Specific scope: One test file or subsystem
• •Clear goal: Make these tests pass
• •Constraints: Don't change other code
• •Expected output: Summary of root cause and changes

3. Dispatch in Parallel

gemini --prompt "Fix agent-tool-abort.test.ts failures..." --approval-mode auto_edit &
gemini --prompt "Fix batch-completion-behavior.test.ts failures..." --approval-mode auto_edit &
gemini --prompt "Fix tool-approval-race-conditions.test.ts failures..." --approval-mode auto_edit &
wait

4. Review and Integrate (Claude)

When Gemini workers return:

• •Read each summary
• •Verify fixes don't conflict
• •Run full test suite
• •Commit all changes

Gemini Prompt Structure

Good prompts are:

1. •Focused - One clear problem domain
2. •Self-contained - All context needed
3. •Specific about output - What should be returned?
4. •Explicit about git - DO NOT commit

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.
Do NOT commit - Claude will review and commit.

Return: Summary of what you found and what you fixed.

Common Mistakes

Bad: "Fix all the tests" - Gemini gets lost Good: "Fix agent-tool-abort.test.ts" - focused scope

Bad: "Fix the race condition" - no context Good: Paste the error messages and test names

Bad: No constraints - might refactor everything Good: "Do NOT change production code" or "Fix tests only"

Bad: "Fix it" - vague output Good: "Return summary of root cause and changes"

When NOT to Use Parallel

• •Related failures: Fixing one might fix others
• •Need full context: Understanding requires seeing entire system
• •Exploratory debugging: You don't know what's broken yet
• •Shared state: Workers would interfere (editing same files)

Claude-Only Operations

These operations should ALWAYS use Claude agents, not Gemini:

Verification

After Gemini workers return:

1. •Review each summary - Understand what changed
2. •Check for conflicts - Did workers edit same code?
3. •Run full suite - Verify all fixes work together
4. •Spot check - Workers can make systematic errors
5. •Commit - Claude commits with clear message