snappy-launch

Orchestrate parallel subagent launches with coordinated work tracking. This skill pairs with snappy-subagents (which governs an individual subagent's behavior) to handle the higher-level orchestrator's responsibilities: deciding how many parallel agents, what each does, collecting their writebacks, and assessing whether the parallel work made aggregate progress. Failure mode prevented: orchestrators that launch agents but don't verify they wrote back, or that launch N agents without confirming the work was actually independent.

Steps

1. Define work units

• Identify independent tasks that can run in parallel (fan-out shape).
• Each unit is one Task or headless claude -p subagent.
• Skip the launch if tasks touch the same files (can't parallelize safely).

2. Compose subagent briefs

• For each unit, write a brief that names the setpoint (state/skills/<slug>/AGENTS.md).
• Include explicit FORBIDDEN paths list (files this subagent must NOT touch).
• Mandate writeback line before exit: echo "[$(date -u +%FT%TZ)] <slug>: <gap or fix> [FIXED|LOGGED]" >> state/log/loader-feedback.log.

3. Launch and collect

• Fan out the subagents (Task tool for attended, headless claude -p for Stop-hook drains).
• Wait for all subagents to return and emit writebacks.
• Read the feedback log; verify each subagent's writeback is present.

4. Assess progress

• For each subagent's writeback, check if the claimed [FIXED] edit is on disk.
• Tally: how many succeeded, how many need re-dispatch, how many silently failed.
• Log an overall verdict (1.0 = all clean | 0.5 = some re-dispatch | 0.0 = any silent returns).

5. Log + eval

import { score } from "../../lib/eval";
score("snappy-launch", run_id, {
  score: <1.0 if all subagents wrote back AND every [FIXED] claim on disk
         | 0.5 if writebacks present but ≥1 re-dispatch needed
         | 0.0 if any silent return OR clobber OR lied [FIXED]>,
  primary_issue: <null | "silent-return" | "clobber" | "lied-fix">,
});

Eval

Actor: the thing that produces the output (a dispatch model, a CLI, or the state/lib/snappy-launch.ts library if one exists). Auditor: the thing that judges (must be different - see CONSTITUTION invariant #3). Name both explicitly.

Score convention:

If you cannot name a deterministic auditor, switch the frontmatter to eval: manual and log to state/log/pending-eval.ndjson - but fight to avoid manual. Manual is the escape hatch that leaks the thesis.

Gotchas

• List concrete failure modes you hit while building. Examples: "API

returns 200 with empty body"; "round-tripped text has a , artifact where em-dashes used to be"; "cache file is stale after 12h."

• If a gotcha matches an entry in user memory (see ~/.claude/CLAUDE.md),

cite the memory name so future agents can follow the trail.

snappy-launch - loader

Per-turn rules for the snappy-launch skill. Full reference: state/skills/snappy-launch/SKILL.md. Do not skip these.

Critical Rules

• Default to apply: false - preview the work, require explicit confirmation

before any side effect ships. (CONSTITUTION invariant #3 - actor ≠ auditor.)

• Every run writes ONE eval row to state/log/evals.ndjson via

score(). No exceptions. (CONSTITUTION invariant #4.)

• If you discover a rule, command, or pitfall that should live in this

loader, follow the PID feedback footer below - patch the loader inline (FIXED) when the fix is small, otherwise log LOGGED and let the Stop-hook drain regenerate the loader.

Commands

|library: state/lib/snappy-launch.ts (only if it exists; otherwise leave blank) |sidecar: state/bin/snappy-launch/ (optional) |reference: state/skills/snappy-launch/SKILL.md |eval log: state/log/evals.ndjson

Known Pitfalls

• Replace this bullet with the first concrete failure mode you hit. If you

hit none on the first run, replace it with the first thing you wished this loader had told you.

Self-Test

An agent reading this should correctly:

1. [ ] Default to scope-only (apply: false) and require explicit confirmation

before shipping any side effect?

1. [ ] Append exactly one eval row per run to state/log/evals.ndjson?
2. [ ] Patch this loader inline (or log LOGGED) when a gap is discovered?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] snappy-launch: <what was missing>" >> state/log/loader-feedback.log

<!-- footer-injection-point -->

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] <skill-name>: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/agents-md-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.