Stage 3 · build

Dev team pack reference

Every skill in the Dev team pack — what it makes, when to use it, what it needs, its quality bar, and what it hands off to.

Build-and-ship: story splitting, implementation with adversarial review, test plans, triage, pull request descriptions, a ranked technical-debt register, migrations, launch readiness, release notes, agent-policy files, and code-quality gates.

Skills

accessibility-audit

Adversarially audit a UI (component code, page markup, screenshot, or flow) against WCAG 2.2 AA — findings cited to specific success criteria, centered on the user and assistive tech each one blocks, severity-tagged, with a concrete fix and what a scanner would miss.

Tier heavy · v0.1.0 · SKILL.md · skill page

Use it when the user wants an accessibility review, a11y audit, WCAG check, or to find what blocks screen-reader / keyboard / low-vision users before shipping.

A good result:

• Every finding cites a specific success criterion (number + name + level). Uncited "issues" are opinions.
• Every finding names the user group and assistive tech it blocks. No victim, no finding.
• Severity reflects task-completion impact, calibrated — not everything is a blocker, and a real keyboard trap is never a minor.
• Contrast and target-size claims are computed numbers against the threshold, not visual guesses.
• Coverage limits are stated and unverifiable checks are listed as must-test-with-AT, never silently passed. A screenshot audit never claims keyboard operability is fine.
• [auto] vs [manual] is tagged, so CI-gateable findings are separated from the human-only ones.
• "What's solid" is present, so good semantics survive the next refactor.

Not for:

• Setting the accessibility target (which WCAG level, on which scope) — that's nfr-spec
• General code correctness/security review — that's devils-advocate
• Writing the component — fix findings in your normal build loop, or hand to feature-implement-loop
• A full certified VPAT/conformance attestation — this audit feeds one, but legal sign-off is a formal process beyond a review

agents-md-generator

Generate or audit a repository's AGENTS.md — the agent-policy file Claude Code, Codex, Cursor, Copilot, Kiro and Antigravity read — with every command traced to real evidence in the repo, generic virtue instructions stripped, and forbidden actions named.

Tier standard · v0.1.2 · SKILL.md · skill page

Use it when a repo has no AGENTS.md, when an existing one is stale or ignored, when onboarding a codebase to agentic coding, or when an agent keeps running commands that don't exist.

A good result:

• Zero unverified commands. Every one traces to a file and key, or is stated as a gap ([missing: …] in the provenance table, a plain "none defined" line in the file). This is the bar; a file that fails it is worse than no file.
• A newcomer agent could build and test from this file alone — or can see plainly that the repo has no such command.
• Forbidden actions are named, not implied.
• Every convention line passes the counterfactual test. If an agent would do the right thing without it, it is padding.
• ≤150 lines generated. Over the cap means something was kept that should have been cut.
• No virtue instructions survive. Search the output for "clean", "best practice", "thorough", "appropriate", "as needed" — each hit is a line that changes nothing.
• It does not restate the README. Different reader, different job: the README sells and explains, AGENTS.md constrains.

Not for:

• Writing human contributor docs — that's CONTRIBUTING.md, a different reader
• Explaining what the project is — that's the README
• Operating a running service — that's runbook-generator
• Reviewing an existing document's prose quality — that's doc-critique, which takes documents; this one takes a repository

behaviour-equivalence

Prove that a rewritten, migrated or refactored component behaves the same as the old one with a golden-master comparison — record inputs and outputs at a boundary (HTTP, function calls, batch files, DB writes, events) from production-shaped traffic and edge cases, run the old system twice to find its nondeterminism, normalise narrowly field by field, replay against the new one, triage every difference as defect, intended change (with a named approver) or missing normalisation, and give a verdict of EQUIVALENT, EQUIVALENT EXCEPT LISTED CHANGES, NOT EQUIVALENT or NOT PROVEN.

Tier standard · v0.1.2 · SKILL.md · skill page

Use it when the user asks "does the new one behave the same as the old one", "can we sign off the rewrite", "are these diffs just noise", wants a golden-master, approval or shadow-traffic comparison, a parity check between old and new outputs, or says "prove behaviour equivalence".

Needs: Python 3 for its scripts (standard library only).

A good result:

• The first line is one of the four verdicts with the reason in plain words.
• Every difference is classified as defect, intended change or missing normalisation; none is left as "minor".
• Every normalisation rule names one field and a reason, and the field varied old-vs-old.
• Money is compared exactly in minor units; any float tolerance is per field with a reason.
• Error behaviour and side effects are compared, not only return values.
• Coverage is stated by input class, and the verdict covers only the recorded classes.
• Intended changes name an approver from the input, or stay unresolved.
• Every case id, value, count and cause is from the input or the script output.

