pm-claude-skills 76.0.0 → 76.2.0

package/README.md

@@ -1,8 +1,8 @@
-# 🧠 PM Skills — 1098 Professional Agent Skills for Claude, ChatGPT, Gemini, Cursor, Codex & Hermes
+# 🧠 PM Skills — 1099 Professional Agent Skills for Claude, ChatGPT, Gemini, Cursor, Codex & Hermes
 
 <p align="center">
   <a href="https://mohitagw15856.github.io/pm-claude-skills/">
-    <img src="web/docs-assets/hero.svg" width="100%" alt="PM Skills — 1098 professional skills your AI assistant can read. Plain markdown, works with Claude, ChatGPT, Gemini, Cursor, and Codex. MIT licensed." />
+    <img src="web/docs-assets/hero.svg" width="100%" alt="PM Skills — 1099 professional skills your AI assistant can read. Plain markdown, works with Claude, ChatGPT, Gemini, Cursor, and Codex. MIT licensed." />
   </a>
 </p>
 
@@ -25,7 +25,7 @@
 ## What is PM Skills?
 
 <!-- AEO Answer Capsule — 68 words -->
-PM Skills is an open-source library of 1098 Agent Skills — plain-markdown SKILL.md files that teach an AI assistant to do one professional task to a senior professional's standard, from writing a PRD to decoding a lease or running a blameless postmortem. Each skill bundles the framework, an output template, quality checks, and anti-patterns. It is MIT-licensed and works with Claude, ChatGPT, Gemini, Cursor, and Codex.
+PM Skills is an open-source library of 1099 Agent Skills — plain-markdown SKILL.md files that teach an AI assistant to do one professional task to a senior professional's standard, from writing a PRD to decoding a lease or running a blameless postmortem. Each skill bundles the framework, an output template, quality checks, and anti-patterns. It is MIT-licensed and works with Claude, ChatGPT, Gemini, Cursor, and Codex.
 <!-- End AEO Capsule -->
 
 **Decode a lease before you sign it. Write a PRD your team can execute. Simulate the promotion committee before the real one meets. Check the weather with zero API keys.** Generic AI gives you filler; these give you the structure a senior professional actually uses.
@@ -117,8 +117,8 @@ It's not just a folder of files — the whole library is explorable, runnable, a
 <table>
 <tr>
 <td width="50%" align="center">
-<a href="https://mohitagw15856.github.io/pm-claude-skills/galaxy3d.html"><img src="web/docs-assets/demo-galaxy.gif" width="100%" alt="Galaxy 3D — fly through all 1098 skills as a glowing constellation you orbit and click into" /></a>
-<br /><sub><b>🌌 <a href="https://mohitagw15856.github.io/pm-claude-skills/galaxy3d.html">Galaxy 3D</a></b> — fly through all 1098 skills as a living constellation. The ones you've run burn brighter.</sub>
+<a href="https://mohitagw15856.github.io/pm-claude-skills/galaxy3d.html"><img src="web/docs-assets/demo-galaxy.gif" width="100%" alt="Galaxy 3D — fly through all 1099 skills as a glowing constellation you orbit and click into" /></a>
+<br /><sub><b>🌌 <a href="https://mohitagw15856.github.io/pm-claude-skills/galaxy3d.html">Galaxy 3D</a></b> — fly through all 1099 skills as a living constellation. The ones you've run burn brighter.</sub>
 </td>
 <td width="50%" align="center">
 <a href="https://mohitagw15856.github.io/pm-claude-skills/wrapped.html"><img src="web/docs-assets/demo-holo.gif" width="100%" alt="PM Skills Wrapped — your practice turned into a shareable, Spotify-Wrapped-style story" /></a>
@@ -127,7 +127,7 @@ It's not just a folder of files — the whole library is explorable, runnable, a
 </tr>
 </table>
 
