Make chat recover from transient failures instead of ending on them

.agents/skills/a2a-protocol/SKILL.md

@@ -17,6 +17,17 @@ Agents call other agents over A2A, a JSON-RPC protocol for discovery and
 delegation. Use it when work belongs to a different agent entirely — not the
 local agent chat.
 
+**No workarounds when A2A feels flaky.** The strong default is `ask_app` (or
+`call-agent`) working reliably, full stop — not apps reaching around it. Do
+not have app A generate and execute raw SQL against app B's database, and do
+not expose B's internal tools directly to A as a substitute for delegation.
+The receiving agent has context, skills, and guardrails the caller doesn't;
+bypassing it to work around a flaky A2A call reintroduces exactly the bugs A2A
+exists to prevent, and makes the real reliability problem invisible instead of
+fixing it. If A2A delegation is unreliable, fix A2A — file it as a bug in the
+delegation path (timeout handling, retries, typed terminal states), don't
+route around it app by app.
+
 Connecting app A to app B is two independent things, and both must be true:
 
 1. **B is registered on A** as a `remote-agents/<id>.json` resource.

.agents/skills/concurrent-agents/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: concurrent-agents
+description: >-
+  How to work safely when many Claude Code and Codex agents share this one
+  checkout at once. Use before editing any file, before concluding someone
+  reverted your work, before any branch operation, and before committing,
+  pushing, or merging — this is almost always relevant here.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Concurrent Agents
+
+Steve runs many Claude Code and Codex sessions against this one checkout on
+purpose, often on the same branch or file. Default assumption on every task:
+any uncommitted change you did not make is a peer's live, in-progress work —
+not clutter, not a mistake, not yours to clean up, revert, or "tidy" away.
+Modified or untracked files you don't recognize are this repo's normal state.
+
+## Read before you edit
+
+Before touching a file that already has uncommitted changes, re-read it and
+build your edit on top of what's there. Landing your own complete fix over a
+peer's in-progress one has happened repeatedly — "another agent landed its own
+complete fix for the exact same bug in the exact same file, overwriting my
+in-progress edits on disk." There is no conflict, no warning; the edit vanishes.
+
+## Diagnosing "did someone revert my work" — correctly
+
+`git diff --stat` line counts are not evidence of a revert — a refactor can
+show the same magnitude of deletions. An agent once announced a revert from
+stat counts alone and was wrong; it cost a full investigation to disprove.
+Before you say "reverted" out loud, run:
+
+```bash
+git log --oneline <base>..HEAD    # what actually landed, in order
+git diff <base>..HEAD -- <path>   # the real hunks for the files in question
+```
+
+Read the hunks: a revert removes logic and puts nothing equivalent back; a
+refactor removes the same lines and adds different code doing the same job.
+Only the hunks tell you which happened — never `--stat` alone.
+
+## Never move branches without an explicit instruction
+
+Don't create, switch, delete, reset, rebase, stash, or worktree-add a branch
+unless the user asked for that exact operation in the current task — it
+strands every other agent on it. This isn't a tool-level block anymore —
+`.agents/skills/new-branch/SKILL.md` carries it now, through an activation
+guard that refuses to fire unless the user explicitly asked for `/new-branch`
+or a fresh branch. That guard is what took unrequested branch creation from a
+recurring complaint to zero; read it before any branch operation instead of
+assuming a prohibition still lives at the tool layer.
+
+## Timing the next branch around in-flight peers
+
+Unrequested branch creation is solved; the residual risk now is timing.
+Cutting a fresh branch right after your own merge, while other agents are
+still mid-flight on the branch you're about to leave, strands their
+uncommitted work just as surely as an unrequested branch move would. Before
+running `/new-branch`, even on an explicit request, check who else is still
+using the current branch:
+
+```bash
+git status --short                          # uncommitted changes here — yours or a peer's
+ls -la .claude/leases/ 2>/dev/null           # fresh (<15 min) leases = a session actively editing
+ls .claude/worktrees/ 2>/dev/null            # peers working this branch from a separate worktree
+gh pr list --head "$(git branch --show-current)" --state open
+```
+
+If any of those show live activity, say so and confirm with the user before
+moving off the branch — don't assume a merge landing means everyone else is
+done with it too.
+
+## File leases
+
+`scripts/hooks/file-lease.mjs` claims a file on every edit and denies the next
+write when another live session leased it in the last 15 minutes, or the file
+changed on disk since your session last wrote it. Both mean stop and look, not
+force through: work a different file, or re-read it and build on the landed
+change before writing again. If it's genuinely your file being taken back,
+say so in your response after re-reading.
+
+## Before you ship
+
+Assume another agent may already be committing, pushing, or opening a PR for
+the same fix — "stop shipping, another agent is doing that right now" is a
+real recurring collision. Before you commit, push, or merge, check `git log
+--oneline -5`, `git status`, and `gh pr list --head <branch>` for a PR someone
+already opened. If the work you were about to do just landed, say so and stop.
+
+## Reading a Codex peer's intent
+
+Relaying between agents by hand is the user's most tedious job — don't make
+him paste what a Codex session is doing. Read its transcript yourself:
+
+```bash
+ls ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
+```
+
+Each line is a JSON event; `payload.type == "user_message"` is what the user
+asked, `payload.type == "agent_message"` is what it answered — enough to learn
+a peer's task without interrupting it or the user.
+
+## Related
+
+- `new-branch` — the one workflow allowed to move branches, only on explicit
+  `/new-branch` invocation.
+- `ship` — the commit/push/PR workflow; check for an in-flight peer first.

