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

• /tmp clones (not worktrees): Worktree symlinks confuse nested Claude sessions. Clean clones avoid this.

• --subprocess-safe : Classic mode passes this flag to skip staging/env updates, preventing concurrent write races on ~/.amplihack/.claude/ (issue #2567).

• Recipe Runner adapter: CLISubprocessAdapter shells out to claude -p for each agent step within the recipe (no amplihack wrapper, so no staging race).

• 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

Before large multitask runs (10+ workstreams):

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

After merging PRs:

python orchestrator.py --cleanup workstreams.json

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).