ktg-plugin-marketplace/plugins/ultraplan-local/templates/headless-launch-template.md

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

#!/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.