Hands off to: migration-plan when the verdict is EQUIVALENT or EQUIVALENT EXCEPT LISTED CHANGES and traffic or data still has to move.

Not for:

• Planning the refactor or rewrite steps themselves — refactor-plan
• Phasing a data or platform migration, backfill and cutover — migration-plan
• A test plan for a new feature or changed behaviour — test-plan-generator
• Getting oriented in the old codebase before starting — codebase-tour

bug-triage

Turn a vague bug report (Slack message, support ticket, "it's broken on mobile sometimes") into an actionable ticket — searchable symptom title, numbered repro steps from a clean state, expected vs actual, severity separated from priority, evidence tagged reported-vs-verified, and labeled hypotheses instead of root-cause guesses.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user wants to triage a bug, write up a bug report, turn a complaint into a ticket, or make a flaky issue actionable.

A good result:

• An engineer can start without contacting the reporter. Either the repro stands alone or the no-repro diagnostics list says exactly what to collect.
• Title findable by symptom search. If the words a future reporter would type don't appear in it, retitle.
• Zero untagged claims. Every factual statement is [reported], [verified], or [assumption] — a triager's authority comes from the tags.
• Severity and priority each have a stated reason, and they were judged independently — one line each, no shared justification.
• Hypotheses ≤ 3, each with a concrete check. A hypothesis without a check is a vibe.
• The verbatim error text is present when any error was shown — quoted exactly, not paraphrased.

Hands off to: feature-implement-loop when the defect is reproduced and scoped.

Not for:

• Actually fixing the bug — hand the ticket to feature-implement-loop or a human
• A production incident in progress — mitigate first; this is queue work, not response work
• The post-incident analysis — that's postmortem-generator
• A feature request wearing a bug costume ("bug: there's no dark mode") — route to user-story-splitter

codebase-tour

Get a newcomer (a new engineer, or the agent itself) oriented in an unfamiliar repository before they make one specific change, with a short tour scoped to that change. It gives the install, run and test commands taken from CI, package scripts and the Makefile; the path the change touches, traced through the code with file:line citations; where the change goes; the conventions the code actually follows; the traps (generated files, a second copy of the logic, untested code, env vars, flags); and a first step that can be checked.

Tier standard · v0.1.1 · SKILL.md · skill page

Use it when someone says "I'm new to this repo", "get me oriented", "where would I make this change", "walk me through the code for X", "onboard me before I start this ticket", or "how do I run and test this".

Needs: Python 3 for its scripts (standard library only).

A good result:

• Every claim has a citation or an [inferred] tag. Run a spot check: pick any three statements in the tour, and each must lead to a file and line that says it.
• Zero invented commands. Every command traces to CI, a package script, a Makefile, a tox or nox session or pyproject, or it is a labelled derived filter of a runner the repo already calls.
• Ran and read are never blurred. Every command carries ran: passed, ran: failed, or read, not run.
• README-versus-code conflicts are named, each with both citations and the code taken as the fact.
• Scoped, not surveyed. The path stops at the change's far edge, the tour fits the caps, and the scope line says what was skipped.
• The trap checks all report, including "none found". A second copy of the logic, when one exists, is named with its location.
• The tests for the area are named, with a command for just those, or the tour says plainly that there are none.
• It ends at a place to work. Files and functions, then a first step with a command and an expected result, then at most five open questions.
• The reply leads with the 3–5 things that matter, not a tree.

Hands off to: feature-implement-loop when the tour names where the change goes and a first step.

Not for:

• A full as-is architecture write-up or diagram of the whole system: reverse-architecture
• Drawing a diagram of a flow or a system: interactive-diagram or architecture-diagrams
• Writing a standing AGENTS.md or agent-policy file for the repo: agents-md-generator
• Writing the code for the change: feature-implement-loop
• Reviewing a diff that already exists: pre-merge-review

dependency-upgrade-review

Give a merge verdict on a dependency-upgrade pull request (Dependabot, Renovate or a hand-made bump) across npm, pip, Go, Cargo and Maven lockfiles and GitHub Actions pins. Reads the release notes for every skipped version, lists what the lockfile changes beyond the PR title (transitive bumps, new and removed packages, install scripts, registry changes), checks each SHA pin against its release tag and against the PR's other pins, checks raised runtime floors against the images and runners that install it, says whether CI ran the changed code, traces what each caller of a changed API now does and writes the rollback. The reply leads with MERGE, MERGE AFTER CHECKS or DO NOT MERGE and the reasons that decide it.

