rayfernando-skills

rayfernando-skills

A collection of installable Skill files for AI coding agents, built to play together instead of sitting in a grab bag. The centerpiece is waves, wave engineering for agent teams (WAVE = Workers · Aggregate · Verify · Extend): one big task fans out to a bounded, verified team of parallel subagents instead of grinding through an open-ended loop. Around it: running-bug-review-board, the real-user QA skill the collection started with (its parallel QA pass now runs as a wave), and bootstrap-ios, a single entry point for loading Ray's iOS/macOS agent skill stack.

Skills in this collection

Each skill installs into Claude Code, Cursor, Codex, and ~50 other agents; full per-agent steps are in the sections below.

Jump to: waves · running-bug-review-board (QA) · bootstrap-ios · swiftui-animation-match · Repo structure · Contributing

How the skills play together

This collection is becoming an ecosystem rather than a list. The skills reference and strengthen each other:

• waves is the orchestration layer. Any job too big for one clean linear pass (research, audits, data analysis, a QA sweep) can run as a bounded wave of parallel, verified workers.
• running-bug-review-board is its first consumer. When waves is installed, the QA skill's parallel mode runs as a wave: coverage-gated shards, structured handoffs, tiered verification of PASS/FAIL claims, and cheap-model routing for low-risk shards.
• One discipline, two agent platforms. The same wave playbook ships tuned for Cursor (waves) and Codex (waves-codex), with every Cursor→Codex translation recorded in adaptation-notes.md so the variants can't drift apart silently.
• bootstrap-ios is the router. Rather than pasting every community Swift rule into context, it loads the right focused skill for the task, the same progressive-disclosure principle the other skills are built on. When the task is animation or motion work, it routes to swiftui-animation-match.
• swiftui-animation-match is the first catalog skill. Its catalogs were themselves built with a wave: parallel read-only workers each read a slice of the source repo and returned structured entries. The recipe for cataloging the next animation repo (documented in the skill) reuses that same fan-out.

waves: wave engineering for agent teams

waves turns one big task into a team of agents. The lead agent splits the goal into independent slices, fans them out to isolated parallel Workers, Aggregates their structured handoffs, Verifies the evidence behind each one (the moat), and Extends into another wave only when the verified results earn it. A wave is a bounded round with verification as the stop condition, not an open-ended loop.

Reach for it when a single linear pass would be slow and the work splits into independent slices: big research jobs, whole-repo audits, large data analysis, multi-stream comparisons, codebase exploration. It ships as two tool-tuned variants with the same discipline and different mechanics:

• waves is for Cursor, built on parallel Task tool calls: isolated background subagents, custom .cursor/agents/ roles (with a fallback when a role isn't registered), per-slice model routing, and worktree-isolated competing attempts. It adopts the principles the Cursor team proved out in their cloud orchestrate plugin (planners plan, workers hand off up, no cross-talk) and runs in place of cloud orchestration — local subagent runs cover the whole workload with zero setup.
• waves-codex is for Codex, built on Codex subagents: built-in and custom TOML roles, spawn_agents_on_csv for row-shaped fleets, config.toml thread/depth limits, reasoning-effort routing, and codex exec fleets for scripted runs.

Why a wave and not a loop

The default way to push an agent through a big job is a loop: one context, one agent, iterate until it looks done. Loops fail quietly, in two ways. First, a loop doesn't know when to stop; its stop condition is "seems done," or a spent budget. Second, iteration is non-monotonic: past a point, more rounds make the output worse, not just more expensive, because one long context accumulates every dead end, and models told to "double-check yourself" with no external signal flip correct answers to wrong more often than the reverse (sources for these claims are cited in verification.md).

A wave restructures the work so neither failure can happen silently:

Loops aren't banned. They're right exactly when a cheap, reliable, near-ground-truth verifier exists and gives a crisp signal: a failing test, an exec error, a schema check. That's code-with-tests territory, and the skill says to keep loop-until-done there (still hard-capped). Everything open-ended (research, analysis, audits, writing, exploration) is where waves win: at equal cost, independent attempts plus verification usually beat critique/debate loops, and the verify round is what turns parallel exploration into one answer you can trust.

What a run actually looks like

1. Discover before decomposing. A few cheap tool calls to learn the shape of the problem. If the goal is vague, treat it as entropy reduction first: dig locally, send a small scouting wave at the unknowns, ask the user only when a question genuinely pays. Slicing a vague goal yields overlapping, mis-sized slices.
2. Stage the data and prove coverage. Remote or messy inputs get pulled, cleaned, and pre-chunked once, centrally, then checked (counts, bounds, partition sums) before anything spawns. A missing chunk is a silent blind spot.
3. Triage into a wave manifest. State the run shape out loud in one line, then give every slice a row (scope, worker type, model, depends_on, verification tier) written before spawning. The manifest doubles as the completion gate: a worker that never returns can no longer silently drop its slice.
4. Fan out in parallel. Wave 1 is every slice with no dependencies, launched at once as isolated workers; a dependent slice launches only after its dependency's handoff is verified. Each prompt is fully self-contained (workers can't see the chat) and ends with a required structured handoff format.
5. Verify before trusting. A worker's Status: success is a claim, not evidence. Every handoff gets cheap checks (citations resolve, scope matches, headline counts recount), and contested or high-stakes claims go to dedicated blinded verifiers that see the claim and its sources but never the generator's reasoning or authorship.
6. Extend deliberately, or stop. Open questions become candidate second-wave tasks; each barrier compresses the verified findings to disk so the next wave reads distilled synthesis, never raw transcripts. When a wave surfaces nothing new, the run is over.
7. Deliver one artifact, with each claim's confidence carried through (verified / single-sourced / unverified). A low-confidence finding never gets laundered into a confident sentence.

The run that shaped the skill: one "analyze all my messages and build a roadmap" request became 16 workers across 3 waves, and the staging gate caught a timestamp-sort bug before fan-out, when it could still be fixed once centrally instead of corrupting the partition every data worker depended on. The full worked example and reusable recipes (repo audit, row-shaped codemod, CI-failure triage, implement-a-reviewed-plan) are in examples.md.

The discipline that makes it converge

• Verification is the stop function. The single load-bearing idea: a wave ends at a barrier where evidence is checked before anything extends the run. Everything else exists to make that check cheap and honest.
• Entropy-first decomposition. Reduce uncertainty (dig locally → scouting wave → ask last) before slicing, aiming each probe at the unknown that eliminates the most plans. Grounded in the information-gain literature, with the mechanisms (not just the citations) written into the skill.
• Tiered, blinded verification. Spend the checking budget by stakes: auto-accept → single verifier → multi-model panel → debate. Verifiers reason against the cited sources with authorship hidden, because LLM judges favor output labeled as their own.
• Per-slice model routing. Scouting and read-heavy slices run on cheap fast models (Composer on Cursor, low reasoning effort on Codex); frontier models are reserved for verification, synthesis, and high-stakes calls. Model slugs are read from the environment, never guessed.
• Multi-model panels for the highest stakes. Fan the same contested slice to several different models and synthesize one verdict. Most of the gain is in the synthesis step, not the model diversity (OpenRouter's Fusion result), and judge panels drawn from disjoint model families beat a single frontier judge (PoLL).