.agents/skills/delegating-work/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: delegating-work
+description: >-
+  Which tier — main thread vs. a cheaper subagent — owns a piece of work,
+  decided at the moment you're about to start it. Use before writing an
+  implementation yourself, driving a browser, babysitting a PR, running a
+  test/fix loop, or doing a mechanical multi-file sweep on the main thread.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Delegating Work
+
+## Activation guard
+
+Use this at the moment you're about to start a multi-step task yourself —
+before the first line of code, the first browser action, the first CI poll,
+or the first test run. It applies whenever the main thread is about to *do*
+work, not just when the user says "parallelize this."
+
+Skip it for a genuinely single small edit with nothing independent to split
+off — spawning overhead would exceed the work itself.
+
+## Do NOT do this on the main thread
+
+Each of these is a real temptation, not a hypothetical — they're the
+single most-repeated correction the user gives, most recently today
+(2026-07-31):
+
+- **Writing the implementation yourself** because the change "looks quick." Spawn
+  a coding subagent even for a small fix; the main thread reviews the diff, it
+  doesn't produce it. *"Hmm why are you coding on the main thread? You're
+  supposed to spawn cheaper models like sonnet to write the code."*
+- **Driving the browser yourself** for a UI check or E2E pass. Spawn a subagent
+  to run Playwright / Chrome DevTools MCP and report back. *"use cheaper sub
+  agents for testing ... don't use fable (you) for browser automation bro"*
+- **Babysitting a PR yourself** (polling CI, pushing fixups). Spawn a subagent to
+  watch and fix. *"please use a cheaper model to do the babysitting - like
+  sonnet. not you"*
+- **Running the test/fix retry loop yourself.** Spawn a subagent to run tests,
+  read failures, patch, and re-run until green. *"i prefer to use terra sub
+  agents for testing/fixing and not use you, the main thread, for these
+  things like i see you doing rn"*
+- **Doing a mechanical multi-file sweep yourself** (renames, lint fixes, the
+  same small edit repeated across files). Split by file set, one subagent per
+  slice.
+- **Skipping delegation "just this once"** because the task feels urgent. Cost
+  is the reason to delegate, not an excuse to skip it. *"this run is getting
+  really expensive ... fable model is now per-token pricing so this is
+  costing me thousands"*
+
+## Decision table
+
+| Kind of work | Tier |
+| --- | --- |
+| Planning, architecture, ambiguity calls | Main thread |
+| Synthesis / final review of subagent output | Main thread |
+| Talking to the user | Main thread |
+| Writing an implementation slice | Cheap subagent |
+| Browser automation / E2E verification | Cheap subagent |
+| PR babysitting (CI polling + fixups) | Cheap subagent |
+| Test-fix-retry loops | Cheap subagent |
+| Mechanical sweeps (rename, lint, repeated edit) | Cheap subagent(s), one per disjoint file set |
+| Research / repo scans / docs extraction | Cheap subagent |
+
+Default to the cheapest tier that can do the work reliably — Haiku for
+bulk/mechanical work, Sonnet for anything needing real coding judgment.
+Reserve the expensive/frontier model for the main-thread row above. This is a
+standing instruction: don't ask the user for permission to parallelize.
+
+## What the main thread keeps
+
+Planning, prioritization, ambiguity resolution, integrating what subagents
+return, final review before the user sees it, and all direct conversation
+with the user. Everything else in this table is a delegation candidate by
+default, not an exception.
+
+## Parallel edits are the intended pattern, not a risk
+
+This repo has exactly one collision guard: `scripts/hooks/file-lease.mjs`. It
+denies a write only when another live session leased the same file in the
+last 15 minutes, or the file changed on disk since your session last wrote
+it. Parallel subagents editing disjoint files is normal and expected here —
+give each subagent its own file set up front so leases never collide, and let
+the hook catch the rare real overlap instead of avoiding parallelism to be safe.
+
+## Related skills
+
+This skill is the decision point; it doesn't replace the workflows that
+follow it:
+
+- `efficient-frontier` — the orchestration workflow once you've decided to
+  delegate: handoff packets, fan-out limits, the review loop.
+- `efficient-fable` — the same workflow, plus Fable's per-token pricing as a
+  reason it matters even more.
+- `delegate-to-agent` — the briefing contract (objective / context / output /
+  boundaries) and fan-out discipline (cap ~3, default to one) for spawning a
+  sub-agent from the main thread.