Tier standard · v0.2.1 · SKILL.md · skill page

Use it when the user says "review this Dependabot PR", "is this Renovate bump safe to merge", "can I merge this dependency upgrade", "check this lockfile diff", or "is this action SHA pin right".

Needs: Python 3 for its scripts (standard library only).

A good result:

• The first line is the verdict and the reasons that decide it, one verdict per PR, following from the checks. Any unverified SHA, added install script, or removed API still in use rules out MERGE.
• Every release between old and new is accounted for: read, with its breaking changes, runtime drops, deprecations, security fixes and licence changes, or named as unread.
• Everything the lockfile changes beyond the title is listed, in one line: transitive bumps, added and removed packages, install scripts, native code, source and runtime changes.
• Every changed API has a search result and every hit is traced: what the caller does now and the fix, or the search command when there is no repo.
• Every raised runtime floor is compared with the base image, the CI runtime, the runners and the lockfile tool's runtime.
• Every changed SHA pin is verified or given as the git ls-remote command, and the PR's pins are compared with each other.
• CI coverage is named per changed package: the job and test that exercise it, or "nothing does", and how each workflow installs.
• A rollback with the exact command and what a revert does not undo.
• Nothing reads as checked that was not run, and nothing describes the session's tools or network.
• No invented versions, advisories, APIs, files or test names; version numbers are copied from the notes.

Hands off to: migration-plan when the upgrade is a major framework or runtime jump that cannot land as one PR; pre-merge-review when the PR also carries hand-written code changes beyond manifests, lockfiles and pins.

Not for:

• Reviewing a PR whose substance is the repo's own code change: use pre-merge-review
• Writing the release notes or changelog for this project's next version: use release-notes
• Planning a multi-step framework or runtime migration (a major framework version across many services): use migration-plan
• Scanning installed skills for supply-chain patterns: that is the skilldrop scan command
• Choosing which library to adopt in the first place: this reviews a version change, not a selection

devils-advocate

Adversarial review of a code change before it merges — the real bugs, most consequential first, each checked against the code before it is reported, with a fix that works. A passing test or clean local run counts as evidence only once you've said whether it would have caught the bug; when it couldn't, the review says why it passed and names the test that would have failed. Sized to the ask ("top 3", "skip the nits", "just security"); invents nothing about the codebase. Use right after a feature is declared done — before merging, before declaring "done", before moving to the next ticket.

Tier heavy · v0.2.0 · SKILL.md · skill page

A good result:

• Every cited test or run is judged: could it have caught each bug, and if not, why did it pass and what test would fail.
• Every finding survives a trace through the code and the stated rules. No false positives.
• The answer to "can this merge?" comes first; findings are ordered by consequence.
• Fixes work, and are code when the change is small.
• The scope asked for is respected.
• Nothing about the codebase is invented.

Not for:

• For greenfield prototype or spike code that's about to be thrown away.
• For one-line or trivial changes.
• As a substitute for human code review — it's a pre-pass.
• For evaluating the choice of approach before code exists. That's a design conversation: design-doc, then doc-critique.
• For code in a language you can't reason about line by line. Refuse rather than fabricate findings.

feature-implement-loop

Implement a feature or story so it ends up verified, not just generated. Takes a description + acceptance criteria, writes code and tests, then runs an adversarial review pass that hunts for gaps (broken edge cases, baked-in assumptions, uncovered acceptance criteria), and re-generates to close them — looping until the review is clean or a 3-round cap is hit.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when handed a ticket / story / feature spec with acceptance criteria and the goal is shippable, self-checked code — not a first draft.

A good result:

• Every acceptance criterion maps to a test by the final report. A criterion with no asserting test is an ❌ open item — not a pass. This is the rule that makes the skill more than codegen.
• The review challenges the code; it doesn't rubber-stamp it. A round-1 review that finds nothing on a non-trivial feature is a smell — re-run it adversarially, assuming the first pass missed something (it usually did).
• Tests assert behavior, not just execution. ❌ a test that calls the function and checks it didn't throw. ✅ a test that asserts the criterion's expected output. Catch assertion theater in the review.
• Regeneration is targeted. Each round fixes the named gaps and leaves passing code alone. Don't rewrite the whole feature every round — that loses ground and never converges.
• The cap is real. 3 rounds, then stop and report. A loop that "just one more round"s past 3 is a bug. If it can't converge in 3, a human needs to see why.
• The round log is honest. If round 2 found nothing new, say so. If a gap was downgraded rather than fixed, say why. The log is the audit trail.

