1545 Requirements 5edbf736

Requirements: Fix /zerg:rush Task Tool Mode Default

Status: APPROVED Created: 2026-02-04 Feature: rush-task-mode-default

Problem Statement

When /zerg:rush is invoked as a Claude Code slash command without explicit --mode, it incorrectly delegates to the Python CLI/Orchestrator (subprocess mode) instead of executing in Task Tool Mode.

Root Cause

The current rush.core.md describes container/subprocess mode as the primary execution path:

• Step 2: Create Worker Branches (git worktrees)
• Step 5: Launch Containers (Docker)
• Step 6: Start Orchestrator (Python process)

Task Tool Mode is documented in rush.details.md but is never invoked as the default path. The core file lacks:

1. Mode detection logic at the start
2. Conditional branching based on mode
3. Task Tool execution loop as the primary path

Expected Behavior

/zerg:rush                    → Task Tool Mode (default)
/zerg:rush --mode task        → Task Tool Mode (explicit)
/zerg:rush --mode container   → Container Mode (Docker + worktrees)
/zerg:rush --mode subprocess  → Subprocess Mode (Python processes)

Functional Requirements

FR-1: Mode Detection at Entry

At the start of /zerg:rush execution, detect the requested mode:

IF $ARGUMENTS contains "--mode container":
  MODE = "container"
ELSE IF $ARGUMENTS contains "--mode subprocess":
  MODE = "subprocess"
ELSE:
  MODE = "task"  # DEFAULT

FR-2: Task Tool Mode as Primary Execution Path

When MODE = "task" (default), the slash command executor (Claude) drives execution directly via the Task tool. No external processes are spawned.

Level Execution Loop:

FOR each level in task-graph.json (ascending order):
  1. Collect all tasks at this level
  2. Batch tasks by WORKERS count
  3. FOR each batch:
       Launch all tasks as parallel Task tool calls
       (subagent_type: "general-purpose")
       Wait for all to return
       Record pass/fail per task
  4. Handle failures:
       - Retry failed tasks ONCE
       - If retry fails: mark blocked, warn, continue
       - If ALL tasks fail: ABORT
  5. Run quality gates (lint, typecheck)
  6. Proceed to next level
END FOR

FR-3: Subagent Prompt Structure

Each Task tool call uses the template from rush.details.md:263-301:

• Task ID, title, description, level
• Files to create/modify/read
• Design context references
• Acceptance criteria
• Verification command
• Commit instructions

FR-4: Container/Subprocess Mode Fallback

When MODE = "container" or MODE = "subprocess", invoke the Python Orchestrator:

from zerg.orchestrator import Orchestrator
orch = Orchestrator(feature=FEATURE, launcher_mode=MODE)
orch.start(task_graph_path=SPEC_DIR/task-graph.json, worker_count=WORKERS)

This path is only taken with explicit --mode container or --mode subprocess.

FR-5: Claude Code Task System Integration

In Task Tool Mode, use Claude Code's native Task system for tracking:

• TaskCreate for each task from task-graph.json
• TaskUpdate to mark in_progress when launching subagent
• TaskUpdate to mark completed/failed on return
• TaskList for resume logic

FR-6: Resume Support

/zerg:rush --resume behavior in Task Tool Mode:

1. Call TaskList to get current task states
2. Skip tasks with status "completed"
3. Resume from first incomplete level
4. Maintain retry counts from previous run

Non-Functional Requirements

NFR-1: No Python Process Spawning in Default Mode

Task Tool Mode must NOT spawn any external processes:

• No python3 -m zerg.orchestrator
• No docker run
• No subprocess.Popen

All orchestration happens within the slash command context.

NFR-2: Parallel Execution via Task Tool

Tasks at the same level execute in parallel via multiple Task tool calls in a single message. This is the Task tool's native parallel execution capability.

NFR-3: Shared Workspace

In Task Tool Mode, all subagents work in the same workspace (no worktrees). File ownership from task-graph.json prevents conflicts.

NFR-4: Single Branch Commits

No worker branches or merge operations. Subagents commit directly to the current branch, sequentially after each batch.

Scope

In Scope

1. Restructure rush.core.md to use Task Tool Mode as default
2. Move container/subprocess instructions to conditional section
3. Add mode detection logic at entry
4. Ensure Task Tool execution loop is complete and actionable

Out of Scope

1. Changes to Python CLI (zerg/commands/rush.py)
2. Changes to Orchestrator (zerg/orchestrator.py)
3. Changes to launcher infrastructure
4. New Python code

Acceptance Criteria

1. /zerg:rush without flags executes via Task tool subagents
2. /zerg:rush --mode container invokes Python Orchestrator with container launcher
3. /zerg:rush --mode subprocess invokes Python Orchestrator with subprocess launcher
4. Task Tool Mode completes a multi-level task graph successfully
5. Resume works correctly in Task Tool Mode
6. Documentation matches implementation

Files to Modify

Open Questions

1. Quality gates in Task Tool Mode: Should we run gates after each level or only at the end?

   • Recommendation: After each level (matches container mode behavior)

2. Error handling granularity: How detailed should failure reporting be?

   • Recommendation: Report task ID, error summary, suggest retry

3. Progress display: How to show progress without external orchestrator?

   • Recommendation: Print progress table after each batch completes