.agents/skills/fix-at-the-boundary/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: fix-at-the-boundary
+description: >-
+  How to find every sibling instance of a reported bug before fixing it. Use
+  whenever a bug report names one file but the defect is a call pattern,
+  hook, duplicated literal, or copy-pasted helper that plausibly exists in
+  other files, apps, or templates.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Fix at the Boundary
+
+## Activation guard
+
+Use this skill when a reported bug's root cause is a **pattern** — a function
+shape, a write sequence, a device/permission check, a duplicated literal, a
+copy-pasted helper — rather than a fact unique to the one file named in the
+report.
+
+If the bug is genuinely local (a typo, a value that only makes sense for that
+one app, a one-time data fix), say so explicitly — "this is local to
+`<file>`, no sweep needed" — and skip the rest of this skill. Don't sweep as
+theater.
+
+### Do NOT skip the sweep in these situations
+
+- "The report only names one file, I'll patch that and move on." A stale-diff
+  write race, a mic-device resolution order, a missing scoped-access check —
+  these are usually copy-pasted everywhere the same operation is implemented.
+- "I found 3 callers and fixed those, that's probably all." Enumerate every
+  hit from the search *before* editing anything — stopping at the first few
+  you notice is how instances 4–9 survive.
+- "Grepping the whole repo will take too long." A few `rg` calls take
+  seconds; rediscovering the same fix across four more user reports doesn't.
+- "This looks like the same bug in an area I don't own, but that's not what I
+  was asked to fix." Still enumerate it — just don't edit it (see below).
+- "I fixed the shared helper, callers will pick it up automatically." Only
+  true if every sibling actually calls it — confirm with the same search.
+
+## Workflow
+
+1. **Derive the fingerprint from the symptom**, not the file: the exact
+   function/hook name, the anti-pattern shape (read stale state → write
+   without re-checking), a literal string, or an import path.
+2. **Search before editing:**
+   ```bash
+   # exact call/hook, whole repo
+   rg -n "computeDiffBase\(|stashLocalDiffBase\(" --type ts -g '!**/node_modules/**'
+   # duplicated literal (device id, action name, config key)
+   rg -n "'design-native-asset'" -g '*.ts' -g '*.tsx'
+   # same shape copy-pasted across template apps
+   rg -n "getUserMedia" templates/*/app templates/*/src 2>/dev/null
+   ```
+   Widen the pattern (drop args, add `-C 3`, try a sibling term like
+   `diffBase` vs `diff_base`) until confident no caller phrases it slightly
+   differently.
+3. **Enumerate every hit before touching any file** — write the list in your
+   response so step 5 is checkable.
+4. **Decide where the fix lives.** A shared helper some callers bypass →
+   fix the helper and point bypassers at it. No shared helper and N ≥ 3
+   duplicate sites → consider extracting one instead of pasting a 4th time.
+5. **Apply the fix to every in-scope hit.**
+
+### Ownership boundaries
+
+Enumerating isn't editing. A hit inside a path this task's `DO NOT TOUCH`
+list assigns to another agent gets listed as found-but-out-of-scope and
+flagged via `spawn_task` or a direct note — never silently edited or
+silently dropped. See **concurrent-agents**.
+
+## Reporting the sweep
+
+Report the full blast radius, not just what you changed:
+
+```
+Fixed the stale-diff-base race in:
+- insert-design-native-asset.ts (as reported)
+- insert-asset.ts, apply-a11y-fix.ts, generate-design.ts (same pattern)
+Found but out of scope (owned by another agent this task): apply-visual-edit.ts
+in templates/design/** — flagged via spawn_task.
+No other callers of computeDiffBase().
+```
+
+## Why this exists
+
+- "apply-visual-edit.ts has the same stale-diff-base write-race bug that was
+  just fixed in insert-design-native-asset.ts, insert-asset.ts,
+  apply-a11y-fix.ts ... and generate-design.ts" — one defect, 9 files, fixed
+  one report at a time instead of once.
+- Mic-device resolution was independently fixed in four different Clips
+  surfaces (`useMediaDevices.ts`, `media-capture-constraints.ts`,
+  `offscreen.ts`, `recorder-engine.ts`).
+- "i want to make sure universally cmd+click works ... can we do a quick
+  sweep of other apps" — the user had to ask for a sweep across 4 templates
+  that should have happened proactively.
+- "remember - if any other apps like in our core repo templates/ does this
+  wrong, fix that too" — exists only because the first fix didn't already
+  answer it.
+
+## Related Skills
+
+- **concurrent-agents** — why an out-of-scope sibling gets flagged, not edited.
+- **adding-a-feature** — the four-area checklist a proper fix should satisfy.