Hands off to: pre-merge-review when the code exists and the question is whether it can merge.

Not for:

• One-line fixes / trivial changes — the loop is overhead; just make the change.
• Greenfield spikes / throwaway prototypes — verifying code you'll delete wastes rounds.
• Specs with no acceptance criteria and none inferable — there's no gate to close. Get criteria first.
• Pure code review of code you didn't generate — that's devils-advocate standalone.
• Open-ended design questions ("should we use Postgres or Dynamo?") — that's design-doc + doc-critique.

launch-readiness

Produce a go/no-go launch readiness report for a merged change before it goes live — one row per check (rollback path, alert and runbook per new failure mode, NFR targets measured, comms drafted, data/privacy sign-off), each with an owner, evidence link, and met / not met / n/a-because status, ending in a PROCEED / PROCEED WITH CONDITIONS / REVISE / BLOCKED verdict.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user asks "are we ready to launch", "go/no-go", "production readiness review", "launch checklist", or "can we ship this to users".

A good result:

• Every row has evidence or is not met. Readiness asserted is not readiness.
• The failure modes are specific to this change. "The service could go down" is true of everything and checks nothing.
• Rollback is judged first and can block alone. Every other gap can be fixed while live; an irreversible launch with no way back cannot.
• The verdict follows mechanically from the rows. Two reviewers given the same rows reach the same verdict.
• Owners are roles. "Payments on-call", not a person who will change teams.

Hands off to: migration-plan when the change has no tested rollback path; observability-plan when a new failure mode has no alert; runbook-generator when an alert exists but has no runbook entry.

Not for:

• Deciding whether to merge. That is pre-merge-review's gate, which happens earlier.
• Planning the rollout phases themselves. That is migration-plan; this skill checks that the plan exists and has been rehearsed.
• Choosing when to launch. Timing and freeze windows are the release owner's call, or council-review's if they are contested.

migration-plan

Generate a phased migration or rollout plan (schema change, API version, datastore swap, platform move, auth-provider switch) — expand→migrate→contract by default, every phase reversible or its point of no return named, observable gates between phases, idempotent backfill with parity checks.

Tier standard · v0.1.1 · SKILL.md · skill page

Use it when the user needs a migration plan, cutover plan, rollout strategy, or asks "how do we get from X to Y without downtime".

A good result:

• Every phase is reversible, or is the named point of no return. A reader can answer "how do we get back from here?" for any row in the plan.
• Every gate is observable with a bake time. "Looks good" is not a gate; "error rate ≤ baseline +0.1% for 48h and parity job green" is.
• One change per phase. A failed phase implicates exactly one change — that's what makes rollback decisions fast.
• Backfill is idempotent, resumable, rate-limited, parity-checked — all four stated, none implied.
• The contract phase has a date, an owner, and a gate. Plans that end at "100% on new path" are unfinished.
• Rollback steps are tested, not asserted. Each rollback names when it was (or will be) rehearsed; an unrehearsed rollback is a hypothesis.

Not for:

• A change deployable in one reversible step — normal deploy, no plan needed
• Choosing the target ("should we move to DynamoDB?") — this skill starts after the decision
• The test depth itself — emit gates here, hand verification design to test-plan-generator
• Organizational/process migrations with no system state — different problem

pr-description-writer

Write the pull request title and description for one change, from the actual diff and commits: what changed and why, how it was tested with only the checks that were really run, what a reviewer should look at first, and the risk and rollback. It also reports what the diff contains that the commits don't mention, such as a dependency bump, a deleted test or a schema change.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user asks to write a PR description, a pull request summary, a merge request body, or says "describe this change for review", "write up this branch".

A good result:

• Everything traces to the diff, the commits or the user. No invented issue numbers, metrics, reviewers or test results.
• The test section is honest. A check that wasn't run is listed as not run.
• A reviewer learns where to look. The body names the riskiest part of the diff.
• Surprises are surfaced. A dependency bump, deleted test, migration or API change that the commits skip appears under Reviewer notes.
• Claims about the code are checked. Before saying a test does or doesn't cover a change, or that two changes are independent, work it through against the diff (run the arithmetic, trace the call). If you can't confirm it, leave the claim out.
• Short. The body fits on one screen. A long PR gets a tighter summary, not a longer one.

Not for:

• Notes for a whole release or a changelog entry across many changes. Use release-notes.
• Deciding whether the change is safe to merge. Use pre-merge-review.
• Designing the tests the change needs. Use test-plan-generator.

