Skip to content
Back to search

paad

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Ovid/paad with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Ovid/paad'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ovid--paad/badge.svg)](/listings/ovid--paad)

HTML

<a href="/listings/ovid--paad"><img src="/api/listings/ovid--paad/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

In Claude Code:

/plugin marketplace add Ovid/paad

**In the Claude desktop app**, that command just opens **Settings → Plugins** and adds nothing. Add PAAD from there instead: click **+ Add** → **Add marketplace** → **Add from a repository**, enter `Ovid/paad`, and click **Sync**. PAAD then appears in the list — click **Add to this computer** and you're done; skip the steps below. [See this ticket for more details](https://github.com/Ovid/paad/issues/25).

In the terminal, follow that with:

/plugin install paad@paad

Pick a scope when the details panel opens, then `/reload-plugins`. Run `/paad-help` to see everything.

Not using Claude Code? One command installs PAAD into 70+ other agents — Cursor, Codex, GitHub Copilot, Gemini CLI, Cline, Zed, Warp, Amp, OpenCode:

npx skills@latest add Ovid/paad

`npx` comes with [Node.js](https://nodejs.org/); if `npx --version` says "command not found", install Node first.

See [Installation](#installation) for the details, including the experimental **Pi** package.

The skills

| Skill | What it does | |---|---| | `/pushback [document]` | Argues with your spec before anyone builds it | | `/alignment [files...]` | Checks that the plan and the spec say the same thing | | `/agentic-review [base-branch] [path]` | Six specialists review your branch before merge | | `/agentic-architecture [path...]` | Five specialists find structural debt while it's cheap | | `/fix-architecture [report]` | Works through those findings one at a time, test-first | | `/agentic-a11y [path]` | Accessibility audit against WCAG 2.2 AA, by disability category | | `/vibe [task]` | Small fixes, TDD guardrails still on | | `/rethink [topic]` | Checks whether the premises under a recommendation hold | | `/test-roadmap` | Builds a test suite that catches real regressions | | `/handoff [save\|resume]` | Hands this session's work to a fresh one, in writing | | `/makefile` | Creates or updates a project `Makefile` | | `/paad-help [skill-name]` | Lists the skills, or explains one |

Experimental skills

| Skill | What it does | |---|---| | `/agentic-dedup [scope]` | Finds duplicated *meaning*, not duplicated text — experimental | | `/agentic-owasp [scope]` | Reviews code against the OWASP Top 10:2025 — experimental | | `/backlog [clean\|fix]` | Clears fixed bugs out of the review backlog, or fixes the next one — experimental |

Every skill can also be steered per project: drop instructions in `paad/config/paad.md` (all skills) or `paad/config/<skill-name>.md` (one skill) and the skill reads them on invocation. Experimental — see [Configuring skills per project](#configuring-skills-per-project).

Full descriptions are further down. The rest of this page is why any of it is worth your tokens.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "paad",
  3. "owner": {
  4. "name": "Curtis \"Ovid\" Poe",
  5. "email": "curtis.poe@gmail.com"
  6. },
  7. "metadata": {
  8. "description": "Engineering-driven AI. Use your engineering excellence — the one thing AI reliably skips.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "paad",
  14. "source": "./plugins/paad",
  15. "description": "Architecture analysis, code quality, and development workflow skills by Ovid",
  16. "version": "2.1.0",
  17. "author": {
  18. "name": "Curtis \"Ovid\" Poe"
  19. },
  20. "homepage": "https://github.com/Ovid/paad",
  21. "repository": "https://github.com/Ovid/paad",
  22. "license": "MIT",
  23. "keywords": ["architecture", "code-quality", "analysis"],
  24. "category": "code-quality"
  25. }
  26. ]
  27. }
README.md · README · 1,489 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # PAAD — Engineering-driven AI, not AI-driven engineering
  2. <p align="center">
  3. <img src="images/paad.png" alt="PAAD — Pushback, Alignment, Architecture, Discipline" width="600">
  4. </p>
  5. <p align="center">
  6. <a href="https://github.com/Ovid/paad/releases/latest"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FOvid%2Fpaad%2Fmain%2Fplugins%2Fpaad%2F.claude-plugin%2Fplugin.json&query=%24.version&label=paad" alt="Current paad version"></a>
  7. </p>
  8. > **paad 2.0.0 is out.** You can now tailor paad to your own needs with
  9. > [config files](CONFIG.md), and security findings now stay out of your
  10. > committed reports. See the [2.0.0 release notes](https://github.com/Ovid/paad/releases/tag/paad--v2.0.0)
  11. > and the [changelog](CHANGELOG.md).
  12. <!-- Remove this notice once 2.1 or 2.2 ships. -->
  13. **PAAD** (rhymes with "pad") is a set of skills that let you write
  14. production-quality code with AI. The AI does the work; you stay the engineer.
  15. PAAD reviews each stage — the spec, the plan, the architecture, the code — while
  16. you can still change it. That's **P**ushback, **A**lignment,
  17. **A**rchitecture, plus the **D**iscipline to actually run them.
  18. [A full explanation/tutorial is here](https://curtispoe.org/paad/).
  19. ## Quick start
  20. In Claude Code:
  21. ```
  22. /plugin marketplace add Ovid/paad
  23. ```
  24. **In the Claude desktop app**, that command just opens **Settings → Plugins**
  25. and adds nothing. Add PAAD from there instead: click **+ Add** → **Add
  26. marketplace** → **Add from a repository**, enter `Ovid/paad`, and click
  27. **Sync**. PAAD then appears in the list — click **Add to this computer** and
  28. you're done; skip the steps below. [See this ticket for more
  29. details](https://github.com/Ovid/paad/issues/25).
  30. In the terminal, follow that with:
  31. ```
  32. /plugin install paad@paad
  33. ```
  34. Pick a scope when the details panel opens, then `/reload-plugins`. Run
  35. `/paad-help` to see everything.
  36. Not using Claude Code? One command installs PAAD into 70+ other agents —
  37. Cursor, Codex, GitHub Copilot, Gemini CLI, Cline, Zed, Warp, Amp, OpenCode:
  38. ```bash
  39. npx skills@latest add Ovid/paad
  40. ```
  41. `npx` comes with [Node.js](https://nodejs.org/); if `npx --version` says
  42. "command not found", install Node first.
  43. See [Installation](#installation) for the details, including the experimental
  44. **Pi** package.
  45. ### The skills
  46. | Skill | What it does |
  47. |---|---|
  48. | `/pushback [document]` | Argues with your spec before anyone builds it |
  49. | `/alignment [files...]` | Checks that the plan and the spec say the same thing |
  50. | `/agentic-review [base-branch] [path]` | Six specialists review your branch before merge |
  51. | `/agentic-architecture [path...]` | Five specialists find structural debt while it's cheap |
  52. | `/fix-architecture [report]` | Works through those findings one at a time, test-first |
  53. | `/agentic-a11y [path]` | Accessibility audit against WCAG 2.2 AA, by disability category |
  54. | `/vibe [task]` | Small fixes, TDD guardrails still on |
  55. | `/rethink [topic]` | Checks whether the premises under a recommendation hold |
  56. | `/test-roadmap` | Builds a test suite that catches real regressions |
  57. | `/handoff [save\|resume]` | Hands this session's work to a fresh one, in writing |
  58. | `/makefile` | Creates or updates a project `Makefile` |
  59. | `/paad-help [skill-name]` | Lists the skills, or explains one |
  60. ### Experimental skills
  61. | Skill | What it does |
  62. |---|---|
  63. | `/agentic-dedup [scope]` | Finds duplicated *meaning*, not duplicated text — experimental |
  64. | `/agentic-owasp [scope]` | Reviews code against the OWASP Top 10:2025 — experimental |
  65. | `/backlog [clean\|fix]` | Clears fixed bugs out of the review backlog, or fixes the next one — experimental |
  66. Every skill can also be steered per project: drop instructions in
  67. `paad/config/paad.md` (all skills) or `paad/config/<skill-name>.md` (one skill)
  68. and the skill reads them on invocation. Experimental — see
  69. [Configuring skills per project](#configuring-skills-per-project).
  70. Full descriptions are further down. The rest of this page is why any of it is
  71. worth your tokens.
  72. ## "AI slop" is technical debt with better marketing
  73. We have been accumulating technical debt since long before AI showed up, and
  74. we already know how to handle it: review the requirements, review the plan,
  75. review the architecture, review the code. Every one of those is an old,
  76. boring, well-understood engineering skill.
  77. What AI changed is not the nature of the debt. It's the speed it arrives at.
  78. - **Vibe coding** piles up debt fast.
  79. - **Spec-driven development** piles it up slowly.
  80. - Neither piles up zero.
  81. That's the problem and it isn't new. It's just faster than the review
  82. habits most teams have, so the debt lands before anyone looks at it.
  83. The model reads every line of your repository in seconds. It has never once
  84. heard about the outage that put that validation check there.
  85. **PAAD** is how you stay on top of it — the same review layers your team
  86. already believes in, applied at the speed the assistant is working.
  87. ## The four letters
  88. Four points where the AI is about to decide something for you:
  89. | Area | What it means |
  90. |------|---------------|
  91. | **P**ushback | Argues with your spec before anyone builds it |
  92. | **A**lignment | Checks that the plan and the spec actually say the same thing |
  93. | **A**rchitecture | Finds the structural debt while it's still cheap to fix |
  94. | **D**iscipline | Yours, not the tool's — running the first three when the deadline says don't |
  95. The first three are reviews you run. The fourth is the one thing in the list
  96. the assistant will never bring for you.
  97. Your team already runs specs, tests, code review, CI, QA, and incident
  98. response — layers that exist because mistakes are cheap to fix early and
  99. expensive to fix late, and because humans are stochastic. AI is stochastic
  100. too. PAAD's argument isn't that AI needs *special* safeguards; it's that AI
  101. needs the *same* safeguards, running fast enough to keep up with it.
  102. It doesn't replace your current AI-assisted development tools; it complements
  103. them. You like [Superpowers](https://github.com/obra/superpowers/)? Use it
  104. with PAAD.
  105. PAAD supports **Claude Code** natively, installs into 70+ other agents with one
  106. `npx` command, and ships as an experimental **Pi** package. Hand-copying the
  107. pre-converted **Kiro**/**Antigravity**/**Cursor** tree still works and is now
  108. deprecated.
  109. ## Who's driving
  110. Most organizations adopting AI right now have it backwards. A developer tells
  111. the AI what to do and hopes the AI can take over. The AI is happy to oblige —
  112. it always is — and the developer finds out what it decided when the code
  113. lands.
  114. That's **AI-driven engineering**: the assistant sets the pace, and the
  115. engineers are downstream of decisions they never saw made.
  116. PAAD replaces it with **engineering-driven AI**. Same speed, opposite
  117. direction: you see what the AI is about to do while you can still change it,
  118. and you make the calls.
  119. | | AI-driven engineering | Engineering-driven AI |
  120. |---|---|---|
  121. | The spec | Whatever you typed, unchallenged | `pushback` argues with it before anyone builds it |
  122. | The plan | Assumed to match the spec | `alignment` checks both directions |
  123. | The code | A green CI run | `agentic-review` puts six specialists on the PR |
  124. | The structure | Discovered later, expensively | `agentic-architecture` finds it while it's cheap |
  125. | The decisions | The model's | Yours, on the record |
  126. You stay in the driver's seat. That is the point, and it's also the cost: PAAD
  127. gives you visibility and control, not autopilot.
  128. ## Workflow
  129. There's a lot to take in with PAAD, [so I've written an article to explain how
  130. to write production-quality code with
  131. it](https://curtispoe.org/articles/watching-claude-sonnet-outperform-opus).
  132. If you are new to PAAD, start with `/paad-help` to see the available skills and when to use them.
  133. A typical workflow looks like this:
  134. 1. Write the spec, using your existing spec-driven development method.
  135. 2. Run `pushback` on the spec. Revise and repeat as needed.
  136. 3. Develop the task list (you or the agent).
  137. 4. Run `pushback` on the task list. Revise and repeat as needed.
  138. 5. Run `alignment` on the task list to check it against the spec, and rewrite
  139. it for TDD. Revise and repeat as needed.
  140. 6. Execute the tasks, in a fresh session for each task.
  141. 7. Run `agentic-review` on the result. Fix findings and repeat as needed.
  142. 8. Human PR approval and merge. Repeat for the next feature.
  143. That is the per-feature loop (section 10 of [the
  144. tutorial](https://curtispoe.org/paad/)). It improves the quality of each feature
  145. before it gets merged into your primary branch:
  146. <p align="center">
  147. <img src="images/pushback.png" alt="PAAD per-feature loop: write the spec, then /pushback on it; develop the task list, then /pushback and /alignment on it; execute the tasks, then /agentic-review the result; human PR approval and merge" width="700">
  148. </p>
  149. AI is now good enough that, with `pushback` alone, fewer issues surface in the
  150. rest of the loop. But the loop only minimizes slop in the current task. It
  151. can't prevent slop across the project as a whole. That takes aggressive
  152. technical debt management: `agentic-architecture` to find the structural
  153. problems, `fix-architecture` to work through them, and `agentic-review`
  154. before the fixes merge.
  155. <p align="center">
  156. <img src="images/architecture.png" alt="PAAD aggressive technical debt maintenance: reserve time and choose scope, then /agentic-architecture; prioritise findings on a feature branch, then /fix-architecture; verify the changes, then /agentic-review; human PR approval and merge" width="700">
  157. </p>
  158. Both loops lean on your test suite to catch what breaks. If it is weak or
  159. missing, build it first with `test-roadmap`: one run writes the roadmap, then
  160. each phase is its own small feature — a fresh session, one `/test-roadmap`
  161. run, `/agentic-review` on the result, then a PR that a human reviews and
  162. merges. Repeat until the roadmap is complete.
  163. <p align="center">
  164. <img src="images/test-roadmap.png" alt="PAAD test roadmap: run /test-roadmap to answer questions and get a test roadmap, optionally /pushback on it; then loop: start a new session, /test-roadmap to build the next test phase, /agentic-review and fix findings, push the PR, human review, merge; repeat until the roadmap is complete" width="700">
  165. </p>
  166. Not sure if the AI is presenting you with the best options? Run `rethink` to
  167. check whether the premises behind a recommendation actually hold.
  168. Depending on the type of work, I also use (see below for full descriptions):
  169. 1. `agentic-a11y` for UI changes and accessibility-sensitive work
  170. 2. `vibe` for small fixes that still benefit from guardrails
  171. Rerun `pushback` and `alignment` whenever the spec or the task list changes.
  172. ## Configuring skills per project
  173. > **Experimental.** This may change or be withdrawn in any release, including
  174. > a patch release. Read the [CHANGELOG](CHANGELOG.md) before you update.
  175. Tired of typing the same extra instructions after every slash command, or of
  176. writing a wrapper skill just to add them? Put them in a file and every paad
  177. skill reads it on its own:
  178. | File | Read by |
  179. |---|---|
  180. | `paad/config/paad.md` | every paad skill |
  181. | `paad/config/<skill-name>.md` | that one skill, e.g. `paad/config/agentic-review.md` |
  182. Both are optional, relative to where you run the skill (normally the repo
  183. root). There is no schema — write plain instructions, as you would have typed
  184. them. For example, `paad/config/agentic-architecture.md`:
  185. ```markdown
  186. - All output must be in simplified technical English.
  187. - Add one more subagent that looks for over-engineering.
  188. - Keep a log in `paad/logs/agentic-architecture.md` of every finding an
  189. agent raised that the verifier discarded.
  190. ```
  191. The skill follows it for the whole run and passes the relevant parts to the
  192. subagents it dispatches. **You know it was read** because the skill's final
  193. answer opens with a line naming each file it followed:
  194. ```
  195. Config: paad/config/paad.md, paad/config/agentic-architecture.md
  196. ```
  197. No such line means nothing in the run came from your config.
  198. What to watch for:
  199. - **Add, don't subtract.** Config can tell a skill to skip or reorder its own
  200. safety gates, and the skill may comply. Use it for additions — an extra
  201. agent, an output rule, an artifact, a language.
  202. - **One thing is refused:** config cannot change a subagent's type or give it
  203. write tools. The skill says so and carries on.
  204. - **It's untrusted input.** A `paad/config/` in a repo you cloned was written
  205. by someone else, and a skill will follow it. Read it before you run anything.
  206. - **Results vary.** If a config line matters, check the output for it.
  207. The full details are in [CONFIG.md](CONFIG.md).
  208. ## What PAAD can't fix
  209. <details>
  210. <summary>The limits, and who has to cover them</summary>
  211. An engineer has to drive this — including knowing when the tool is wrong.
  212. - **PAAD reports; you decide.** A finding is an argument, not a verdict — see
  213. [The AI sees all of your code and none of your context](#the-ai-sees-all-of-your-code-and-none-of-your-context).
  214. - **It's non-deterministic**, like the assistant it's checking. Run it twice
  215. on the same branch and you'll get overlapping, not identical, results. Run
  216. the important ones more than once.
  217. - **A report you ignore is worse than no report.** `agentic-architecture` on a
  218. codebase nobody has time to change just produces a document that makes
  219. everyone feel bad.
  220. - **It can't fix a problem that isn't technical.** No skill in here rescues a
  221. project that's short on time, short on staff, or aimed at the wrong thing.
  222. - **It's not a replacement for human review.** It's a much stronger automated
  223. backstop, which is a different job.
  224. If you want the assistant to think for you, PAAD is the wrong tool. It exists
  225. for engineers who want to stay responsible for the result and need help
  226. keeping up.
  227. </details>
  228. ## The AI sees all of your code and none of your context
  229. <details>
  230. <summary>Why the missing half is the expensive one</summary>
  231. The model reads your repository faster and more patiently than any human will.
  232. That part is real, and it's why PAAD works at all.
  233. But the expensive decisions in software rarely turn on what's in the
  234. repository. They turn on what isn't.
  235. | The model sees | The engineer knows |
  236. |---|---|
  237. | Every line, in seconds | Which lines are load-bearing, and why |
  238. | That the retry logic is duplicated | That the gateway already retries, so this layer is the bug |
  239. | That a validation check looks redundant | That it was added after the outage nobody wrote up |
  240. | That the design is internally consistent | That next quarter's volume breaks it |
  241. | That two modules should be merged | That they belong to two teams and three release trains |
  242. | That the data handling is convoluted | That the partner feed is malformed and the fix is a phone call |
  243. None of the facts in the right-hand column are in the codebase. Most were never
  244. written down anywhere. They live in the people who were there — which is what
  245. experience actually is, once you stop treating it as a personality trait.
  246. **The failure mode isn't silence. It's confidence.** An assistant missing the
  247. right-hand column doesn't stop and say it lacks context. It produces a
  248. thorough, well-reasoned, entirely plausible recommendation about the half it
  249. can see. It will tidy the retry logic instead of deleting it. It will remove
  250. the check that prevented the outage. It will hand you a tasteful list of
  251. improvements to an architecture that should be thrown away.
  252. That advice is not obviously wrong. It's the same shape as the good advice,
  253. which is exactly why it survives review by anyone who doesn't already know
  254. better.
  255. ### Why this matters to whoever is paying for it
  256. The argument for keeping engineers in charge is usually made on feelings —
  257. trust, craft, morale. Here it's simpler than that, and it's measurable.
  258. **Seniority isn't nostalgia. It's an input the model doesn't have.** The
  259. engineer who remembers the outage is not being sentimental; they are supplying
  260. a fact that is absent from every file the AI just read. Remove them from the
  261. decision and you haven't made the process leaner, you've deleted critical
  262. input and added confident output.
  263. Which produces the line worth remembering when the reports look clean:
  264. **"the AI found no problems" is not the same as "there are no problems."** It
  265. means the AI found no problems *in what it could see*. Whether that's
  266. reassuring depends entirely on how much of the decision lived outside the
  267. repository — and only a person can answer that.
  268. This is why PAAD reports instead of deciding, and why every skill in it ends
  269. with a human choice rather than a merge. Not because the AI is untrustworthy in
  270. some abstract way, but because it's working from a partial input and the
  271. engineer is holding the rest. **Engineering-driven AI is the arrangement where
  272. those two halves actually meet.** AI-driven engineering is the one where the
  273. half that was written down wins by default.
  274. </details>
  275. ## Why people are using PAAD
  276. <details>
  277. <summary>The four skills people reach for, and what users say about them</summary>
  278. The strongest early adoption has come from four skills:
  279. - **`pushback`**, which critically reviews specs before implementation
  280. - **`alignment`**, which checks whether the planned work actually matches the
  281. spec and design
  282. - **`agentic-review`**, which performs a deeper pre-merge review than the
  283. lightweight AI review tools many developers are used to
  284. - **`agentic-architecture`**, which allows you to find and fix the tech debt
  285. you're accruing over time
  286. One user described `pushback` this way:
  287. > “I'm using it for every non-trivial change, and so far, I think I've argued with 2 of maybe 40 recommendations. It has improved EVERY SINGLE spec I've fed it so far.”
  288. If English is the new programming language, `pushback` is the code review.
  289. In practice, `pushback` consistently improves specifications, and `alignment`
  290. catches gaps between the intended work and the implementation plan before
  291. those gaps become expensive.
  292. `agentic-review` serves a different but equally important role: it reviews a
  293. working branch with multiple specialists looking for logic errors, edge cases,
  294. security issues, and integration problems before merge. In practice, it
  295. catches substantially more than the shallow, single-pass AI reviews now common
  296. in tools like GitHub Copilot. It is not a replacement for human review, but it
  297. is a much stronger automated backstop. Running it more than once is valuable.
  298. The other skills are also valuable, especially for architecture analysis,
  299. accessibility review, and smaller task execution with guardrails. But
  300. `pushback`, `alignment`, and `agentic-review` currently form the core workflow
  301. that delivers the most consistent day-to-day value.
  302. </details>
  303. ## What it costs you
  304. <details>
  305. <summary>Honest findings, paid for in tokens</summary>
  306. PAAD is built to be honest about risk. If your spec is weak, your plan is
  307. misaligned, an architectural decision is fragile, or a change introduces
  308. problems, you hear about it early and plainly. It's for people who want the
  309. speed and still want to be able to defend the result.
  310. That honesty has a price, and it's tokens. A single feature will cost more
  311. because you're paying to review the spec, review the plan, and review the code
  312. on top of writing it. The bet is that this is cheaper than shipping the wrong
  313. thing and rebuilding it — a good bet for software you'll maintain for years, a
  314. bad one for a prototype you'll throw away on Friday. Spend the review on the
  315. code you'll still be living with next year.
  316. </details>
  317. ## Installation
  318. The Quick start above is the whole install for most people. This section is the
  319. long form: scopes, updating, every other agent, and the alternative routes.
  320. **What PAAD sends:** PAAD runs no server and sends no telemetry. Some skills
  321. have your agent use its own web search or fetch tools, where it has them, to
  322. check facts against public sources; the skills tell it never to put your code
  323. in those requests.
  324. <details>
  325. <summary><strong>Full installation instructions</strong></summary>
  326. ### Claude Code
  327. #### Install the plugin
  328. Add the marketplace:
  329. ```bash
  330. /plugin marketplace add Ovid/paad
  331. ```
  332. Install the plugin:
  333. ```bash
  334. /plugin install paad@paad
  335. ```
  336. That opens the plugin's details rather than installing straight away — you pick
  337. a scope there: **Install for you (user scope)**, **Install for all collaborators
  338. on this repository (project scope)**, or **Install for you, in this repo only
  339. (local scope)**. Then run `/reload-plugins` to activate the skills in the
  340. session you're in. Claude Code prompts you to do that as well, so you aren't
  341. relying on this README to know it.
  342. If you're not using Claude Code, see other examples below.
  343. #### Updating the plugin
  344. New skills and fixes do **not** arrive on their own. Claude Code disables
  345. auto-update for third-party marketplaces by default, and PAAD is one, so you
  346. pull updates yourself.
  347. Open `/plugin`, go to the **Installed** tab, select **paad**, and choose
  348. **Update now**. Then run `/reload-plugins` to load the new version.
  349. That single action already refreshes the marketplace catalog from GitHub before
  350. it looks for a new version.
  351. To confirm which version you're on, run any skill — every skill announces its
  352. own name and version on invocation (`Running paad:vibe v<version>`). This works
  353. because Claude Code resolves the version from `plugin.json` and uses it as the
  354. update-detection key; on the npx route there is no such key, the install tracks
  355. `main`, and the announced version only tells you which release the sources were
  356. last bumped to. Compare that against the version in
  357. [`plugins/paad/.claude-plugin/plugin.json`](plugins/paad/.claude-plugin/plugin.json).
  358. If a skill documented here is missing entirely, you're on an older version —
  359. run through the update steps above.
  360. ### Every other agent — `npx skills`
  361. One command, and it covers 70+ agents:
  362. ```bash
  363. npx skills@latest add Ovid/paad
  364. ```
  365. `npx` comes with [Node.js](https://nodejs.org/); if `npx --version` says
  366. "command not found", install Node first.
  367. It opens a picker. Everything under **Universal (`.agents/skills`)** — Amp,
  368. Antigravity, Cline, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Warp,
  369. Zed and others — is always included. The list below that is opt-in and holds
  370. another fifty-odd; **Kiro CLI** (`.kiro/skills`) and Claude Code are both in
  371. there, so search for yours and select it.
  372. ```bash
  373. npx skills@latest add Ovid/paad --list # list the skills, install nothing
  374. npx skills@latest add Ovid/paad --skill pushback # install one skill
  375. npx skills@latest add Ovid/paad -a cursor -a codex -y # skip the pickers
  376. npx skills@latest add Ovid/paad --copy # real copies instead of symlinks
  377. ```
  378. <details>
  379. <summary>Three things worth knowing before you run it</summary>
  380. **Skills refer to each other by slash command** — `/agentic-architecture`,
  381. `/pushback`. If your assistant does not take slash commands, ask for the skill
  382. by name instead: "run the pushback skill". The name is always the same; only
  383. the way you invoke it differs.
  384. **These skills work by splitting one job across several helper agents.**
  385. `agentic-review`, `agentic-architecture`, `agentic-a11y`, `agentic-dedup`,
  386. `agentic-owasp`, `test-roadmap`, `rethink` and `backlog` all work this way. If your
  387. assistant supports helper agents, each helper gets its own separate conversation
  388. and examines your code from one angle — security, error handling, and so on —
  389. and they all work at the same time. If your assistant does not support them, a
  390. single agent does every one of those passes itself, one after another, in one
  391. conversation. The work still gets done. It is slower, and one conversation has
  392. to hold everything it reads. Nothing errors and nothing warns you.
  393. If your agentic coding tool only allows a single agent:
  394. * **Nothing constrains what the helper agents can do to your files.** In Claude
  395. Code, PAAD's analysis helpers are dispatched through an agent definition that
  396. grants read, grep, find, ls and bash and withholds the editing tools — bash
  397. means it is not a read-only sandbox, but the editing tools are genuinely
  398. absent. That agent definition lives outside the skills directory, so this
  399. install route does not carry it, and neither does Pi's. What is left is the
  400. instruction in the prose, and this repository's own steering file records that
  401. control failing in practice: subagents have been observed editing source code
  402. to test whether a finding was real. Treat an analysis run as capable of
  403. writing, and run it on a clean branch you can throw away.
  404. * **`test-roadmap` loses a real check.** One of its gates works by asking a
  405. helper that has not seen the test to try to break it. A single agent holding
  406. both cannot be blinded, so that gate reports success while verifying nothing.
  407. * **`backlog fix` loses its independent check.** It removes an entry only after
  408. a separate analyst confirms the bug is gone. Without helper agents, the agent
  409. that made the fix is the one confirming it.
  410. **Updates track `main`, and there is no pinned form.** Re-run the same command
  411. to pull the latest; there is no version argument, so the version a skill
  412. announces on invocation is *not* a reliable way to tell two npx installs apart.
  413. Renamed or deleted skills are not pruned. This release renamed `help` to
  414. `paad-help`, so an install made before it leaves a stale `help` directory
  415. behind.
  416. **Check what you are deleting before you delete it.** That skills root is
  417. shared across every assistant the installer supports, `help` is about the most
  418. collision-prone name a skill can have, and `--copy` mode leaves PAAD's copy
  419. indistinguishable from one you wrote yourself. Confirm the directory is PAAD's
  420. — its `SKILL.md` announces `paad:help` — and only then remove it. If it is not
  421. PAAD's, leave it alone; a stale copy is harmless next to the renamed one.
  422. </details>
  423. <details>
  424. <summary><strong>Pi — experimental</strong></summary>
  425. Pi support is **not settled**. The package layout, the skills it exposes, and
  426. the extension it depends on may change — or the packaging may be withdrawn — in
  427. **any** release, including a patch release. The Claude Code plugin is the
  428. supported path; if Pi is your daily driver, pin your version and please [file
  429. what breaks](https://github.com/Ovid/paad/issues).
  430. Install PAAD directly from Git:
  431. ```bash
  432. pi install git:github.com/Ovid/paad
  433. ```
  434. To try a local checkout without installing it permanently:
  435. ```bash
  436. pi -e .
  437. ```
  438. Invoke a skill with `/skill:<name>` or by name.
  439. #### The multi-agent skills need two more pieces
  440. `agentic-review`, `agentic-architecture`, `agentic-a11y`, `agentic-dedup`,
  441. `agentic-owasp`, `rethink` and `backlog` split their work across helper agents. Pi does not
  442. support helper agents on its own, and a Pi package cannot declare them, so
  443. neither piece ships inside the package. Without both pieces installed those
  444. skills still run — a single agent does every pass itself, one after another, in
  445. one conversation. You get no parallel work and no separation between passes.
  446. Nothing errors and nothing warns you.
  447. **1. A subagent extension.** Pi ships one as an
  448. [example](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/subagent),
  449. not as an installable package — it is a clone-and-symlink into `~/.pi/agent/`,
  450. not `pi install`. Follow that example's own README.
  451. **2. The analyst agent.** This repo generates a Pi copy of the analyst agent
  452. the skills ask for. Copy it in:
  453. ```bash
  454. cp pi/agents/paad-analyst.md ~/.pi/agent/agents/
  455. ```
  456. This file is what withholds the editing tools from an analysis helper: it grants
  457. `read`, `grep`, `find`, `ls` and `bash` and nothing that writes. `bash` means it
  458. is not a read-only sandbox, but `edit` and `write` are genuinely absent. Skip
  459. this step and any helper runs with whatever your setup gives it by default,
  460. with only the prose asking it not to write — and this repository's steering file
  461. records that asking failing in practice, with subagents editing source code to
  462. test whether a finding was real. The npx install route has no equivalent step at
  463. all: it resolves the skills directory and never sees `pi/agents/`.
  464. **`rethink` is degraded on Pi.** The Claude Code analyst also holds `WebSearch`
  465. and `WebFetch`, and Pi has no web tool to map those onto — its built-ins are
  466. `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls`. So on Pi the analyst
  467. cannot reach a primary source outside the repository. `rethink` still runs and
  468. still verifies everything the repository can settle, but a premise that needs a
  469. vendor's documentation, a standard, or a changelog will come back `Ungrounded`
  470. rather than checked. That is the correct answer given the tools, not a failure —
  471. but it is a narrower skill than the Claude Code one.
  472. Two known rough edges even with both installed. The skills name their subagent
  473. type in Claude Code's syntax (`subagent_type: paad:paad-analyst`), which is not
  474. how Pi's example extension dispatches — you may have to nudge the assistant
  475. toward the `paad-analyst` agent by name. And that extension caps parallel work
  476. at 8 tasks, while `agentic-review` asks for 12 dispatches on diffs over 500
  477. lines; the skill has a documented two-pass fallback for exactly this case, so
  478. say yes to it rather than accepting a half-coverage review.
  479. </details>
  480. <details>
  481. <summary><strong>Copying from <code>kiro_and_antigravity/</code> — deprecated</strong></summary>
  482. **Prefer `npx skills@latest add Ovid/paad`.** The instructions below still work
  483. and are not being removed this release, but they are no longer the recommended
  484. route.
  485. They stay for one reason: this tree has the Claude-Code-only sections stripped
  486. and the `subagent_type:` fragments removed, which `npx skills` does not do. If
  487. that matters more to you than a one-line install, keep copying.
  488. **These copies write reports to `.reviews/`, not `paad/`.** That is deliberate
  489. and unchanged — every other install route uses `paad/`. Your existing reports
  490. do not follow you across: if you switch, move the contents of each `.reviews/`
  491. folder into the matching `paad/` one, or `fix-architecture`, `test-roadmap` and
  492. the `agentic-review` backlog all start over. Switching also means removing the
  493. copies you made here, so you are not loading two versions of the same skill.
  494. #### Cursor
  495. PAAD skills use the same `SKILL.md` format that [Cursor
  496. skills](https://cursor.com/docs/skills) expect.
  497. All skills (bash/zsh):
  498. ```bash
  499. cp -r kiro_and_antigravity/skills/.kiro/skills/* .cursor/skills/
  500. ```
  501. All skills (Windows):
  502. ```powershell
  503. xcopy kiro_and_antigravity\skills\.kiro\skills\* .cursor\skills\ /E /I
  504. ```
  505. One skill (for example, `pushback`):
  506. ```bash
  507. cp -r kiro_and_antigravity/skills/.kiro/skills/pushback .cursor/skills/
  508. ```
  509. #### Kiro
  510. All skills (bash/zsh):
  511. ```bash
  512. cp -r kiro_and_antigravity/skills/.kiro/skills/* .kiro/skills/
  513. ```
  514. All skills (Windows):
  515. ```powershell
  516. xcopy kiro_and_antigravity\skills\.kiro\skills\* .kiro\skills\ /E /I
  517. ```
  518. One skill (for example, `pushback`):
  519. ```bash
  520. cp -r kiro_and_antigravity/skills/.kiro/skills/pushback .kiro/skills/
  521. ```
  522. #### Antigravity
  523. Antigravity skills function as wrappers that reference Kiro skill files, so
  524. you need both:
  525. All skills (bash/zsh):
  526. ```bash
  527. cp -r kiro_and_antigravity/skills/.kiro/skills/* .kiro/skills/
  528. cp -r kiro_and_antigravity/skills/.agent/skills/* .agent/skills/
  529. ```
  530. All skills (Windows):
  531. ```powershell
  532. xcopy kiro_and_antigravity\skills\.kiro\skills\* .kiro\skills\ /E /I
  533. xcopy kiro_and_antigravity\skills\.agent\skills\* .agent\skills\ /E /I
  534. ```
  535. One skill (for example, `pushback`):
  536. ```bash
  537. cp -r kiro_and_antigravity/skills/.kiro/skills/pushback .kiro/skills/
  538. cp -r kiro_and_antigravity/skills/.agent/skills/pushback .agent/skills/
  539. ```
  540. </details>
  541. ### Using skills outside Claude Code
  542. However you installed them, skills are recognized automatically by your
  543. assistant. You can simply ask the assistant to
  544. perform the task, such as:
  545. * “Run a pushback review on this spec”
  546. * “Check whether this plan aligns with the requirements”
  547. * “Analyze the architecture of the backend code”
  548. The assistant will follow the procedures defined in the skill files.
  549. </details>
  550. ---
  551. ## Skill reference
  552. <details>
  553. <summary><strong>Every skill in detail</strong> — arguments, behavior, and where each writes its report</summary>
  554. **Security findings go somewhere else.** In `agentic-review`,
  555. `agentic-architecture`, `agentic-owasp`, `agentic-dedup`, `pushback` and
  556. `test-roadmap`, any finding that would help an attacker is written only under
  557. `paad/security/`, whatever the skill's ordinary report path. No other skill
  558. routes anything there: an `alignment` report or a `handoff.md` that records a
  559. weakness lands where that skill always writes. That directory carries its own `.gitignore`
  560. holding a single `*`, so it ignores itself from the moment it is created, and
  561. the ordinary report is left with a count and a pointer — no path, severity,
  562. symbol, or description. The skills never add the map of live weaknesses to
  563. git, and they stop and ask rather than write there if that `.gitignore` is
  564. wrong or git already tracks something in the directory. That protection has
  565. limits. `git add -f`, or deleting the `.gitignore`, bypasses it. Anything
  566. committed before stays in history, so moving it does not help: `git rm
  567. --cached` it and rotate what it exposed. `/test-roadmap` and `/fix-architecture`
  568. are the exceptions by design: the tests that pin a security finding are
  569. committed, and their neutral names do not stop them reproducing the weakness. Add `paad/security/` to your
  570. own `.gitignore` as well, and treat it as scratch rather than a record: it
  571. exists on one machine, `git clean -x` deletes it, and nothing brings it back.
  572. ### Pushback
  573. <details>
  574. <summary><code>/pushback [document]</code> — argues with your spec before anyone builds it</summary>
  575. If English is the new programming language, `pushback` is the code review.
  576. AI assistants rarely tell you that your spec has problems. `pushback` does. It
  577. critically reviews specs, PRDs, and design plans before work begins so you do
  578. not build on flawed assumptions — and it works the same way on any document
  579. that makes claims about the code, such as an agent steering file (`CLAUDE.md`,
  580. `AGENTS.md`) or a generated analysis report.
  581. * **Arguments:** `/pushback path/to/spec.md` (specific file) or
  582. `/pushback` (auto-detect from conversation history, common file locations,
  583. agent steering files, or generated reports)
  584. * **Source control reality check** — scans recent git history for commits that
  585. conflict with what the spec assumes, presented before other analysis
  586. * **Scope shape check** — flags unrelated features bundled together and
  587. oversized specs; suggests splits only when each piece delivers independent
  588. value
  589. * **6 analysis categories** — contradictions, feasibility, scope imbalance,
  590. omissions, ambiguity, and security concerns
  591. * **Severity-ordered review** — presents the most consequential issues first,
  592. one at a time, with concrete options and recommendations
  593. * **Flexible output** — update the spec in place or write a separate report to
  594. `paad/pushback-reviews/`
  595. </details>
  596. <details>
  597. <summary><code>/rethink [what to re-examine]</code> — checks whether the premises under a recommendation hold</summary>
  598. `pushback` argues with a spec. `rethink` argues with an answer — including one
  599. of `pushback`'s. When options have been laid out and one has been chosen, it
  600. goes and checks whether the premises under that choice actually hold.
  601. The distinction it exists for: a recommendation can be correct *and* unsound.
  602. The premises may hold and yet have been taken on faith from a source nobody
  603. tested. That answer is right today and will stay right until the day it isn't,
  604. with no one watching. `rethink` reports that case as its own verdict rather
  605. than waving the recommendation through.
  606. * **Arguments:** `/rethink` (the most recent option set) or
  607. `/rethink the caching approach` (when several decisions are live)
  608. * **Premise extraction** — writes out everything the recommendation depends on,
  609. including the unstated assumptions, sorted into checkable now, checkable by
  610. experiment, and not checkable at all
  611. * **Primary sources only** — verifies against the software, not its
  612. documentation; a claim sourced from a doc is checked against the thing the
  613. doc describes
  614. * **Five verdicts** — Sound, Lucky (holds but unchecked), Wrong reason (false
  615. premise, surviving conclusion), Premise false, and Ungrounded (with the
  616. cheapest experiment that would settle it)
  617. * **Evidence per premise** — every claim names what was checked to reach it
  618. * **Plain-terms walkthrough** — you probably ran this because you weren't sure
  619. about the options, so it re-presents them without jargon or internal names,
  620. with pros *and* cons for each, and says what verification changed about where
  621. each one stands
  622. * **A recommendation, with its reason** — and where the call also turns on
  623. something it can't see (a deadline, headcount, an unshipped roadmap) it gives
  624. you both halves: the option the evidence supports, plus the specific missing
  625. input and what it would flip the answer to. It goes silent only when the
  626. evidence supports no default at all
  627. * **No option list** — deliberately unlike `pushback`. It proposes an
  628. alternative only when verification exposed a real defect, and then exactly
  629. one, tied to that defect
  630. * **Writes nothing** — no report, no edits. The conversation is the deliverable
  631. </details>
  632. ---
  633. ### Alignment
  634. <details>
  635. <summary><code>/alignment [files...]</code> — checks that the plan and the spec say the same thing</summary>
  636. AI assistants drift off-scope. `alignment` catches that by checking whether
  637. requirements, design documents, and implementation plans actually match before
  638. code gets written.
  639. * **Arguments:** `/alignment` (auto-detect) or `/alignment
  640. requirements.md plan.md` (specific files) or `/alignment docs/specs/
  641. docs/plans/` (directories)
  642. * **Auto-detection** — scans `.kiro/`, `specs/` (spec-kit), `docs/plans/`,
  643. `docs/specs/`, and common filenames; classifies documents as intent
  644. (requirements) versus action (tasks)
  645. * **Source control reality check** — scans recent git history for conflicts
  646. with what the documents assume
  647. * **3 alignment checks** — requirements coverage, scope compliance, and design
  648. alignment (when design docs exist)
  649. * **Dependency-ordered issues** — surfaces root causes before downstream
  650. symptoms, one issue at a time
  651. * **Mandatory TDD rewrite** — once aligned, rewrites tasks in
  652. red/green/refactor format for better implementation outcomes
  653. * **Flexible output** — update documents in place or write a separate report
  654. to `paad/alignment-reviews/`
  655. </details>
  656. ---
  657. ### Architecture
  658. <details>
  659. <summary><code>/agentic-architecture [path...]</code> — five specialists find structural debt while it's cheap</summary>
  660. AI can build quickly on weak foundations. `agentic-architecture` identifies
  661. those structural problems before they compound. Five specialists review the
  662. codebase from different angles so issues do not hide behind a single
  663. reviewer’s blind spots. This skill is diagnostic only; it does not propose
  664. fixes.
  665. * **Arguments:** `/agentic-architecture` (full repo) or
  666. `/agentic-architecture src/` (scoped) or `/agentic-architecture
  667. packages/api/ packages/shared/` (multiple directories)
  668. * **Parallel analysis** — five specialists run simultaneously, followed by a
  669. verification phase that filters false positives by reading code and checking
  670. git history
  671. * **14 strength categories** — including modular boundaries, cohesion,
  672. coupling, error handling, observability, security, and testability
  673. * **34 flaw and risk types** — including god objects, tight coupling, circular
  674. dependencies, leaky abstractions, dead code, missing tests, and hard-coded
  675. secrets
  676. * **Coverage checklist** — ensures every category is assessed
  677. * **Hotspots** — identifies the files and directories most worth reviewing
  678. * **Report** — written to `paad/architecture-reviews/`
  679. </details>
  680. <details>
  681. <summary><code>/fix-architecture [report]</code> — works through those findings one at a time, test-first</summary>
  682. Architecture analysis tells you what is wrong. `fix-architecture` helps you
  683. resolve those findings one at a time with a test-first workflow. Each fix is
  684. validated, tested, tracked, and committed so the work can continue across
  685. multiple sessions.
  686. * **Arguments:** `/fix-architecture` (find most recent report) or
  687. `/fix-architecture path/to/report.md` (specific report)
  688. * **Pre-flight checks** — branch protection, report staleness detection, test
  689. infrastructure verification, and baseline test run
  690. * **Developer conversation** — confirms solo versus team workflow, batch size,
  691. auto-commit versus manual commit, flaw triage strategy, and plan
  692. confirmation
  693. * **Test-first fixes** — validates that each flaw still exists, writes
  694. safety-net tests where needed, proposes options with tradeoffs, and executes
  695. using red/green/refactor
  696. * **Status tracking** — records outcomes in the report: Fixed, Won't fix,
  697. Partially fixed, Skipped, Fixed (pre-existing), Attempted/reverted
  698. * **Flaw dependency detection** — flags when fixing one flaw resolves others
  699. * **Security flaws** — also loads the flaws `agentic-architecture` moved to
  700. `paad/security/`, and commits fixing them name neither the flaw nor the report
  701. * **Iterative workflow** — designed to run across multiple sessions against
  702. the same report
  703. Requires a feature branch (not `main` or `master`) and an existing
  704. architecture report.
  705. **Why sequential?** Architecture fixes happen one at a time rather than in
  706. parallel. Fixing one structural flaw often resolves others, and that
  707. dependency can only be discovered sequentially. Worktree-based parallelism
  708. avoids file collisions, but merging multiple structural refactors back
  709. together is a reliable way to introduce new bugs.
  710. </details>
  711. ---
  712. ### Discipline
  713. Code quality rarely degrades in one dramatic change. More often, it slips
  714. through a series of small decisions that each seem reasonable in isolation.
  715. <details>
  716. <summary><code>/agentic-review [base-branch] [path]</code> — six specialists review your branch before merge</summary>
  717. Discipline means reviewing before merging, every time. `agentic-review` uses
  718. multiple specialist agents to examine your branch for logic errors, edge
  719. cases, security issues, and integration problems that lightweight AI review
  720. tools often miss.
  721. Where typical AI review features tend to provide shallow, opportunistic
  722. feedback, `agentic-review` is designed as a deliberate pre-merge quality gate:
  723. parallel analysis, finding verification, deduplication, and severity ranking.
  724. * **Arguments:** `/agentic-review` (diff against `main`) or
  725. `/agentic-review develop` (diff against `develop`) or
  726. `/agentic-review main src/auth/` (scoped to a directory)
  727. * **Parallel review** — six specialists examine your branch simultaneously
  728. (Logic & Correctness, Error Handling & Edge Cases, Contract & Integration,
  729. Concurrency & State, Security, Spec Compliance), then findings are verified
  730. against actual code and deduplicated
  731. * **Severity ranking** — Critical / Important / Suggestion
  732. * **Spec Compliance** — pulls intent from PR description, plan/design docs,
  733. recent commits, or branch name; flags missing features, deviations, and
  734. out-of-scope additions (replaces the older Plan Alignment agent)
  735. * **Out-of-scope handling** — pre-existing bugs persist to
  736. `paad/code-reviews/backlog.md`, or to `paad/security/backlog.md` when the
  737. finding is security-related; the two files have the same shape, and only the
  738. first is committed. Out-of-scope additions are flagged for per-PR decision
  739. (keep / split / revert) without backlog persistence
  740. * **Report** — written to `paad/code-reviews/`
  741. Requires a feature branch (not `main` or `master`) with committed changes.
  742. </details>
  743. <details>
  744. <summary><code>/agentic-a11y [path]</code> — accessibility audit against WCAG 2.2 AA, by disability category</summary>
  745. Discipline also means accessibility is not treated as an afterthought.
  746. `agentic-a11y` scans your codebase for meaningful accessibility barriers and
  747. organizes them by who they affect. **Important**: this skill will help
  748. substantially, but human accessibility review of your application is still
  749. required. Accessibility is important, but hard.
  750. Supports **web, iOS, Android, React Native, Flutter, desktop, CLI, and
  751. games**. Evaluates against WCAG 2.2 AA, applied through WCAG2ICT for non-web
  752. platforms, with AAA noted as bonus recommendations.
  753. * **Arguments:** `/agentic-a11y` (full repo) or `/agentic-a11y
  754. src/components/` (scoped to a directory or file)
  755. * **Automatic platform detection** — identifies the project’s platform and
  756. adapts checks accordingly
  757. * **Specialists by disability category** — dedicated reviewers for screen
  758. reader usage, visual and color contrast, keyboard and motor interaction,
  759. cognitive load, and multimedia
  760. * **Platform-specific agent** (conditional) — dispatched for
  761. framework-specific pitfalls such as React, Vue, SwiftUI, Jetpack Compose,
  762. Flutter, Unity, and others
  763. * **Verification phase** — confirms that barriers are real and not already
  764. handled by the framework, platform, or component library
  765. * **WCAG conformance checklist** plus platform-specific guidance from sources
  766. such as Apple HIG, Material Design, and Xbox Accessibility Guidelines
  767. * **Impact summary by user group** — explains how the codebase affects each
  768. disability category
  769. * **Quick wins** — identifies the five highest-impact, lowest-effort
  770. improvements
  771. * **Report** — written to `paad/a11y-reviews/`
  772. </details>
  773. <details>
  774. <summary><code>/test-roadmap</code> — builds a test suite that catches real regressions</summary>
  775. PAAD is risky to use with codebases without a strong test suite. This skill
  776. builds that suite for you.
  777. High coverage numbers lie. A line can be "covered" by a test that asserts
  778. nothing — green forever, catching nothing. So when you finally refactor the
  779. scary part of a legacy codebase, the suite stays quiet and the regression
  780. ships anyway.
  781. `test-roadmap` builds the suite that does *not* stay quiet. It pins your
  782. code's **current** behavior, deliberately including the buggy parts, so that
  783. the day you start changing things the tests break loudly and tell you exactly
  784. what you changed.
  785. **Run it once to get a roadmap. Then keep running it — one phase of tests per
  786. run — until the roadmap is done.**
  787. That is the whole usage model, and it is the one thing people get wrong: they
  788. run `/test-roadmap`, get a plan, and stop with zero tests written. The
  789. command does something different every time you invoke it, because it looks
  790. for `paad/test-roadmap/test-roadmap.md` and routes on whether it exists:
  791. | Invocation | What it does |
  792. | --- | --- |
  793. | **1st run** — no roadmap yet | Detects your stack, grades the tests you already have, and writes a phased plan to `paad/test-roadmap/test-roadmap.md`. **Writes no tests.** |
  794. | **2nd run** | Writes Phase 1's tests, proves they catch the bug they claim to, commits them, marks the phase done. |
  795. | **3rd run** | Phase 2. |
  796. | **…** | …one phase per run… |
  797. | **Final run** | The last phase lands and the skill tells you the roadmap is finished. Then you stop. |
  798. So a 14-phase roadmap takes 15 invocations. Each run ends by telling you where
  799. you are (`Phase 8 of 14 — 7 done, 6 to go`) and whether to run it again. One
  800. phase per run is deliberate: each phase gets written, verified against a
  801. deliberately injected bug, and committed on its own, with a clean context.
  802. Sessions don't need to be consecutive, or even the same session — the roadmap
  803. file is the memory, so you can pick it up tomorrow, on a fresh clone, after a
  804. squash merge, and it resumes from what has already landed.
  805. * **Arguments:** `/test-roadmap` (no arguments — the presence of the
  806. roadmap file selects build mode or execute mode)
  807. * **Every phase names the bug it would catch** — a phase that cannot answer
  808. *"what breakage makes these tests go red?"* is coverage theater, and gets
  809. rewritten or dropped
  810. * **It proves each test actually works** — before a phase counts as done, it
  811. injects the very bug the phase claims to catch and confirms the test goes
  812. red; a passing command and a covered line are never accepted as proof
  813. * **Bug injection is disposable** — it happens in a throwaway `git worktree`,
  814. never in your working tree, database, or config
  815. * **It grades the tests you already have** — existing tests are classified
  816. against a catalog of test theater (assertion-free, tautological,
  817. snapshot-only, over-mocked, happy-path-only) before anything new is planned
  818. * **It will not call a phase done while the run is noisy** — your whole suite
  819. runs normally and again under coverage; it fixes what is its own to fix and
  820. surfaces the rest, and never edits your code to quiet a warning
  821. * **You finish with a bug list you did not start with** — contradictions found
  822. while pinning behavior are logged with the test that proves them. It never
  823. fixes them; that is your call
  824. * **Resumable** — across unrelated commits, squash merges, fresh clones, and
  825. sessions that remember nothing about the last one
  826. Requires a git checkout and a working branch. Started on `main` (or `master`,
  827. or `trunk`), it stops and offers to create a branch first, so your primary
  828. branch never fills up with half-built tests.
  829. **This skill writes tests and commits them** — one commit per phase, onto the
  830. branch you are on. `/fix-architecture` also commits; `/vibe` and `/backlog fix`
  831. edit source and leave the commit to you. Every other skill reports, advises,
  832. or edits documents.
  833. </details>
  834. ---
  835. ### Workflow
  836. <details>
  837. <summary><code>/makefile</code> — creates or updates a project <code>Makefile</code></summary>
  838. Creates or updates a project `Makefile` with standard targets such as `help`,
  839. `all`, `test`, `cover`, `lint`, and `format`. It detects your stack
  840. automatically and never modifies an existing target without asking first.
  841. Note: this skill might be removed in the future, or moved to a different
  842. namespace. Let me know if you rely on it.
  843. </details>
  844. <details>
  845. <summary><code>/vibe [task description]</code> — small fixes, TDD guardrails still on</summary>
  846. Speed without recklessness. `vibe` supports smaller fixes and quick changes
  847. while keeping TDD guardrails in place.
  848. * **Arguments:** `/vibe` (prompt for the task)
  849. * **Pre-flight checks** before writing code:
  850. * test infrastructure exists; if not, warn and ask how to proceed
  851. * scope check; if the change spans four or more files or crosses modules,
  852. warn that it may not be a good vibe task
  853. * architecture smell detection; if a simple task requires too much work,
  854. investigate deeper issues first
  855. * reusable component search; look for existing utilities before building
  856. from scratch
  857. * **Mandatory red/green/refactor** — write a failing test, write the minimal
  858. code to pass, then refactor; if the test passes or fails unexpectedly, stop
  859. and reassess
  860. * **Post-fix summary** — suggests relevant next steps such as `agentic-review`
  861. for security-sensitive changes, `agentic-a11y` for UI changes, or
  862. architecture review if the fix was harder than expected
  863. </details>
  864. <details>
  865. <summary><code>/handoff [save|resume]</code> — hands this session's work to a fresh one, in writing</summary>
  866. Claude Code already has `/compact`, and for most of what you want it is
  867. enough. The gap `handoff` fills is narrow and specific: `/compact`'s summary is
  868. written by the machine, lands without being read, and lives inside the
  869. transcript where you cannot edit it. `handoff` writes the same kind of state to
  870. a file you can open, correct, and hand to a genuinely fresh session.
  871. That makes the review the point, not a courtesy. A handoff nobody reads is a
  872. worse `/compact` — same summary, more ceremony — and the skill says so out loud
  873. rather than letting it slide.
  874. The thing it guards against isn't forgetfulness. An agent writing a handoff
  875. unaided keeps the expensive material well: the approaches already tried and
  876. abandoned, the reasons behind them, the constraint you mentioned once an hour
  877. ago. What it gets wrong is the cheap material — a test's file path, which
  878. changes are really in the last commit, a line number, who said the sentence
  879. it's quoting. Those are settleable with a tool in seconds, and they arrive in
  880. exactly the same confident voice as everything it got right. A fresh session
  881. has no memory to catch them with.
  882. * **Arguments:** `/handoff` (infers from whether the session has history) or
  883. `/handoff save` or `/handoff resume`
  884. * **Verifies before it writes** — commit, branch, dirty state, file paths, line
  885. numbers, test names, and whether the suite actually passes are checked with
  886. tools, not recalled. What can't be settled is marked inferred instead of
  887. asserted
  888. * **Weighted toward what a fresh session can't reconstruct** — decisions and
  889. their reasons, approaches ruled out and how far they got, constraints that
  890. exist nowhere on disk. No architecture tour, no session narrative, nothing
  891. `git diff` already shows
  892. * **Asks for the review that matters** — names the two or three claims it is
  893. least sure of, rather than a general disclaimer you'd skim
  894. * **Checks for drift on the way back in** — compares the recorded commit
  895. against HEAD, confirms the files it named still exist, and reports mismatches
  896. before acting on anything
  897. * **Never deletes the handoff** — it's untracked, so git can't restore it. The
  898. next save overwrites it
  899. * **Artifact** — `handoff.md` in the working directory, which it suggests you
  900. add to `.gitignore`
  901. </details>
  902. <details>
  903. <summary><code>/paad-help [skill-name]</code> — lists the skills, or explains one</summary>
  904. Shows help for all PAAD skills or detailed help for one skill.
  905. * **Arguments:** `/paad-help` (overview of all skills) or `/paad-help vibe`
  906. (detailed help for one skill)
  907. </details>
  908. ---
  909. ### Experimental skills
  910. These skills are shipped so they get real use, but they are **not settled**.
  911. Their arguments, output paths, and behavior may change — or the skill may be
  912. withdrawn — in **any** release, including a patch release. The semver promise
  913. the other skills carry does not apply to them. Read the
  914. [CHANGELOG](CHANGELOG.md) before you update. Please [file what
  915. breaks](https://github.com/Ovid/paad/issues).
  916. <details>
  917. <summary><code>/agentic-dedup [scope]</code> — finds duplicated <em>meaning</em>, not duplicated text</summary>
  918. Duplication that a clone detector finds is the easy kind. The expensive kind
  919. is two pieces of code that *mean* the same thing while looking nothing alike —
  920. a validator and a schema that accept the same values, a `for` loop and a
  921. stream pipeline that compute the same total, a permission check reimplemented
  922. through a different helper chain. Those drift apart silently, and the bug
  923. surfaces when one side is fixed and the other is not.
  924. `agentic-dedup` hunts for shared meaning rather than shared text, and reports only what survives verification.
  925. * **Arguments:** `/agentic-dedup` (whole repo) or `/agentic-dedup
  926. src/auth/` (scoped) or `/agentic-dedup --changed main` (seeded from the
  927. branch diff) or `/agentic-dedup --type-constraints` (schemas, type
  928. aliases, validators, DB constraints) or `/agentic-dedup --domain
  929. "payments"` (scoped to a domain term)
  930. * **Six discovery strategies** — name and concept search, behavioral
  931. fingerprints, type and constraint equivalence, control-flow normalization,
  932. tests read as behavioral specs, and a search for an existing canonical
  933. utility that the duplicates should have been calling
  934. * **Five specialists in parallel** — Semantic Equivalence, Type & Constraint
  935. Equivalence, Domain Boundary & Intent, Divergence Risk, and Refactoring
  936. Safety
  937. * **Skeptical verification** — findings based on name similarity, field-shape
  938. similarity, or visual structure are rejected, as is anything where the
  939. duplication is an intentional bounded-context boundary and sharing would be
  940. the riskier change
  941. * **Relationship, not just a verdict** — the type and constraint table states
  942. whether two constraints are exact, overlapping, subset, superset, or already
  943. drifting
  944. * **Rejected candidates are recorded** — so the next run does not spend
  945. context rediscovering the same false positives
  946. * **Report** — written to `paad/dedup-reviews/`, with a persistent `INDEX.md`
  947. across runs
  948. It never refactors anything. The report is the deliverable.
  949. </details>
  950. <details>
  951. <summary><code>/agentic-owasp [scope]</code> — reviews code against the OWASP Top 10:2025</summary>
  952. > **Note**: this skill is experimental and may change in any release, including
  953. > a patch release. Read the [CHANGELOG](CHANGELOG.md) before you update.
  954. > Further, **it is not a replacement for static security tools or human review.** It
  955. > is a deeper automated backstop that can catch issues those tools miss, but it
  956. > is not a guarantee of security.
  957. >
  958. > At present, static security tools are still the best way to catch many
  959. > security issues.
  960. Most security review output is pattern matching wearing a suit. A tool greps for
  961. string concatenation near a SQL call and reports injection, without ever
  962. checking that the ORM two lines up parameterizes by default, that the value
  963. interpolated is an enum, or that the route is behind an admin middleware chain.
  964. The developer reads twenty findings, confirms the first three are wrong, and
  965. stops reading. The twenty-first was real.
  966. `agentic-owasp` reviews code against the [OWASP Top
  967. 10:2025](https://owasp.org/Top10/2025/) and puts every candidate finding through
  968. an exploitability gate before it reaches the page. A finding has to name an
  969. attacker-controlled source with a line number, trace the call path to the
  970. dangerous operation hop by hop, and say which controls sit in that path and why
  971. they do not hold. Findings that cannot do all three become hardening notes or
  972. get rejected with the reason recorded — so the next run does not spend context
  973. rediscovering them.
  974. * **Arguments:** `/agentic-owasp` (whole repo) or `/agentic-owasp src/api/`
  975. (scoped) or `/agentic-owasp --changed main` (seeded from the branch diff) or
  976. `/agentic-owasp --category A01` (one category, or `A01,A05,A07`) or
  977. `/agentic-owasp --deps` (dependencies, lockfiles, and CI/CD only)
  978. * **Breadth costs depth, and it costs it silently** — a wide pass does not return
  979. a shallower version of a narrow one, it returns a *different* one. Measured on
  980. a real framework: pointed at a single module, the review found its flagship
  981. weakness in three runs out of three; a full-repository pass over 133 files read
  982. that same module, filed a piece of the weakness as a hardening note, and
  983. shipped without it. The wide run reported *more* findings overall, which is
  984. exactly what hides the trade. So past roughly forty source files the skill
  985. stops and asks: narrow to the untrusted-input surface, split into separate
  986. subsystem passes, or take the wide pass with the dilution written into the
  987. report. Prefer several scoped runs to one sweep
  988. * **Six specialists, all ten categories, none orphaned** — Access Control &
  989. Authentication (A01, A07), Injection & Untrusted Input (A05), Cryptography &
  990. Data Protection (A04), Configuration & Supply Chain (A02, A03), Design,
  991. Integrity & Failure Modes (A06, A08, A10), and Logging, Alerting & Detection
  992. (A09). The 2025 list is the current one: supply chain and mishandled
  993. exceptional conditions are new categories, and logging is now about
  994. *alerting*, not just recording
  995. * **A seventh specialist organized by mechanism, not by consequence** — an OWASP
  996. category names what a weakness *does*, so a hole in the seam between two
  997. components that are each individually correct belongs to no category and is
  998. owned by none of the six. The Mechanism & Round-Trip specialist hunts two
  999. patterns instead: paired APIs that disagree on a round trip — what one renders,
  1000. the other parses back as something else — and facts the codebase stores twice,
  1001. where the security decision reads the copy the attacker writes. It files what
  1002. it finds under the category of the impact
  1003. * **A library's callers are applications you cannot see** — "no caller in this
  1004. repository passes request data into that parameter" is true of every library
  1005. and rejects nothing. When the subject is a library or framework and its own
  1006. documentation shows the vulnerable call, the documented API is the source, and
  1007. the doc reference stands in for the in-repo one. Documentation that teaches
  1008. the unsafe call ships the defect to every downstream user
  1009. * **Framework defaults are read first** — what the ORM, template engine, and
  1010. middleware already do decides which findings are real. Where a framework
  1011. protects by default, the finding is the opt-out, and the report names the line
  1012. it is on
  1013. * **A coverage table that admits what nobody looked at** — all ten categories,
  1014. each marked assessed or not. "No findings in A04" and "nobody checked A04" are
  1015. different sentences, and a report that blurs them leaves you worse off than
  1016. before you ran it
  1017. * **Severity that means something** — Critical is reachable-and-unauthenticated,
  1018. not "looks scary". Hardening notes live in their own section so they cannot be
  1019. mistaken for exploitable findings. Whether a finding was actually executed is
  1020. a separate `unproven` field and never lowers its severity: a traced smuggling
  1021. path is "High, unproven", not Medium, because a hedged rank is a claim about
  1022. impact you have not earned and the downgraded row is the one nobody fixes
  1023. * **A verifier that tries to break the findings** — it defaults to refuted when
  1024. uncertain, and it clears a control by enumerating every caller that reaches
  1025. the value without passing through it, not by reading where the control lives.
  1026. A sanitizer on the serialization path says nothing about the sibling accessor
  1027. that skips it
  1028. * **Chains that cross category boundaries survive the split** — specialists
  1029. covering ten categories means a weakness assembled from a default in one
  1030. category and a leak in another arrives as two harmless-looking halves that
  1031. each fail the exploitability gate alone. Specialists report what they see
  1032. outside their own categories as fragments rather than dropping it, and the
  1033. verifier — the only component holding all seven outputs — composes before it
  1034. rejects. A chain link is supposed to look harmless on its own
  1035. * **Every fragment reaches the page, not just a count of them** — the pool is the
  1036. run's working set, and "63 fragments pooled" is not a record of it. Once the
  1037. session ends, a fragment that exists only as a number is gone, and nobody can
  1038. tell afterwards whether a sink was seen and dropped or never looked at. The
  1039. report lists each one with its `path:line`, the sentence the specialist wrote,
  1040. and where it ended up — composed into a finding, left without a counterpart, or
  1041. never traced. That is also what makes a run's conclusions checkable later
  1042. instead of taken on trust
  1043. * **Reads by default; asks before it runs anything** — no specialist and no
  1044. verifier starts the application, connects to a database, or sends a request to
  1045. any host. Where a sink is reachable in-process, it offers a proof script per
  1046. finding that exits 0 while the weakness is open, and lays out both sides
  1047. before you decide. The offer is ordered by severity, not by whichever proof
  1048. looks easiest — a run that proves its footnotes and leaves its Criticals
  1049. "reasoned from source" aimed the tool at the cheapest question. It never
  1050. executes without a yes, declining costs you nothing but the `unproven` mark,
  1051. and every unproven finding says why it went unproven. Testing a *deployed* system is a different
  1052. job with a different authorization scope, and out of scope in every mode
  1053. * **It tells you what it did not find** — every run ends by saying the report is
  1054. not a complete list of the weaknesses and is not evidence the rest is secure.
  1055. Zero findings means one reviewer looked once, inside ten categories, at one
  1056. scope. Business logic, race conditions, and tenant isolation are outside the
  1057. Top 10 and were never in scope. A clean report read as an all-clear leaves you
  1058. worse off than never having run it. The same closing block adds the one thing
  1059. the ignored directory cannot prevent on its own: a report that *is* committed,
  1060. by whatever route, ages into a false clearance for code that has since moved
  1061. * **Credentials are reported by location, never by value** — a secret pasted
  1062. into a report file is a second copy of the leak, and rotation goes to the top
  1063. of the remediation order because it is the one item that cannot wait
  1064. * **Report** — written to `paad/security/`, with an `INDEX.md` across runs.
  1065. Every OWASP finding is security-related by definition, so the whole report,
  1066. its index, and any proof scripts live in that ignored directory. Nothing is
  1067. left in a committed file but the run's own summary
  1068. It never fixes anything. The report is the deliverable.
  1069. </details>
  1070. <details>
  1071. <summary><code>/backlog [clean|fix]</code> — clears fixed bugs out of the review backlog, or fixes the next one</summary>
  1072. `/agentic-review` records pre-existing bugs it finds outside your branch in a
  1073. backlog instead of losing them. Nothing ever empties that backlog: entries
  1074. pile up long after the bug they describe was fixed, until nobody reads it.
  1075. `backlog` is the other half — it keeps the list honest, and works it.
  1076. * **Arguments:** `/backlog` (list entries, then choose), `/backlog clean`, or
  1077. `/backlog fix`
  1078. * **Clean** — one skeptical read-only analyst per entry re-checks it against
  1079. the current code and deletes it only on cited evidence that the bug is fixed
  1080. or the code is gone. Any doubt keeps the entry; a renamed symbol is not a fix
  1081. * **Fix** — proposes the most severe, oldest entry (you can pick another), fixes it, and removes it only
  1082. after an independent analyst confirms from the code that the bug is gone.
  1083. One entry per run
  1084. * **Both backlogs** — reads `paad/code-reviews/backlog.md` and the
  1085. uncommitted `paad/security/backlog.md`, and writes each edit back to the file
  1086. it came from
  1087. * **Never commits** — prints the commit command for you to run, and never
  1088. includes the security backlog in it
  1089. </details>
  1090. </details>
  1091. ## Invoking skills
  1092. <details>
  1093. <summary>Slash commands, plain English, and the <code>paad:</code> prefix</summary>
  1094. The headings above spell each skill with a leading slash — `/pushback`,
  1095. `/agentic-review` — because that's the shortest thing that works. You often
  1096. don't need to type it at all.
  1097. Claude Code recognizes these skills by name in an ordinary sentence, so "run
  1098. pushback on this spec" or "review the architecture of this module" reaches the
  1099. right one. When you'd rather be explicit, the bare slash command does it:
  1100. `/pushback on the options you just gave me`.
  1101. The fully-qualified `/paad:pushback` form exists for one job — disambiguation.
  1102. When a name is already taken, the `paad:` prefix says which one you mean.
  1103. Nothing in PAAD currently collides, so until you install a plugin that shares a
  1104. name, you can ignore it. The help skill is called `paad-help` rather than `help`
  1105. for exactly this reason: `/help` is Claude Code's own built-in.
  1106. </details>
  1107. ## Working on PAAD itself
  1108. <details>
  1109. <summary>Running the preview tree, and the test targets</summary>
  1110. The repository carries two copies of the plugin. **`preview/paad/` is where all
  1111. new work goes.** `plugins/paad/` is the last released tree — it is what everyone
  1112. installs, and it is written only by `make promote`, never by hand. An edit made
  1113. there reaches `main` unpromoted and unbumped, ships immediately to anyone
  1114. installing fresh, and is then erased without warning by the next release, whose
  1115. first step copies preview straight over it.
  1116. Drive your changes against preview:
  1117. ```bash
  1118. claude --plugin-dir ./preview/paad
  1119. ```
  1120. Then invoke skills with `/paad-help` to see available commands, or try
  1121. `/vibe`, `/pushback`, and the rest directly. Preview announces itself as
  1122. `v<version>-preview`, so a transcript always says which tree ran.
  1123. After making changes, run `/reload-plugins` inside Claude Code to pick up
  1124. updates without restarting.
  1125. ### Testing
  1126. Run all checks with:
  1127. ```bash
  1128. make test
  1129. ```
  1130. This validates the marketplace and Claude plugin structure, then runs
  1131. consistency checks such as package version sync, digraph presence, help and
  1132. README coverage, and frontmatter validation. Use `make help` to see all
  1133. available targets.
  1134. Individual checks can also be run separately:
  1135. ```bash
  1136. make check-versions # package.json ↔ marketplace.json ↔ plugin.json version sync
  1137. make check-digraphs # every skill (except paad-help) has a digraph
  1138. make check-help # every skill is documented in paad-help
  1139. make check-readme # every skill is documented in README.md
  1140. make check-skill-names # skill folder names follow the Agent Skills naming rules
  1141. make check-frontmatter # SKILL.md frontmatter, plus the internal flag across all three skill trees
  1142. make check-references # references/ dispatches resolve; no orphaned reference files
  1143. make validate # claude plugin validate on marketplace + plugins
  1144. ```
  1145. </details>
  1146. ## Contributing
  1147. <details>
  1148. <summary>How to submit a change</summary>
  1149. 1. Fork the repository and create a feature branch.
  1150. 2. Make your changes. See `CLAUDE.md` for conventions on adding or modifying skills.
  1151. 3. Run `make test` to verify everything passes.
  1152. 4. Open a pull request.
  1153. Key rules from `CLAUDE.md`:
  1154. * Every skill except `paad-help` must include a Graphviz digraph covering its
  1155. decision points
  1156. * Skill folder names must match the `name` field in `SKILL.md` frontmatter
  1157. * Use `make bump-version VERSION=X.Y.Z` to keep all versioned files in sync
  1158. * Put new and changed skills in `preview/paad/skills/`, never in
  1159. `plugins/paad/skills/`
  1160. * Update `paad-help` and `CLAUDE.md` when adding or changing skills. The
  1161. `README.md` entry lands on the release branch instead — README describes what
  1162. can actually be installed, and a preview-only skill cannot be yet
  1163. </details>
  1164. ## Star History
  1165. <a href="https://github.com/Ovid/star-history">
  1166. <picture>
  1167. <source media="(prefers-color-scheme: dark)" srcset=".github/star-history/dark.svg">
  1168. <source media="(prefers-color-scheme: light)" srcset=".github/star-history/light.svg">
  1169. <img alt="Star history for Ovid/paad: 59 stars as of 2026-07-25" src=".github/star-history/light.svg" width="800">
  1170. </picture>
  1171. </a>
  1172. ## License
  1173. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.