80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
# 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.
|