pre-merge-review

Gate an existing change for merge — run one skill that fires the whole production-readiness pass. First a deterministic mechanical gate (lint + typecheck + tests, via a script whose exit code decides), then the three-reviewer panel dispatched in parallel — devils-advocate (correctness), security-reviewer (exploitability), code-quality (craft) — then a single READY / NOT READY verdict. Use before opening a PR or merging, when you want the full review fleet run on a diff you already have. Do NOT use to implement a feature from a spec (that's feature-implement-loop) or to review a document (that's doc-critique).

Tier standard · v0.1.5 · SKILL.md · skill page

Needs: Python 3 for its scripts (standard library only).

A good result:

• The mechanical gate is run, not assumed. A verdict with no real gate result is invalid — you ran the script (or reported BLOCKED), you didn't eyeball the tests.
• The gate is un-bypassable. A RED gate is NOT READY regardless of how good the review looks. The review can add blockers; it can never clear a failing gate.
• Findings are merged and de-duped across the three lenses — the same line is not reported three times.
• The verdict is one word plus the blocking reasons, not a hedged paragraph. A reader sees READY/NOT READY and exactly what stands in the way.
• Design disagreements go to council-review, not adjudicated here — this skill gates a change, it doesn't decide an architecture.

Hands off to: council-review when the blocker is a design disagreement, not a defect.

Not for:

• Implementing a feature from a spec — that's feature-implement-loop, which generates and loops; this skill only judges an existing change.
• One lens is enough — a pure bug pass is devils-advocate standalone; a pure doc pass is doc-critique.
• An open design decision ("Postgres or Dynamo?") — that's council-review.

refactor-plan

Plan paying down one piece of technical debt as a refactor that serves the goal it is blocking — characterisation tests on the riskiest behaviour first, then small steps each merged to main with main releasable after every one, pure refactors kept apart from the behaviour changes the goal needs, a scope fence, a stop point, a technique per step (extract, branch by abstraction, parallel change, strangler fig, mikado) and the clashes with in-flight feature work.

Tier standard · v0.2.0 · SKILL.md · skill page

Use it when the user asks for a refactor plan, how to untangle, break up, replace or clean up a module without a rewrite, how to pay down a tech-debt item, "how do we refactor X without stopping feature work", "how do we get off X without a big bang", or wants a strangler-fig or mikado plan.

A good result:

• The first two lines give the approach and the first step. A chat question gets a chat-sized plan; a document only when asked or large.
• Every step serves the stated goal, and the last step reaches the structure that goal needs.
• Every step is labelled refactor or behaviour change; behaviour changes stand alone, after the refactor that makes them safe.
• Characterisation tests come first, on the incident-prone behaviour, and no open PR leaves that behaviour unpinned.
• Caller contracts, copies outside the module and real test coverage are reported from the files, cited file:function.
• Every in-flight clash has a decision, and a must-land feature PR is never blocked.
• The scope fence and stop point exist; new findings go to the register.
• Every file, function, metric and number is from the input. Unknowns are checks to run.

Hands off to: feature-implement-loop when the plan is agreed and a step is ready to build; tech-debt-register when planning or a step turns up debt outside the scope fence, or the stop point is reached.

Not for:

• Listing or ranking the debt in the first place — tech-debt-register
• Moving data, changing a schema or switching platforms with a backfill — migration-plan
• Writing the code for one of the steps — feature-implement-loop
• Deciding the target architecture or recording why — adr-generator or design-doc
• Reviewing a refactor PR that already exists — pre-merge-review
• Splitting a feature into user stories — user-story-splitter

release-notes

Write release notes from a git log, a list of merged PRs or rough notes about what changed — for the audience and in the format the user names (a customer changelog page, an email, an in-app "what's new", store text, a CHANGELOG.md entry). Says nothing the input doesn't, writes a vague change only as far as it was described, puts breaking changes and anything the reader must do first, and keeps internal noise and working notes out of the text.

Tier standard · v0.2.0 · SKILL.md · skill page

Use it when the user wants release notes, a changelog entry, "what's in this release", a deploy announcement, or to summarise changes since the last tag.

A good result:

• Nothing in the notes goes beyond the input. No invented feature, behaviour, symptom, figure, date, version, PR number or count.
• Reverted and superseded changes don't appear; the final state does.
• Breaking changes and required actions come first, found from the text as well as the markers, with an action that fits how the audience gets the release.
• Internal noise is absent from customer text.
• The format, length and tone are the ones the user asked for, and the notes carry no working notes.
• Vague items are left out or kept vague, and named once to the user.

