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).
• Context hygiene between waves. One scratch dir per run (.waves/<run>/), handoff digests capped, synthesis compressed at every barrier. Long, irrelevant context measurably degrades reasoning, so it never travels.
• Measured, not vibed. Both variants ship evals/: with-skill vs baseline A/B runs in fresh sessions, graded PASS/FAIL against fixtures with seeded ground truth, including a deliberately wrong count and a phantom citation the orchestrator must catch before synthesis.
• Re-verified mechanics. The Cursor/Codex plumbing carries a "checked on" date and gets re-verified against live docs and bug trackers. When good ideas show up elsewhere (a public deep-research skill, the Cursor team's orchestrate plugin), they're verified first, then folded in.

How it enriches the other skills

Waves is the orchestration layer of this collection, and the QA skill is its first consumer. With waves installed, running-bug-review-board runs its parallel pass as a bounded wave: a Test-ID coverage gate before launch (every scenario in exactly one shard, counts sum to the plan), structured shard handoffs instead of transcript-tailing, tiered verification of PASS/FAIL claims (the coordinator personally re-runs write-path and highest-risk IDs), and cheap-model routing for low-risk shards (details). Same pattern, different domain: QA shards are just slices, and run reports are just handoffs.

Example prompts

Because a run spawns more agents than usual, it's opt-in: invoke it explicitly with /waves (or /waves-codex) rather than relying on auto-trigger (disable-model-invocation: true).

/waves analyze all 3,000 tickets in support-tickets.csv and rank the top themes with counts

/waves research OpenAI Realtime, LiveKit, and Pipecat for a voice agent, then give me a comparison and recommendation

/waves audit this repo across security, performance, dead code, and test coverage in one severity-ordered report

/waves read my whole chat export, find the recurring goals and frustrations, and turn them into an app roadmap

/waves implement the reviewed plan in docs/plan.md: research wave, then disjoint edit workers, then a verify wave

Install waves

Cursor:

npx skills add https://github.com/RayFernando1337/rayfernando-skills/tree/main/plugins/waves/skills/waves -a cursor

Codex:

codex plugin marketplace add RayFernando1337/rayfernando-skills
codex plugin add waves-codex@rayfernando-skills

Claude Code: /plugin install waves@rayfernando-skills (Cursor-tuned) or /plugin install waves-codex@rayfernando-skills (Codex-tuned).

Cross-vendor (npx skills add): point the installer at either skill folder and pass -a <agent> (e.g. -a codex, -a claude-code, --all).

What's inside

• SKILL.md (per variant): the orchestration playbook, covering the loop, bounded-wave caps, the worker prompt contract, verification tiers, and model routing.
• references/: handoff-format.md (the structured worker handoff contract), verification.md (the verification playbook, with sources), and examples.md (the worked run + decomposition recipes). The Codex variant adds recommended-config.md and adaptation-notes.md, the Cursor→Codex translation record.
• evals/: scenarios, fixtures with known ground truth, and the A/B grading protocol (evals/README.md).

running-bug-review-board: real-user QA

running-bug-review-board points an AI agent at your live app to QA it like a real, slightly unforgiving customer: it drives the UI, files structured P0/P1/P2 bug reports with reproduction steps, and gives you a YES/NO "is this ready to ship?" verdict, plus a self-contained HTML report you can hand to the team.

What you get

Most AI workflows point at code review and miss where users actually hit bugs: the live app, on a real phone, with stale storage from yesterday and a flaky auth provider the unit tests never see. This Skill file encodes a battle-tested QA cadence so an agent can find those bugs for you.

• A real-user QA pass, not a code review. The agent drives the app from URLs and clicks; it is forbidden from marking anything "pass" by reading source. It hunts the failures users hit first: stale state across flows, mobile overflow, auth↔routing races, copy that lies, paths that 404 mid-onboarding.
• Structured bug reports. Every defect lands as BUG-NNN-*.md with severity (P0/P1/P2), impact, what-happened-vs-expected, reproduction steps, and evidence (screenshots, console, network).
• A ship/defer decision. Each pass ends with a YES/NO sign-off for the phase, listing open P0/P1 blockers and a paste-ready handoff prompt for the next agent.
• An editorial HTML dashboard stakeholders can open and share: the bug list and each bug report, regenerated every pass. (see it below)
• Works with what you have. Repo-agnostic and browser-tool-agnostic; web and iOS/iPadOS apps; optional two-way sync with Linear, GitHub Issues, Jira, or Notion. Runs fine in a cloud VM (e.g. Cursor cloud) with just a browser driver.

See the output

The agent regenerates a self-contained HTML report at the end of every pass, designed to read like a magazine, not a Kanban board (editorial typography, ink-on-paper palette, no chips or pills). Here is what you instantly get:

The QA dashboard	A single bug report
Verdict first, then the prioritized bug list and recent runs.	One bug, told for an engineer: impact → what's happening vs. what should → steps → evidence.

It is responsive, too: on a phone the dashboard collapses to a single column with a sticky primary action. (mobile sample · design notes)

Example prompts

Once the skill is installed, just ask your agent in plain language:

QA this app. Run a manual test plan on mobile and tell me what's broken.

Is phase 3 ready to ship? Give me a YES/NO with the open P0/P1 list.

Drive the signup flow like a brand-new user with stale storage, and file any bugs you find.

Re-test the fixed bugs BUG-007 and BUG-012 on the latest build and update the report.

Run the Interactive Bug Review Board with me on the open backlog.

The skill activates on phrases like "QA this", "is this ready to ship?", "find the bugs", or "run a test plan", so you don't have to name it.

Quick start

After installing, the agent walks itself through:

1. Discover the app: read the product spec / README / phase doc, open bugs, and public routes.
2. Plan: derive real-user scenarios from the spec and the gates.
3. Prepare: environment, test accounts, primary viewport.
4. Execute: drive the app like a customer, capturing evidence.
5. File bugs: BUG-NNN-*.md with priority + reproduction steps.
6. Sign off: YES/NO verdict, open P0/P1 list, and a paste-ready handoff.

No QA folder yet? The skill ships a scaffolder. After installing it lives in the Skill folder (e.g. ~/.claude/skills/running-bug-review-board/scripts/scaffold-qa.sh). To run it without installing, clone and call it directly:

git clone https://github.com/RayFernando1337/rayfernando-skills.git
bash rayfernando-skills/plugins/running-bug-review-board/skills/running-bug-review-board/scripts/scaffold-qa.sh \
     /path/to/your/repo PHASE_NUMBER

This creates docs/qa/ with the bug template, run-report skeletons, gates checklist, and a per-phase manual test plan. It is idempotent and won't overwrite existing files.

Install

Pick the section for the agent you use. Each one installs the same Skill file; they differ only in how the agent discovers it.

Claude Code

/plugin marketplace add RayFernando1337/rayfernando-skills
/plugin install running-bug-review-board@rayfernando-skills

To pin a specific release tag, append it to the marketplace add (e.g. @v0.4.0). Docs: code.claude.com/docs/en/plugin-marketplaces.

Factory Droid

droid plugin marketplace add https://github.com/RayFernando1337/rayfernando-skills
droid plugin install running-bug-review-board@rayfernando-skills

Factory Droid reads the same .claude-plugin/marketplace.json Claude Code uses. Docs: docs.factory.ai/cli/configuration/plugins.

Codex (app, desktop, IDE, and CLI)

On Codex CLI, add the marketplace and install:

codex plugin marketplace add RayFernando1337/rayfernando-skills
codex plugin add running-bug-review-board@rayfernando-skills

On older Codex CLI without plugin add, open Codex, type /plugins, switch to the rayfernando-skills tab, and Install. In the app/desktop, use the Plugins / Skills installer and restart Codex so the skill cache reloads. Docs: developers.openai.com/codex/plugins/build.

Cursor

Cursor's /add-plugin is reserved for the cursor.com/marketplace listings, so for this repo use the cross-vendor installer. It writes the Skill folder into ~/.cursor/skills/, which Cursor reads on startup:

npx skills add https://github.com/RayFernando1337/rayfernando-skills/tree/main/plugins/running-bug-review-board/skills/running-bug-review-board -a cursor

Docs: cursor.com/docs/skills.

Cross-vendor: npx skills add

The vercel-labs/skills installer detects every supported agent CLI on your machine and writes the Skill folder into each one's expected location (Claude Code, Cursor, Codex, Factory Droid, Windsurf, Zencoder, and ~50 others):

npx skills add https://github.com/RayFernando1337/rayfernando-skills/tree/main/plugins/running-bug-review-board/skills/running-bug-review-board

Add -a <agent> to target one tool (-a cursor, -a codex, -a droid) or --all for every detected agent.

claude.ai (Settings → Features → Skills)

Download running-bug-review-board.zip from the latest release and upload it. To build the zip from a local clone (claude.ai expects a zip whose root contains SKILL.md):

cd plugins/running-bug-review-board/skills
zip -r ../../../running-bug-review-board.zip running-bug-review-board

Manual install (any other agent)

Clone once and symlink the Skill folder into whichever directory your agent reads:

git clone https://github.com/RayFernando1337/rayfernando-skills.git ~/Code/rayfernando-skills
ln -sf ~/Code/rayfernando-skills/plugins/running-bug-review-board/skills/running-bug-review-board \
       ~/.<agent>/skills/running-bug-review-board

Replace ~/.<agent>/skills/ with your agent's path (~/.cursor/skills/, ~/.codex/skills/, ~/.factory/skills/, …). The same symlink can be committed inside a project (e.g. under .claude/skills/ or .cursor/skills/) so anyone who clones it picks up the skill.

How it works

• Drives the live app. The agent works through URLs and clicks; marking PASS from code inspection alone is forbidden.
• Three hats, one pass. Every pass wears PM (does it still deliver the promise?), QA (run the user scenarios with evidence), and Engineer (catch invalidated assumptions). Finding gaps is the point.
• BRB cadence. Bugs live in a versioned folder with status transitions (open → in-progress → fixed → verified). P0/P1/P2 tells the team what to ship and what to defer. Triage happens in a separate Interactive Bug Review Board session so triage bias never contaminates discovery.
• Tool- and repo-agnostic. Adopts whatever conventions exist and scaffolds folders when there are none. Parallel or sequential QA modes, and when the waves skill is installed, the parallel pass runs as a bounded wave: Test-ID coverage gate, structured shard handoffs, tiered verification, cheap-model routing for low-risk shards, and evidence kept on disk instead of in context.

Browser & Computer Use

The agent drives the UI with the best driver your environment has, falling back gracefully, so a pass succeeds whether you're in Cursor, another IDE, or a headless cloud VM:

1. cursor-ide-browser MCP (default inside Cursor)
2. Chrome DevTools for agents (chrome-devtools-mcp): auto-waits for results (fewer flaky races) and adds network / console / Lighthouse / accessibility introspection; can attach to your real signed-in Chrome so auth flows don't get bot-flagged
3. browser-use MCP / Playwright
4. Codex Computer Use (macOS): a human-fidelity pass that sees, clicks, and types in the real app, and the only way to reach a native macOS app
5. Manual driving with screenshot/console relay

Details and "drive like a human (don't trip the tests)" recipes live in the browser playbook and the Computer Use playbook. For iOS/iPadOS apps the skill orchestrates and defers simulator driving to the iOS community's purpose-built skills, and it never spins up an iOS simulator for a web-only app.

What's inside

Each Skill file uses progressive disclosure: a lean SKILL.md entry point, with references loaded only when needed. Auditing the skill (or asking your own agent to security-check it) starts at:

• SKILL.md: the entry point, covering workflow, surfaces, modes, and deliverables.
• references/: the detailed playbooks (discovery, test plan, browser, Computer Use, iOS, trackers, triage, HTML report, extending).
• scripts/: tiny shell helpers (scaffold a QA folder, list bugs needing tracker sync/pull). No magic; the agent does the work.

bootstrap-ios: load the iOS agent stack

bootstrap-ios is a meta-skill for Apple-platform app work. It gives agents one place to start before touching iOS, iPadOS, macOS, Swift, SwiftUI, SwiftData, Core Data, Swift Testing, Xcode build/test/debug, Simulator, or App Intents.

It does not try to paste every community Swift rule into context. It routes the agent to the right focused references and tools:

• Paul Hudson / Hacking with Swift skill packs for SwiftUI, concurrency, Swift Testing, and SwiftData.
• Antoine van der Lee / SwiftLee skill packs, including Xcode Build Optimization.
• Official OpenAI build iOS/macOS plugin references.
• Krzysztof Zablocki's public Merowing rules and rule-loader approach.
• AppCreator buildability ideas.
• XcodeBuildMCP for parseable Xcode build, test, simulator, and debug flows.

Install the skill:

/plugin install bootstrap-ios@rayfernando-skills

Cursor / cross-vendor install:

npx skills add https://github.com/RayFernando1337/rayfernando-skills/tree/main/plugins/bootstrap-ios/skills/bootstrap-ios -a cursor

Optional one-command helper, after installing or cloning:

bash plugins/bootstrap-ios/skills/bootstrap-ios/scripts/bootstrap-ios-skills.sh --dry-run --agent cursor

Run without --dry-run only when you really want to install the public community skill packs into that agent environment. After a real install the helper verifies every expected skill landed and is complete: each skill must have a SKILL.md under a known skill root, and every references/, scripts/, and assets/ file it cites must exist on disk. The script fails loudly with reinstall instructions (npx skills add <url> --full-depth) if any skill is missing entirely or installed shallow — either way agents would follow a references/ pointer into nothing and silently degrade. Pass --skip-verify to opt out.

swiftui-animation-match: interaction-to-animation matching

swiftui-animation-match turns a vaguely felt interaction wish — "saving should feel more satisfying", "the empty screen is boring while it loads" — into either a specific, proven SwiftUI animation pattern from a curated catalog, or the deliberate decision that the system already covers it.

Most of the time you know the feeling you want, not the animation's name. This skill encodes the judgment step: name the interaction moment (waiting, confirming, toggling, browsing, revealing…), check what modern SwiftUI gives you free (springs, .symbolEffect, .contentTransition, .sensoryFeedback, Liquid Glass chrome on iOS 26+), and only then match into cataloged custom motion that earns its place. The catalogs are a menu, not a quota — the skill is explicitly biased against forcing an animation where the platform already shines.

What's in the first catalog

The launch catalog covers Shubham0812/SwiftUI-Animations (Apache-2.0, iOS 17+): 30 self-contained SwiftUI animations plus 7 Metal shader effects, every one read at source level and cataloged with its exact repo path, the load-bearing technique (matchedGeometryEffect scatter, animatableData shape morphs, traveling .trim windows, layerEffect shader wiring…), the spring/duration values that create the feel, lift notes (dependencies, difficulty, known bugs to fix on lift), and search keywords. Entries are grouped by interaction moment: wait states, determinate progress, action feedback, toggles with identity, card decks and carousels, text heroes, input chrome, reveals, and shader effects.

Built to grow

Send it another animation repo and it becomes one more catalog file: adding-a-source.md documents the repeatable recipe — stage and pin the repo, fan out parallel read-only workers over folder slices (a wave, if waves is installed), each returning entries in the fixed block format, then assemble, register in sources.md, and spot-check claims against the pinned commit.

Example prompts

Plan the onboarding flow for my recipe app — where would animation actually help, and which patterns?

The download button in my app feels dead. What's a proven pattern for inline download progress?

I want deleting a note to feel consequential. What fits?

Users don't notice the app is syncing — suggest something calm, not a spinner.

Add https://github.com/<owner>/<another-animation-repo> to the animation-match skill.

Install swiftui-animation-match

Claude Code: /plugin install swiftui-animation-match@rayfernando-skills

Cursor / cross-vendor:

npx skills add https://github.com/RayFernando1337/rayfernando-skills/tree/main/plugins/swiftui-animation-match/skills/swiftui-animation-match -a cursor

What's inside

• SKILL.md: the matcher — moment-first workflow, system-vs-custom decision rules, restraint rules, adaptation posture.
• references/matching-playbook.md: the moment taxonomy, the system-first checklist, worked examples, anti-patterns.
• references/catalog-shubham0812-swiftui-animations.md: the 37-entry catalog with shared-infrastructure notes and a lift checklist.
• references/sources.md: source index with pinned commits, licenses, and the staleness policy.
• references/adding-a-source.md: the recipe for cataloging the next repo.

Repo structure

rayfernando-skills/
├── .claude-plugin/
│   └── marketplace.json                 # marketplace catalog
├── plugins/
│   ├── waves/                     # Cursor variant (parallel Task tool subagents)
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json               # plugin manifest
│   │   └── skills/
│   │       └── waves/
│   │           ├── SKILL.md
│   │           ├── references/           # examples, handoff-format, verification
│   │           └── evals/                # evals.json + fixtures + eval README
│   ├── waves-codex/               # Codex variant (subagents + config.toml)
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   │       └── waves-codex/
│   │           ├── SKILL.md
│   │           ├── agents/openai.yaml
│   │           ├── references/           # adaptation-notes, examples, handoff-format, recommended-config, verification
│   │           └── evals/                # evals.json + fixtures + eval README
│   ├── running-bug-review-board/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   │       └── running-bug-review-board/
│   │           ├── SKILL.md              # lean entry point; references load on demand
│   │           ├── references/           # loaded on demand
│   │           │   ├── workflow.md
│   │           │   ├── discovering-the-app.md
│   │           │   ├── test-plan.md
│   │           │   ├── test-accounts.md
│   │           │   ├── session-hygiene.md
│   │           │   ├── browser-playbook.md
│   │           │   ├── computer-use-playbook.md
│   │           │   ├── ios-simulator-playbook.md
│   │           │   ├── parallel-coordinator.md
│   │           │   ├── sequential-wrapup.md
│   │           │   ├── bug-filing.md
│   │           │   ├── gate-merge.md
│   │           │   ├── issue-trackers.md
│   │           │   ├── brb-interactive.md
│   │           │   ├── triage-heuristics.md
│   │           │   ├── html-report-style-guide.md
│   │           │   ├── extending-the-skill.md
│   │           │   └── templates/        # bug, test-plan, run-report, merge, BRB,
│   │           │       │                 #   qa-config, and html-report/ + samples/
│   │           │       └── html-report/
│   │           └── scripts/
│   │               ├── scaffold-qa.sh           # create the QA folder layout
│   │               ├── bugs-needing-sync.sh     # list bugs missing a tracker ID
│   │               └── bugs-needing-pull.sh     # list bugs with stale tracker sync
│   ├── bootstrap-ios/                            # iOS/macOS router skill + optional installer helper
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   │       └── bootstrap-ios/
│   │           ├── SKILL.md
│   │           ├── references/           # workflow, skill map, XcodeBuildMCP, sources
│   │           └── scripts/
│   │               └── bootstrap-ios-skills.sh
│   └── swiftui-animation-match/                  # interaction-to-animation matcher
│       ├── .claude-plugin/
│       │   └── plugin.json
│       └── skills/
│           └── swiftui-animation-match/
│               ├── SKILL.md
│               └── references/           # matching playbook, catalogs, sources, adding-a-source
├── scripts/
│   ├── validate-skill-metadata.py        # release-time Codex-metadata validator
│   └── validate-skill-evals.py           # release-time skill-eval validator
├── .github/workflows/release.yml         # builds the claude.ai zip on tag push
├── CHANGELOG.md
├── LICENSE
└── README.md

Contributing

Issues and PRs welcome. If you've used the Skill file on a real project, a short writeup of a lesson learned is the most valuable contribution: a session-hygiene rule that saved you, a bug that reveals a new real-user pattern, or a playbook for an auth provider this skill doesn't cover yet. See extending-the-skill.md for how the skill grows without rewrites. For the waves variants, changes to orchestration guidance should be checked against the skill evals (evals/README.md in each variant): run the with-skill vs baseline A/B and report the delta.

Style guide: SKILL.md body under ~500 lines with references one level deep; imperative voice; third-person frontmatter description; examples from real projects; no time-sensitive copy (use "old patterns" sections instead).

Background

Ray spent 12 years at Apple working across many parts of the system. The lesson he carried away: finding the bugs your users would hit first comes from a repeatable workflow, and he has been refining that cadence on his own projects ever since. The Skill files in this collection are his encoding of that work, and waves generalizes the same instinct, verify before you trust, from QA passes to whole teams of agents.

Changelog

This project follows Semantic Versioning and Keep a Changelog. Recent highlights: run-shape triage, dependency-aware dispatch, and missing-role fallbacks in both waves variants (adapted from a public deep-research skill, re-verified against live Cursor/Codex docs); skill evals and deeper paper grounding for waves; entropy-first decomposition and per-slice model routing; the QA skill's parallel pass running as a wave; plus a Computer Use + Chrome DevTools driver playbook, an editorial HTML report (Zite + Dieter Rams), and confirmed two-way issue-tracker sync. Full history in CHANGELOG.md.

License

Apache License 2.0, copyright 2026 Ray Fernando. The Skill files here can be used, modified, and redistributed in any project, including commercial and internal use. Attribution is appreciated but not required.