# Headless Launch Script Template

This template is used by the session-decomposer agent to generate a launch script
for headless execution of decomposed sessions.

## Template

```bash
#!/usr/bin/env bash
# Headless launch script — generated by ultraplan-local
# Master plan: {plan_path}
# Generated: {date}
# Sessions: {total_sessions} ({parallel_count} parallel, {sequential_count} sequential)

set -euo pipefail

# Prevent accidental API billing — remove this line if you intend to use API credits
unset ANTHROPIC_API_KEY

PLAN_DIR="{session_dir}"
LOG_DIR="{session_dir}/logs"
mkdir -p "$LOG_DIR"

echo "=== Ultraplan Headless Execution ==="
echo "Plan: {plan_path}"
echo "Sessions: {total_sessions}"
echo ""

# --- Wave {N}: Parallel sessions (no dependencies) ---
echo "--- Wave {N}: {description} ---"

{# For each parallel session in this wave: }
claude -p "$(cat "$PLAN_DIR/session-{n}-{slug}.md")" \
  --dangerously-skip-permissions \
  > "$LOG_DIR/session-{n}.log" 2>&1 &
PID_{n}=$!
echo "Started session {n}: {title} (PID $PID_{n})"

{# After all parallel sessions in this wave: }
echo "Waiting for Wave {N} to complete..."
wait $PID_{n1} $PID_{n2}
echo "Wave {N} complete."
echo ""

# --- Verify wave results ---
echo "--- Verifying Wave {N} ---"
{# For each session in the wave, run its exit condition commands }
{verify_commands}

# --- Wave {N+1}: Sequential sessions (depends on previous wave) ---
{# Repeat wave pattern for dependent sessions }

echo ""
echo "=== All sessions complete ==="
echo "Review logs in $LOG_DIR/"
echo "Run final verification: {final_verify_command}"
```

## Rules for the session-decomposer

When generating a launch script from this template:

1. **Group sessions into waves** by dependency. Sessions with no dependencies
   or whose dependencies are all in earlier waves can run in the same wave.
2. **Each wave waits for completion** before the next wave starts.
3. **Verification runs after each wave** — if verification fails, the script
   stops and reports which session failed.
4. **Log each session** to a separate file for debugging.
5. **Use `claude -p`** with the session spec file as the prompt.
6. **Use `--dangerously-skip-permissions`** rather than `--allowedTools` — the
   executor needs flexible tool access and enumerating every tool is fragile.
7. **Final verification** at the end runs the master plan's verification section.
8. **Never include secrets** in the generated script.
9. **Wave verification must be independent.** After each wave completes, run
   verification commands fresh via Bash — never parse session log files as proof
   of success. Log files contain executor self-reporting, not ground truth. The
   command's exit code is the only authoritative verification signal.
10. **Billing preamble.** Prepend `unset ANTHROPIC_API_KEY` with a comment at
    the top of the script to prevent accidental API billing. Users who intend
    to use API credits can remove this line.