Not for:

• A single PR description — that's one change; use pr-description-writer
• Reviewing the changes for quality or risk — that's devils-advocate / sonar-review
• A narrative about why the release matters strategically — feed the notes to exec-summary
• Writing commit messages going forward — this skill reads history, it doesn't write it

rollout-plan

Plan the progressive release of a code change behind a feature flag or canary — the exposure ladder (internal, beta cohort, 1%, 5%, 25%, 50%, 100%, or what the traffic supports), and for each step who is exposed, decision and guardrail metrics with a baseline and a threshold against a control cohort, the minimum traffic and time before the numbers mean anything, a promote / hold / roll back rule set in advance, who watches and what aborts automatically; then what turning the flag off does not undo, and who removes the flag by when.

Tier standard · v0.2.2 · SKILL.md · skill page

Use it when the user asks for a rollout plan, canary plan, ramp schedule, progressive delivery or percentage rollout, "how long should the canary run", "when do we go from 5% to 25%", or how to turn on a flagged feature safely.

Needs: Python 3 for its scripts (standard library only).

A good result:

• The first two lines answer the user's question in plain words, with the input fact that settles it.
• The binding constraint is named and the ladder visibly follows it (cap, cycle, deadline, segment, shadow, volume).
• Every threshold is testable: metric, baseline, limit against the flag-off control; counts where volumes are small.
• Every number traces to the input, to arithmetic on it, or to a one-line [assumption].
• A deadline in the input gets a dated ladder that shows whether it is met.
• Promote, hold, roll back and abort are written before the step, with a watcher, a sign-off where one is needed, and an override role.
• The not-undone list covers what this change sends, writes or charges, with handling for each.
• The flag has an owner and a removal date.
• The reply is shorter than the plan it replaces would be at full length; "To confirm" is never longer than the ladder.

Hands off to: migration-plan when the change also alters a schema, backfills data, swaps a datastore or dual-writes; launch-readiness when the rollout plan is written and someone must decide whether the change may go live at all.

Not for:

• Schema changes, backfills, datastore or provider swaps, dual-writes: migration-plan
• "Are we ready to launch?" go/no-go: launch-readiness
• SLOs, alerts and dashboards for the service: observability-plan
• Defining what success means for the feature: success-metrics
• The on-call procedure for the service as a whole: runbook-generator
• A change with no flag, canary or staged deploy: there is nothing to ramp; plan the gate first

sonar-onboard

Scaffold a repo for Sonar compliance — supports both SonarQube server (self-hosted) and SonarCloud (SaaS), user picks at setup time. Generates sonar-project.properties with language-correct source/test/coverage paths, a CI workflow that runs the scanner on every push and PR and blocks merge on quality-gate failure, and a README snippet documenting the gate. One-shot setup; pair with sonar-review for per-change feedback.

Tier light · v0.1.0 · SKILL.md · skill page

Use it when the user says "set up Sonar", "add SonarQube to this repo", "wire up SonarCloud", "set up the quality gate", or asks to make a project Sonar-compliant for the first time.

A good result:

• Properties file is keyed to the actual repo. sonar.projectKey, sonar.sources, sonar.tests, and the coverage path must reflect what's on disk — not a generic example. A properties file that scans the wrong directories produces a green gate that means nothing.
• The workflow blocks merge on gate failure. A scan that runs but doesn't fail PRs is decoration. The sonarqube-quality-gate-action step is non-negotiable.
• Coverage path exists or is marked TODO. Pointing at a coverage file that the test step never produces gives Sonar 0% coverage and a false-failing gate. Either wire it up end-to-end or leave it explicit.
• fetch-depth: 0 in checkout. Shallow clones break Sonar's new-code-period detection. The first scan will look fine; the next ten PRs will mis-attribute issues.
• Secrets are referenced, never inlined. No raw tokens or URLs in committed files. The token belongs in GitHub Secrets; the URL too, even though it's not technically secret — it keeps fork PRs from leaking the host.
• README snippet tells the next contributor what the gate enforces. "Sonar must pass" is not enough — list the conditions (no new bugs, no new vulnerabilities, coverage on new code ≥ X%, duplication ≤ Y%).

Not for:

• Repo already has a working sonar-project.properties and a CI workflow that runs the scanner. Use sonar-review for per-change feedback instead.
• User wants to disable rules or relax the gate to make a failing scan pass. That's a code-quality conversation, not a setup task — push back.
• User wants language-specific deep config (custom rule profiles, Sonar plugins, branch analysis tuning). Out of scope; point at reference.md and the Sonar docs.
• User wants both SonarQube server and SonarCloud scanning the same repo. Pick one — running both means two gates, two histories, and two answers to "did the build pass?".

