multitask

Multitask Skill

Purpose

Execute multiple independent development tasks in parallel. Each workstream runs in an isolated /tmp clone with its own Recipe Runner process following code-enforced workflow steps.

Key Advantage: Uses Recipe Runner YAML recipes instead of prompt-based markdown workflows. Python controls step execution, making it impossible to skip steps.

Quick Start

Inline Tasks

/multitask
- #123 (feat/add-auth): Implement user authentication
- #124 (feat/add-logging): Add structured logging
- #125 (feat/update-api): Update API endpoints

JSON Config

Create workstreams.json:

[
  {
    "issue": 123,
    "branch": "feat/add-auth",
    "description": "User authentication",
    "task": "Implement JWT-based authentication with login/logout endpoints",
    "recipe": "default-workflow"
  },
  {
    "issue": 124,
    "branch": "feat/add-logging",
    "description": "Structured logging",
    "task": "Add structured JSON logging across all API endpoints"
  }
]

Then: /multitask workstreams.json

How It Works

User provides task list
        |
        v
For each task:
  1. Clone branch to /tmp/amplihack-workstreams/ws-{issue}/
  2. Write launcher.py (Recipe Runner with CLISubprocessAdapter)
  3. Write run.sh (sets session tree vars, runs launcher.py)
  4. Launch subprocess via Popen
        |
        v
Monitor all workstreams (60s intervals)
        |
        v
Report: PR numbers, success/failure, runtime

Why Recipe Runner?

Aspect	Classic (markdown)	Recipe Runner (YAML)
Step ordering	Prompt-based (skippable)	Code-enforced (Python loop)
Template variables	None	{{task_description}}, {{repo_path}}
Error handling	Implicit	Fail-fast per step
Progress tracking	Opaque	Step-by-step status

Critical Implementation Details

1. /tmp clones (not worktrees): Worktree symlinks confuse nested Claude sessions. Clean clones avoid this.
2. --subprocess-safe: Classic mode passes this flag to skip staging/env updates, preventing concurrent write races on ~/.amplihack/.claude/ (issue #2567).
3. Recipe Runner adapter: CLISubprocessAdapter shells out to claude -p for each agent step within the recipe (no amplihack wrapper, so no staging race).
4. Child env cleanup: The shared build_child_env() utility strips blocking env vars and propagates session tree context.

Execution Modes

Recipe Mode (Default)

Each workstream runs run_recipe_by_name() through a Python launcher:

from amplihack.recipes import run_recipe_by_name

result = run_recipe_by_name("default-workflow",
    user_context={"task_description": task, "repo_path": "."})

Classic Mode

Falls back to single-session prompt-based execution with --subprocess-safe to avoid concurrent staging races (see issue #2567):

amplihack claude --subprocess-safe -- -p "@TASK.md Execute autonomously following DEFAULT_WORKFLOW.md."

The --subprocess-safe flag skips all staging/env updates so parallel workstreams don't race on ~/.amplihack/.claude/. The parent amplihack process has already staged the framework files.

Use --mode classic when Recipe Runner is unavailable or for tasks that benefit from full session context.

Available Recipes

Any recipe in amplifier-bundle/recipes/ can be used per-workstream:

Recipe	Steps	Best For
default-workflow	52	Features, bugs, refactoring (default)
investigation-workflow	23	Research, codebase analysis
verification-workflow	5	Trivial changes, config updates
auto-workflow	9	Autonomous iteration until complete

Specify per-task: "recipe": "investigation-workflow" in JSON config.

Monitoring

# Watch all logs
tail -f /tmp/amplihack-workstreams/log-*.txt

# Check specific workstream
tail -f /tmp/amplihack-workstreams/log-123.txt

# Check running processes
ps aux | grep launcher.py

# Final report
cat /tmp/amplihack-workstreams/REPORT.md

When to Read Supporting Files

Need	File
Full API, config options, architecture	reference.md
Real-world usage examples	examples.md
Python orchestrator source	orchestrator.py

Disk Management & Cleanup

Understanding Disk Usage

Each workstream creates a full git clone (~1.5GB). With 10 parallel workstreams, this is ~15GB of temporary disk usage.

Locations:

• /tmp/amplihack-workstreams/ws-{issue}/ - Each workstream's working directory
• /tmp/amplihack-workstreams/log-{issue}.txt - Log files (kept separately)
• /tmp/amplihack-workstreams/REPORT.md - Final execution report

When to Clean Up

✅ SAFE to delete:

• PR has been merged to main
• You've finished debugging/inspecting the workstream
• You need disk space for new workstreams
• All PRs from a multitask session are complete

❌ NOT safe to delete:

• PR is still under review
• PR has merge conflicts you need to resolve manually
• You might need to inspect the working directory for debugging
• Workstream failed and you haven't diagnosed the issue

Manual Cleanup Commands

# Check disk usage first
du -sh /tmp/amplihack-workstreams/*

# Clean up specific workstream (after PR merged)
rm -rf /tmp/amplihack-workstreams/ws-123

# Clean up all workstreams (after all PRs merged)
rm -rf /tmp/amplihack-workstreams/ws-*

# Keep log files, delete only working directories
find /tmp/amplihack-workstreams -type d -name "ws-*" -exec rm -rf {} +

# Check available disk space
df -h /tmp

Automatic Cleanup (Helper Command)

After merging PRs, use the cleanup helper to automatically remove merged workstreams:

# Clean up all workstreams with merged PRs
python .claude/skills/multitask/orchestrator.py --cleanup workstreams.json

# Dry run (show what would be deleted)
python .claude/skills/multitask/orchestrator.py --cleanup --dry-run workstreams.json

The cleanup helper:

• Checks each workstream's PR status using gh CLI
• Only deletes workstreams with MERGED status
• Preserves log files for historical reference
• Reports disk space freed

Disk Space Monitoring

The orchestrator automatically checks disk space before launching workstreams:

⚠️  WARNING: Only 8.2GB free in /tmp
Each workstream requires ~1.5GB. Consider cleaning up:
  rm -rf /tmp/amplihack-workstreams/ws-*
Continue anyway? (y/N):

Rule of thumb: Keep at least 20GB free for comfortable multi-workstream development.

Preventing Disk Issues

1. Before large multitask runs (10+ workstreams):

   df -h /tmp  # Check available space
   rm -rf /tmp/amplihack-workstreams/ws-*  # Clean old workstreams
   

2. After merging PRs:

   python orchestrator.py --cleanup workstreams.json
   

3. Monitor during execution:

   watch -n 60 'du -sh /tmp/amplihack-workstreams && df -h /tmp'
   

Troubleshooting

Empty log files: Process started but exited immediately. Check if amplihack package is importable in the clone's environment.

Recipe not found: Ensure amplifier-bundle/recipes/ exists in the cloned branch. The recipe discovery checks this directory first.

Fallback: If recipe mode fails, retry with --mode classic to use the prompt-based approach.

Disk full during execution: The orchestrator warns if <10GB free. If disk fills mid-execution, manually clean up: rm -rf /tmp/amplihack-workstreams/ws-* (after stopping running workstreams).