Skip to content

An agent organization structured as a company — 15+ departments, 125+ skills, each independently installable, citing the standards and regulators that settle the question. Runs in Claude Code and ChatGPT.

Use cases, social card generator, 15 skills, and D25 (#8)

Chris Brock42b4a27b8306
diff --git a/README.md b/README.md
index 6eea55a..1ce0a16 100644
--- a/README.md
+++ b/README.md
@@ -5,13 +5,13 @@
<p align="center">
<a href="https://claude.com/claude-code"><img alt="Built for Claude Code" src="https://img.shields.io/badge/built%20for-Claude%20Code-D97757?style=flat-square"></a>
<img alt="14 departments" src="https://img.shields.io/badge/departments-14-3F4B5B?style=flat-square">
- <img alt="101 skills" src="https://img.shields.io/badge/skills-101-3F4B5B?style=flat-square">
+ <img alt="116 skills" src="https://img.shields.io/badge/skills-116-3F4B5B?style=flat-square">
<a href="LICENSE"><img alt="MIT licensed" src="https://img.shields.io/badge/license-MIT-3F4B5B?style=flat-square"></a>
<a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-2EA043?style=flat-square"></a>
</p>
An agent organization for [Claude Code](https://claude.com/claude-code), structured as a company:
-a chief executive over 14 departments, 101 skills in total.
+a chief executive over 14 departments, 116 skills in total.
Every department is an independently installable plugin, so a project loads only the functions it
needs rather than all of them at once.
@@ -40,6 +40,11 @@ right specialist engages:
Invoke one directly by name when you want a specific lens: `/finance:financial-modeling`.
+Seven situations that cross departments — a SOC 2 demand from an enterprise prospect, a
+security incident, a stalled funnel — are worked through end to end in
+[docs/USE-CASES.md](docs/USE-CASES.md), including where a reviewer-class department stops the
+work rather than adding an opinion.
+
Each department also ships an agent charter in `.claude/agents/`, so a department can be delegated
to as a subagent with its own exclusive write surface.
@@ -171,25 +176,35 @@ to as a subagent with its own exclusive write surface.
</details>
<details>
-<summary><b>Finance</b> (CFO) — 4 skills</summary>
+<summary><b>Finance</b> (CFO) — 9 skills</summary>
| Skill | What it does |
|---|---|
| `budgeting-and-forecasting` | Runs the planning cycle — annual budget, rolling forecast, consolidation of business unit inputs, and the variance analysis that explains actuals against plan. |
+| `capital-allocation` | Evaluates where to spend limited capital — investment appraisal, hurdle rates, payback, and comparing proposals that are not alike. |
| `chief-financial-officer` | Owns the financial position: planning, budgeting, forecasting, unit economics, cash, and the numbers the business is run and reported on. |
| `financial-modeling` | Builds and stress-tests financial models for forecasting, scenario planning, and decision support — revenue build, cost structure, driver logic, and the sensitiviti…. |
+| `financial-reporting-and-close` | Runs the period-end close and produces reporting — close calendar, reconciliations, accruals, variance analysis, and reporting that gets read. |
+| `internal-controls-and-audit` | Designs and tests controls over financial reporting — segregation of duties, approval limits, evidence, and preparing for audit. |
+| `revenue-recognition` | Determines when and how revenue is recognised — performance obligations, contract terms that change the answer, and the deal structures that create accounting probl…. |
+| `treasury-and-liquidity` | Manages cash and liquidity — cash forecasting, runway, working capital, banking structure, and currency and counterparty exposure. |
| `unit-economics` | Establishes whether the business makes money on each customer or unit — contribution margin, acquisition cost, payback period, lifetime value, and the cohort behavi…. |
</details>
<details>
-<summary><b>Operations</b> (COO) — 4 skills</summary>
+<summary><b>Operations</b> (COO) — 9 skills</summary>
| Skill | What it does |
|---|---|
+| `business-continuity-and-resilience` | Plans for operating through disruption — impact analysis, recovery objectives, continuity plans, and the exercises that prove they work. |
+| `capacity-and-demand-planning` | Matches operational capacity to expected demand — forecasting load, sizing teams and systems, managing queues, and deciding when to add capacity. |
| `chief-operating-officer` | Owns execution: how work actually gets done across the organization, including process, program management, capacity, vendors, supply chain, and service delivery. |
| `process-design` | Designs, documents, and fixes operational processes — mapping the current state, finding where work actually stalls, redesigning the flow, and building controls tha…. |
| `program-management` | Plans and drives cross-functional programs to delivery — scope, sequencing, dependencies, status, risk, and the escalations that keep work moving. |
+| `quality-management` | Builds quality into operations — defining standards, catching defects at the right point, root cause analysis, and continuous improvement. |
+| `service-level-management` | Defines and manages service levels — setting targets that reflect what customers need, measuring honestly, and handling breaches. |
+| `supply-chain-and-logistics` | Manages the flow of goods and inputs — sourcing, inventory, lead times, fulfilment, and supply risk. |
| `vendor-management` | Selects, contracts, and manages suppliers and vendors — requirements, evaluation, negotiation support, onboarding, performance management, and exit. |
</details>
@@ -234,14 +249,19 @@ to as a subagent with its own exclusive write surface.
</details>
<details>
-<summary><b>People</b> (CHRO) — 4 skills</summary>
+<summary><b>People</b> (CHRO) — 9 skills</summary>
| Skill | What it does |
|---|---|
| `chief-human-resources-officer` | Owns the organization itself: org design, hiring, performance, compensation, development, culture, and employee relations. |
| `compensation-and-leveling` | Builds and maintains the leveling framework and pay structure — level definitions, salary bands, benchmarking, pay equity, and how raises and promotions are decided. |
+| `employee-relations` | Handles the difficult human situations — grievances, complaints, investigations, conflict, and separations conducted properly. |
| `hiring-and-interviewing` | Designs and runs hiring — role definition, sourcing, interview loop design, structured evaluation, and the decision itself. |
+| `learning-and-development` | Builds capability — skills gaps, career frameworks, training that transfers to the job, and internal mobility. |
+| `onboarding-and-offboarding` | Designs the joining and leaving experience — first-day readiness, ramp to productivity, knowledge capture, and clean exits. |
| `org-design` | Designs how an organization is structured — reporting lines, team boundaries, spans and layers, role definition, and workforce planning against the strategy. |
+| `performance-management` | Runs performance systems that change behaviour — expectations, feedback, review cycles, calibration, and handling underperformance. |
+| `workforce-planning` | Plans the shape and size of the workforce — demand for roles, build-versus-buy, attrition, and sequencing hiring against budget. |
</details>
@@ -271,6 +291,7 @@ plugins/<department>/
.claude/agents/<id>.md one charter per department
docs/AGENT-SURFACES.md every path has exactly one owner, enforced in CI
docs/DECISION-LOG.md numbered decisions with options and recommendations
+docs/USE-CASES.md situations worked end to end across departments
```
Agents split by **exclusive write surface**, not by topic — a topic split has no checkable
@@ -283,8 +304,10 @@ boundary, and two agents working on "SEO" and "UI" both end up in the same file.
./scripts/check-all.sh
```
-Verifies the surface map is coherent, every skill's frontmatter is valid and unique, no third-party
-licence text has appeared, and every manifest parses. CI runs the same script.
+Verifies the surface map is coherent, every skill's frontmatter is valid and unique, no
+third-party licence text has appeared, the generated README and social card are current, every
+`department:skill` reference in the docs resolves, and every manifest parses. CI runs the same
+script, so local and CI cannot drift.
A new department needs its roster row in `docs/AGENT-SURFACES.md`, a surface block, a charter in
`.claude/agents/`, and an entry in `.claude-plugin/marketplace.json` — all in the same change, or
diff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.md
index 0f57cda..fbd7ee2 100644
--- a/docs/DECISION-LOG.md
+++ b/docs/DECISION-LOG.md
@@ -702,3 +702,42 @@ not zero.
that gets used. Any one of those makes the ask legible. **Revisit sooner** if the D7/D8 vertical
variants become a commercial product — that is a different question (pricing, not donations) and
deserves its own entry rather than a sponsor button.
+
+---
+
+## D25. Whether to register a domain for the About field — ✅ Resolved
+
+GitHub's About panel has a Website field. The available domains were `headcount.biz`,
+`headcount.info` and similar — the short, conventional ones are gone.
+
+- (a) Register a cheap available TLD (`.biz`, `.info`) and link it now.
+- **(b) Leave the Website field empty; revisit when there is something to point at.** ←
+ **chosen**
+- (c) Register `headcount.dev` if free and hold it unused against later need.
+- (d) Point the Website field at a GitHub Pages site built from this repository.
+
+**Resolution: (b), with (c) as a cheap optional hedge.**
+
+- **`.biz` and `.info` are negative signals to this audience.** They are the TLDs of parked
+ pages and expired-domain farms. Someone deciding whether to install 101 skills into their
+ agent is making a trust judgement, and that domain in the About field reads worse than a blank
+ field. A rare case where the cheap option is worse than nothing rather than merely weaker.
+- **A domain does not serve this product yet.** Installation is `/plugin marketplace add
+ cbrock84/headcount`, typed inside Claude Code. Discovery runs through repository topics, the
+ plugin ecosystem, and word of mouth — none of which route through a domain. Nobody searches
+ the web for "headcount" and finds an agent marketplace; they find HR software.
+- **A link has to point at something.** A redirect to the repository adds a hop for no gain, and
+ a parked domain is a worse signal than an empty field. (d) has the same problem until there is
+ documentation that does not fit in the README.
+
+**The part worth keeping.** That the short TLDs are gone is *evidence for the collision caveat
+already recorded in D22*, discovered by accident. `headcount` is a common noun in HR software,
+and the domain market is confirming how crowded that space is. The name remains right for a
+repository, where the namespace is `cbrock84/headcount` and collision costs nothing — but **do
+not build an identity that depends on owning the word.** Accepting a degraded TLD would be
+exactly that mistake in miniature.
+
+**Revisit when** the D7/D8 vertical variants become something distributed or sold. That is a real
+product with a reason for a hub, and it is the same moment the trademark question in D22 needs a
+proper answer rather than a caveat. Prefer `.dev` then — correct signal for developer tooling and
+HTTPS-only — or a modified name over a degraded TLD.
diff --git a/docs/USE-CASES.md b/docs/USE-CASES.md
new file mode 100644
index 0000000..352ee48
--- /dev/null
+++ b/docs/USE-CASES.md
@@ -0,0 +1,148 @@
+# Use cases
+
+A collection of skills answers a question. An organization answers a *situation* — several
+functions engaging in order, with someone able to say no.
+
+These are the situations this catalogue is shaped around. Every skill named here exists; a check
+in CI fails if a reference stops resolving, so this page cannot rot as skills are renamed or
+consolidated.
+
+## Single asks
+
+The fastest path is to just ask. Skills load themselves when a request matches.
+
+| You ask | What loads |
+|---|---|
+| "why isn't this landing page converting?" | `demand-generation:landing-page-cro-expert` |
+| "can we afford this hire?" | `finance:unit-economics` |
+| "review this design before we build it" | `security:threat-modeling` |
+| "our growth has stalled" | `executive:business-growth-consultant` |
+| "is this contract term normal?" | `legal-risk:contract-review` |
+| "how should we level this role?" | `people:compensation-and-leveling` |
+| "what does the support queue tell us?" | `customer-experience:voice-of-customer` |
+| "our data model is a mess" | `data-analytics:data-modeling` |
+
+To force a specific lens, invoke by name: `/finance:financial-modeling`.
+
+---
+
+## Situations that cross departments
+
+Each of these is one prompt, not seven. The point is what engages, in what order, and where it
+stops.
+
+### An enterprise prospect demands SOC 2
+
+The deal is real, the certification is not, and sales wants a date.
+
+1. `revenue:chief-revenue-officer` — what the deal is worth and what is genuinely blocked by it
+2. `security:security-architecture-review` — the posture you actually have, not the one on the website
+3. `security:access-and-identity` — least privilege and joiner-mover-leaver, the controls audits fail on most
+4. `legal-risk:privacy-and-data-protection` — the data processing agreement and subprocessor chain
+5. `operations:process-design` — evidence collection has to be repeatable, or year two is a fire drill
+6. `finance:budgeting-and-forecasting` — auditor, tooling and the engineering time nobody costed
+
+**Where it stops.** `security` is reviewer-class. A finding that the access model can't support the
+control isn't a trade-off revenue gets to price against the deal — the date moves, or the control
+gets built.
+
+### You've had a security incident
+
+The clock started before you knew.
+
+1. `security:incident-response` — contain first, scope second
+2. `legal-risk:privacy-and-data-protection` — which notification clocks are running, and from when
+3. `customer-experience:escalation-management` — what affected customers are told, and by whom
+4. `marketing:public-relations` — the external statement, if there is one
+5. `executive:chief-executive` — who decides, and what is disclosed
+
+**Where it stops.** Communications cannot outrun the legal position. `legal-risk` sets the
+notification obligation; PR writes inside it, never ahead of it.
+
+### Should we build this?
+
+Everyone has an opinion and nobody has the number.
+
+1. `product:chief-product-officer` — what problem, for whom, and how you'd know it worked
+2. `data-analytics:business-intelligence` — whether the evidence exists or is being asserted
+3. `finance:unit-economics` — what it costs to serve once it is real
+4. `corporate-strategy:portfolio-strategy` — whether it fits the bets already placed
+5. `security:threat-modeling` — before it is built, while changing the design is still cheap
+6. `technology:implementation-planning` — what it actually takes
+
+**Where it stops.** Threat modelling after the build is archaeology. It sits at step five
+deliberately.
+
+### Growth has stalled
+
+Everyone is proposing a tactic. Nobody has agreed on the diagnosis.
+
+1. `executive:business-growth-consultant` — diagnosis before remedy
+2. `data-analytics:business-intelligence` — where the funnel actually leaks
+3. `revenue:activation` and `revenue:retention` — whether it is a top or a bottom problem
+4. `customer-experience:voice-of-customer` — what the people who stayed and left actually said
+5. `demand-generation:experimentation` — how you'd test the fix rather than argue about it
+6. `marketing:positioning-and-messaging` — if the leak is that nobody understands the product
+
+**Why the order.** Reaching for `demand-generation:paid-advertising` first is the common failure:
+buying traffic for a funnel that leaks makes the leak more expensive.
+
+### Hiring your first real team
+
+Ten offers will encode a structure you will live with for years.
+
+1. `people:org-design` — the shape before the headcount
+2. `people:compensation-and-leveling` — bands and levels, before the first offer sets a precedent
+3. `finance:budgeting-and-forecasting` — fully loaded cost against runway
+4. `people:hiring-and-interviewing` — a process that survives volume
+5. `legal-risk:contract-review` — offer letters, IP assignment, classification
+
+**Worth stating plainly.** Employment classification, compensation regulation and equity structuring
+are legal and tax matters. These skills structure the decision and tell you what to ask; they are
+not a substitute for qualified counsel.
+
+### An enterprise contract lands on your desk
+
+Signed as-is, it is a promise engineering has not seen.
+
+1. `legal-risk:contract-review` — what is unusual, and what is expensive
+2. `security:security-architecture-review` — the security addendum, against what you actually run
+3. `revenue:pricing-and-packaging` — what the concessions do to the model
+4. `finance:unit-economics` — whether the committed SLAs can be served profitably
+5. `operations:vendor-management` — obligations that flow down to your subprocessors
+
+**Where it stops.** `legal-risk` is reviewer-class. An uncapped indemnity is not a commercial
+preference to be overridden by the revenue number attached to it.
+
+### Preparing for diligence
+
+A buyer's checklist reads your company back to you.
+
+1. `corporate-strategy:mergers-and-acquisitions` — what the process demands and in what order
+2. `finance:financial-modeling` — numbers that survive a stranger's questions
+3. `legal-risk:corporate-governance` — cap table, board minutes, consents
+4. `security:vulnerability-management` — the open findings you will be asked about
+5. `data-analytics:data-governance` — what data you hold, under what basis
+6. `technology:code-review` — what a technical reviewer will find first
+
+---
+
+## How the org behaves
+
+**Reviewer-class departments** (`security`, `legal-risk`) report to the chief executive rather than
+into the functions they review, and their blocking findings are not overrulable by the department
+under review. That is why they appear as a stop in the situations above rather than as another
+opinion.
+
+**Departments install independently.** Nothing above requires the whole organization. Take the
+three departments a situation touches:
+
+```
+/plugin install security@headcount
+/plugin install legal-risk@headcount
+/plugin install revenue@headcount
+```
+
+**Delegate a whole department.** Each ships an agent charter in `.claude/agents/`, so a department
+can be handed work as a subagent with its own exclusive write surface — see
+`executive:agent-hierarchy` for the method and why surfaces, not topics, are the split.
diff --git a/docs/assets/social-card.html b/docs/assets/social-card.html
new file mode 100644
index 0000000..0d417c2
--- /dev/null
+++ b/docs/assets/social-card.html
@@ -0,0 +1,120 @@
+<meta charset="utf-8">
+<!-- GENERATED by scripts/build-social-card.py — edit that, not this file. -->
+<style>
+ /* Fixed 1280x640 canvas. Every block is absolutely positioned: on a canvas of known size
+ that is deterministic, where flex sizing silently failed to place the footer row. */
+ * { margin:0; padding:0; box-sizing:border-box; }
+ html,body { width:1280px; height:640px; overflow:hidden; }
+ body {
+ background:#0B0E14;
+ font-family:"Liberation Sans","Helvetica Neue",Arial,sans-serif;
+ color:#E6EDF3; position:relative;
+ }
+ .grid {
+ position:absolute; inset:0;
+ background-image:
+ linear-gradient(rgba(255,255,255,.03) 1px, transparent 1px),
+ linear-gradient(90deg, rgba(255,255,255,.03) 1px, transparent 1px);
+ background-size:40px 40px;
+ }
+ .glow {
+ position:absolute; width:820px; height:820px; right:-260px; top:-260px; border-radius:50%;
+ background:radial-gradient(circle, rgba(217,119,87,.17) 0%, rgba(217,119,87,0) 65%);
+ }
+ .bar {
+ position:absolute; left:0; top:0; width:8px; height:100%;
+ background:linear-gradient(180deg,#D97757 0%,#C2663F 46%,#33404F 100%);
+ }
+ .eyebrow {
+ position:absolute; left:80px; top:62px;
+ font-family:"DejaVu Sans Mono",monospace;
+ font-size:20px; letter-spacing:.14em; color:#69768A; text-transform:uppercase;
+ }
+ h1 {
+ position:absolute; left:76px; top:96px;
+ font-size:122px; font-weight:700; letter-spacing:-.048em; line-height:1; color:#fff;
+ }
+ .tagline {
+ position:absolute; left:80px; top:246px;
+ font-size:36px; color:#9FB0C3; letter-spacing:-.014em;
+ }
+ .chip {
+ position:absolute; left:80px; top:318px;
+ background:#151A22; border:1px solid #283040; border-radius:12px; padding:18px 26px;
+ font-family:"DejaVu Sans Mono",monospace; font-size:26px; color:#B7C4D2;
+ }
+ .chip .at { color:#D97757; font-weight:700; }
+ .rule {
+ position:absolute; left:80px; top:498px; width:604px; height:1px;
+ background:linear-gradient(90deg,#2A3341 0%, rgba(42,51,65,0) 100%);
+ }
+ .meta {
+ position:absolute; left:80px; top:534px;
+ font-size:20px; letter-spacing:.12em; text-transform:uppercase; color:#7D8B9C;
+ white-space:nowrap;
+ }
+ .meta b { color:#E6EDF3; font-weight:700; }
+ .meta .sep { color:#3D4756; padding:0 13px; }
+ .chart { position:absolute; right:96px; top:150px; }
+</style>
+
+<div class="grid"></div>
+<div class="glow"></div>
+<div class="bar"></div>
+
+<div class="eyebrow">cbrock84 / headcount</div>
+<h1>headcount</h1>
+<div class="tagline">Add a department, not a prompt.</div>
+<div class="chip">/plugin install security<span class="at">@headcount</span></div>
+
+<div class="rule"></div>
+<div class="meta">
+ <b>14</b> departments <span class="sep">/</span>
+ <b>116</b> skills <span class="sep">/</span>
+ MIT <span class="sep">/</span> for Claude Code
+</div>
+
+<!-- The chart is the organization's actual shape: one chief executive, departments beneath, and
+ the reviewer-class departments (accent outline) hanging off a spine that runs from the top,
+ because they report to the chief executive rather than into the function they oversee. -->
+<div class="chart">
+<svg width="342" height="342" viewBox="0 0 342 342" fill="none">
+ <g stroke="#3A4553" stroke-width="2">
+ <path d="M171 70 L171 104"/>
+ <path d="M48 104 L294 104"/>
+ <path d="M48 104 L48 136"/><path d="M122 104 L122 136"/>
+ <path d="M220 104 L220 136"/><path d="M294 104 L294 136"/>
+ <path d="M171 104 L171 228"/>
+ <path d="M72 228 L270 228"/>
+ <path d="M72 228 L72 258"/><path d="M171 228 L171 258"/>
+ <path d="M270 228 L270 258"/>
+ </g>
+ <rect x="117" y="24" width="108" height="46" rx="10" fill="#D97757"/>
+ <g fill="#31251F">
+ <rect x="137" y="40" width="46" height="5" rx="2.5"/>
+ <rect x="137" y="52" width="30" height="5" rx="2.5"/>
+ </g>
+ <g fill="#1A2029" stroke="#3A4553" stroke-width="2">
+ <rect x="18" y="136" width="60" height="60" rx="9"/>
+ <rect x="92" y="136" width="60" height="60" rx="9"/>
+ <rect x="190" y="136" width="60" height="60" rx="9"/>
+ <rect x="264" y="136" width="60" height="60" rx="9"/>
+ <rect x="141" y="258" width="60" height="54" rx="9"/>
+ </g>
+ <g fill="#1A2029" stroke="#D97757" stroke-width="2">
+ <rect x="42" y="258" width="60" height="54" rx="9"/>
+ <rect x="240" y="258" width="60" height="54" rx="9"/>
+ </g>
+ <g fill="#3A4553">
+ <rect x="30" y="152" width="36" height="5" rx="2.5"/><rect x="30" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="104" y="152" width="36" height="5" rx="2.5"/><rect x="104" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="202" y="152" width="36" height="5" rx="2.5"/><rect x="202" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="276" y="152" width="36" height="5" rx="2.5"/><rect x="276" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="153" y="274" width="36" height="5" rx="2.5"/><rect x="153" y="286" width="24" height="5" rx="2.5"/>
+ </g>
+ <g fill="#8A5039">
+ <rect x="54" y="274" width="36" height="5" rx="2.5"/><rect x="54" y="286" width="24" height="5" rx="2.5"/>
+ <rect x="252" y="274" width="36" height="5" rx="2.5"/><rect x="252" y="286" width="24" height="5" rx="2.5"/>
+ </g>
+</svg>
+</div>
diff --git a/docs/assets/social-preview.png b/docs/assets/social-preview.png
new file mode 100644
index 0000000..ce6b299
Binary files /dev/null and b/docs/assets/social-preview.png differ
diff --git a/docs/org-chart.md b/docs/org-chart.md
index cb88e06..a658dbb 100644
--- a/docs/org-chart.md
+++ b/docs/org-chart.md
@@ -35,15 +35,15 @@ than into the function they oversee.
| `marketing` | Marketing | CMO | 17 |
| `demand-generation` | Demand Generation | CMO | 11 |
| `revenue` | Revenue | CRO | 8 |
-| `finance` | Finance | CFO | 4 |
-| `operations` | Operations | COO | 4 |
+| `finance` | Finance | CFO | 9 |
+| `operations` | Operations | COO | 9 |
| `customer-experience` | Customer Experience | CCO | 5 |
| `data-analytics` | Data & Analytics | CDO | 5 |
| `corporate-strategy` | Corporate Strategy | CSO | 5 |
-| `people` | People | CHRO | 4 |
+| `people` | People | CHRO | 9 |
| `legal-risk` | Legal & Risk | CLO / CCO | 5 · reviewer-class |
-14 departments, 101 skills.
+14 departments, 116 skills.
<!-- END GENERATED: departments -->
## Remaining gaps
diff --git a/plugins/finance/skills/capital-allocation/SKILL.md b/plugins/finance/skills/capital-allocation/SKILL.md
new file mode 100644
index 0000000..5ee3db5
--- /dev/null
+++ b/plugins/finance/skills/capital-allocation/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: capital-allocation
+description: Evaluates where to spend limited capital — investment appraisal, hurdle rates, payback, and comparing proposals that are not alike. Use this to evaluate an investment or major purchase, compare competing funding requests, set a hurdle rate, decide between building and buying, or review whether past investments delivered what was claimed.
+---
+
+# Capital allocation
+
+Choosing among investments is choosing what not to do. This is the appraisal of individual
+proposals; which businesses and bets the company should be in belongs to
+`corporate-strategy:portfolio-strategy`.
+
+## Appraise on incremental cash
+
+Only cash flows that change because of the decision belong in the analysis:
+
+- **Sunk costs are irrelevant.** Money already spent is not a reason to continue, though it is
+ reliably presented as one.
+- **Allocated overhead is usually irrelevant.** If the cost occurs anyway, it does not belong in the
+ incremental case.
+- **Opportunity cost is relevant**, including the capacity consumed that then cannot serve anything
+ else.
+- **Working capital is a real outflow.** Growth that consumes cash is not free because it is growth.
+
+Discount for time and risk. A hurdle rate should reflect the risk of the specific proposal — applying
+one company-wide rate systematically overfunds risky projects and starves safe ones.
+
+## Read payback for what it tells you
+
+Payback ignores everything after the threshold and so is a poor ranking tool. It is a good *liquidity
+and uncertainty* measure: how long capital is at risk, and how far into an uncertain future the case
+depends on.
+
+Use net present value to decide, payback to understand exposure. A proposal with strong NPV whose
+returns all arrive in years four and five is a forecasting question as much as an investment one.
+
+## Interrogate the case, not the sponsor
+
+Every proposal arrives advocated for. The useful questions are structural:
+
+- What has to be true for this to work, and which of those is least certain?
+- What is the counterfactual — what happens if we do nothing?
+- Where is the optionality: can it be staged so a small commitment buys information before the large
+ one?
+- Who is accountable for the benefit after approval?
+
+Stage-gating dominates all-or-nothing commitment where uncertainty is high. Paying for information
+first is usually cheaper than being right by luck.
+
+## Look back, or the numbers stay fictional
+
+Compare realised outcomes against the approved case, and make it routine rather than punitive. Where
+nobody looks back, forecasts drift optimistic because optimism is rewarded at approval and never
+tested afterwards.
+
+## Never
+
+- Include sunk cost in a forward case.
+- Apply one hurdle rate to proposals of different risk.
+- Rank by payback.
+- Approve a benefit with no owner after approval.
diff --git a/plugins/finance/skills/financial-reporting-and-close/SKILL.md b/plugins/finance/skills/financial-reporting-and-close/SKILL.md
new file mode 100644
index 0000000..ac38cc5
--- /dev/null
+++ b/plugins/finance/skills/financial-reporting-and-close/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: financial-reporting-and-close
+description: Runs the period-end close and produces reporting — close calendar, reconciliations, accruals, variance analysis, and reporting that gets read. Use this to shorten or stabilise a monthly close, design a close checklist, investigate a variance, structure management reporting, or work out why the numbers keep changing after close.
+---
+
+# Financial reporting and close
+
+A close is a manufacturing process whose output is a number people will make decisions on. Treat it
+as a process — sequence, dependencies, quality control — and it gets faster and more accurate
+together, which sounds contradictory only if you think speed comes from cutting checks.
+
+## Design the close as a critical path
+
+Map every task with its owner, its dependencies and its duration. Most closes are slow because
+independent work is running in series out of habit, not because any step is long.
+
+Move work out of the close window wherever it does not depend on period-end: reconcile subledgers
+continuously, book recurring accruals from a schedule, prepare consolidation structure in advance.
+Anything you can do on day minus three is a day you are not doing on day two.
+
+Set a **hard cutoff** and hold it. A close that stays open for late entries never finishes and
+teaches everyone that deadlines are advisory.
+
+## Reconciliations are the control
+
+Every balance sheet account gets an owner and a reconciliation. The reconciliation is not the
+schedule — it is the explanation of the difference and what will clear it.
+
+Watch aged reconciling items specifically. An unexplained item that has survived three closes is not
+a timing difference; it is an error that has been carried forward by people assuming someone else
+understood it.
+
+## Accruals and the honesty of estimates
+
+Accrue on the best available evidence and document the basis. The basis matters more than the number,
+because next period someone has to decide whether it still holds.
+
+Track how estimates resolve against actuals. Consistent bias in one direction is information about
+the estimator or the process, and it is invisible unless someone looks.
+
+## Reporting that gets read
+
+Explain variance against a stated expectation — budget, prior period, or forecast — and say which.
+A variance without a baseline is a number.
+
+Lead with the two or three things that changed and why, then supporting detail. A report that
+requires the reader to find the story does not get read, and its absence of readership is discovered
+during a crisis.
+
+Separate **timing** from **run-rate**. A miss caused by something slipping a week is a different
+business fact from a miss caused by demand falling, and conflating them produces the wrong reaction.
+
+## Never
+
+- Leave the ledger open for late entries after the stated cutoff.
+- Carry an unexplained reconciling item forward a second time.
+- Present a variance without saying what it is a variance from.
+- Report a number you cannot trace to a reconciliation.
diff --git a/plugins/finance/skills/internal-controls-and-audit/SKILL.md b/plugins/finance/skills/internal-controls-and-audit/SKILL.md
new file mode 100644
index 0000000..76394cb
--- /dev/null
+++ b/plugins/finance/skills/internal-controls-and-audit/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: internal-controls-and-audit
+description: Designs and tests controls over financial reporting — segregation of duties, approval limits, evidence, and preparing for audit. Use this to design controls for a process, prepare for an external audit, respond to an audit finding, set approval thresholds, or assess where a small team's segregation of duties is genuinely broken.
+---
+
+# Internal controls and audit
+
+Controls exist because a single person who can initiate, approve and record a transaction can also
+conceal one. Everything else is elaboration on that.
+
+**This structures control design and audit readiness. Statutory audit requirements, and regimes such
+as SOX where they apply, are matters for your auditors and qualified advisers.**
+
+## Segregation of duties
+
+Four capabilities should not sit with one person: **initiating** a transaction, **approving** it,
+**recording** it, and **holding the asset**. Any two combined is a risk; three is an unmonitored
+opportunity.
+
+Small teams cannot always separate these. That is a normal constraint and pretending otherwise
+produces a fictional control matrix. Where separation is impossible, compensate visibly:
+
+- Review by someone outside the process, on a defined cadence rather than when convenient.
+- Exception reporting that goes to someone who is not the preparer.
+- Bank confirmations and reconciliations reviewed independently of whoever performs them.
+
+Document the gap and the compensating control. An acknowledged, mitigated gap is a defensible
+position; an unacknowledged one is a finding waiting to be written.
+
+## Design controls that leave evidence
+
+A control that happened but left no trace did not happen, as far as an auditor can determine. Each
+control needs a stated owner, frequency, what is examined, and an artefact produced as a by-product
+of doing the work — not assembled afterwards for the audit.
+
+Prefer **preventive** controls, which stop the transaction, over **detective** ones, which find it
+afterwards. Prefer automated over manual: system-enforced approval limits do not have busy weeks.
+
+## Approval thresholds
+
+Set limits by value and by risk, not value alone. A low-value payment to a new supplier deserves more
+scrutiny than a large one to an established counterparty on contracted terms.
+
+Watch for splitting — transactions repeatedly landing just under a threshold is the pattern the
+threshold creates, and it is straightforward to monitor for.
+
+## Audit findings
+
+Treat a finding as information. Fix the cause rather than the instance, and be sceptical of
+remediation that consists of more careful behaviour: the same conditions will reproduce the finding
+with different people.
+
+Related but distinct: `legal-risk:corporate-governance` owns board and entity governance,
+`legal-risk:enterprise-risk` owns the risk framework. This skill owns controls over financial
+reporting.
+
+## Never
+
+- Sign a control matrix that describes separation the team does not actually have.
+- Accept a control with no evidence produced in the ordinary course of performing it.
+- Remediate a finding with a commitment to be more careful.
+- Set approval limits on value alone and not monitor for splitting.
diff --git a/plugins/finance/skills/revenue-recognition/SKILL.md b/plugins/finance/skills/revenue-recognition/SKILL.md
new file mode 100644
index 0000000..c190908
--- /dev/null
+++ b/plugins/finance/skills/revenue-recognition/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: revenue-recognition
+description: Determines when and how revenue is recognised — performance obligations, contract terms that change the answer, and the deal structures that create accounting problems. Use this to work out how a contract should be recognised, review a non-standard deal before it is signed, understand deferred revenue, or spot terms that would delay or reverse recognition.
+---
+
+# Revenue recognition
+
+Cash received is not revenue earned. The gap between them is where deals get restructured after
+signature and where quarters get restated.
+
+**This structures the question and tells you what to ask. Revenue recognition is a technical
+accounting matter under standards such as ASC 606 and IFRS 15 — conclusions on a material or unusual
+contract need your auditors or a qualified accountant, not a checklist.**
+
+## The shape of the question
+
+Recognition follows the transfer of control to the customer, worked through in five steps: identify
+the contract, identify the distinct performance obligations, determine the transaction price,
+allocate it across the obligations, then recognise as each is satisfied.
+
+Most disputes happen at step two and step four. What sales sold as one thing is frequently several
+obligations for accounting purposes — software plus implementation plus support — and the price has
+to be allocated across them on standalone selling price, not on how the quote was written.
+
+## Terms that change the answer
+
+These belong in a pre-signature review, because after signature the only remedy is an amendment the
+customer has no reason to agree to:
+
+- **Acceptance clauses** — a customer right to reject can defer recognition until acceptance.
+- **Termination for convenience** — a short-notice exit can shorten the contract term for accounting
+ purposes, however long the stated term is.
+- **Contingent or milestone fees** — variable consideration, constrained until it is probable there
+ will be no significant reversal.
+- **Material rights** — a renewal or upgrade priced below standalone value can itself be a
+ performance obligation carved out of today's price.
+- **Extended payment terms** — payment far from delivery can introduce a financing component.
+- **Side letters.** Any promise made outside the contract is still part of the contract. They are the
+ single most common cause of restatement, and by construction finance does not know they exist.
+
+## Working with sales
+
+Recognition treatment is a deal input, not a post-signature discovery. A concession that costs
+nothing commercially can move revenue across a period boundary, and by the time finance sees the
+signed paper the trade has already been made.
+
+Give `revenue:chief-revenue-officer` and `revenue:pricing-and-packaging` a small set of standard
+structures that recognise cleanly, and route anything outside them through review before signature —
+alongside `legal-risk:contract-review`, which owns the legal exposure the same clauses create.
+
+## Deferred revenue is an obligation
+
+The deferred balance is work owed, not money banked. Track it by cohort and obligation so you can
+answer what it is composed of and when it releases. A balance nobody can decompose is one that
+surprises you.
+
+## Never
+
+- Recognise on invoice date or cash receipt as a shortcut.
+- Allocate price across obligations the way the quote happened to be laid out.
+- Let a side letter exist.
+- Conclude a material or novel contract's treatment without your auditors.
diff --git a/plugins/finance/skills/treasury-and-liquidity/SKILL.md b/plugins/finance/skills/treasury-and-liquidity/SKILL.md
new file mode 100644
index 0000000..0e3880a
--- /dev/null
+++ b/plugins/finance/skills/treasury-and-liquidity/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: treasury-and-liquidity
+description: Manages cash and liquidity — cash forecasting, runway, working capital, banking structure, and currency and counterparty exposure. Use this to build a cash forecast, extend runway, improve working capital, decide where cash should sit, or assess exposure to a bank, currency, or customer concentration.
+---
+
+# Treasury and liquidity
+
+Profitable companies fail on cash. Earnings are an opinion arrived at through accruals; cash is a
+balance you either have on the day or do not.
+
+## Forecast cash directly
+
+The indirect method — net income adjusted for non-cash items — is right for reporting and nearly
+useless for operating. Build a direct forecast of receipts and disbursements by week, from actual
+expected timing.
+
+Thirteen weeks is the working horizon: long enough to act, short enough to be accurate. Roll it
+weekly and **compare last week's forecast against what happened**. A forecast never checked against
+outturn does not improve, and its errors are the most useful information it produces.
+
+Model timing, not just amount. A receipt that arrives four days late is the same money and a
+different liquidity position.
+
+## Runway is a decision variable
+
+Runway is cash divided by net burn, but the useful version is scenario-based: the plan, a downside
+where revenue underperforms, and the case where a large receivable slips.
+
+Know your decision points in advance — the date by which a raise must start, the date a cost
+reduction must be committed to take effect in time. Decision dates always precede the cash-out date,
+often by more than people assume, and discovering that late removes the good options.
+
+## Working capital is free financing, or a leak
+
+Cash is trapped in the cycle between paying for inputs and being paid for output:
+
+- **Receivables** — invoice promptly and accurately; disputed invoices age indefinitely, and most
+ disputes trace to an invoice that did not match the contract. Watch the aging trend, not the average.
+- **Payables** — take terms offered, pay on time rather than early, and do not fund suppliers who did
+ not ask to be funded.
+- **Inventory** — every unit is cash on a shelf. See `operations:supply-chain-and-logistics`.
+
+A week off the cycle is permanent working capital released, and it costs nothing in interest.
+
+## Where cash sits
+
+Concentration in one bank is a single point of failure, as depositors have periodically rediscovered.
+Spread operating balances against counterparty limits, and hold reserves in instruments whose
+maturity matches when the money is needed.
+
+Do not reach for yield with money you have a date for. The return on operating cash is not worth the
+liquidity risk, and treasury losses of this kind are always described afterwards as conservative
+investments.
+
+## Never
+
+- Run the business on an indirect cash forecast.
+- Report runway as a single number without a downside case.
+- Let the decision date for financing pass while watching the cash-out date.
+- Concentrate operating cash in one counterparty because the relationship is convenient.
diff --git a/plugins/operations/skills/business-continuity-and-resilience/SKILL.md b/plugins/operations/skills/business-continuity-and-resilience/SKILL.md
new file mode 100644
index 0000000..de90230
--- /dev/null
+++ b/plugins/operations/skills/business-continuity-and-resilience/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: business-continuity-and-resilience
+description: Plans for operating through disruption — impact analysis, recovery objectives, continuity plans, and the exercises that prove they work. Use this to run a business impact analysis, set RTO and RPO, write or test a continuity plan, prepare for a supplier or site failure, or answer a customer's resilience questionnaire.
+---
+
+# Business continuity and resilience
+
+Continuity is a business question wearing technical clothing. The technical restore is covered by
+`it-operations:backup-and-recovery`; this is about which processes must keep running, for whom, and
+how long you can survive without them.
+
+## Start with impact, not systems
+
+A business impact analysis asks, per process: what breaks downstream, how fast, and who notices.
+Work outward from the customer-visible failure, not inward from the asset register — an inventory of
+systems tells you what you own, never what matters.
+
+For each critical process establish:
+
+- **Maximum tolerable outage** — the point past which the damage is not recoverable by working harder
+ afterwards. This is a business judgement, made by the process owner, not by IT.
+- **RTO** — how quickly it must be back. Always shorter than someone wants to pay for.
+- **RPO** — how much data you can afford to lose, measured in time. An RPO of zero is a claim about
+ spending, not about intent.
+
+RTO and RPO that were not signed by the person accountable for the process are aspirations.
+
+## Plans people can follow badly
+
+A continuity plan is read by a stressed person at 03:00 who did not write it. Optimise for that
+reader: named roles rather than names, decision authority stated explicitly, and the first three
+actions on the first page.
+
+Include what to do when the plan's assumptions fail — the alternate site is also affected, the key
+person is unreachable, the supplier is not answering. Plans that only handle the anticipated failure
+handle almost nothing.
+
+## Exercises
+
+Untested plans are documents, not capabilities. Escalate the rigour:
+
+1. **Walkthrough** — read it aloud together and find the steps nobody can actually perform.
+2. **Tabletop** — inject a scenario and make the decisions under time pressure.
+3. **Live failover** — actually run on the alternate path, in production, with the real people.
+
+The exercise produces findings or it was theatre. Track them as work with owners and dates, and
+re-run the scenario that failed rather than a fresh one, so improvement is demonstrable.
+
+## Concentration risk
+
+Resilience fails where dependencies converge invisibly: three suppliers who all sit on one cloud
+region, redundant network paths in the same physical duct, a manual workaround that requires a
+system you have just lost. Map dependencies to the point where they stop being yours, and check
+whether the redundancy is real or just contractual.
+
+## Never
+
+- Set an RTO without the process owner agreeing to what it costs.
+- Count a plan as tested because it was reviewed.
+- Treat a backup as continuity — an unrestored backup is an untested assumption.
+- Write a plan whose first step requires the system that has just failed.
diff --git a/plugins/operations/skills/capacity-and-demand-planning/SKILL.md b/plugins/operations/skills/capacity-and-demand-planning/SKILL.md
new file mode 100644
index 0000000..da698f6
--- /dev/null
+++ b/plugins/operations/skills/capacity-and-demand-planning/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: capacity-and-demand-planning
+description: Matches operational capacity to expected demand — forecasting load, sizing teams and systems, managing queues, and deciding when to add capacity. Use this to plan staffing for expected volume, diagnose a queue that keeps growing, size support or fulfilment capacity, or decide whether a bottleneck needs more capacity or better flow.
+---
+
+# Capacity and demand planning
+
+This is operational throughput — how much work the organization can absorb. Allocating people
+across projects is portfolio work, handled in `pmo:portfolio-governance`.
+
+## Forecast demand honestly
+
+Separate the three components, because they need different treatment:
+
+- **Baseline** — the steady rate, best estimated from your own history rather than from a plan.
+- **Trend** — the direction, measured over enough periods to distinguish it from noise.
+- **Spikes** — launches, seasonality, campaigns, incidents. Known spikes are a planning input;
+ unknown ones are what headroom is for.
+
+Forecast in the unit the work actually arrives in — tickets, orders, shipments, minutes of handling
+— not in revenue. Revenue divided by an average is a forecast of an average, and averages are where
+capacity planning goes to die.
+
+## Capacity is not headcount
+
+Usable capacity is people multiplied by available hours multiplied by the fraction spent on the work
+in question. The last term is the one everyone omits and it is rarely above 70%: meetings, training,
+holiday, and the interruptions that come with the job are real.
+
+Plan against realistic effective capacity. Planning at 100% guarantees the plan fails on its first
+ordinary week.
+
+## Queues tell you before the dashboard does
+
+Utilisation above roughly 80% makes wait times rise sharply and non-linearly — a system at 95% is not
+slightly slower than one at 85%, it is qualitatively worse. This is why "we have spare capacity on
+paper" coexists with a queue that never clears.
+
+Watch the **trend in queue age**, not the queue length. A stable-length queue whose oldest item keeps
+getting older is a queue that is quietly failing its slowest customers.
+
+## Add capacity or fix flow
+
+Before adding capacity, establish which it is:
+
+- **Genuine capacity shortfall** — arrival rate exceeds service rate at reasonable utilisation. Add
+ capacity.
+- **Flow problem** — rework, handoffs, waiting on another team, batching. Adding capacity here adds
+ cost and often makes throughput worse by increasing coordination. Send this to
+ `operations:process-design`.
+
+The tell: if work spends most of its life waiting rather than being worked, it is a flow problem.
+
+## Never
+
+- Plan against nominal headcount rather than effective capacity.
+- Run a critical queue at sustained high utilisation and treat the wait times as a mystery.
+- Add capacity to a process you have not measured.
+- Forecast in aggregate currency when work arrives in discrete units.
diff --git a/plugins/operations/skills/quality-management/SKILL.md b/plugins/operations/skills/quality-management/SKILL.md
new file mode 100644
index 0000000..203ac36
--- /dev/null
+++ b/plugins/operations/skills/quality-management/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: quality-management
+description: Builds quality into operations — defining standards, catching defects at the right point, root cause analysis, and continuous improvement. Use this to reduce a defect or error rate, design quality controls into a process, run a root cause analysis, respond to a customer quality complaint, or set up quality metrics that drive behaviour.
+---
+
+# Quality management
+
+Inspection at the end sorts good from bad. It never makes anything good. Quality is decided by the
+process that produced the work, so that is where the effort belongs.
+
+## Define quality as the customer experiences it
+
+A standard nobody outside the team recognises is a preference. State quality in terms a customer
+would agree with: correct, on time, complete, usable — with a threshold, so conformance is a fact
+rather than an opinion.
+
+Then distinguish:
+
+- **Specification quality** — does it match what was specified?
+- **Fitness for purpose** — does the specification serve the actual need?
+
+A process can hit specification perfectly while producing something nobody wants. Only the second
+question protects against that.
+
+## Catch defects where they are cheap
+
+Cost of correction rises steeply with distance from the point of creation. Order of preference:
+
+1. **Prevent** — make the defect impossible. Constraints, defaults, required fields, fixtures.
+2. **Detect at source** — the person doing the work sees the error immediately.
+3. **Detect downstream** — the next step catches it. Slower, and adds rework.
+4. **Detect at the customer** — the most expensive possible option, and it costs trust as well.
+
+Every control pushed one step earlier is worth more than an additional control at the end.
+
+## Root cause, not first cause
+
+"Human error" is where analysis stops, not where it should. Ask what made the error easy to make and
+hard to notice: an ambiguous form, an unenforced sequence, a target that rewarded speed.
+
+Work backwards through the causal chain until you reach something you can change structurally. A
+corrective action that depends on people being more careful is not a corrective action — the same
+conditions will produce the same result with different people.
+
+Verify the fix by watching the defect rate, not by confirming the action was completed.
+
+## Metrics that do not corrupt
+
+Any quality metric attached to individual performance will be gamed, usually by reclassifying
+defects rather than preventing them. Measure at the process level, review trends rather than points,
+and pair any rate metric with a volume metric so improvement by doing less is visible.
+
+Escaped defects — those the customer found — are the honest measure. Everything else is a proxy.
+
+## Never
+
+- Attribute a defect to carelessness and stop there.
+- Add an inspection step in place of fixing the process that produced the defect.
+- Set a quality target for an individual that they can meet by reclassifying.
+- Close a corrective action without evidence the rate moved.
diff --git a/plugins/operations/skills/service-level-management/SKILL.md b/plugins/operations/skills/service-level-management/SKILL.md
new file mode 100644
index 0000000..e32b55d
--- /dev/null
+++ b/plugins/operations/skills/service-level-management/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: service-level-management
+description: Defines and manages service levels — setting targets that reflect what customers need, measuring honestly, and handling breaches. Use this to write or negotiate an SLA, decide what to measure and at what threshold, respond to a missed service level, or work out why a service that meets its targets still has unhappy customers.
+---
+
+# Service level management
+
+A service level is a promise with a number attached. The number is the easy part; choosing what to
+measure is where these go wrong.
+
+## Measure what the customer feels
+
+The characteristic failure is a service meeting every target while customers are angry. It happens
+when the measure is chosen for availability of data rather than relevance:
+
+- **Uptime that excludes degraded operation.** Technically up and unusably slow is down.
+- **Response time instead of resolution time.** An instant acknowledgement that resolves nothing
+ measures the autoresponder.
+- **Averages instead of percentiles.** A mean hides the tail, and the tail is who complains. Commit
+ at p95 or p99, not the mean.
+- **Measurement from inside your own perimeter**, which excludes the part of the path the customer
+ actually traverses.
+
+## Set targets you would fund
+
+A target is a spending decision. Each added nine costs disproportionately more than the last, so the
+question is never "what would be good?" but "what is the gap worth to the customer, and does it
+exceed what closing it costs?"
+
+Set the internal objective tighter than the external commitment. The gap between them is your
+warning margin; without it, the first thing you learn about a breach is the breach.
+
+## Write them so both sides can tell
+
+An unmeasurable clause is a future dispute. Every service level needs: what is measured, where it is
+measured from, how it is calculated, what is excluded, over what window, and what happens when it is
+missed.
+
+Exclusions are the substance — planned maintenance, force majeure, customer-caused failures,
+dependencies outside your control. Vague exclusions get read narrowly when it matters. For anything
+with contractual teeth, `legal-risk:contract-review` owns the remedy language; this skill owns
+whether the number is achievable.
+
+## When you breach
+
+Say so before the customer does. A breach reported by the provider with a cause and a fix costs far
+less trust than one the customer discovers and raises.
+
+Then separate the incident from the pattern. One breach is an incident, handled by
+`customer-experience:escalation-management`. Repeated breaches of the same target mean the target was
+never fundable — renegotiate it honestly rather than continuing to miss it.
+
+## Never
+
+- Commit to a level you have not measured yourself achieving for a sustained period.
+- Report availability on a mean when the customer experiences the tail.
+- Agree an SLA whose exclusions are undefined.
+- Let a target stand that you have missed repeatedly without either funding it or renegotiating it.
diff --git a/plugins/operations/skills/supply-chain-and-logistics/SKILL.md b/plugins/operations/skills/supply-chain-and-logistics/SKILL.md
new file mode 100644
index 0000000..312f4c5
--- /dev/null
+++ b/plugins/operations/skills/supply-chain-and-logistics/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: supply-chain-and-logistics
+description: Manages the flow of goods and inputs — sourcing, inventory, lead times, fulfilment, and supply risk. Use this to reduce stockouts or excess inventory, plan for a supplier failure, decide reorder points and safety stock, improve fulfilment reliability, or assess concentration risk in a supply base.
+---
+
+# Supply chain and logistics
+
+Supply chains fail at variability, not at averages. A chain planned on average demand and average
+lead time will disappoint at both ends: stockouts when either runs long, dead stock when they do not.
+
+## Inventory is a bet on uncertainty
+
+Safety stock exists to absorb variation in demand and in lead time. Sizing it needs both the average
+and the spread — a supplier averaging 20 days at ±2 is a different proposition from one averaging 20
+days at ±15, and treating them the same guarantees you are wrong about one.
+
+Set reorder points on lead-time demand plus safety stock, and revisit them when either input moves.
+A reorder point set once is a reorder point that is now wrong.
+
+Hold inventory where it is most flexible. Stock held as components serves several finished
+configurations; the same value held as finished goods serves one and obsoletes faster.
+
+## Lead time is a distribution
+
+Quoted lead time is a marketing number. Plan against your own measured receipt dates, including the
+bad months. Track the variance explicitly — reliability of lead time usually matters more than its
+length, because a long predictable lead time can be planned around and a short erratic one cannot.
+
+## Concentration is the risk that actually bites
+
+Map dependencies past the first tier. Two suppliers on paper who share a single sub-supplier, a
+single port, or a single region are one supplier with extra paperwork.
+
+For each critical input know: who else could supply it, how long qualifying them takes, and whether
+anything in the design makes switching hard. That answer is worth having before you need it —
+qualifying an alternate under pressure is where quality problems enter.
+
+Supplier commercial terms and exit rights belong with `operations:vendor-management`; continuity of
+the wider business process belongs with `operations:business-continuity-and-resilience`.
+
+## Fulfilment reliability
+
+Measure on-time-in-full, not on-time and in-full separately — partial shipments that arrive on
+schedule are a way of appearing to hit a target while failing the customer.
+
+Diagnose misses by cause: supply, capacity, information, or process. The remedies do not overlap,
+and a fulfilment problem attributed to the wrong one gets more expensive rather than better.
+
+## Never
+
+- Size safety stock from average demand without accounting for variability.
+- Treat a quoted lead time as a planning input when you have measured data.
+- Count two suppliers as redundancy without tracing where their chains converge.
+- Report on-time and in-full separately to make the number look better.
diff --git a/plugins/people/skills/employee-relations/SKILL.md b/plugins/people/skills/employee-relations/SKILL.md
new file mode 100644
index 0000000..681e1e0
--- /dev/null
+++ b/plugins/people/skills/employee-relations/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: employee-relations
+description: Handles the difficult human situations — grievances, complaints, investigations, conflict, and separations conducted properly. Use this to respond to a complaint or grievance, structure an investigation, handle a conflict between colleagues, prepare for a difficult conversation, or work out what a manager can and cannot do in a given situation.
+---
+
+# Employee relations
+
+These situations are consequential for the person, for the organization's legal exposure, and for
+everyone watching how it is handled. Process is what protects all three.
+
+**This structures the approach and tells you what to ask. Grievances, investigations, dismissals,
+discrimination and accommodation are legally regulated and vary substantially by jurisdiction —
+involve qualified employment counsel early rather than at the point of decision.**
+
+## Take complaints seriously and visibly
+
+How the first complaint is handled determines whether you hear about the second. An organization that
+mishandles one complaint does not stop having problems; it stops being told about them, and then
+learns about them from a regulator or a lawyer.
+
+Acknowledge promptly, explain what will happen next, and say what the person can expect to be told.
+Do not promise confidentiality you cannot deliver — say who will need to know and why. A broken
+confidentiality promise destroys the reporting channel permanently.
+
+Protect against retaliation actively. Retaliation is frequently a worse exposure than the original
+complaint, and it often occurs through ordinary decisions — a changed assignment, an excluded
+invitation — made by someone who would deny any such intent.
+
+## Investigations
+
+An investigation establishes what happened. It is not a negotiation and not a disciplinary process.
+
+- **Independent investigator** — not in the reporting line of anyone involved.
+- **Scope agreed in writing** at the start, so it neither drifts nor is later described as narrow.
+- **Both sides heard**, with the respondent told the substance of the allegation in enough detail to
+ answer it.
+- **Contemporaneous notes**, and evidence preserved from the moment you are aware.
+- **Findings on the balance of evidence**, stated separately from any recommendation.
+
+Move quickly. Investigations that drift damage everyone involved and the delay itself becomes a
+complaint.
+
+## Conflict that is not misconduct
+
+Most friction is not a policy matter. Address it directly and early: separate the behaviour from the
+person, establish what each actually needs, and be explicit that the working relationship has to
+function even where warmth is not available.
+
+Escalating ordinary disagreement into a formal process is its own harm — it takes something
+resolvable and makes it permanent.
+
+## Separations
+
+Whatever the reason, conduct them with dignity, on a documented basis, consistently with how others
+have been treated. Inconsistency is the single most common source of successful claims.
+
+The people who remain draw conclusions from how leavers are treated, and those conclusions are
+durable.
+
+## Never
+
+- Promise confidentiality you cannot keep.
+- Investigate a matter in your own reporting line.
+- Act on an allegation the respondent has not had a fair chance to answer.
+- Make a termination decision without qualified employment counsel.
diff --git a/plugins/people/skills/learning-and-development/SKILL.md b/plugins/people/skills/learning-and-development/SKILL.md
new file mode 100644
index 0000000..f04aebd
--- /dev/null
+++ b/plugins/people/skills/learning-and-development/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: learning-and-development
+description: Builds capability — skills gaps, career frameworks, training that transfers to the job, and internal mobility. Use this to design a career ladder, close a capability gap, decide whether to build or hire a skill, structure onboarding into a role, or work out why training keeps failing to change anything.
+---
+
+# Learning and development
+
+Training is the most reliably wasted budget in an organization, because attendance is easy to measure
+and transfer to the job is not.
+
+## Start from the capability gap
+
+Training is a solution. Establish the problem first: what should people be able to do that they
+cannot, and is the cause actually capability?
+
+Frequently it is not. If someone knows how but does not, look for the real obstacle — no time, a
+process that makes the right thing harder, an incentive pointing elsewhere, or no feedback on whether
+they did it correctly. Training a motivation or system problem changes nothing and consumes the
+budget that would have fixed it.
+
+## Design for transfer
+
+Most of what people can actually do is learned by doing it, with feedback, on real work. Formal
+instruction is a small part and it decays quickly without application.
+
+So: teach close to the moment of use, give people real work immediately afterwards, and arrange
+feedback from someone competent. A course two months before the work is entertainment.
+
+Measure transfer, not satisfaction. Whether attendees enjoyed it is uncorrelated with whether they
+now do the job differently. Ask their manager at ninety days what changed.
+
+## Career frameworks
+
+A framework answers what is expected at each level and what growth looks like. It carries weight far
+beyond development — it drives compensation bands, promotion decisions, and whether people believe
+progression is fair. It should be built with `people:compensation-and-leveling`, not separately.
+
+Make it observable. Levels described by scope, autonomy and impact can be assessed; levels described
+by seniority adjectives cannot, and collapse into tenure.
+
+Provide a path that is not management. Forcing the best practitioners into management to progress is
+how organizations lose their best practitioners and gain mediocre managers.
+
+## Internal mobility
+
+Internal moves are usually cheaper and lower-risk than external hiring, and they are the main reason
+capable people stay. The obstacle is almost always managers hoarding talent, which is rational for
+the manager and expensive for the company.
+
+Fix the incentive rather than the policy: make developing and releasing people something managers are
+evaluated on. A mobility policy that costs a manager their best person and gives them nothing will be
+quietly resisted, and quiet resistance always wins.
+
+## Never
+
+- Deliver training for a problem that is not a capability problem.
+- Measure a programme by satisfaction scores.
+- Write levels in adjectives rather than observable scope and impact.
+- Make management the only route to progression.
diff --git a/plugins/people/skills/onboarding-and-offboarding/SKILL.md b/plugins/people/skills/onboarding-and-offboarding/SKILL.md
new file mode 100644
index 0000000..dae3374
--- /dev/null
+++ b/plugins/people/skills/onboarding-and-offboarding/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: onboarding-and-offboarding
+description: Designs the joining and leaving experience — first-day readiness, ramp to productivity, knowledge capture, and clean exits. Use this to design or fix onboarding, shorten time to productivity, structure a leaver process, capture knowledge before someone leaves, or coordinate the access and asset steps around a joiner or leaver.
+---
+
+# Onboarding and offboarding
+
+Both ends are cross-functional processes that fail at the handoffs. The failures are predictable,
+which means they are preventable by design rather than by diligence.
+
+## Onboarding starts before day one
+
+Everything procurable in advance should be ready: accounts, hardware, access, a first assignment, and
+a named person responsible for the human side. A first day spent waiting for a laptop is a permanent
+first impression, and it is entirely a coordination failure.
+
+The identity and equipment steps are executed by
+`it-operations:identity-lifecycle-administration` and `it-operations:endpoint-management`; access
+policy — what a role should be entitled to — belongs to `security:access-and-identity`. This skill
+owns the sequence and whether it actually completed.
+
+## Ramp deliberately
+
+Separate the three things a new person is learning, because they need different support:
+
+- **The job** — often the part they already have.
+- **The context** — the systems, the codebase, the customers, the history.
+- **The people** — who decides what, who to ask, how things really get done.
+
+The third is the one nobody plans and the one that most determines how quickly someone becomes
+useful. Make introductions explicit assignments rather than leaving them to chance and extroversion.
+
+Give real work early, scoped to succeed. A meaningful contribution in the first fortnight does more
+for confidence and belonging than any amount of orientation material.
+
+Check in at deliberate intervals — a week, a month, a quarter — with the question phrased so problems
+can surface. "What has been more confusing than it should be?" gets an answer; "how's it going?" does
+not.
+
+## Offboarding: knowledge before access
+
+Knowledge capture has to precede the access cutoff, which means starting on the day notice is given,
+not the day before departure.
+
+Prioritise what is genuinely undocumented and only in one head: the systems they alone maintain, the
+relationships they hold, the decisions whose reasoning exists nowhere. Ask directly — "what will
+break, and who will not know why?" — because they know and will usually say.
+
+Then run the mechanical steps as a checklist with an owner: access revoked across every system
+including those outside single sign-on, assets returned, delegations and approvals reassigned, and
+handover confirmed by the person receiving it rather than by the person leaving.
+
+## Exits are data
+
+Exit conversations produce candid information that is unavailable any other way, and it is routinely
+collected and never used. Aggregate themes over time and look by manager and by team; a single exit
+is an anecdote, a pattern across four is a finding for `people:chief-human-resources-officer`.
+
+## Never
+
+- Let a start date arrive without access and equipment confirmed ready.
+- Leave relationship introductions to chance.
+- Cut access before knowledge capture has happened.
+- Collect exit feedback nobody ever reads in aggregate.
diff --git a/plugins/people/skills/performance-management/SKILL.md b/plugins/people/skills/performance-management/SKILL.md
new file mode 100644
index 0000000..b9e3ef3
--- /dev/null
+++ b/plugins/people/skills/performance-management/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: performance-management
+description: Runs performance systems that change behaviour — expectations, feedback, review cycles, calibration, and handling underperformance. Use this to design or fix a review process, run calibration, write or coach on feedback, address sustained underperformance, or work out why reviews consume weeks and change nothing.
+---
+
+# Performance management
+
+Most review systems are an expensive annual ritual that surprises nobody and improves nothing. The
+work happens in the ordinary week; the cycle should record it, not discover it.
+
+**Performance documentation carries legal weight, particularly around termination, discrimination and
+accommodation. Employment law varies by jurisdiction — involve qualified counsel before acting on
+sustained underperformance.**
+
+## Expectations before assessment
+
+Nobody can be fairly assessed against a standard they were not given. Expectations need to be
+specific to the level, written down, and shared before the period rather than produced during review
+as justification.
+
+Separate two axes deliberately, because conflating them is the most common structural flaw:
+
+- **Outcomes** — what was delivered, which is partly situational.
+- **Behaviours** — how it was done, which is more within the person's control.
+
+Someone who delivered through a collapsing market and someone who delivered by scorching the earth
+around them are different cases. A single blended rating hides both.
+
+## Feedback in the week, not the quarter
+
+Feedback is useful proportional to its proximity to the event. Specific, immediate, and about the
+work: what happened, what the effect was, what to do differently.
+
+The annual cycle should contain nothing new. A review that surprises someone is a reporting failure
+by their manager, and the surprise is the finding.
+
+## Calibration
+
+Managers rate differently — some systematically generously, some harshly — and the differences are
+invisible until ratings sit side by side. Calibration exists to make comparison possible, not to fit
+a distribution.
+
+Forced distributions are the failure mode here. On small teams they are statistically meaningless,
+and they reliably destroy exactly the collaboration the values section claims to reward.
+
+Calibrate on evidence: what was delivered, at what level, against what expectation. A rating that
+cannot be defended with an example is a preference.
+
+## Sustained underperformance
+
+Address it early and directly. Late intervention is worse for everyone, most of all the person, who
+has been allowed to believe they were fine.
+
+Establish which it is first, because the remedies do not overlap: unclear expectations, missing
+capability, a role mismatch, or something outside work. Treating a role mismatch as a capability
+problem produces a performance plan that fails for reasons nobody named.
+
+Where a formal plan is warranted it needs specific outcomes, a real timeframe, defined support, and a
+stated consequence. A plan that is only a paper trail for a decision already taken is recognised as
+such and does damage well beyond the individual.
+
+## Never
+
+- Assess against expectations that were not set in advance.
+- Deliver news in a review that should have been given weeks earlier.
+- Force a distribution on a small team.
+- Start a performance plan without deciding whether the problem is capability or fit.
diff --git a/plugins/people/skills/workforce-planning/SKILL.md b/plugins/people/skills/workforce-planning/SKILL.md
new file mode 100644
index 0000000..8228c18
--- /dev/null
+++ b/plugins/people/skills/workforce-planning/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: workforce-planning
+description: Plans the shape and size of the workforce — demand for roles, build-versus-buy, attrition, and sequencing hiring against budget. Use this to build a hiring plan, decide which roles to open and in what order, model attrition and backfill, plan for a growth or contraction scenario, or connect headcount plans to the budget.
+---
+
+# Workforce planning
+
+A hiring plan is an org design decision spread over twelve months and a large financial commitment
+made in small pieces. It deserves the scrutiny of both.
+
+## Plan capability, not headcount
+
+Headcount is an input. Start from what the organization must be able to do that it currently cannot,
+then work out what closes the gap — hiring, developing existing people, contracting, or not doing the
+work.
+
+The shape follows from `people:org-design`; this is about sequencing and quantity over time, funded
+against `finance:budgeting-and-forecasting` on fully loaded cost rather than salary. Salary is
+typically well under the true cost, and plans built on it are wrong by a wide and consistent margin.
+
+## Sequence matters more than total
+
+Twelve hires in a year is not one number; it is twelve dated decisions with dependencies.
+
+- **Hire the people who make other hires productive first.** A manager, a lead, or the person who can
+ onboard the next five. Hiring five juniors before the person who will develop them wastes most of
+ the investment.
+- **Respect absorption capacity.** An organization can only integrate so many people at once before
+ onboarding quality falls and existing output drops. Growth past that rate makes things slower for
+ a quarter, reliably.
+- **Front-load long-lead roles.** Scarce skills take months to find. Plotting them at the same lead
+ time as abundant ones is how plans silently slip.
+
+## Attrition is a planning input
+
+Some attrition is expected and healthy; the planning error is treating it as noise. Model it by
+segment — teams, levels and tenure bands differ substantially — and plan backfill lead time from the
+resignation date, not the leaving date.
+
+Watch **regretted** attrition specifically, and by manager. Aggregate attrition looks fine while one
+team is bleeding people, and the aggregate is what gets reported.
+
+## Scenarios, including down
+
+Plan the base case, the growth case and the contraction case. Knowing in advance what you would stop
+doing, and which commitments are hard to reverse, is what makes a downturn a decision rather than a
+scramble.
+
+Offers, notice periods and some contractor arrangements are commitments before anyone starts. Know
+which parts of the plan can still be unwound and by when.
+
+## Never
+
+- Build a plan on salary rather than fully loaded cost.
+- Hire faster than the organization can absorb and expect output to rise.
+- Treat attrition as a residual instead of a modelled input.
+- Report aggregate attrition without looking at it by team and by manager.
diff --git a/scripts/build-readme.py b/scripts/build-readme.py
index dd03ee9..b1699fd 100755
--- a/scripts/build-readme.py
+++ b/scripts/build-readme.py
@@ -110,6 +110,11 @@ out = [
"",
"Invoke one directly by name when you want a specific lens: `/finance:financial-modeling`.",
"",
+ "Seven situations that cross departments — a SOC 2 demand from an enterprise prospect, a",
+ "security incident, a stalled funnel — are worked through end to end in",
+ "[docs/USE-CASES.md](docs/USE-CASES.md), including where a reviewer-class department stops the",
+ "work rather than adding an opinion.",
+ "",
"Each department also ships an agent charter in `.claude/agents/`, so a department can be delegated",
"to as a subagent with its own exclusive write surface.",
"",
@@ -139,6 +144,7 @@ out += [
".claude/agents/<id>.md one charter per department",
"docs/AGENT-SURFACES.md every path has exactly one owner, enforced in CI",
"docs/DECISION-LOG.md numbered decisions with options and recommendations",
+ "docs/USE-CASES.md situations worked end to end across departments",
"```",
"",
"Agents split by **exclusive write surface**, not by topic — a topic split has no checkable",
@@ -151,8 +157,10 @@ out += [
"./scripts/check-all.sh",
"```",
"",
- "Verifies the surface map is coherent, every skill's frontmatter is valid and unique, no third-party",
- "licence text has appeared, and every manifest parses. CI runs the same script.",
+ "Verifies the surface map is coherent, every skill's frontmatter is valid and unique, no",
+ "third-party licence text has appeared, the generated README and social card are current, every",
+ "`department:skill` reference in the docs resolves, and every manifest parses. CI runs the same",
+ "script, so local and CI cannot drift.",
"",
"A new department needs its roster row in `docs/AGENT-SURFACES.md`, a surface block, a charter in",
"`.claude/agents/`, and an entry in `.claude-plugin/marketplace.json` — all in the same change, or",
diff --git a/scripts/build-social-card.py b/scripts/build-social-card.py
new file mode 100755
index 0000000..52541c9
--- /dev/null
+++ b/scripts/build-social-card.py
@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Generate the GitHub social preview card.
+
+The card states the department and skill counts, so it drifts exactly the way the README used
+to (D19). It is generated from the same tree walk instead of hand-drawn, and `--check` compares
+the committed HTML against freshly generated output — a text comparison, so CI verifies it
+without needing a browser.
+
+ python3 scripts/build-social-card.py regenerate HTML, then render the PNG
+ python3 scripts/build-social-card.py --check fail if the HTML is stale (CI)
+ python3 scripts/build-social-card.py --html regenerate HTML only, skip rendering
+
+Rendering needs Chromium. The PNG is a build artefact committed for convenience: GitHub wants a
+file upload, not a URL, so a copy in the repository is what you re-download when re-uploading it.
+"""
+import glob
+import os
+import shutil
+import subprocess
+import sys
+
+HTML_OUT = "docs/assets/social-card.html"
+PNG_OUT = "docs/assets/social-preview.png"
+WIDTH, HEIGHT = 1280, 640 # GitHub's recommended social preview size; rendered at 2x
+
+# Same glob as build-readme.py. Both walk the tree directly rather than sharing state, so the
+# card and the README cannot report different numbers for the same commit.
+def counts():
+ depts = sorted(
+ os.path.basename(os.path.dirname(os.path.dirname(m)))
+ for m in glob.glob("plugins/*/.claude-plugin/plugin.json")
+ )
+ skills = len(glob.glob("plugins/*/skills/*/SKILL.md"))
+ return len(depts), skills
+
+
+TEMPLATE = """<meta charset="utf-8">
+<!-- GENERATED by scripts/build-social-card.py — edit that, not this file. -->
+<style>
+ /* Fixed {W}x{H} canvas. Every block is absolutely positioned: on a canvas of known size
+ that is deterministic, where flex sizing silently failed to place the footer row. */
+ * {{ margin:0; padding:0; box-sizing:border-box; }}
+ html,body {{ width:{W}px; height:{H}px; overflow:hidden; }}
+ body {{
+ background:#0B0E14;
+ font-family:"Liberation Sans","Helvetica Neue",Arial,sans-serif;
+ color:#E6EDF3; position:relative;
+ }}
+ .grid {{
+ position:absolute; inset:0;
+ background-image:
+ linear-gradient(rgba(255,255,255,.03) 1px, transparent 1px),
+ linear-gradient(90deg, rgba(255,255,255,.03) 1px, transparent 1px);
+ background-size:40px 40px;
+ }}
+ .glow {{
+ position:absolute; width:820px; height:820px; right:-260px; top:-260px; border-radius:50%;
+ background:radial-gradient(circle, rgba(217,119,87,.17) 0%, rgba(217,119,87,0) 65%);
+ }}
+ .bar {{
+ position:absolute; left:0; top:0; width:8px; height:100%;
+ background:linear-gradient(180deg,#D97757 0%,#C2663F 46%,#33404F 100%);
+ }}
+ .eyebrow {{
+ position:absolute; left:80px; top:62px;
+ font-family:"DejaVu Sans Mono",monospace;
+ font-size:20px; letter-spacing:.14em; color:#69768A; text-transform:uppercase;
+ }}
+ h1 {{
+ position:absolute; left:76px; top:96px;
+ font-size:122px; font-weight:700; letter-spacing:-.048em; line-height:1; color:#fff;
+ }}
+ .tagline {{
+ position:absolute; left:80px; top:246px;
+ font-size:36px; color:#9FB0C3; letter-spacing:-.014em;
+ }}
+ .chip {{
+ position:absolute; left:80px; top:318px;
+ background:#151A22; border:1px solid #283040; border-radius:12px; padding:18px 26px;
+ font-family:"DejaVu Sans Mono",monospace; font-size:26px; color:#B7C4D2;
+ }}
+ .chip .at {{ color:#D97757; font-weight:700; }}
+ .rule {{
+ position:absolute; left:80px; top:498px; width:604px; height:1px;
+ background:linear-gradient(90deg,#2A3341 0%, rgba(42,51,65,0) 100%);
+ }}
+ .meta {{
+ position:absolute; left:80px; top:534px;
+ font-size:20px; letter-spacing:.12em; text-transform:uppercase; color:#7D8B9C;
+ white-space:nowrap;
+ }}
+ .meta b {{ color:#E6EDF3; font-weight:700; }}
+ .meta .sep {{ color:#3D4756; padding:0 13px; }}
+ .chart {{ position:absolute; right:96px; top:150px; }}
+</style>
+
+<div class="grid"></div>
+<div class="glow"></div>
+<div class="bar"></div>
+
+<div class="eyebrow">cbrock84 / headcount</div>
+<h1>headcount</h1>
+<div class="tagline">Add a department, not a prompt.</div>
+<div class="chip">/plugin install security<span class="at">@headcount</span></div>
+
+<div class="rule"></div>
+<div class="meta">
+ <b>{DEPTS}</b> departments <span class="sep">/</span>
+ <b>{SKILLS}</b> skills <span class="sep">/</span>
+ MIT <span class="sep">/</span> for Claude Code
+</div>
+
+<!-- The chart is the organization's actual shape: one chief executive, departments beneath, and
+ the reviewer-class departments (accent outline) hanging off a spine that runs from the top,
+ because they report to the chief executive rather than into the function they oversee. -->
+<div class="chart">
+<svg width="342" height="342" viewBox="0 0 342 342" fill="none">
+ <g stroke="#3A4553" stroke-width="2">
+ <path d="M171 70 L171 104"/>
+ <path d="M48 104 L294 104"/>
+ <path d="M48 104 L48 136"/><path d="M122 104 L122 136"/>
+ <path d="M220 104 L220 136"/><path d="M294 104 L294 136"/>
+ <path d="M171 104 L171 228"/>
+ <path d="M72 228 L270 228"/>
+ <path d="M72 228 L72 258"/><path d="M171 228 L171 258"/>
+ <path d="M270 228 L270 258"/>
+ </g>
+ <rect x="117" y="24" width="108" height="46" rx="10" fill="#D97757"/>
+ <g fill="#31251F">
+ <rect x="137" y="40" width="46" height="5" rx="2.5"/>
+ <rect x="137" y="52" width="30" height="5" rx="2.5"/>
+ </g>
+ <g fill="#1A2029" stroke="#3A4553" stroke-width="2">
+ <rect x="18" y="136" width="60" height="60" rx="9"/>
+ <rect x="92" y="136" width="60" height="60" rx="9"/>
+ <rect x="190" y="136" width="60" height="60" rx="9"/>
+ <rect x="264" y="136" width="60" height="60" rx="9"/>
+ <rect x="141" y="258" width="60" height="54" rx="9"/>
+ </g>
+ <g fill="#1A2029" stroke="#D97757" stroke-width="2">
+ <rect x="42" y="258" width="60" height="54" rx="9"/>
+ <rect x="240" y="258" width="60" height="54" rx="9"/>
+ </g>
+ <g fill="#3A4553">
+ <rect x="30" y="152" width="36" height="5" rx="2.5"/><rect x="30" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="104" y="152" width="36" height="5" rx="2.5"/><rect x="104" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="202" y="152" width="36" height="5" rx="2.5"/><rect x="202" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="276" y="152" width="36" height="5" rx="2.5"/><rect x="276" y="164" width="24" height="5" rx="2.5"/>
+ <rect x="153" y="274" width="36" height="5" rx="2.5"/><rect x="153" y="286" width="24" height="5" rx="2.5"/>
+ </g>
+ <g fill="#8A5039">
+ <rect x="54" y="274" width="36" height="5" rx="2.5"/><rect x="54" y="286" width="24" height="5" rx="2.5"/>
+ <rect x="252" y="274" width="36" height="5" rx="2.5"/><rect x="252" y="286" width="24" height="5" rx="2.5"/>
+ </g>
+</svg>
+</div>
+"""
+
+
+def render_html():
+ depts, skills = counts()
+ return TEMPLATE.format(W=WIDTH, H=HEIGHT, DEPTS=depts, SKILLS=skills)
+
+
+def find_chromium():
+ """Playwright's bundled Chromium first, then anything on PATH."""
+ pw = os.environ.get("PLAYWRIGHT_BROWSERS_PATH", "/opt/pw-browsers")
+ candidates = [
+ os.path.join(pw, "chromium"),
+ *(shutil.which(n) for n in
+ ("chromium", "chromium-browser", "google-chrome", "google-chrome-stable")),
+ ]
+ return next((c for c in candidates if c and os.path.exists(c)), None)
+
+
+def main():
+ content = render_html()
+
+ if "--check" in sys.argv:
+ current = open(HTML_OUT, encoding="utf-8").read() if os.path.exists(HTML_OUT) else ""
+ if current != content:
+ print(f" {HTML_OUT} is stale — run: python3 scripts/build-social-card.py")
+ return 1
+ print("social card is current")
+ return 0
+
+ os.makedirs(os.path.dirname(HTML_OUT), exist_ok=True)
+ open(HTML_OUT, "w", encoding="utf-8").write(content)
+ depts, skills = counts()
+ print(f"{HTML_OUT} regenerated — {depts} departments, {skills} skills")
+
+ if "--html" in sys.argv:
+ return 0
+
+ chrome = find_chromium()
+ if not chrome:
+ print(" no Chromium found — HTML written, PNG not rendered.")
+ print(" install Chromium, or open the HTML and screenshot it at "
+ f"{WIDTH}x{HEIGHT}.")
+ return 0
+
+ subprocess.run([
+ chrome, "--headless", "--no-sandbox", "--disable-gpu", "--hide-scrollbars",
+ "--force-device-scale-factor=2", f"--window-size={WIDTH},{HEIGHT}",
+ f"--screenshot={PNG_OUT}", HTML_OUT,
+ ], check=True, capture_output=True)
+ kb = os.path.getsize(PNG_OUT) // 1024
+ print(f"{PNG_OUT} rendered — {WIDTH*2}x{HEIGHT*2}, {kb} KB "
+ f"(GitHub's limit is 1 MB; upload at Settings -> General -> Social preview)")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/check-all.sh b/scripts/check-all.sh
index 26f609b..e7e5674 100755
--- a/scripts/check-all.sh
+++ b/scripts/check-all.sh
@@ -25,6 +25,10 @@ run "No third-party licence text" \
python3 scripts/check-provenance.py
run "README is current" \
python3 scripts/build-readme.py --check
+run "Social card is current" \
+ python3 scripts/build-social-card.py --check
+run "Skill references resolve" \
+ python3 scripts/check-skill-refs.py
run "Manifests parse" \
python3 -c "
import json,glob,sys
diff --git a/scripts/check-skill-refs.py b/scripts/check-skill-refs.py
new file mode 100755
index 0000000..5db6e3e
--- /dev/null
+++ b/scripts/check-skill-refs.py
@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Verify that every `department:skill` reference in the documentation resolves.
+
+Prose naming specific skills rots as skills are renamed or consolidated — and this repository
+has already consolidated once, losing six capabilities in the process. A reference to a skill
+that no longer exists is a broken promise to a reader, and nothing else in the tree catches it.
+
+Only tokens whose prefix is a real department directory are checked, so ordinary prose with a
+colon in it is ignored rather than guessed at.
+"""
+import glob
+import os
+import re
+import sys
+
+DOCS = ["README.md", "CONTRIBUTING.md"] + sorted(glob.glob("docs/**/*.md", recursive=True))
+# `dept:skill` inside backticks — the convention this repository uses for addressing a skill.
+REF = re.compile(r"`([a-z][a-z0-9-]*):([a-z][a-z0-9-]*)`")
+
+
+def main():
+ departments = {
+ os.path.basename(os.path.dirname(os.path.dirname(m)))
+ for m in glob.glob("plugins/*/.claude-plugin/plugin.json")
+ }
+ if not departments:
+ print(" no departments found — run from the repository root")
+ return 1
+
+ problems = []
+ checked = 0
+ for path in DOCS:
+ if not os.path.exists(path):
+ continue
+ for n, line in enumerate(open(path, encoding="utf-8"), 1):
+ for dept, skill in REF.findall(line):
+ if dept not in departments:
+ continue # not a skill reference, just prose with a colon
+ checked += 1
+ if not os.path.exists(f"plugins/{dept}/skills/{skill}/SKILL.md"):
+ problems.append(f"{path}:{n}: `{dept}:{skill}` does not exist")
+
+ for p in problems:
+ print(f" {p}")
+ print(f"skill references: {checked} checked, {len(problems)} problems")
+ return 1 if problems else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())