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

Skill	What it does	Primary install (Claude Code)
waves · Cursor + Codex	Turn one big task into a team of parallel subagents: a bounded, verified wave (Workers · Aggregate · Verify · Extend) instead of an open-ended loop. For big research, audits, data analysis, and codebase exploration.	/plugin install waves@rayfernando-skills
running-bug-review-board · QA	Point an AI agent at your live app; it QAs like a real user, files P0/P1/P2 bug reports, and returns a YES/NO ship verdict plus a shareable HTML report. Runs its parallel pass as a wave when waves is installed.	/plugin install running-bug-review-board@rayfernando-skills
bootstrap-ios · iOS/macOS	One entry point for Swift, SwiftUI, SwiftData/Core Data, Swift Testing, Xcode build/test/simulator, XcodeBuildMCP, and curated community iOS skills.	/plugin install bootstrap-ios@rayfernando-skills
swiftui-animation-match · iOS UX	Match a UI/UX interaction need ("saving should feel satisfying") to a proven SwiftUI animation pattern from curated open-source catalogs — or to the system affordance that makes custom motion unnecessary. Extensible: each new animation repo becomes one more catalog.	/plugin install swiftui-animation-match@rayfernando-skills

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:

	An open-ended loop	A wave
Stop condition	"Looks done," or the budget runs out	A verification barrier: evidence checked, then a deliberate extend-or-stop decision
Context	One thread carries every dead end forward	Isolated workers; only distilled, verified handoffs move between waves
More effort buys	More rounds over the same context; quality can drop as cost rises	More independent attempts in parallel, then selection, budgeted ~60% generation / 40% verification
Coverage	Whatever the loop happened to touch	A manifest written before spawning: N slices out = N handoffs checked back in
Bounds	Emergent	Explicit: 3–8 workers per wave, a stated worker/token budget, and a manifest-gated stop (completion, stagnation, or budget — never "we did two waves")

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).