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.

Add a getting-started guide, four operating-company situations, and a usage layer on the org chart

Claude53108b59cb12
diff --git a/README.md b/README.md
index d431704..2ddb149 100644
--- a/README.md
+++ b/README.md
@@ -53,10 +53,14 @@ 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.
+New to this? [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) covers which departments to
+install first, the three ways to invoke a skill, and what reviewer-class departments do
+differently.
+
+Eleven situations that cross departments — a SOC 2 demand from an enterprise prospect, a link
+down between two sites, a renewal that auto-renewed because nobody owned the date — are worked
+through end to end in [docs/USE-CASES.md](docs/USE-CASES.md), including what comes back and
+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.
@@ -376,6 +380,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/GETTING-STARTED.md install, what to take first, and how to invoke a skill
docs/USE-CASES.md situations worked end to end across departments
docs/org-chart.html interactive org chart, searchable across every skill
docs/index.html GitHub Pages entry point, redirects to the chart
diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md
new file mode 100644
index 0000000..4b11dbd
--- /dev/null
+++ b/docs/GETTING-STARTED.md
@@ -0,0 +1,108 @@
+# Getting started
+
+This is a library of expertise, packaged as sixteen independently installable departments for
+[Claude Code](https://claude.com/claude-code). You install the ones you need, and the relevant
+specialist loads itself when you ask something in its territory.
+
+Nothing here changes your project. Installing a department adds skills to Claude Code — it does not
+write to your repository, add dependencies, or run anything on its own.
+
+## Install
+
+Add the marketplace once:
+
+```
+/plugin marketplace add cbrock84/headcount
+```
+
+Then install departments one at a time:
+
+```
+/plugin install it-operations@headcount
+/plugin install security@headcount
+```
+
+`/plugin` on its own opens the plugin menu, where installed plugins can be reviewed and managed.
+
+**Install what you will use, not everything.** Sixteen departments is a lot of surface, and a
+smaller set produces sharper triggering. You can add more at any point.
+
+## Which departments to install first
+
+Start from what you actually spend your week on rather than from the org chart.
+
+| If you… | Start with |
+|---|---|
+| Run IT or infrastructure for a company | `it-operations`, `security`, `operations` |
+| Run a small company or a whole function | `executive`, `finance`, `operations` |
+| Own revenue or go-to-market | `revenue`, `marketing`, `demand-generation` |
+| Build product | `product`, `technology`, `data-analytics` |
+| Run delivery or a PMO | `pmo`, `operations` |
+| Own people or hiring | `people`, `legal-risk` |
+| Have customers to keep | `customer-experience`, `revenue` |
+
+**Add `security` and `legal-risk` early regardless of what else you install.** They are the two
+that tell you something you did not want to hear, which is the whole reason to have them.
+
+## Three ways to use it
+
+**1. Just ask.** Skills load themselves when a request matches. This is the normal path and the one
+to reach for first.
+
+> *"Our margins slipped this quarter and nobody can tell me why."*
+
+**2. Name the skill** when you want a specific lens rather than the one that would trigger:
+
+```
+/finance:cost-accounting
+```
+
+Skills are addressed as `department:skill`, so names never collide across departments.
+
+**3. Delegate a whole department.** Each department ships an agent charter in `.claude/agents/`,
+so it can be handed a body of work as a subagent with its own exclusive write surface. See
+`executive:agent-hierarchy` for the method, and why the split is by write surface rather than by
+topic.
+
+## What to expect back
+
+A skill is not a template that fills itself in. Most will start by asking you the two or three
+things that decide the answer — what the unit is, what the comparison is, who owns the consequence —
+because those are the questions that get skipped and are the reason the usual answer is wrong.
+
+Expect to be told what the library cannot determine. A skill that names its limits is doing the job;
+one that answers everything confidently is the failure mode this catalog is built against.
+
+## Reviewer-class departments behave differently
+
+`security` and `legal-risk` review what other departments commit to. They hold no write surface,
+they report to the chief executive rather than into the function they review, and **their blocking
+findings are not overrulable by the department under review.**
+
+In practice: when you ask a revenue question and the security review says the access model cannot
+support the control the deal requires, that is not a trade-off to price against the deal. The date
+moves or the control gets built. This is deliberate, and it is why those two are worth installing
+even when they are not your job.
+
+## What this is not
+
+Several skills carry an explicit disclaimer, and it is not boilerplate. Employment classification,
+tax, financing terms, contract positions, privacy obligations and regulatory filings are matters
+where the facts and the jurisdiction decide the answer. These skills structure the question and
+tell you what to ask — they are not a substitute for qualified counsel, and they say so.
+
+## Seeing what is in it
+
+The [live org chart](https://cbrock84.github.io/headcount/org-chart.html) is searchable across every
+skill in every department, generated from the repository so it cannot drift from what actually
+ships.
+
+[Worked situations](USE-CASES.md) show what happens when a problem crosses departments — what
+engages, in what order, what comes back, and where the library has nothing useful to say.
+
+## Getting help
+
+Questions, gaps and disagreements belong in
+[Discussions](https://github.com/cbrock84/headcount/discussions). A situation the catalog handles
+badly is the most useful thing you can report, more than a missing skill — the gap is usually that
+a skill exists and fails to trigger, or triggers and answers the wrong question.
diff --git a/docs/USE-CASES.md b/docs/USE-CASES.md
index 4586b51..9934420 100644
--- a/docs/USE-CASES.md
+++ b/docs/USE-CASES.md
@@ -7,6 +7,9 @@ These are the situations this catalog is shaped around. Every skill named here e
in CI fails if a reference stops resolving, so this page cannot rot as skills are renamed or
consolidated.
+New here? [Getting started](GETTING-STARTED.md) covers installing, which departments to take first,
+and the three ways to invoke a skill.
+
## Single asks
The fastest path is to just ask. Skills load themselves when a request matches.
@@ -127,6 +130,118 @@ A buyer's checklist reads your company back to you.
---
+## Situations from an operating company
+
+The situations above are shaped like a software business. These four are shaped like a company with
+sites, contracts, staff and customers — and they are where the catalog's operations, IT and finance
+depth actually shows. Each one names what comes back, not only what engages.
+
+### Two sites, one lost its link at 6am, and nobody can say whether it is the carrier or us
+
+The first hour goes to arguing about whose problem it is, which is the hour that matters.
+
+1. `operations:incident-management` — declare it, name a commander whose hands stay out of the
+ system, and start a timeline. The instinct to skip this because "it's just the link" is what
+ turns a thirty-minute outage into a four-hour one.
+2. `it-operations:network-administration` — diagnose in layers, from physical upward. The
+ multi-site section is the relevant one: a second site multiplies the failure modes, not the work.
+3. `operations:vendor-management` — the carrier is a supplier with a contract, and what you can
+ demand of them is written down somewhere nobody has read this morning.
+4. `operations:service-level-management` — whether their service level was breached, what the
+ remedy is, and whether the credit is worth the claim.
+5. `operations:business-continuity-and-resilience` — only if it runs long enough to matter, and
+ the answer is usually that the impact analysis was never done for this site.
+
+**What comes back.** A separation of two questions that get merged under pressure: *restore service*
+and *establish whose fault it is*. The first is yours regardless. The second decides whether you get
+a credit and whether you change carriers, and it is answered from the timeline you kept — not from
+memory afterward, which is unreliable within hours.
+
+**The hard part it will name.** You almost certainly cannot demonstrate the demarcation point from
+your own monitoring, which is why the carrier conversation goes in circles. That is a gap to close
+before the next outage, not during this one.
+
+### A vendor renewal auto-renewed at a 22% increase because nobody owned the date
+
+The increase is the symptom. The absence of an owner is the finding.
+
+1. `operations:vendor-management` — the renewal was lost at the notice date, not at the price. Its
+ Never list has this exact failure: reaching a renewal date without having started the renewal,
+ because the auto-renew clause is the vendor's leverage and it is designed to be.
+2. `legal-risk:contract-review` — what the notice period actually required, whether the increase is
+ within a cap you already agreed, and what leaving now costs.
+3. `finance:budgeting-and-forecasting` — the variance against plan, and whether this repeats across
+ other contracts nobody is tracking either.
+4. `it-operations:it-asset-management` — if it is software. The SaaS half of the estate is where
+ spend hides, and it is found through the expense system and single sign-on logs as much as
+ through any inventory.
+5. `operations:operating-cadence` — the actual fix: a named owner and a date that surfaces before
+ the notice window, rather than a resolution to be more careful.
+
+**What comes back.** Two separate pieces of work. The immediate one is a negotiation you are
+entering from a weak position, and it will tell you so plainly — the leverage was in the notice
+period and it is spent. The structural one is a renewal register with owners and dates, because a
+single renegotiated contract changes nothing about the next four.
+
+**Worth stating.** The honest answer on the 22% may be that you pay it this year. What you can get
+is a shorter term, a cap on the next increase, or a co-terminus date that makes the portfolio
+manageable — which is `revenue:deal-negotiation` read from the buying side.
+
+### Someone left and still had access to a shared mailbox three weeks later
+
+Every part of this is a process failure, and one part may be an incident.
+
+1. `it-operations:identity-lifecycle-administration` — the leaver path, completely. Shared mailboxes
+ and group memberships are the two that survive an offboarding built around the primary account.
+2. `it-operations:collaboration-platform-administration` — a shared mailbox with a sign-in-capable
+ account is an unmonitored identity with a password, and that is the specific shape of what
+ happened here.
+3. `security:access-and-identity` — whether the access review would ever have caught it, and
+ whether anything else is in the same state right now.
+4. `people:onboarding-and-offboarding` — offboarding has to reach identity, devices and payroll on
+ the same day, with one owner running the checklist end to end. Split ownership is exactly how
+ accounts stay live.
+5. `security:detection-and-monitoring` — the uncomfortable question: would you know whether the
+ access was used? If the answer is no, that is a bigger finding than the access itself.
+
+**Where it stops.** `security` is reviewer-class. If the mailbox held anything regulated and the
+logs cannot rule out access, that becomes an incident with notification clocks attached, and
+`legal-risk:privacy-and-data-protection` sets the obligation — a conclusion IT does not get to
+overrule on the grounds that it was probably fine.
+
+**What comes back.** A same-day containment step, a sweep for other accounts in the same condition,
+and a rewritten leaver checklist. Also a question you may not want: how you found out, because
+discovering it three weeks later by accident says the control that should have caught it does not
+exist.
+
+### Client rate cards have not been reviewed and now there is a margin problem
+
+The margin moved for a reason, and it is rarely the one people reach for first.
+
+1. `finance:cost-accounting` — decompose price, volume and mix before anything else. Without that,
+ a shift toward lower-margin work gets reported as a pricing failure and priced accordingly.
+2. `finance:financial-statement-analysis` — the trend and where it started, against prior period
+ and against plan, which answer different questions.
+3. `finance:unit-economics` — margin by client and by service rather than blended. Blended
+ economics almost always conceal one account subsidizing another, and the average is the least
+ useful number on the page.
+4. `revenue:pricing-and-packaging` — whether the rate card structure is the problem, not just the
+ levels. A metric clients cannot predict produces the disputes that erode realized rates.
+5. `revenue:deal-negotiation` — repricing an existing client is a negotiation where you have less
+ leverage than a new deal, and the concessions have to be traded rather than conceded.
+6. `customer-experience:customer-success-management` — which accounts survive a price change and
+ which are single-threaded on someone who will not defend it internally.
+
+**What comes back.** Almost always the same finding: it is not one rate card. It is a mix shift,
+an allocation basis that flatters some work and punishes other work, and two or three accounts
+priced years ago that nobody revisited. Those are three different fixes and only one of them is a
+conversation with clients.
+
+**The order matters.** Going to the client with a rate increase before the cost decomposition is
+done means arguing for a number you cannot defend, in a conversation you only get once.
+
+---
+
## How the org behaves
**Reviewer-class departments** (`security`, `legal-risk`) report to the chief executive rather than
diff --git a/docs/assets/org-chart-dark.png b/docs/assets/org-chart-dark.png
index b3841da..951633c 100644
Binary files a/docs/assets/org-chart-dark.png and b/docs/assets/org-chart-dark.png differ
diff --git a/docs/assets/org-chart-light.png b/docs/assets/org-chart-light.png
index 9047e08..7c2225d 100644
Binary files a/docs/assets/org-chart-light.png and b/docs/assets/org-chart-light.png differ
diff --git a/docs/org-chart.html b/docs/org-chart.html
index b3e92cb..afd078a 100644
--- a/docs/org-chart.html
+++ b/docs/org-chart.html
@@ -57,6 +57,32 @@
margin:12px 0 0; text-wrap:balance;
}
.lede { color:var(--ink-2); margin:12px 0 0; max-width:60ch; }
+ .use {
+ margin:30px 0 0; padding:20px 22px; border:1px solid var(--rule);
+ border-radius:10px; background:var(--paper-2);
+ }
+ .use h2 {
+ margin:0 0 4px; font-family:Archivo,sans-serif; font-size:15px;
+ letter-spacing:-.01em; font-weight:700;
+ }
+ .use p { margin:8px 0 0; color:var(--ink-2); max-width:72ch; }
+ .use code {
+ background:var(--paper); border:1px solid var(--rule); border-radius:4px;
+ padding:1px 5px; font-size:12.5px;
+ }
+ .use pre {
+ margin:10px 0 0; padding:11px 13px; background:var(--paper);
+ border:1px solid var(--rule); border-radius:7px; overflow-x:auto;
+ }
+ .use pre code { background:none; border:none; padding:0; }
+ .use .steps { display:flex; flex-wrap:wrap; gap:22px; margin-top:14px; }
+ .use .step { flex:1 1 240px; min-width:0; }
+ .use .step b {
+ display:block; font-family:Archivo,sans-serif; font-size:12px;
+ text-transform:uppercase; letter-spacing:.07em; color:var(--ink-3);
+ }
+ .use .links { margin-top:16px; padding-top:14px; border-top:1px solid var(--rule); }
+ .use .links a { margin-right:18px; white-space:nowrap; }
.figures { display:flex; flex-wrap:wrap; gap:26px; margin-top:26px; }
.figure b {
display:block; font-family:Archivo,sans-serif; font-weight:700;
@@ -250,6 +276,38 @@
</p>
<div class="figures" id="figures"></div>
+ <section class="use">
+ <h2>Using this</h2>
+ <p>
+ Sixteen departments, each an independently installable plugin for Claude Code. Install the
+ ones you need — a smaller set triggers more sharply than all of them at once.
+ </p>
+ <div class="steps">
+ <div class="step">
+ <b>1 · Add the marketplace</b>
+ <pre><code>/plugin marketplace add cbrock84/headcount</code></pre>
+ </div>
+ <div class="step">
+ <b>2 · Install a department</b>
+ <pre><code>/plugin install security@headcount</code></pre>
+ <p>Every card below carries its own install line — click one to copy it.</p>
+ </div>
+ <div class="step">
+ <b>3 · Ask</b>
+ <p>
+ Skills load themselves when a request matches. Name one directly —
+ <code>/finance:cost-accounting</code> — when you want a specific lens instead.
+ </p>
+ </div>
+ </div>
+ <p class="links">
+ <a href="https://github.com/cbrock84/headcount/blob/main/docs/GETTING-STARTED.md">Getting started</a>
+ <a href="https://github.com/cbrock84/headcount/blob/main/docs/USE-CASES.md">Worked situations</a>
+ <a href="https://github.com/cbrock84/headcount/discussions">Ask a question</a>
+ <a href="https://github.com/cbrock84/headcount">Source</a>
+ </p>
+ </section>
+
<div class="controls">
<input id="q" type="search" placeholder="Search 172 skills — try “threat”, “pricing”, “backup”…" autocomplete="off">
<button class="btn" id="revonly" aria-pressed="false">Reviewer-class only</button>
diff --git a/scripts/build-org-chart.py b/scripts/build-org-chart.py
index 0e364a7..8d5c2b2 100755
--- a/scripts/build-org-chart.py
+++ b/scripts/build-org-chart.py
@@ -164,6 +164,32 @@ TEMPLATE = r"""<meta charset="utf-8">
margin:12px 0 0; text-wrap:balance;
}
.lede { color:var(--ink-2); margin:12px 0 0; max-width:60ch; }
+ .use {
+ margin:30px 0 0; padding:20px 22px; border:1px solid var(--rule);
+ border-radius:10px; background:var(--paper-2);
+ }
+ .use h2 {
+ margin:0 0 4px; font-family:Archivo,sans-serif; font-size:15px;
+ letter-spacing:-.01em; font-weight:700;
+ }
+ .use p { margin:8px 0 0; color:var(--ink-2); max-width:72ch; }
+ .use code {
+ background:var(--paper); border:1px solid var(--rule); border-radius:4px;
+ padding:1px 5px; font-size:12.5px;
+ }
+ .use pre {
+ margin:10px 0 0; padding:11px 13px; background:var(--paper);
+ border:1px solid var(--rule); border-radius:7px; overflow-x:auto;
+ }
+ .use pre code { background:none; border:none; padding:0; }
+ .use .steps { display:flex; flex-wrap:wrap; gap:22px; margin-top:14px; }
+ .use .step { flex:1 1 240px; min-width:0; }
+ .use .step b {
+ display:block; font-family:Archivo,sans-serif; font-size:12px;
+ text-transform:uppercase; letter-spacing:.07em; color:var(--ink-3);
+ }
+ .use .links { margin-top:16px; padding-top:14px; border-top:1px solid var(--rule); }
+ .use .links a { margin-right:18px; white-space:nowrap; }
.figures { display:flex; flex-wrap:wrap; gap:26px; margin-top:26px; }
.figure b {
display:block; font-family:Archivo,sans-serif; font-weight:700;
@@ -357,6 +383,38 @@ TEMPLATE = r"""<meta charset="utf-8">
</p>
<div class="figures" id="figures"></div>
+ <section class="use">
+ <h2>Using this</h2>
+ <p>
+ Sixteen departments, each an independently installable plugin for Claude Code. Install the
+ ones you need — a smaller set triggers more sharply than all of them at once.
+ </p>
+ <div class="steps">
+ <div class="step">
+ <b>1 · Add the marketplace</b>
+ <pre><code>/plugin marketplace add cbrock84/headcount</code></pre>
+ </div>
+ <div class="step">
+ <b>2 · Install a department</b>
+ <pre><code>/plugin install security@headcount</code></pre>
+ <p>Every card below carries its own install line — click one to copy it.</p>
+ </div>
+ <div class="step">
+ <b>3 · Ask</b>
+ <p>
+ Skills load themselves when a request matches. Name one directly —
+ <code>/finance:cost-accounting</code> — when you want a specific lens instead.
+ </p>
+ </div>
+ </div>
+ <p class="links">
+ <a href="https://github.com/cbrock84/headcount/blob/main/docs/GETTING-STARTED.md">Getting started</a>
+ <a href="https://github.com/cbrock84/headcount/blob/main/docs/USE-CASES.md">Worked situations</a>
+ <a href="https://github.com/cbrock84/headcount/discussions">Ask a question</a>
+ <a href="https://github.com/cbrock84/headcount">Source</a>
+ </p>
+ </section>
+
<div class="controls">
<input id="q" type="search" placeholder="Search 135 skills — try “threat”, “pricing”, “backup”…" autocomplete="off">
<button class="btn" id="revonly" aria-pressed="false">Reviewer-class only</button>
diff --git a/scripts/build-readme.py b/scripts/build-readme.py
index 9da4c9d..55e2fc5 100755
--- a/scripts/build-readme.py
+++ b/scripts/build-readme.py
@@ -129,10 +129,14 @@ 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.",
+ "New to this? [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) covers which departments to",
+ "install first, the three ways to invoke a skill, and what reviewer-class departments do",
+ "differently.",
+ "",
+ "Eleven situations that cross departments — a SOC 2 demand from an enterprise prospect, a link",
+ "down between two sites, a renewal that auto-renewed because nobody owned the date — are worked",
+ "through end to end in [docs/USE-CASES.md](docs/USE-CASES.md), including what comes back and",
+ "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.",
@@ -163,6 +167,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/GETTING-STARTED.md install, what to take first, and how to invoke a skill",
"docs/USE-CASES.md situations worked end to end across departments",
"docs/org-chart.html interactive org chart, searchable across every skill",
"docs/index.html GitHub Pages entry point, redirects to the chart",