snappy-subagents

Launch and coordinate parallel subagents in snappy-os. The PiD chain (verb → agent → loader → skill) only learns when each join writes back - this skill is the prose that tells an orchestrator how to dispatch work, how to keep N concurrent commits from clobbering each other, and how to close the loop with a [FIXED|LOGGED] line so the next dispatch starts sharper. Failure mode prevented: parallel agents that silently overwrite each other's work, or worse, return success without a writeback so the loader stays blind to gaps the agent already discovered.

Observed user requests

These are the prompts that triggered this skill being scaffolded:

• "/loop 10 minutes make sure you keep launching subagents and keep pushing them lets see if we can achieve homemade AGI"
• "Ok great please commit and push and then I need you to first tell me ok so all of these subagents that have been working"
• "Tell me what you think, because it seems to me this makes sense, but I just want to make sure that with this, can we ach"
• "before you do it can you please look up online first and learn just to make sure we benefit from what others have alread"
• "this is kind of nuts are you telling me we actually achieved our 'homemade agi'?"

The Steps section below is a first-draft response to this cluster - refine as eval scores accumulate.

Steps

1. Decide the fan-out shape

• One subagent per independent unit of work. If two tasks touch the

same file, queue them sequentially in one subagent - don't fan out.

• Prefer the in-session Task tool (Anthropic harness) over headless

claude -p for attended work. Headless is for Stop-hook drains, scheduled cron, or when the parent is about to exit. Both inherit the same memory; the subagent will read this loader on its first prompt.

2. Brief each subagent with a closed PiD

• Every subagent prompt MUST mandate a writeback line before exit. If the loader has a gap, edit this AGENTS.md inline. git log on the file is the audit trail. No silent return edges - see memory feedback_subagent_prompts_must_close_pid.
• Even if the work is fully satisfied with no edits, the subagent must

still emit a [FIXED] line confirming proof-of-life - silence trips agi-loop-validator.ts (see cockpit-layout/AGENTS.md Rule on consumer no-op).

• Tell the subagent which loader is its setpoint (state/skills/<slug>/AGENTS.md)

so a P-fix lands in the right file, not a generic note.

3. Race-safe shared worktree (mandatory when N > 1)

• NEVER git add -A, git add ., git stash -u, or git commit -a -

they sweep other agents' WIP. Use explicit pathspec on commit: git commit -m "msg" -- <your-paths>. The pathspec on commit closes the TOCTOU window between git add and git commit.

• After git pull --rebase origin main, re-Read your files before Edit -

the rebase silently rewrites the worktree. If a stash-pop conflict resolved by dropping your work, recover via git checkout stash@{0} -- <files>.

• Each parallel xcodebuild MUST set -derivedDataPath /tmp/snappy-shell-build-<batch>

to avoid colliding artifacts. Cockpit-layout/AGENTS.md Rule 5 has the full incident catalog; cite it.

4. Drain on return - orchestrator IS the live drain

• After each subagent returns, read its writeback line from

state/log/loader-feedback.log and elevate the rule into the right loader IN-SESSION (don't wait for the cron Stop-hook drain). The next dispatch in the same session benefits - see memory feedback_orchestrator_is_live_drain.

• If the subagent claimed [FIXED] but you don't see the file edit,

the subagent lied - re-dispatch with a stricter prompt and log a pid-validator [LOGGED] line.

5. Log + eval

import { score } from "../../lib/eval";
score("snappy-subagents", run_id, {
  score: <1.0 if every subagent wrote back AND no clobber AND every reported FIX is on disk
         | 0.5 if writebacks landed but at least one needed re-dispatch
         | 0.0 if any subagent returned silently OR clobbered another agent's commit>,
  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-subagents.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-subagents - loader

Per-turn rules for fan-out + coordination. Full skill: state/skills/snappy-subagents/SKILL.md (5 Steps: fan-out shape → brief → race-safe → drain on return → log+eval). The PiD chain only learns when each agent writes back.

Critical Rules

• Compose any snappy-subagents UI through the current OpenUI path. Persist as artifact lang_body only when reusable.

1. One subagent per independent unit. Same-file work must sequence in ONE subagent. Concurrent same-file = git clobber.
2. Prefer in-session Task over headless claude -p. Headless: Stop-hook drains, cron, parent exit only. Task: attended loop.
3. EVERY subagent MUST emit writeback before exit. Even no-ops. Mandatory: echo "[$(date -u +%FT%TZ)] <slug>: <gap or fix> [FIXED|LOGGED]" >> state/log/loader-feedback.log. Silence = hung consumer.
4. Tell subagent its AGENTS.md setpoint. Specify state/skills/<slug>/AGENTS.md as P-fix target so edits land correctly.
5. Pathspec commits only. NEVER: -A, -a, -am, -u, stash -u. Use: git commit -m "msg" -- <paths>.
6. Re-Read files after git pull --rebase. Rebase silently rewrites. Recover dropped work: git checkout stash@{0} -- <files>.
7. Parallel xcodebuild: -derivedDataPath /tmp/snappy-shell-build-<batch> prevents artifact collisions.
8. Never claude -p from attended if git active. Auto-regen child can clobber. Defer to Stop-hook.
9. FORBIDDEN paths in every brief. Subagent brief MUST list files it must NOT touch (e.g. App.tsx, styles.css). Pattern: FORBIDDEN: web/src/App.tsx, web/src/styles.css in heading.
10. Orchestrator = live drain. Read writeback on return, elevate rules IN-SESSION (not Stop-hook).
11. Honest [FIXED] claims must match disk. Missing edit = lie. Re-dispatch stricter. Actor ≠ auditor (CONSTITUTION #3).
12. Subagent model floor: model: "sonnet". Haiku too weak for UI/Swift parity. Sonnet default. Haiku only for trivial data tasks.
13. screencapture -x captures active screen. Non-attended: activate app first: osascript -e 'tell app "SnappyChat" to activate'.
14. Concurrent build-app.sh blocks chat-drive tests. Lock builds or accept test contamination.

Commands

| ui model | live composition via compose_inline, persisted as artifact lang_body, reopened with OpenArtifact |

Score Convention

Self-Test

• [ ] One subagent per independent unit; same-file work sequential?
• [ ] Prefer in-session Task over headless claude -p?
• [ ] Every subagent writes writeback, even no-ops?
• [ ] Tell subagent its AGENTS.md setpoint?
• [ ] Pathspec commits only (-- <paths>), never -a/-A?
• [ ] Re-Read files after rebase before Edit?
• [ ] Parallel xcodebuild: -derivedDataPath /tmp/snappy-shell-build-<batch>?
• [ ] Never nested claude -p from attended context?
• [ ] Every brief lists explicit FORBIDDEN paths?
• [ ] Read writebacks in-session, elevate rules immediately?
• [ ] Verify [FIXED] claims on disk?
• [ ] Agent/Task calls: model: "sonnet" (floor) - haiku only for trivial data?
• [ ] Activate app before screencapture -x in non-attended context?
• [ ] Concurrent builds locked or test contamination logged?

Found a gap? Edit this file. <!-- footer-injection-point -->