task-bg

<Purpose> Task-bg launches droids as background tasks for parallel execution. Factory Droid CLI does not have native `run_in_background` support, so this skill uses `background-manager.py` to manually manage background task lifecycle: launch, monitor, collect results, and cleanup. </​Purpose>

<Use_When>

• Need to run a droid task in the background while continuing other work
• User says "background", "task-bg", "run in background"
• Long-running operations (builds, test suites, large refactors)
• Multiple independent tasks that should run concurrently
• Used internally by ultrawork and ralph for parallel droid orchestration </​Use_When>

<Do_Not_Use_When>

• Quick operations that complete in seconds -- run directly
• Tasks that need interactive feedback -- run in foreground
• For full parallel orchestration -- use ultrawork which manages task-bg internally </​Do_Not_Use_When>

<What_You_MUST_Do>

1. PARSE - Extract description, prompt, and droid selection
2. LAUNCH - Run python3 hooks/​background-manager.py launch ...
3. TRACK - Task is recorded in ~/​.factory/​.omd/​background-tasks/
4. MONITOR - Use list for summary or status <id> for specific task
5. COLLECT - Use output <id> to read stdout/​stderr
6. REPORT - Summary of all background task outcomes </​What_You_MUST_Do>

<What_You_MUST_NOT_Do>

1. DO NOT run quick operations in background
2. DO NOT forget to collect results
3. DO NOT skip cleanup of completed tasks
4. DO NOT use for tasks needing interactive feedback </​What_You_MUST_NOT_Do>

<Why_Manual_Python> Factory Droid CLI does not support run_in_background: true like some other platforms. Instead, we use background-manager.py which:

• Executes droid exec --auto <autonomy> -- "<prompt>" as a background process
• Tracks tasks in ~/​.factory/​.omd/​background-tasks/ as JSON files (task state) and .out files (output)
• Provides CLI commands: launch, complete, status, output, list, prune, cleanup, hook-complete
• Integrates with the SubagentStop hook via hook-complete for automatic completion tracking </​Why_Manual_Python>

<Background_Manager_CLI>

Launch a task

python3 hooks/​background-manager.py launch "<description>" "<prompt>" <droid> <parent_session_id> [autonomy_level] [model]

• description: Short task label (3-5 words)
• prompt: Full task instructions for the droid
• droid: Droid name (e.g., executor-med, explorer)
• parent_session_id: Current session ID (use "main" if unknown)
• autonomy_level: low | medium (default) | high
• model: Optional model override

Examples

# Search task (low autonomy - read only)
python3 hooks/​background-manager.py launch "Find auth patterns" "Find all authentication implementations in src/" explorer "main" low

# Implementation task (medium autonomy - default)
python3 hooks/​background-manager.py launch "Fix API errors" "Fix all validation errors in src/​api/" executor-med "main" medium

# Complex task (high autonomy + model override)
python3 hooks/​background-manager.py launch "Refactor auth" "Refactor auth module to support OAuth2" executor-high "main" high opus

# Multiple tasks in parallel
python3 hooks/​background-manager.py launch "Fix auth" "Fix auth module errors" executor-med "main"
python3 hooks/​background-manager.py launch "Fix API" "Fix API route errors" executor-med "main"
python3 hooks/​background-manager.py launch "Fix UI" "Fix frontend type errors" executor-med "main"

Monitor tasks

# List all tasks with status summary (total, running, queued, completed, error)
python3 hooks/​background-manager.py list

# Check specific task status (returns full task JSON)
python3 hooks/​background-manager.py status <task_id>

# Get task stdout/​stderr output from .out file
python3 hooks/​background-manager.py output <task_id>

Complete a task manually

python3 hooks/​background-manager.py complete <task_id> "<result>" [error_message]

Cleanup

# Prune stale/​timed-out tasks (marks as ERROR, respects TTL of 30 min)
python3 hooks/​background-manager.py prune

# Reset all tasks from memory (does NOT delete .json files)
python3 hooks/​background-manager.py cleanup

Hook integration (internal - called by SubagentStop hook)

# Reads session_id from stdin JSON, finds matching task, marks complete with transcript result
python3 hooks/​background-manager.py hook-complete

</​Background_Manager_CLI>

<Autonomy_Levels>

<Available_Droids>

<Steps> 1. **Parse**: Extract description, prompt, and droid selection from user input 2. **Launch**: Run `python3 hooks/​background-manager.py launch ...` via Execute tool 3. **Track**: Task is automatically recorded in `~/​.factory/​.omd/​background-tasks/<task_id>.json` 4. **Monitor**: Use `list` for summary or `status <id>` for specific task 5. **Collect**: Use `output <id>` to read stdout/​stderr from `<task_id>.out` 6. **Report**: Summary of all background task outcomes </​Steps>

<Task_Lifecycle>

launch() -> RUNNING -> complete() -> COMPLETED
                    -> error      -> ERROR
                    -> prune()    -> ERROR (timeout/​stale)

Files per task:

• ~/​.factory/​.omd/​background-tasks/<task_id>.json - Task state (status, progress, metadata)
• ~/​.factory/​.omd/​background-tasks/<task_id>.out - Stdout/​stderr from droid exec

Hook: SubagentStop event calls background-manager.py hook-complete which reads transcript and auto-completes the matching task. </​Task_Lifecycle>

<Output_Format>

Background Tasks

Completed

• Task: [result summary]

Still Running

• </​Output_Format>