sonar-review

Run a Sonar scan against the just-changed code on the current branch and produce a structured compliance report — quality-gate verdict (PASS / FAIL), then severity-tagged findings (🟥 blocker / 🟧 critical / 🟨 major / ⚪ minor / ⚪ info) scoped to changed files, each with file:line, the Sonar rule ID, the category (bug / vulnerability / security hotspot / code smell), why it matters, and a concrete fix. Works against both SonarQube server (self-hosted) and SonarCloud (SaaS) — mode is detected from sonar-project.properties. Sister skill to devils-advocate, but enforces Sonar's rule catalog and the project's quality gate rather than a hand-rolled lens sweep. Use after writing code, before pushing or opening a PR, when the user says "is this Sonar-compliant?", "run Sonar on this", "will the quality gate pass?", or any pre-merge compliance check.

Tier standard · v0.1.0 · SKILL.md · skill page

Needs: environment: SONAR_TOKEN.

A good result:

• Verdict comes from the gate, not from you. The quality gate is the source of truth. ✅ "Gate FAIL — 1 new vulnerability." ❌ "Looks risky to me." If the gate passed, say PASS even if you'd personally flag issues.
• Findings are scoped to changed files. The repo has pre-existing debt; this skill is a pre-merge check, not a backlog dump. Pre-existing issues in touched files go in a separate "FYI" section — issues in untouched files don't appear at all.
• Every finding cites file:line and the Sonar rule ID. javascript:S2228 is a click-through to the Sonar UI catalog. Strip either and the finding becomes unactionable.
• Severity is Sonar's, not yours. Don't downgrade a CRITICAL because you disagree, and don't upgrade a MINOR to make the report scarier. If you disagree with the catalog, raise it in the lens body, don't rewrite the severity.
• Fixes name a concrete change. A patch line, a function rename, a missing test case — not "consider refactoring".
• Don't recommend disabling rules to pass the gate. That's a code-quality conversation. Suggest fixes or scoping (Sonar-scoping comments like // NOSONAR should be rare and justified in the code, not as a default).
• Security hotspots are flagged for review, not "fixed". Hotspots ask "is this safe?" — the resolution is a human decision (mark Safe, At Risk, Acknowledged). The fix you write is the evidence the user needs to make that call, not a code patch.

Not for:

• Repo isn't set up for Sonar (no sonar-project.properties). Run sonar-onboard first.
• User wants a code review broader than Sonar's catalog covers (architecture, idiomatic concerns, test-design). Use devils-advocate instead — different lens.
• User wants to fix the whole codebase's Sonar debt. This skill is per-change; for a debt-paydown plan, query the Sonar UI directly.
• Repo only has linters (ESLint, Pylint, golangci-lint) and no Sonar. Different tool, different catalog — running this skill would produce nothing.
• Repo isn't wired to either SonarQube server or SonarCloud — no sonar-project.properties means there's nothing to scan against. Run sonar-onboard first.

tech-debt-register

Turn a pile of technical-debt complaints, TODOs and incident notes into a ranked register: each item with where it lives, the cost it imposes today backed by evidence, the size of the fix, a decision (pay now, schedule, accept or watch) with the trigger that reopens it, and an owner if one was given. It ends with the few items worth paying down this quarter and why.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user asks for a tech debt register, a debt inventory or backlog, "what debt should we pay down", "prioritise our tech debt", or wants to make the case for refactoring time.

A good result:

• Every cost has evidence or says it has none. No invented hours, incident counts, percentages or money.
• Every item has a place or is listed as unlocated.
• Every item has a decision and a trigger.
• The top of the list is defensible: evidenced cost, fix the team can finish.
• It fits a planning meeting. One table, one short lead-in.

Not for:

• Planning how to carry out one large change. Use migration-plan.
• Sorting incoming bug reports. Use bug-triage.
• Cleaning up a tracker backlog of mixed work. Use backlog-triage.
• Business or delivery risks that are not about the code. Use risk-register.

test-plan-generator

Generate a risk-based test plan for a feature, PR, or release — risks ranked by likelihood × impact, test cases pushed to the lowest pyramid level that catches the failure, every acceptance criterion mapped to a test, and an explicit "not tested" list.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user asks for a test plan, test cases, a QA strategy for a change, "how should we test this", or pre-release test coverage.

A good result:

• Risk table precedes test cases, and effort tracks priority. A plan that gives equal depth to every area was written by coverage habit, not risk.
• Every test case has a concrete expected result. ✅ "Then the response is 422 with error code DUPLICATE_SKU" — ❌ "Then an appropriate error is shown".
• Every AC appears in the coverage table. Uncovered ACs are listed as gaps at the top of the plan, never silently absent.
• The "Not tested" section is non-empty. A plan that tests everything is a plan that prioritized nothing — naming accepted risks is the deliverable.
• Pyramid placement is justified by failure location, not by what's easiest to write. Each e2e case states why no lower level could catch it.

Not for:

• Writing the test code itself — hand the plan to feature-implement-loop or a human
• Adversarial review of code already written — that's devils-advocate
• Static-analysis or quality-gate findings — that's sonar-review
• A trivial change (typo, copy edit) — the plan would cost more than the risk

user-story-splitter

Split an epic, feature request, or PRD chunk into independently shippable user stories with testable Gherkin acceptance criteria and a recommended build order.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when Use whenever the user wants to "break this down", turn an epic or PRD into a backlog, slice a feature for sprint planning, or write acceptance criteria for a story.

A good result:

• Every story is demoable to a non-engineer. If the demo is "look at this table in the database", it's a horizontal slice — re-cut it.
• Every acceptance criterion is pass/fail without interpretation. A tester who has never seen the epic can verdict it. ✅ "Then the order total shows the discounted price within 2s" — ❌ "Then the discount works correctly".
• Dependency graph is a chain or shallow tree, never a web. No story depends on more than one other story; if it needs two, the cut is wrong.
• Assumptions are tagged, not embedded. Every default the skill picked appears as a visible [assumption], so planning can challenge it.
• The epic is fully accounted for. Everything in the input is either inside a story or named in "Out of scope / not covered" — no silent drops.

Hands off to: feature-implement-loop when a story has acceptance criteria a test can assert.

Not for:

• The work has no user-visible behavior (pure refactor, dependency bump) — write a task list, not stories
• The story is already small and clear — go straight to feature-implement-loop
• Estimating effort in hours/points — this skill orders and sizes by slice, it does not estimate
• Writing the implementation — hand the story off instead

Loops

build

Take an agreed requirement to merged code through a capped generate-verify-gate loop, with a mechanical gate that decides and a human who owns the merge.

Cap: 3 returns before BLOCKED. LOOP.md

modernize

Replace or rewrite a legacy component without changing what it does: orient in the old code, plan the restructuring and the move, record the old system's behaviour before anything is rebuilt, rebuild in small steps, prove the new one gives the same results on the recordings, and cut over only when a person accepts the evidence.

Cap: 3 returns before BLOCKED. LOOP.md

release

Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call.

Cap: 3 returns before BLOCKED. LOOP.md

Included from core

Installed with this pack. Details: Core pack reference.

• brief-intake: Turn raw mess — a Slack thread, meeting transcript, Jira ticket, half-written Notion page, email chain, or paragraph of free-form context — into a structured brief that the downstream skill (adr-generator, design-doc, runbook-generator, exec-summary, slide-outliner) can consume without further intake.
• context-graph: Map the decisions behind a codebase from its ADRs, RFCs and design records — each record's status and date, what supersedes or amends what, which records cite which, the files and folders each decision governs, and with git the commits that implemented it and the commits that changed each decision's code since it was made, and who made them — then answer "why is it like this?" from the record and check the record is still true. Finds supersessions only one side records, current decisions pointing at code that is gone, code that has drifted from its decision, two current decisions governing the same path, and references to records that don't exist.
• council-review: Convene a council of distinct senior-engineer personas (Architect, Security, Operator/SRE, Pragmatist, User-Advocate, plus optional bench seats) to deliberate a decision, design, or code change — each takes an independent stance, the genuine disagreements are surfaced as named cruxes, and a Chair issues a reconciled verdict that records dissents and states what would change the decision. The "Claude Council."
• doc-critique: Review an existing document — ADR, design doc, runbook, exec summary, tech-comparison matrix, deck outline, decision log — and produce a structured critique against the same quality bars the skilldrop generators enforce. Categorizes findings by severity (blocker / major / minor / nit), points to the exact section/line, and suggests a concrete fix for each.
• output-hygiene: Review agent-written text before it ships and strip the machine artifacts it carries — invisible Unicode, non-breaking spaces, homoglyphs, harness-added provenance trailers, trailing chat closers — then flag the prose tells a script cannot catch, each quoted with a rewrite.

Edit this page on GitHub · View source