---

name: 003-execute-tasks description: Spawn a sub-agent using Claude, Gemini, or Codex CLI with selected model. Use when the user says "use /subagent to" followed by a task.

Subagent Spawner

Spawn sub-agents using different AI CLI providers. Supports two modes:

1. Ad-hoc tasks — General purpose task execution
2. Project tasks — Execute tasks from .claude/tasks.json with completion protocol

---

Mode Detection

Project mode if any of:

• User says "run task T005" or "run T005"
• User says "run next task" or "next task"
• User says "continue project" or "continue"
• Current directory has .claude/tasks.json

Ad-hoc mode otherwise.

---

Ad-Hoc Mode (Simple Tasks)

For general tasks not part of a structured project.

Step 1: Capture Task

Everything after "use /subagent to" is the TASK.

Step 2: Provider Selection

Copy{
  "questions": [{
    "question": "Which AI provider?",
    "header": "Provider",
    "options": [
      {"label": "Claude (Recommended)", "description": "Anthropic Claude Code CLI"},
      {"label": "Gemini", "description": "Google Gemini CLI"},
      {"label": "Codex", "description": "OpenAI Codex CLI"}
    ],
    "multiSelect": false
  }]
}

Step 3: Model Selection

Claude:

• sonnet (Recommended) — Balanced
• haiku — Fast, cheap
• opus — Most capable

Gemini: Default model (no selection)

Codex:

• gpt-5.2-codex (Recommended)
• gpt-5.1-codex-mini — Lightweight
• gpt-5.1-codex-max — Maximum

Step 4: Permission Mode

Claude:

• Auto-approve edits → --permission-mode acceptEdits
• YOLO → --dangerously-skip-permissions

Gemini:

• Auto-approve edits → --approval-mode auto_edit
• YOLO → -y

Codex:

• Full-auto → --full-auto
• YOLO → --dangerously-bypass-approvals-and-sandbox

Step 5: Execute

Write prompt to project history (avoids shell escaping, keeps history):

Copymkdir -p .claude/prompts
cat > .claude/prompts/{TASK_ID}.md << 'EOF'
[TASK PROMPT HERE]
EOF

Then pipe to subagent:

Copy# Claude
cat .claude/prompts/{TASK_ID}.md | claude --model MODEL --permission-mode acceptEdits -p

# Gemini
cat .claude/prompts/{TASK_ID}.md | gemini --approval-mode auto_edit

# Codex
cat .claude/prompts/{TASK_ID}.md | codex exec --skip-git-repo-check --full-auto --model MODEL -

---

Project Mode (Structured Tasks)

For tasks from a /002-setup-project generated project.

Step 1: Detect Project

Check for .claude/tasks.json in current or specified directory.

If not found:

Copy{
  "questions": [{
    "question": "No project found. What would you like to do?",
    "header": "Project",
    "options": [
      {"label": "Specify path", "description": "I'll provide the project path"},
      {"label": "Run ad-hoc", "description": "Execute without project context"}
    ],
    "multiSelect": false
  }]
}

Step 2: Determine Task

If user specified task ID (e.g., "run T005"):

• Load that specific task

If user said "next task" or "continue":

• Find first task with status: pending
• Verify dependencies are completed

Step 3: Display Task Summary

Output a concise table — no prose explanation:

Copy┌──────────────────────────────────────────────────────────┐
│ T003 — Set up client with Vite and React                 │
├─────────────┬────────────────────────────────────────────┤
│ Phase       │ foundation                                 │
│ Complexity  │ simple                                     │
│ Depends on  │ T001 ✓, T002 ✓                             │
│ Outputs     │ client/, vite.config.ts, package.json      │
└─────────────┴────────────────────────────────────────────┘

Then immediately proceed to model selection.

Step 4: Generate Task Prompt

Build prompt using template from task-prompt-template.md:

1. Read .claude/tasks.json for task details
2. Read .claude/CONTEXT.md for project state
3. Substitute into template
4. Include completion signal instructions

Step 5: Provider, Model & Permission Selection

Follow the full ad-hoc flow (Steps 2-4) with complexity-based recommendations.

5a. Provider Selection:

Copy{
  "questions": [{
    "question": "Task {TASK_ID} ({COMPLEXITY}). Which provider?",
    "header": "Provider",
    "options": [
      {"label": "Claude (Recommended)", "description": "Anthropic Claude Code CLI"},
      {"label": "Gemini", "description": "Google Gemini CLI"},
      {"label": "Codex", "description": "OpenAI Codex CLI"}
    ],
    "multiSelect": false
  }]
}

5b. Model Selection (based on provider):

Recommend based on task complexity:

(Gemini uses default model — skip this step)

5c. Permission Mode:

• Claude: acceptEdits or dangerously-skip-permissions
• Gemini: auto_edit or -y
• Codex: full-auto or dangerously-bypass-approvals-and-sandbox

Step 6: Execute with Protocol

Run the subagent with the generated prompt.

The prompt instructs the subagent to:

1. Read CONTEXT.md first
2. Complete the task
3. Run success criteria
4. Update PROGRESS-NOTES.md
5. Update CONTEXT.md
6. Update tasks.json
7. Emit completion signal

See project-protocol.md for full protocol.

Step 7: Parse Completion Signal

After subagent completes, find and parse:

Copy--- TASK COMPLETION ---
task_id: T005
status: completed
...
next_task: T006
--- END COMPLETION ---

Step 8: Sweep & Enhance Documentation

After subagent completes, perform a documentation sweep. You (in the main Claude session) have broader project context than the subagent, so actively review and enhance:

1. Read files created/modified by subagent
2. Verify subagent updates to CONTEXT.md, PROGRESS-NOTES.md, tasks.json
3. Enhance if needed — you have broader project context:

1. Skip sweep only if task was trivial and completion signal confirms all updates made

Step 8.5: Simplify & Polish Code

When the completion signal includes simplification_requested: true, apply code simplification to the modified files.

Read the files from files_created and files_modified, then apply:

1. Preserve Functionality — Only change HOW, not WHAT

2. Apply Project Standards — Draw from .claude/ARCHITECTURE.md and .claude/DECISIONS.md

3. Enhance Clarity:

   • Reduce unnecessary complexity and nesting
   • Eliminate redundant code and abstractions
   • Improve variable/function names for clarity
   • Avoid nested ternaries — prefer switch/if-else
   • Choose clarity over brevity

4. Maintain Balance — Don't over-simplify; prioritize readability

Skip simplification if:

• Task was trivial/simple complexity
• Code is already clean and follows project standards
• Files are configuration-only (no logic to simplify)

See simplifier-guidelines.md for detailed principles.

Step 9: Report & Continue

Report results to user:

Copy✓ Task T005 completed successfully

Files created:
- src/models/User.ts

Success criteria: 3/3 passed

Next task: T006 — Create Genome model

Continue with next task?

If status: blocked:

Copy⚠ Task T005 blocked

Blocker: Missing CLERK_SECRET_KEY environment variable

Required action:
1. Create Clerk account at clerk.dev
2. Add CLERK_SECRET_KEY to .env.local

See .claude/BLOCKERS.md for details.

---

Completion Signal Format

Subagents MUST emit this at response end:

Copy--- TASK COMPLETION ---
task_id: T005
task_name: Create User model
status: completed | blocked | failed
duration_minutes: 15

files_created:
  - path/to/file

files_modified:
  - path/to/file

success_criteria:
  - [PASS] file_exists: src/models/User.ts
  - [PASS] command_succeeds: npx tsc --noEmit

blocker: none | "description"

notes: |
  Summary of work done

context_updated: true
progress_notes_updated: true
tasks_json_updated: true

next_task: T006 | null
--- END COMPLETION ---

---

Quick Reference: Commands

Always write prompt to project history, then pipe:

Copy# Write prompt to history (creates audit trail)
mkdir -p .claude/prompts
cat > .claude/prompts/T001.md << 'EOF'
[Your prompt here]
EOF

# Claude (recommended for most tasks)
cat .claude/prompts/T001.md | claude --model sonnet --permission-mode acceptEdits -p
cat .claude/prompts/T001.md | claude --model opus --dangerously-skip-permissions -p

# Gemini
cat .claude/prompts/T001.md | gemini --approval-mode auto_edit
cat .claude/prompts/T001.md | gemini -y

# Codex
cat .claude/prompts/T001.md | codex exec --skip-git-repo-check --full-auto --model gpt-5.2-codex -

---

References

• project-protocol.md — Completion signal spec, file update requirements
• task-prompt-template.md — Template for project task prompts