-▶ **[Open the Playground](https://mohitagw15856.github.io/pm-claude-skills/)** to run any of the 1098 skills with your own key — or just [browse them all](SKILLS.md).
+▶ **[Open the Playground](https://mohitagw15856.github.io/pm-claude-skills/)** to run any of the 1099 skills with your own key — or just [browse them all](SKILLS.md).
 
 ## 💬 What can I ask it to do?
 
@@ -140,7 +140,7 @@ Anything below is a real ask that activates a real skill — say it in your own
 | 🛂 *"prep me for the visa interview"* → [the-visa-interview](skills/the-visa-interview/SKILL.md) | 🔨 *"is this contractor quote fair?"* → [home-contractor-quote-decoder](skills/home-contractor-quote-decoder/SKILL.md) | 🏡 *"should we rent or buy?"* → [rent-vs-buy](skills/rent-vs-buy/SKILL.md) |
 | 📝 *"draft my self-review honestly"* → [performance-review](skills/performance-review/SKILL.md) | 🚀 *"are we ready to launch?"* → [product-launch-checklist](skills/product-launch-checklist/SKILL.md) | 📬 *"my inbox is 4,000 deep"* → [email-triage-system](skills/email-triage-system/SKILL.md) |
 
-…all 1098 asks live in **[the catalog](SKILLS.md)**.
+…all 1099 asks live in **[the catalog](SKILLS.md)**.
 
 ## ⚡ Quick start
 
@@ -156,7 +156,7 @@ No `npm install` needed — `npx pm-claude-skills …` always runs the latest. `
 
 ## 📚 The skills
 
-Every skill follows the same discipline: what it produces, the inputs it needs, a real framework (severity scales, decision rules — not vibes), a concrete output template, quality checks, and anti-patterns. All 1098 pass the [SkillSpec](SKILLSPEC.md) L3 gate and a security audit in CI.
+Every skill follows the same discipline: what it produces, the inputs it needs, a real framework (severity scales, decision rules — not vibes), a concrete output template, quality checks, and anti-patterns. All 1099 pass the [SkillSpec](SKILLSPEC.md) L3 gate and a security audit in CI.
 
 <table align="center">
   <tr align="center">
@@ -311,6 +311,46 @@ The library grew an ecosystem — all optional, all linked from the **[full show
 
 **[▶ Skill Playground](https://mohitagw15856.github.io/pm-claude-skills/)** — try any skill in your browser, no install · **[📸 the Gallery](docs/GALLERY.md)** — the creative side, in screenshots · **[Anti-Pattern Museum](https://mohitagw15856.github.io/pm-claude-skills/museum.html)** — 2,900+ shareable rules · **[The Handbook](https://mohitagw15856.github.io/pm-claude-skills/handbook.html)** (also a [real printed book](docs/print/)) · **[Workflow recipes](WORKFLOWS.md)** · **[Subagents & slash commands](agents/)** · **[MCP server + REST API](mcp-remote/)** · **[n8n / Slack / Obsidian integrations](connectors/)** · **[The Boardroom](https://mohitagw15856.github.io/pm-claude-skills/boardroom.html)** · **[SkillBench](skillbench/)** · **[Org Edition](org/)** · **[🇪🇸 🇫🇷 🇨🇳 🇯🇵 translations](skills-i18n/)**
 
+### Lint your own skills in CI
+
+The validator that keeps these 1,099 honest, as a GitHub Action:
+
+```yaml
+- uses: mohitagw15856/pm-claude-skills@v76
+  with:
+    path: .claude/skills   # optional — it finds them otherwise
+```
+
+It checks frontmatter, the `Use when …` trigger clause a model actually matches
+on, leftover template text, and structure — and **annotates each finding inline
+on the pull request diff**, because a finding on the line beats a finding in a
+log nobody opens. Also available as `npx pm-claude-skills skillcheck`.
+
+Zero dependencies, no Docker image, no model call.
+
+### Companion tools — for the bits a skill shouldn't guess
+
+A skill can tell a model to check the contrast. Only arithmetic can actually
+check it. Where a question has a *right answer* rather than a good one, the
+skill calls out to a tool instead of estimating — both are MIT, zero-dependency,
+and **neither makes a model call**, so they cost nothing to run and return the
+same answer every time.
+
+**[notugly](https://github.com/mohitagw15856/notugly)** — design systems that are
+provably not ugly. `#777777` on white is 4.478 and fails AA; `#767676` is 4.542
+and passes, and no amount of looking at a screenshot separates those.
+`accessibility-audit`, `design-system-audit`, `design-handoff-brief`,
+`brand-guidelines` and the Figma reviews now fill their contrast rows from
+`npx notugly`; the MCP server exposes `check_contrast` directly; and
+[`design-system-generate`](skills/design-system-generate/) wraps it for the case
+where there is no design system and something ships on Thursday.
+
+**[rulebook](https://github.com/mohitagw15856/rulebook)** — 37 games, 203
+rulings, and how commonly each house rule is actually played.
+[`board-game-night-planner`](skills/board-game-night-planner/) uses it for teach
+times and for settling the argument, because a rules disagreement is usually two
+groups who learned it differently and are both partly right.
+
 ## 📄 The one-page cheatsheet
 
 The whole library on one poster — start path, standout features, and install one-liners for every tool. Print it, share it, drop it in a slide.
@@ -325,23 +365,23 @@ The whole library on one poster — start path, standout features, and install o
 
 ## 🆕 Latest
 
-**v76.0.0 — the systems wave:** 20 new skills for the bureaucracies and emergencies people face alone — [🏛 pm-civic](plugins/pm-civic) (vote, permits, jury duty, [the letter that gets action](skills/elected-rep-letter/SKILL.md), report a hazard), [♿ pm-accessibility](plugins/pm-accessibility) ([appeal a denied disability benefit](skills/disability-benefit-appeal/SKILL.md), [accommodations](skills/accommodation-request/SKILL.md), accessible travel, disclosure), [✈️ pm-newcomer](plugins/pm-newcomer) (first-90-days in a new country: [arrival setup](skills/arrival-setup/SKILL.md), credential recognition, healthcare, [credit from scratch](skills/credit-from-scratch/SKILL.md)), and [🚨 pm-emergency](plugins/pm-emergency) ([go-bag](skills/go-bag-builder/SKILL.md), [your real local hazards](skills/hazard-risk-map/SKILL.md), [outage plan](skills/power-outage-plan/SKILL.md), after-the-disaster) — every one guard-railed and routed to official sources. **1098 skills, 121 bundles**.
+**v76.0.0 — the systems wave:** 20 new skills for the bureaucracies and emergencies people face alone — [🏛 pm-civic](plugins/pm-civic) (vote, permits, jury duty, [the letter that gets action](skills/elected-rep-letter/SKILL.md), report a hazard), [♿ pm-accessibility](plugins/pm-accessibility) ([appeal a denied disability benefit](skills/disability-benefit-appeal/SKILL.md), [accommodations](skills/accommodation-request/SKILL.md), accessible travel, disclosure), [✈️ pm-newcomer](plugins/pm-newcomer) (first-90-days in a new country: [arrival setup](skills/arrival-setup/SKILL.md), credential recognition, healthcare, [credit from scratch](skills/credit-from-scratch/SKILL.md)), and [🚨 pm-emergency](plugins/pm-emergency) ([go-bag](skills/go-bag-builder/SKILL.md), [your real local hazards](skills/hazard-risk-map/SKILL.md), [outage plan](skills/power-outage-plan/SKILL.md), after-the-disaster) — every one guard-railed and routed to official sources. **1099 skills, 121 bundles**.
 
-**v75.0.0 — the human-edges wave:** 20 new skills for the parts of life nobody built tools for — [🧠 pm-neurodivergent](plugins/pm-neurodivergent) ([masking-budget](skills/masking-budget/SKILL.md), [meltdown-map](skills/meltdown-map/SKILL.md), [body-double-session](skills/body-double-session/SKILL.md), [nt-translator](skills/nt-translator/SKILL.md), [sensory-audit](skills/sensory-audit/SKILL.md)), [🩺 pm-invisible-illness](plugins/pm-invisible-illness) ([diagnosis-limbo-kit](skills/diagnosis-limbo-kit/SKILL.md), [spoon-planner](skills/spoon-planner/SKILL.md), [perimenopause-navigator](skills/perimenopause-navigator/SKILL.md), [flare-day-planner](skills/flare-day-planner/SKILL.md)), [🏳️‍🌈 pm-identity](plugins/pm-identity) ([coming-out-rehearsal](skills/coming-out-rehearsal/SKILL.md), [name-change-navigator](skills/name-change-navigator/SKILL.md), [two-worlds-translator](skills/two-worlds-translator/SKILL.md), [faith-transition-companion](skills/faith-transition-companion/SKILL.md)) — plus [grief-admin](skills/grief-admin/SKILL.md), [legacy-letter](skills/legacy-letter/SKILL.md), [the-ick-decoder](skills/the-ick-decoder/SKILL.md), and [rabbit-hole-rescue](skills/rabbit-hole-rescue/SKILL.md); every sensitive one guard-railed. **1098 skills, 121 bundles**.
+**v75.0.0 — the human-edges wave:** 20 new skills for the parts of life nobody built tools for — [🧠 pm-neurodivergent](plugins/pm-neurodivergent) ([masking-budget](skills/masking-budget/SKILL.md), [meltdown-map](skills/meltdown-map/SKILL.md), [body-double-session](skills/body-double-session/SKILL.md), [nt-translator](skills/nt-translator/SKILL.md), [sensory-audit](skills/sensory-audit/SKILL.md)), [🩺 pm-invisible-illness](plugins/pm-invisible-illness) ([diagnosis-limbo-kit](skills/diagnosis-limbo-kit/SKILL.md), [spoon-planner](skills/spoon-planner/SKILL.md), [perimenopause-navigator](skills/perimenopause-navigator/SKILL.md), [flare-day-planner](skills/flare-day-planner/SKILL.md)), [🏳️‍🌈 pm-identity](plugins/pm-identity) ([coming-out-rehearsal](skills/coming-out-rehearsal/SKILL.md), [name-change-navigator](skills/name-change-navigator/SKILL.md), [two-worlds-translator](skills/two-worlds-translator/SKILL.md), [faith-transition-companion](skills/faith-transition-companion/SKILL.md)) — plus [grief-admin](skills/grief-admin/SKILL.md), [legacy-letter](skills/legacy-letter/SKILL.md), [the-ick-decoder](skills/the-ick-decoder/SKILL.md), and [rabbit-hole-rescue](skills/rabbit-hole-rescue/SKILL.md); every sensitive one guard-railed. **1099 skills, 121 bundles**.
 
-**v74.0.0 — the life-expansion wave:** five new bundles for the parts of life beyond the office — [📖 pm-learning](plugins/pm-learning) (learn anything and make it stick: [learn-anything-roadmap](skills/learn-anything-roadmap/SKILL.md), [feynman-explainer](skills/feynman-explainer/SKILL.md), [spaced-repetition-setup](skills/spaced-repetition-setup/SKILL.md)), [💰 pm-wealth](plugins/pm-wealth) (build wealth on purpose — educational, not advice: [investing-for-beginners](skills/investing-for-beginners/SKILL.md), [first-100k-plan](skills/first-100k-plan/SKILL.md), [ask-for-a-raise](skills/ask-for-a-raise/SKILL.md)), [🤝 pm-social](plugins/pm-social) (the human conversations: [make-friends-as-an-adult](skills/make-friends-as-an-adult/SKILL.md), [boundary-setting-scripts](skills/boundary-setting-scripts/SKILL.md), [repair-after-a-fight](skills/repair-after-a-fight/SKILL.md)), [🩺 pm-caregiving](plugins/pm-caregiving) (care for aging parents — not medical/legal advice: [medical-appointment-advocate](skills/medical-appointment-advocate/SKILL.md), [caregiver-burnout-check](skills/caregiver-burnout-check/SKILL.md)), and [🤖 pm-ai-native](plugins/pm-ai-native) (use AI itself well: [prompt-library-builder](skills/prompt-library-builder/SKILL.md), [delegate-to-ai](skills/delegate-to-ai/SKILL.md), [spot-ai-mistakes](skills/spot-ai-mistakes/SKILL.md)) — 50 new skills; **1098 skills, 121 bundles**.
+**v74.0.0 — the life-expansion wave:** five new bundles for the parts of life beyond the office — [📖 pm-learning](plugins/pm-learning) (learn anything and make it stick: [learn-anything-roadmap](skills/learn-anything-roadmap/SKILL.md), [feynman-explainer](skills/feynman-explainer/SKILL.md), [spaced-repetition-setup](skills/spaced-repetition-setup/SKILL.md)), [💰 pm-wealth](plugins/pm-wealth) (build wealth on purpose — educational, not advice: [investing-for-beginners](skills/investing-for-beginners/SKILL.md), [first-100k-plan](skills/first-100k-plan/SKILL.md), [ask-for-a-raise](skills/ask-for-a-raise/SKILL.md)), [🤝 pm-social](plugins/pm-social) (the human conversations: [make-friends-as-an-adult](skills/make-friends-as-an-adult/SKILL.md), [boundary-setting-scripts](skills/boundary-setting-scripts/SKILL.md), [repair-after-a-fight](skills/repair-after-a-fight/SKILL.md)), [🩺 pm-caregiving](plugins/pm-caregiving) (care for aging parents — not medical/legal advice: [medical-appointment-advocate](skills/medical-appointment-advocate/SKILL.md), [caregiver-burnout-check](skills/caregiver-burnout-check/SKILL.md)), and [🤖 pm-ai-native](plugins/pm-ai-native) (use AI itself well: [prompt-library-builder](skills/prompt-library-builder/SKILL.md), [delegate-to-ai](skills/delegate-to-ai/SKILL.md), [spot-ai-mistakes](skills/spot-ai-mistakes/SKILL.md)) — 50 new skills; **1099 skills, 121 bundles**.
 
-**v73.0.0 — think differently:** two bundles that change *how* your AI reasons, not just what it does — [💭 pm-thinking](plugins/pm-thinking) (escape the generic answer: [the-third-answer](skills/the-third-answer/SKILL.md), [five-minds](skills/five-minds/SKILL.md), [red-team-my-plan](skills/red-team-my-plan/SKILL.md), [devils-advocate](skills/devils-advocate-on-demand/SKILL.md)) and [🎯 pm-focus](plugins/pm-focus) (ADHD-friendly executive function: [where-do-i-start](skills/where-do-i-start/SKILL.md), [overwhelm-triage](skills/overwhelm-triage/SKILL.md), [build-my-memory-file](skills/build-my-memory-file/SKILL.md)) — 50 skills inspired by parallel-divergent-ideation research; passes the 1,000 mark — now 1098 skills, 110 bundles.
+**v73.0.0 — think differently:** two bundles that change *how* your AI reasons, not just what it does — [💭 pm-thinking](plugins/pm-thinking) (escape the generic answer: [the-third-answer](skills/the-third-answer/SKILL.md), [five-minds](skills/five-minds/SKILL.md), [red-team-my-plan](skills/red-team-my-plan/SKILL.md), [devils-advocate](skills/devils-advocate-on-demand/SKILL.md)) and [🎯 pm-focus](plugins/pm-focus) (ADHD-friendly executive function: [where-do-i-start](skills/where-do-i-start/SKILL.md), [overwhelm-triage](skills/overwhelm-triage/SKILL.md), [build-my-memory-file](skills/build-my-memory-file/SKILL.md)) — 50 skills inspired by parallel-divergent-ideation research; passes the 1,000 mark — now 1099 skills, 110 bundles.
 
-**v72.0.0 — the Everyday Life update:** the biggest single drop yet — **100 new skills** across four new bundles: [🎲 hobbies](plugins/pm-hobbies) (wine pairing, board-game nights, D&D), [💪 wellbeing](plugins/pm-wellbeing) (workouts, sleep, habits), [🔐 digital self-defense](plugins/pm-digital-safety) (identity-theft recovery, phishing triage, doxxing response), and [👪 family](plugins/pm-family) (new-baby logistics, wedding vows, condolences) — plus new money, legal, home, career, freelance and learning skills; **1098 skills, 108 bundles**.
+**v72.0.0 — the Everyday Life update:** the biggest single drop yet — **100 new skills** across four new bundles: [🎲 hobbies](plugins/pm-hobbies) (wine pairing, board-game nights, D&D), [💪 wellbeing](plugins/pm-wellbeing) (workouts, sleep, habits), [🔐 digital self-defense](plugins/pm-digital-safety) (identity-theft recovery, phishing triage, doxxing response), and [👪 family](plugins/pm-family) (new-baby logistics, wedding vows, condolences) — plus new money, legal, home, career, freelance and learning skills; **1099 skills, 108 bundles**.
 
-**v67.0.0 — the everywhere wave:** six new rooms — [the trades](plugins/pm-trades) (quotes, stage payments, apprentices), [the committee](plugins/pm-committee) (AGMs, treasurers, the council mic), [open-source maintainers](plugins/pm-maintainer), [aging parents](plugins/pm-aging-parents) (the talks, the sibling summit), [the kitchen](plugins/pm-kitchen), [the band](plugins/pm-musician) — plus [used-car](skills/used-car-decoder/SKILL.md)/[mechanic-quote](skills/mechanic-quote-decoder/SKILL.md) decoders, the [group-trip fixer](skills/group-trip-negotiator/SKILL.md), and [🌱 daily practice](https://mohitagw15856.github.io/pm-claude-skills/streak.html); 1098 skills, 104 bundles. *v66 — new-gen;* [pm-newgen](plugins/pm-newgen) — [decode your first brand deal](skills/creator-deal-decoder/SKILL.md), [clip the podcast](skills/clip-factory/SKILL.md), [prep tonight's D&D](skills/ttrpg-session-forge/SKILL.md), [fix the dating profile honestly](skills/dating-profile-doctor/SKILL.md), [vibe-check the weekend app](skills/the-vibe-check/SKILL.md), [keep the flat peaceful](skills/roommate-agreement/SKILL.md), [climb ranked on purpose](skills/ranked-climb-coach/SKILL.md), [flip thrift finds](skills/resale-flip-kit/SKILL.md), [plan the micro-retirement](skills/micro-retirement-planner/SKILL.md), [get your attention back](skills/attention-reset/SKILL.md); 1098 skills, 104 bundles. *v65 — pm-2027;* ten skills for problems you don't have yet (but will) — [offboard an AI coworker](skills/agent-severance/SKILL.md), [drill the deepfake wire-fraud call](skills/deepfake-drill/SKILL.md), [hire your agent like an employee](skills/agent-hiring-panel/SKILL.md), [declare context bankruptcy](skills/context-bankruptcy/SKILL.md), [send your position to meetings instead of your body](skills/clone-brief/SKILL.md), [publish your personal API](skills/api-for-yourself/SKILL.md), [simulate the reorg before announcing it](skills/the-org-simulator/SKILL.md); 1098 skills, 104 bundles. *v64 — game night;* [pm-tabletop](plugins/pm-tabletop) — teach any board game in 5 minutes, settle rules arguments fairly, plan the lineup, design your own game, and [spar the Catan trade](skills/tabletop-negotiator/SKILL.md) against a hidden agenda with a scored debrief; 1098 skills, 104 bundles. *v63.1 — pixel confetti:* [pixel-gif-maker](skills/pixel-gif-maker/SKILL.md) — custom retro Slack GIFs (scroll, pulse, party, sparkle) from a pure-stdlib deterministic encoder; 1098 skills. *And v63.0.0 — the dead mentors:* history's sharpest operators, resurrected as skills — **[Machiavelli](skills/machiavelli-counsel/SKILL.md)** reads your reorg (with the honest counterweight built in), **[Sun Tzu](skills/sun-tzu-strategy-brief/SKILL.md)** decides fight/reshape/decline, **[Franklin's decision algebra](skills/franklin-decision-ledger/SKILL.md)** settles the offer you keep flip-flopping on, **[Marcus Aurelius](skills/stoic-setback-debrief/SKILL.md)** debriefs the day that went badly, and **[Arnold Bennett (1908)](skills/bennett-time-audit/SKILL.md)** finds your inner day — real methods from public-domain classics, chapter-cited, never misquoted. *Earlier — v62.2, the distribution wave* (SkillScan, telemetry, SkillBench v2, quiz, wins, WhatsApp); *v62.1, nine frontiers.* Full history: **[CHANGELOG](CHANGELOG.md)** · [releases](https://github.com/mohitagw15856/pm-claude-skills/releases)
+**v67.0.0 — the everywhere wave:** six new rooms — [the trades](plugins/pm-trades) (quotes, stage payments, apprentices), [the committee](plugins/pm-committee) (AGMs, treasurers, the council mic), [open-source maintainers](plugins/pm-maintainer), [aging parents](plugins/pm-aging-parents) (the talks, the sibling summit), [the kitchen](plugins/pm-kitchen), [the band](plugins/pm-musician) — plus [used-car](skills/used-car-decoder/SKILL.md)/[mechanic-quote](skills/mechanic-quote-decoder/SKILL.md) decoders, the [group-trip fixer](skills/group-trip-negotiator/SKILL.md), and [🌱 daily practice](https://mohitagw15856.github.io/pm-claude-skills/streak.html); 1099 skills, 104 bundles. *v66 — new-gen;* [pm-newgen](plugins/pm-newgen) — [decode your first brand deal](skills/creator-deal-decoder/SKILL.md), [clip the podcast](skills/clip-factory/SKILL.md), [prep tonight's D&D](skills/ttrpg-session-forge/SKILL.md), [fix the dating profile honestly](skills/dating-profile-doctor/SKILL.md), [vibe-check the weekend app](skills/the-vibe-check/SKILL.md), [keep the flat peaceful](skills/roommate-agreement/SKILL.md), [climb ranked on purpose](skills/ranked-climb-coach/SKILL.md), [flip thrift finds](skills/resale-flip-kit/SKILL.md), [plan the micro-retirement](skills/micro-retirement-planner/SKILL.md), [get your attention back](skills/attention-reset/SKILL.md); 1099 skills, 104 bundles. *v65 — pm-2027;* ten skills for problems you don't have yet (but will) — [offboard an AI coworker](skills/agent-severance/SKILL.md), [drill the deepfake wire-fraud call](skills/deepfake-drill/SKILL.md), [hire your agent like an employee](skills/agent-hiring-panel/SKILL.md), [declare context bankruptcy](skills/context-bankruptcy/SKILL.md), [send your position to meetings instead of your body](skills/clone-brief/SKILL.md), [publish your personal API](skills/api-for-yourself/SKILL.md), [simulate the reorg before announcing it](skills/the-org-simulator/SKILL.md); 1099 skills, 104 bundles. *v64 — game night;* [pm-tabletop](plugins/pm-tabletop) — teach any board game in 5 minutes, settle rules arguments fairly, plan the lineup, design your own game, and [spar the Catan trade](skills/tabletop-negotiator/SKILL.md) against a hidden agenda with a scored debrief; 1099 skills, 104 bundles. *v63.1 — pixel confetti:* [pixel-gif-maker](skills/pixel-gif-maker/SKILL.md) — custom retro Slack GIFs (scroll, pulse, party, sparkle) from a pure-stdlib deterministic encoder; 1099 skills. *And v63.0.0 — the dead mentors:* history's sharpest operators, resurrected as skills — **[Machiavelli](skills/machiavelli-counsel/SKILL.md)** reads your reorg (with the honest counterweight built in), **[Sun Tzu](skills/sun-tzu-strategy-brief/SKILL.md)** decides fight/reshape/decline, **[Franklin's decision algebra](skills/franklin-decision-ledger/SKILL.md)** settles the offer you keep flip-flopping on, **[Marcus Aurelius](skills/stoic-setback-debrief/SKILL.md)** debriefs the day that went badly, and **[Arnold Bennett (1908)](skills/bennett-time-audit/SKILL.md)** finds your inner day — real methods from public-domain classics, chapter-cited, never misquoted. *Earlier — v62.2, the distribution wave* (SkillScan, telemetry, SkillBench v2, quiz, wins, WhatsApp); *v62.1, nine frontiers.* Full history: **[CHANGELOG](CHANGELOG.md)** · [releases](https://github.com/mohitagw15856/pm-claude-skills/releases)
 
 ## ❓ First-timer questions, straight answers
 
 <details>
 <summary><b>Is it actually free?</b></summary>
-Yes — MIT, all 1098 skills, forever. The skills are markdown; there is nothing to gate. Sponsors fund the playground's free model runs, not access.
+Yes — MIT, all 1099 skills, forever. The skills are markdown; there is nothing to gate. Sponsors fund the playground's free model runs, not access.
 </details>
 
 <details>
@@ -384,4 +424,4 @@ MIT — use them, fork them, ship them at work. Skills are judgment, and judgmen
 
 ---
 
-*Built by [Mohit](https://github.com/mohitagw15856) with Claude. 1098 skills · 121 bundles · 35 professions · every commit gated. The long version of this README — every feature, wave, and frontier bet — lives in the **[Showcase](docs/SHOWCASE.md)**.*
+*Built by [Mohit](https://github.com/mohitagw15856) with Claude. 1099 skills · 121 bundles · 35 professions · every commit gated. The long version of this README — every feature, wave, and frontier bet — lives in the **[Showcase](docs/SHOWCASE.md)**.*

package/bin/cli.mjs

@@ -377,7 +377,7 @@ Usage:
   npx pm-claude-skills search [query…] [--json] [--limit <n>]
   npx pm-claude-skills install <owner/repo>   # install skills from ANY GitHub repo — security-scanned + SkillSpec-graded
   npx pm-claude-skills prove --skill <dir> --tasks <file>  # A/B-verify a skill: on vs off, real token counts\n  npx pm-claude-skills mcp-audit [--connect]        # your MCP servers are charging you rent - measure it
-  npx pm-claude-skills verify                 # integrity check: detect drift in anything "install" brought in
+  npx pm-claude-skills skillcheck [--dir <path>]    # validate your own SKILL.md files (--strict, --json)\n  npx pm-claude-skills verify                 # integrity check: detect drift in anything "install" brought in
   npx pm-claude-skills chain <workflow>       # run a whole multi-skill pipeline (chain --list to see them)
   npx pm-claude-skills council <skill>        # author -> cross-vendor critique -> arbiter (2+ provider keys)
   npx pm-claude-skills migrate <dir>          # convert a folder of prompts/SOPs into SkillSpec skills
@@ -482,6 +482,14 @@ else if (cmd === 'prove') {
   try { process.exit(await run(process.argv.slice(3))); }
   catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
 }
+else if (cmd === 'skillcheck') {
+  // Validate SKILL.md files against the authoring standard — this repo's own
+  // validator, pointed at anybody's skills directory. It reads process.argv
+  // itself, so hand it the subcommand's arguments.
+  process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
+  const { run } = await import('./skillcheck.mjs');
+  run();
+}
 else if (cmd === 'verify') {
   const { run } = await import('./verify.mjs');
   try { process.exit(await run(process.argv.slice(3))); }

package/bin/skillcheck.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// SkillCheck — validate SKILL.md files against the authoring standard.
+//
+// This is the same validator that keeps 1,099 skills in this repo honest, made
+// to run against anybody's skills directory. Skill authoring is a new enough
+// craft that most of the mistakes are the same handful, and all of them are
+// cheap to catch: a description with no trigger clause, a frontmatter name that
+// does not match its folder, template placeholder text nobody deleted.
+//
+//   npx pm-claude-skills skillcheck                 # ./skills, or wherever it finds them
+//   npx pm-claude-skills skillcheck --dir .claude/skills
+//   npx pm-claude-skills skillcheck --strict        # warnings fail too
+//   npx pm-claude-skills skillcheck --json          # machine-readable
+//   npx pm-claude-skills skillcheck --annotate      # inline GitHub PR annotations
+//
+// No dependencies. Exit code 1 when something failed, which is what makes it
+// usable as a CI gate.
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+const flag = (name, fallback = null) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? fallback : args[i + 1];
+};
+const has = (name) => args.includes(`--${name}`);
+
+const strict = has('strict');
+const asJson = has('json');
+// GitHub sets CI=true; annotating there by default is what most people want,
+// and it is harmless anywhere else because the lines are just text.
+const annotate = has('annotate') || (process.env.GITHUB_ACTIONS === 'true' && !has('no-annotate'));
+
+// --- finding the skills -------------------------------------------------------
+// Layouts differ. Guessing badly is worse than saying what was searched, so if
+// nothing turns up the error lists every place it looked.
+const CANDIDATES = ['skills', '.claude/skills', 'src/skills', '.'];
+
+function findSkillsDir() {
+  const explicit = flag('dir');
+  // An explicit --dir that does not exist is a typo, and the friendly message
+  // below is far more use than a raw ENOENT stack trace out of readdir.
+  if (explicit) return existsSync(resolve(explicit)) ? resolve(explicit) : null;
+  for (const c of CANDIDATES) {
+    const dir = resolve(c);
+    if (!existsSync(dir)) continue;
+    const hit = readdirSync(dir).some(
+      (n) => statSync(join(dir, n)).isDirectory() && existsSync(join(dir, n, 'SKILL.md'))
+    );
+    if (hit) return dir;
+  }
+  return null;
+}
+
+// --- the standard -------------------------------------------------------------
+
+function parseFrontmatter(text) {
+  // Tolerate leading whitespace and CRLF so a file authored on Windows does not
+  // produce a false negative.
+  const m = text.match(/^\s*---\r?\n([\s\S]*?)\r?\n\s*---\r?\n?([\s\S]*)$/);
+  if (!m) return { meta: null, body: text, lines: {} };
+  const meta = {};
+  const lines = {};
+  const head = m[1].split(/\r?\n/);
+  head.forEach((line, i) => {
+    const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (!kv) return;
+    let v = kv[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    meta[kv[1]] = v;
+    lines[kv[1]] = i + 2; // +1 for the opening ---, +1 for 1-indexing
+  });
+  return { meta, body: m[2], lines };
+}
+
+function checkSkill(skillsDir, name) {
+  const errors = [];
+  const warnings = [];
+  const file = join(skillsDir, name, 'SKILL.md');
+  const at = (line, msg) => ({ line, msg });
+
+  if (!existsSync(file)) {
+    errors.push(at(1, 'No SKILL.md in folder.'));
+    return { name, file, errors, warnings };
+  }
+
+  const text = readFileSync(file, 'utf8');
+  const { meta, body, lines } = parseFrontmatter(text);
+
+  if (!meta) {
+    errors.push(at(1, 'Missing or malformed YAML frontmatter (--- name/description ---).'));
+    return { name, file, errors, warnings };
+  }
+
+  if (!meta.name) errors.push(at(1, 'Frontmatter is missing `name`.'));
+  else if (meta.name !== name)
+    errors.push(at(lines.name ?? 1, `Frontmatter name "${meta.name}" does not match folder "${name}".`));
+
+  if (!meta.description) {
+    errors.push(at(1, 'Frontmatter is missing `description`.'));
+  } else {
+    const d = meta.description;
+    const dl = lines.description ?? 1;
+    if (/your-skill-name|one sentence\.|trigger condition|output description/i.test(d))
+      errors.push(at(dl, 'Description still contains template placeholder text.'));
+    // The trigger clause is the single highest-value line in a skill: it is what
+    // a model matches on when deciding whether this skill applies at all.
+    if (!/\buse when\b/i.test(d)) warnings.push(at(dl, 'Description has no "Use when …" trigger clause.'));
+    if (!/\bproduce(s|d)?\b/i.test(d)) warnings.push(at(dl, 'Description does not state what it Produces.'));
+    if (d.length < 40) warnings.push(at(dl, `Description is very short (${d.length} chars).`));
+    if (d.length > 700)
+      warnings.push(at(dl, `Description is very long (${d.length} chars) — trim for the trigger budget.`));
+  }
+
+  const trimmed = body.trim();
+  const bodyLine = text.split(/\r?\n/).findIndex((l, i) => i > 2 && l.trim().startsWith('#')) + 1 || 1;
+
+  if (!/^#\s+.+/m.test(trimmed)) errors.push(at(bodyLine, 'Body has no top-level `# Title` heading.'));
+  if (/\[Instructions for Claude to follow/i.test(trimmed))
+    errors.push(at(bodyLine, 'Body still contains the template stub line.'));
+  if (trimmed.length < 300)
+    warnings.push(at(bodyLine, `Body is very short (${trimmed.length} chars) for a reusable skill.`));
+  if (!/^#{2,3}\s+.*quality check/im.test(trimmed)) warnings.push(at(bodyLine, 'No "Quality Checks" section.'));
+  if (!/^#{2,3}\s+.*anti-?pattern/im.test(trimmed)) warnings.push(at(bodyLine, 'No "Anti-Patterns" section.'));
+
+  return { name, file, errors, warnings };
+}
+
+// --- run ----------------------------------------------------------------------
+
+export function run() {
+  const skillsDir = findSkillsDir();
+
+  if (!skillsDir) {
+    const looked = flag('dir') ? [flag('dir')] : CANDIDATES;
+    const msg =
+      `No skills found. Looked in: ${looked.join(', ')}.\n` +
+      `A skill is a folder containing a SKILL.md. Point at yours with --dir <path>.`;
+    if (asJson) console.log(JSON.stringify({ skills: 0, errors: 1, warnings: 0, message: msg }, null, 2));
+    else console.error(msg);
+    process.exit(1);
+  }
+
+  const names = readdirSync(skillsDir)
+    .filter((n) => {
+      try {
+        return statSync(join(skillsDir, n)).isDirectory() && existsSync(join(skillsDir, n, 'SKILL.md'));
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+
+  const results = names.map((n) => checkSkill(skillsDir, n));
+  const totalErrors = results.reduce((a, r) => a + r.errors.length, 0);
+  const totalWarnings = results.reduce((a, r) => a + r.warnings.length, 0);
+
+  // Inline annotations. The point of an action over a log is that the finding
+  // lands on the line in the PR diff rather than in a build log nobody opens.
+  if (annotate) {
+    for (const r of results) {
+      const path = relative(process.cwd(), r.file);
+      for (const e of r.errors) console.log(`::error file=${path},line=${e.line},title=SkillCheck::${e.msg}`);
+      for (const w of r.warnings)
+        console.log(`::${strict ? 'error' : 'warning'} file=${path},line=${w.line},title=SkillCheck::${w.msg}`);
+    }
+  }
+
+  if (asJson) {
+    console.log(
+      JSON.stringify(
+        {
+          dir: relative(process.cwd(), skillsDir) || '.',
+          skills: names.length,
+          errors: totalErrors,
+          warnings: totalWarnings,
+          results: results.filter((r) => r.errors.length || r.warnings.length),
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    for (const r of results) {
+      for (const e of r.errors) console.log(`  ✖ ${r.name}: ${e.msg}`);
+      for (const w of r.warnings) console.log(`  ⚠ ${r.name}: ${w.msg}`);
+    }
+    console.log(
+      `\nSkillCheck — ${names.length} skill${names.length === 1 ? '' : 's'} in ${relative(process.cwd(), skillsDir) || '.'} · ` +
+        `${totalErrors} error(s) · ${totalWarnings} warning(s)`
+    );
+  }
+
+  // A repo with zero skills that asked to be checked is a misconfiguration, not
+  // a pass. Silently succeeding there is how a broken CI step goes unnoticed.
+  if (names.length === 0) {
+    if (!asJson) console.error(`No SKILL.md folders in ${skillsDir}. Nothing was checked.`);
+    process.exit(1);
+  }
+
+  const failed = totalErrors > 0 || (strict && totalWarnings > 0);
+  if (failed) {
+    if (!asJson) {
+      console.log(strict && totalWarnings && !totalErrors ? 'Failed (--strict: warnings count as errors).' : 'Failed.');
+    }
+    process.exit(1);
+  }
+  if (!asJson) console.log('All skills valid. ✓');
+}
+
+// Only run when invoked directly, so the CLI can import it without side effects.
+if (import.meta.url === `file://${process.argv[1]}`) run();

package/commands/design-review.md

@@ -0,0 +1,27 @@
+---
+description: Workflow recipe — review a design end-to-end, ending in measured numbers rather than adjectives, by chaining 4 skills.
+argument-hint: "[the design: a URL, a Figma link, a screenshot, or a token file — plus who it's for and what it has to do]"
+---
+
+Run the **Design Review** workflow recipe for: $ARGUMENTS
+
+This is a *chain* of skills. Run each stage in order and **carry every stage's output forward as context** for the next. Open with a one-line plan of the 4 stages, then ask once for essential missing inputs (the actual hex values or a URL, the target WCAG level, whether it will ever be printed, who signs off). Don't re-ask between stages.
+
+**Before stage 2, measure.** A design review that assesses contrast by eye is an opinion with a standards reference attached. If you have a URL or hex values, run these first and carry the numbers through every stage:
+
+```bash
+npx --yes notugly spec <url>                        # palette, type scale, radii — what it is made of
+npx --yes notugly onepager <url> --out review.html  # every pairing, with the nearest passing colour
+npx --yes notugly vision <url>                      # colours that merge for colour-blind viewers
+```
+
+Deterministic, zero dependencies, **no model call**. If you only have a screenshot, say so explicitly in the output — an inferred ratio is not a finding.
+
+Run each stage under a clear `## Stage N — <name>` heading:
+
+1. **React honestly** — apply the `design-critique` skill: what the design is trying to do, where it succeeds, and where intent and execution diverge. Do this *before* the measurements so the critique is about the design rather than about its contrast ratios.
+2. **Measure what can be measured** — apply the `accessibility-audit` skill, filling every contrast row from the `notugly` output above rather than assessing it. Flag explicitly which findings are computed and which are judgement.
+3. **Check the system behind it** — apply the `design-system-audit` skill: is this a one-off, or does it reveal a token problem? Run `npx notugly tokens <file>` if a token file exists; it names failing pairs semantically (`color.text.danger on surface.default is 2.99:1`), which turns a vague note into a bug with an owner.
+4. **Hand it over** — apply the `design-handoff-brief` skill: the decisions, the measured values, and the open questions, in the form an engineer can build from.
+
+Close with a **one-page verdict**: the three things to fix before ship, the measured evidence for each, and the split between *find-and-replace* fixes and fixes that need a design decision. That split is the whole reason this recipe exists — "twelve accessibility issues" gets deferred; "nine are a find-and-replace and three need Priya to pick a colour" gets scheduled.

package/exports/README.md

@@ -8,7 +8,7 @@ by hand; edit the source skill and run:
 node scripts/build-exports.mjs
 ```
 
-Currently exporting **1098 skills** to:
+Currently exporting **1099 skills** to:
 
 - **ChatGPT — Custom GPT instructions** → `exports/chatgpt/`
 - **Google Gemini — Gem instructions** → `exports/gemini/`

package/exports/aider/README.md

@@ -3,7 +3,7 @@
 > Auto-generated from `skills/*/SKILL.md` by `scripts/build-exports.mjs`.
 > **Do not edit these files by hand** — edit the source skill and regenerate.
 
-1098 skills exported. Copy a `.md rule` into the tool to use it.
+1099 skills exported. Copy a `.md rule` into the tool to use it.
 
 | Skill | Bundle | Path |
 |---|---|---|
@@ -293,6 +293,7 @@
 | Design Critique | `pm-design` | `pm-design/design-critique/design-critique.md` |
 | Design Handoff Brief | `pm-advanced` | `pm-advanced/design-handoff-brief/design-handoff-brief.md` |
 | Design System Audit | `pm-design` | `pm-design/design-system-audit/design-system-audit.md` |
+| Design System Generate | `pm-design` | `pm-design/design-system-generate/design-system-generate.md` |
 | Desk Ergonomics Audit | `pm-wellbeing` | `pm-wellbeing/desk-ergonomics-audit/desk-ergonomics-audit.md` |
 | Desk Research Sprint | `pm-cowork` | `pm-cowork/desk-research-sprint/desk-research-sprint.md` |
 | Desktop Zero | `pm-cowork` | `pm-cowork/desktop-zero/desktop-zero.md` |

package/exports/aider/pm-advanced/design-handoff-brief/design-handoff-brief.md

@@ -27,6 +27,31 @@ Ask the user for these if not provided:
 6. Write a "not in scope" section to prevent scope creep in design
 7. **Validate** — Confirm every edge case listed is specific enough to design for, and every out-of-scope item is concrete enough to say "no" to
 
+
+## Programmatic Helper
+
+Contrast ratios cannot be eyeballed. The AA line sits at 4.5:1, and `#777777`
+on white is 4.478 (fails) while `#767676` is 4.54 (passes) — no amount of
+looking at a screenshot separates those. Compute them:
+
+```bash
+npx --yes notugly fix "#8ab4f8" "#ffffff"     # ratio, APCA, and the nearest passing colour
+npx --yes notugly onepager <url> --out review.html   # every pairing, printable
+npx --yes notugly vision                      # which colours merge for colour-blind viewers
+```
+
+`notugly fix` returns the ratio, the APCA lightness contrast, and the closest
+colour to the one already chosen that passes — same hue, same chroma. Paste
+those numbers into the tables below rather than estimating them.
+
+Deterministic, zero dependencies, and **no model call** — so it costs nothing to
+run and gives the same answer every time.
+
+Handoff is exactly where contrast gets lost: a designer picks a colour in a tool
+with no contrast checker, and an engineer implements it faithfully. Put the
+measured ratio next to every colour in the handoff table so the number travels
+with the value.
+
 ## Output Structure
 
 ### Design Brief: [Feature Name]

package/exports/aider/pm-design/accessibility-audit/accessibility-audit.md

@@ -11,6 +11,31 @@ Ask the user for these if not provided:
 - **Known assistive technology users?** (Yes/No — if yes, which: screen reader / switch access / voice control / magnification)
 - **Platform** (Web / iOS / Android / Desktop app)
 
+
+## Programmatic Helper
+
+Contrast ratios cannot be eyeballed. The AA line sits at 4.5:1, and `#777777`
+on white is 4.478 (fails) while `#767676` is 4.54 (passes) — no amount of
+looking at a screenshot separates those. Compute them:
+
+```bash
+npx --yes notugly fix "#8ab4f8" "#ffffff"     # ratio, APCA, and the nearest passing colour
+npx --yes notugly onepager <url> --out review.html   # every pairing, printable
+npx --yes notugly vision                      # which colours merge for colour-blind viewers
+```
+
+`notugly fix` returns the ratio, the APCA lightness contrast, and the closest
+colour to the one already chosen that passes — same hue, same chroma. Paste
+those numbers into the tables below rather than estimating them.
+
+Deterministic, zero dependencies, and **no model call** — so it costs nothing to
+run and gives the same answer every time.
+
+**For 1.4.3 Contrast (Minimum) and 1.4.11 Non-text Contrast**, every row in the
+remediation table should carry a measured ratio, not an assessment. If the user
+supplied a screenshot rather than hex values, say so explicitly in the audit —
+an inferred ratio is not an audit finding.
+
 ## Output Structure
 
 ---

package/exports/aider/pm-design/brand-guidelines/brand-guidelines.md

@@ -15,6 +15,29 @@ Ask for (if not already provided):
 - **The artifact and its audience** (apply mode): what's being branded and for whom
 - **The formality of truth**: is there an official guidelines doc this must defer to, or is this creating the de-facto one?
 
+## Programmatic Helper
+
+Extract mode says "the exact hex values, not memory". Reading them off a
+screenshot *is* memory. Read them off the site:
+
+```bash
+npx --yes notugly steal example.com        # palette with usage counts, fonts, radii, shadows
+npx --yes notugly spec example.com         # the same, as a table you can paste in
+npx --yes notugly name "#4f76b6"           # "Hydrangea" — a name a stakeholder can argue with
+```
+
+`steal` parses the real stylesheets and returns each colour with **how many
+times it is used**, which is what separates a brand colour from a one-off in a
+footer. `spec` adds a measured contrast ratio and an inferred role per colour.
+
+For Apply mode, `npx notugly fix "#fg" "#bg"` gives the nearest passing colour
+to the brand's own — same hue, same chroma — which is how you honour rule 3
+below without abandoning the palette.
+
+Deterministic, zero dependencies, **no model call**. It reads the stylesheets a
+browser fetches on first load, so it sees what a browser sees and not what
+JavaScript adds later — a partial sample, honestly labelled.
+
 ## Extract Method
 
 1. **Mine artifacts, not aspirations.** Pull from what the brand actually ships: the exact hex values (from the site's CSS/screenshots, not memory), the real font stack, how much whitespace they genuinely use, how their headlines are actually written. The "About" page says "bold and human"; the evidence says what that means in practice.
@@ -27,7 +50,7 @@ Ask for (if not already provided):
 
 1. **Token-map the artifact first** — inventory its current colors/fonts/spacings, then map each to the kit's equivalent. Wholesale mapping beats spot-fixing (spot-fixing produces the half-branded artifact, which reads worse than unbranded).
 2. **Apply voice, not just paint** — retitle headings in the brand's headline pattern, sweep for banned phrases, adjust register. A perfectly-colored deck in the wrong voice still feels off-brand.
-3. **Respect the hierarchy of the artifact** — branding never overrides legibility: contrast checks still bind, dense tables stay functional; the brand's job is recognition, not decoration.
+3. **Respect the hierarchy of the artifact** — branding never overrides legibility: contrast checks still bind (measure them — `npx notugly fix` returns the nearest passing colour in the same hue rather than making you abandon the brand colour), dense tables stay functional; the brand's job is recognition, not decoration.
 4. **Note conformance honestly** — what was applied, what couldn't be (font unavailable → declared substitute), what needs a human/designer call.
 
 ## Output Format

package/exports/aider/pm-design/design-system-audit/design-system-audit.md

@@ -13,6 +13,42 @@ Ask the user for these if not provided:
 - **Governance model** — centralised team / federated contributors / no dedicated team?
 - **Goal of the audit** — improve adoption / prepare for a rebrand / onboard new teams / justify investment?
 
+
+## Programmatic Helper
+
+Contrast ratios cannot be eyeballed. The AA line sits at 4.5:1, and `#777777`
+on white is 4.478 (fails) while `#767676` is 4.54 (passes) — no amount of
+looking at a screenshot separates those. Compute them:
+
+```bash
+npx --yes notugly fix "#8ab4f8" "#ffffff"     # ratio, APCA, and the nearest passing colour
+npx --yes notugly onepager <url> --out review.html   # every pairing, printable
+npx --yes notugly vision                      # which colours merge for colour-blind viewers
+```
+
+`notugly fix` returns the ratio, the APCA lightness contrast, and the closest
+colour to the one already chosen that passes — same hue, same chroma. Paste
+those numbers into the tables below rather than estimating them.
+
+Deterministic, zero dependencies, and **no model call** — so it costs nothing to
+run and gives the same answer every time.
+
+**For the token consistency and accessibility sections**, point it at the token
+file directly:
+
+```bash
+npx --yes notugly tokens tokens.json    # W3C design tokens or a Figma variables export
+```
+
+That names the failing pairs semantically — `color.text.danger on
+surface.default is 2.99:1 — needs 4.5` — which is a bug with an owner, rather
+than a general note about contrast. It also flags one colour defined under
+several token names, which is the usual sign a system grew by copy-paste.
+
+For drift over time, `npx notugly watch <url> baseline.json` distinguishes "a
+new colour" from "a colour 0.003 away from one that already existed, because
+somebody could not find the token".
+
 ## Output Structure
 
 ---