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.
HTML agent-marketplacechatgpt-pluginchatgpt-skillsclaude-codeclaude-code-pluginclaude-pluginclaude-skillsmcporganization
Use cases, social card generator, 15 skills, and D25 (#8)
Chris Brock42b4a27b8306
diff --git a/README.md b/README.mdindex 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 itneeds 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 delegatedto 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 departmentdocs/AGENT-SURFACES.md every path has exactly one owner, enforced in CIdocs/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, ordiff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.mdindex 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 verticalvariants become a commercial product — that is a different question (pricing, not donations) anddeserves 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.mdnew file mode 100644index 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.htmlnew file mode 100644index 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.pngnew file mode 100644index 0000000..ce6b299Binary files /dev/null and b/docs/assets/social-preview.png differdiff --git a/docs/org-chart.md b/docs/org-chart.mdindex 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 gapsdiff --git a/plugins/finance/skills/capital-allocation/SKILL.md b/plugins/finance/skills/capital-allocation/SKILL.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.pyindex 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.pynew file mode 100755index 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.shindex 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.pyrun "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.pyrun "Manifests parse" \python3 -c "import json,glob,sysdiff --git a/scripts/check-skill-refs.py b/scripts/check-skill-refs.pynew file mode 100755index 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())