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 security department, MIT licence, and a generated README

Chris Brock4c1a9d28151d
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 54dfc19..f9429c2 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -174,6 +174,22 @@
"contracts"
],
"category": "legal-risk"
+ },
+ {
+ "name": "security",
+ "source": "./plugins/security",
+ "description": "Threat modeling, security architecture review, incident response, vulnerability management, and access and identity. Reviewer-class.",
+ "version": "1.0.0",
+ "author": {
+ "name": "Chris Brock"
+ },
+ "keywords": [
+ "security",
+ "appsec",
+ "incident-response",
+ "identity"
+ ],
+ "category": "security"
}
]
}
diff --git a/.claude/agents/security-review.md b/.claude/agents/security-review.md
new file mode 100644
index 0000000..7c3d26a
--- /dev/null
+++ b/.claude/agents/security-review.md
@@ -0,0 +1,45 @@
+---
+name: security-review
+description: Reviewer-class. Read-only security review of what other departments build — authorization, data handling, secrets, dependencies, and designs that create exposure. Holds no write surface. Blocking findings are not overrulable by the department under review.
+---
+
+# Security review
+
+## Why this agent exists
+
+Engineering does not sign off on its own security exceptions. Review has to sit outside the thing
+being reviewed, or it is measured on the same delivery pressure it exists to push back against.
+
+## Surface
+
+**None.** Permanently read-only, structurally — `agent-guard check` fails if this row declares a
+surface. Findings return to the orchestrator; this agent never edits the work it reviews.
+
+## What it reviews
+
+- Authorization and multi-tenant isolation on anything handling user data.
+- Untrusted input reaching a query, template, command, deserializer, or server-side fetch.
+- Secrets in source, bundles, or logs.
+- New dependencies and what they can reach.
+- Designs whose failure mode is a compromise rather than an outage.
+
+## Standard
+
+Load `security:security-architecture-review` for method. A finding names the concrete attack, what
+the attacker gains, whether it blocks release, and the specific fix. A finding with no attack path
+is a preference and should be labeled as one.
+
+## Independence
+
+A department under review cannot close a blocking finding from this agent. Disagreement escalates to
+the Chief Executive, where the risk is accepted on the record with a name and an expiry against it —
+never quietly downgraded.
+
+## Return contract
+
+1. What was reviewed.
+2. Findings by severity, each with attack path, impact, and fix.
+3. Which are blocking.
+4. What needs qualified counsel or specialist review.
+5. What was checked and found clean.
+6. Open questions for the orchestrator.
diff --git a/.claude/agents/security.md b/.claude/agents/security.md
new file mode 100644
index 0000000..6f6053f
--- /dev/null
+++ b/.claude/agents/security.md
@@ -0,0 +1,39 @@
+---
+name: security
+description: Security (CISO). Owns plugins/security/** and nothing else. Delegate threat modeling, security architecture, incident response, vulnerability management, and identity work here.
+---
+
+# Security (CISO)
+
+## Why this agent exists
+
+The single owner of `plugins/security/**`. Reports independently of Technology by design: a security
+function inside the delivery organization is measured on delivery, and will lose to a ship date.
+
+## Surface
+
+Writes: `plugins/security/**` — currently 6 skills.
+Reads: anything. Commits: nothing; the orchestrator is the sole committer.
+
+## Standard
+
+Load `security:chief-information-security-officer` for the remit. Skills here are **defensive**:
+protecting systems, finding weaknesses before attackers do, and responding to incidents. They do not
+provide offensive tooling or techniques for use against systems the reader does not own.
+
+Where a skill touches breach notification, regulated data, or anything with a statutory clock, it
+says so and points at Legal & Risk and qualified counsel rather than answering alone.
+
+## Verification this surface implies
+
+- `./scripts/check-all.sh` passes.
+- No change outside `plugins/security/**`.
+
+## Return contract
+
+1. What changed, by file.
+2. Why.
+3. What was verified, with output.
+4. Anything left undone.
+5. Any change needed outside this surface.
+6. Open questions for the orchestrator.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..1d1ec69
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Brock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index afde2ea..235bed7 100644
--- a/README.md
+++ b/README.md
@@ -1,139 +1,191 @@
# agents-v1
-An agent organization structured as a company: a chief executive over ten departments, each led
-by a C-level agent with specialists beneath it.
+An agent organization for [Claude Code](https://claude.com/claude-code), structured as a company:
+a chief executive over 11 departments, 86 skills in total.
Every department is an independently installable plugin, so a project loads only the functions it
-There are 79 skills across the ten departments.
+needs rather than all of them at once.
-needs.
+## Install
```
/plugin marketplace add cbrock84/agents-v1
-/plugin install finance@agents-v1
+/plugin install security@agents-v1
```
-This repository is **private**, so the installing machine must be authenticated to it. Visibility is
-an open question — see D16.
+Install as many departments as the project needs. Skills are addressed as `department:skill` —
+`security:threat-modeling`, `finance:unit-economics` — so names never collide.
-Skills are addressed as `department:skill` — `finance:unit-economics`, `revenue:pricing-and-packaging`.
+## Use
-All content in this repository is original. See [`docs/org-chart.md`](docs/org-chart.md) for the
-reporting structure and remaining gaps.
+Skills load themselves when a request matches. Ask a question in the department's territory and the
+right specialist engages:
+
+| You ask | What loads |
+|---|---|
+| "why isn't this landing page converting?" | `demand-generation:landing-page-cro-expert` |
+| "review this design before we build it" | `security:threat-modeling` |
+| "can we afford this hire?" | `finance:unit-economics` |
+| "our growth has stalled" | `executive:business-growth-consultant` |
+
+Invoke one directly by name when you want a specific lens: `/finance:financial-modeling`.
+
+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.
## Departments
-### `executive` — Office of the CEO (Chief Executive) · 6 skills
+<details>
+<summary><b>Office of the CEO</b> (Chief Executive) — 6 skills</summary>
| Skill | What it does |
|---|---|
-| `agent-hierarchy` | Designs orchestrator-and-subagent hierarchies for a repository — splitting agents by exclusive write surface, pairing every producer with an independent auditor, and enf…. |
-| `ai-research-analyst` | Conducts executive-level market research, competitor analysis, trend discovery, and strategic business intelligence grounded in current, cited sources. |
-| `business-growth-consultant` | Identifies the real constraint on a business's growth and the highest-leverage moves to increase revenue, profitability, and retention while scaling sustainably. |
-| `ceo-advisor` | Acts as an experienced CEO coach and strategic advisor who helps founders make better decisions, prioritize ruthlessly, pressure-test plans, and lead with clarity. |
+| `agent-hierarchy` | Designs orchestrator-and-subagent hierarchies for a repository — splitting agents by exclusive write surface, pairing every producer with an independent auditor, an…. |
+| `ai-research-analyst` | Produces executive-level research — market sizing, competitor mapping, trend analysis, and strategic intelligence — grounded in cited sources with the confidence in…. |
+| `business-growth-consultant` | Finds the single constraint currently limiting a business's growth and the highest-leverage moves against it, rather than producing a list of everything that could…. |
+| `ceo-advisor` | Pressure-tests a decision, plan, or idea before it is committed to — surfacing the assumption it rests on, the case against it, and what would have to be true for i…. |
| `chief-executive` | Sets direction, allocates capital and attention, and makes the calls no one else can make. |
-| `saas-idea-validator` | Evaluates SaaS and startup ideas with brutal honesty across problem, market, competition, monetization, defensibility, and execution, and returns a clear verdict rather…. |
+| `saas-idea-validator` | Evaluates a software or startup idea against problem, market, competition, monetization, defensibility, and execution, and returns a verdict rather than encourageme…. |
-### `technology` — Technology (CTO / CIO) · 12 skills
+</details>
+
+<details>
+<summary><b>Technology</b> (CTO / CIO) — 12 skills</summary>
| Skill | What it does |
|---|---|
-| `ai-workflow-architect` | Designs complete AI systems, automations, and agent workflows for businesses using tools like Claude, ChatGPT, MCP servers, APIs, and automation platforms. |
+| `ai-workflow-architect` | Designs AI systems, automations, and agent workflows for a business — identifying which manual work is worth automating, how to structure the system, which tools fi…. |
| `branch-and-worktree-workflow` | Isolates feature work in its own branch or worktree and integrates it cleanly when done. |
| `chief-technology-officer` | Owns architecture, engineering delivery, infrastructure, data platform, and internal systems. |
| `code-review` | Conducts and responds to code review — reviewing a change for correctness, design, and risk, and evaluating review feedback received on your own work. |
-| `completion-verification` | Verifies that work is actually complete before it is claimed to be — running the checks, reading the output, and confirming the original request was satisfied rather tha…. |
+| `completion-verification` | Verifies that work is actually complete before it is claimed to be — running the checks, reading the output, and confirming the original request was satisfied rathe…. |
| `implementation-planning` | Turns a spec or requirement into a written plan a separate session or agent can execute, then drives that plan through review checkpoints. |
| `parallel-agent-delivery` | Splits work across multiple agents or sessions running at once, keeping their surfaces disjoint so results merge cleanly. |
-| `prompt-optimizer` | Transforms rough ideas and weak prompts into production-quality prompts for Claude, ChatGPT, Gemini, and other AI models using real prompt-engineering technique, not sup…. |
+| `prompt-optimizer` | Turns rough intent or a weak prompt into a reliable one — diagnosing why output is inconsistent, restructuring the instruction, and adapting it across models. |
| `skill-authoring` | Writes and revises agent skills so they trigger at the right moments and give usable instruction when they do. |
-| `solution-exploration` | Explores the problem and the range of possible approaches before any code is written — clarifying what is actually being asked, surfacing options with their tradeoffs, a…. |
+| `solution-exploration` | Explores the problem and the range of possible approaches before any code is written — clarifying what is actually being asked, surfacing options with their tradeof…. |
| `systematic-debugging` | Finds the root cause of a bug, test failure, or unexpected behavior before proposing any fix. |
| `test-driven-development` | Drives implementation by writing a failing test first, then the smallest code that passes it. |
-### `product` — Product (CPO) · 9 skills
+</details>
+
+<details>
+<summary><b>Security</b> (CISO) — 6 skills · **reviewer-class**</summary>
| Skill | What it does |
|---|---|
-| `brand-identity` | Defines and applies visual brand — logo usage, palette, typography, imagery direction, and the guidelines that keep expression consistent across product and marketing su…. |
+| `access-and-identity` | Designs and audits who can reach what — authentication, authorization models, privileged access, service credentials, and joiner-mover-leaver process. |
+| `chief-information-security-officer` | Owns the security posture of the organization — architecture, program strategy, risk acceptance, incident command, and the authority to stop work that creates unacc…. |
+| `incident-response` | Runs a security incident from detection to closure — triage, containment, investigation, communication, and the review afterward. |
+| `security-architecture-review` | Reviews a design or change for security before it ships — authentication and authorization, data handling, secrets, dependencies, and the secure-development practic…. |
+| `threat-modeling` | Identifies what could go wrong in a system before it is built or changed — the assets worth attacking, the entry points, the trust boundaries, and the controls that…. |
+| `vulnerability-management` | Runs the loop from discovering a weakness to confirming it is fixed — scanning, triage, prioritization by real exploitability, remediation tracking, and patch policy. |
+
+</details>
+
+<details>
+<summary><b>Product</b> (CPO) — 9 skills</summary>
+
+| Skill | What it does |
+|---|---|
+| `brand-identity` | Defines and applies visual brand — logo usage, palette, typography, imagery direction, and the guidelines that keep expression consistent across product and marketi…. |
| `chief-product-officer` | Owns what gets built and why: product strategy, roadmap, discovery, user experience, and the definition of success for each release. |
-| `design-styles` | Applies a deliberate visual direction to an interface — minimalist editorial, industrial utilitarian, or high-polish commercial — each with its own type scale, palette b…. |
-| `design-system` | Builds and maintains the design system a product is assembled from — tokens for color, type, spacing and elevation, component contracts, and the rules that keep them coh…. |
-| `interface-craft` | Raises the visual and interaction quality of an interface — layout, hierarchy, type, spacing, density, and the details that separate a considered product from a generic…. |
-| `interface-redesign` | Upgrades an existing interface to a higher standard without rebuilding it — auditing what is there, identifying what reads as generic or unfinished, and sequencing chang…. |
+| `design-styles` | Applies a deliberate visual direction to an interface — minimalist editorial, industrial utilitarian, or high-polish commercial — each with its own type scale, pale…. |
+| `design-system` | Builds and maintains the design system a product is assembled from — tokens for color, type, spacing and elevation, component contracts, and the rules that keep the…. |
+| `interface-craft` | Raises the visual and interaction quality of an interface — layout, hierarchy, type, spacing, density, and the details that separate a considered product from a gen…. |
+| `interface-redesign` | Upgrades an existing interface to a higher standard without rebuilding it — auditing what is there, identifying what reads as generic or unfinished, and sequencing…. |
| `presentation-design` | Designs slide decks, one-pagers, and marketing graphics that carry an argument rather than decorate one. |
-| `ux-product-auditor` | Performs senior-level UX, conversion (CRO), usability, and product-strategy audits that tie every finding to a business outcome. |
-| `visual-reference-generation` | Produces design reference imagery before implementation — screen concepts, layout directions, and flows for web or mobile that make a verbal brief concrete enough to arg…. |
+| `ux-product-auditor` | Audits a website, app, onboarding flow, or design for usability, conversion, and product problems, tying every finding to a business outcome and a severity. |
+| `visual-reference-generation` | Produces design reference imagery before implementation — screen concepts, layout directions, and flows for web or mobile that make a verbal brief concrete enough t…. |
+
+</details>
-### `marketing` — Marketing (CMO) · 16 skills
+<details>
+<summary><b>Marketing</b> (CMO) — 17 skills</summary>
| Skill | What it does |
|---|---|
+| `behavioral-marketing` | Applies decision science and cognitive bias research to marketing and product decisions — how people actually choose under uncertainty, and how framing, defaults, s…. |
| `brand-voice` | Captures how a person or brand actually writes and turns it into reusable voice instructions every other content skill draws from. |
-| `chief-content-officer` | Acts as a strategic Head of Content who researches the market, analyzes competitors, and builds content strategies and production-ready assets optimized for business out…. |
+| `chief-content-officer` | Runs content as an operation — the production pipeline, editorial calendar, repurposing engine, competitive content intelligence, and audits of what already exists. |
| `chief-marketing-officer` | Owns brand, demand generation, content, communications, and how the market understands what the business does. |
| `content-strategy` | Decides what content to make and why — topic territory, format mix, cadence, and how content connects to a business outcome rather than to traffic. |
| `customer-research` | Plans, runs, and synthesizes customer research — interviews, surveys, win-loss analysis, and message testing — into findings that change decisions. |
-| `marketing-campaign-planner` | Designs complete, coordinated multi-channel marketing campaigns and product launches built around one clear story, from strategy through timeline, content, and launch ch…. |
+| `marketing-campaign-planner` | Designs a coordinated multi-channel campaign or product launch around one story — objective, message, channel sequencing, timeline, assets, and the checklist that g…. |
| `marketing-copywriting` | Writes and edits marketing copy for any surface — homepage, product and pricing pages, ads, emails, and collateral — and sharpens existing copy that is not working. |
| `marketing-planning` | Builds the marketing plan of record — objectives, channel mix, budget allocation, sequencing, and the measurement that says whether it worked. |
-| `newsletter-writer` | Writes high-performing newsletters and marketing emails that people actually look forward to opening, built to educate, engage, and convert without sacrificing trust. |
+| `newsletter-writer` | Writes and edits newsletters and marketing emails people actually open — subject lines, opening, structure, voice, and the conversion turn where there is one. |
| `partnership-marketing` | Builds reach through other people's audiences — co-marketing partnerships, creator and influencer programs, community building, and affiliate arrangements. |
| `positioning-and-messaging` | Establishes what a product is understood to be, for whom, and instead of what — then turns that into the messaging every other surface inherits. |
| `public-relations` | Plans and executes earned media — press strategy, journalist outreach, announcements, commentary, and crisis response. |
| `social-post-craft` | Writes, structures, and evaluates social posts end to end — hooks, body, formatting for how each platform renders, and a quality check before publishing. |
| `video-content` | Plans and scripts short-form and long-form video, and designs the packaging — titles, thumbnails, and openings — that determines whether it gets watched. |
-| `visual-content` | Designs and directs the visual assets that carry content — carousels, infographics, quote graphics, diagrams, and social imagery — including the generation prompts where…. |
-| `youtube-producer` | Plans, packages, scripts, and optimizes long-form YouTube videos for retention and channel growth. |
+| `visual-content` | Designs and directs the visual assets that carry content — carousels, infographics, quote graphics, diagrams, and social imagery — including the generation prompts…. |
+| `youtube-producer` | Plans, packages, and scripts long-form video for retention and channel growth — idea selection, titles and thumbnails, script structure, and diagnosing why a video…. |
+
+</details>
-### `demand-generation` — Demand Generation (CMO) · 11 skills
+<details>
+<summary><b>Demand Generation</b> (CMO) — 11 skills</summary>
| Skill | What it does |
|---|---|
| `ai-search-optimization` | Optimizes for AI assistants and AI-generated answers — being retrievable, being cited, and being represented accurately when a model answers on your behalf. |
-| `app-store-optimization` | Improves visibility and conversion in the App Store and Google Play — metadata, keywords, screenshots, ratings, and the listing experience that turns an impression into…. |
+| `app-store-optimization` | Improves visibility and conversion in the App Store and Google Play — metadata, keywords, screenshots, ratings, and the listing experience that turns an impression…. |
| `experimentation` | Designs, runs, and reads A/B tests and growth experiments — hypothesis, sample size, duration, and honest interpretation. |
-| `landing-page-cro-expert` | Audits, optimizes, and rewrites landing pages and sales pages using proven conversion-rate-optimization principles to increase signups, sales, and leads. |
+| `landing-page-cro-expert` | Audits and rewrites landing pages, homepages, and sales pages to increase conversion — diagnosing why a page is not converting, rewriting headlines, hero copy and c…. |
| `lead-capture` | Converts anonymous traffic into known contacts — lead magnets, gated content, free tools, popups, and the forms behind them. |
-| `lifecycle-messaging` | Designs automated email and SMS programs — welcome and onboarding sequences, nurture, re-engagement, transactional messaging, and the timing and segmentation behind them. |
+| `lifecycle-messaging` | Designs automated email and SMS programs — welcome and onboarding sequences, nurture, re-engagement, transactional messaging, and the timing and segmentation behind…. |
| `listing-distribution` | Gets a product listed where buyers and crawlers look — directories, marketplaces, review sites, comparison pages, and aggregators. |
| `marketing-analytics` | Sets up, audits, and reports on marketing measurement — tracking plans, event schemas, attribution models, and the dashboards built on them. |
-| `paid-advertising` | Plans, runs, and optimizes paid acquisition across search, social, and display — account structure, targeting, creative, bidding, budget, and the analysis that says whet…. |
-| `programmatic-seo` | Builds large sets of search-targeted pages from a template and a dataset — the location, comparison, integration, and use-case pages that capture long-tail demand at sca…. |
-| `seo-strategy` | Audits and improves organic search performance — technical health, site architecture, internal linking, structured data, and the content decisions that determine what ca…. |
+| `paid-advertising` | Plans, runs, and optimizes paid acquisition across search, social, and display — account structure, targeting, creative, bidding, budget, and the analysis that says…. |
+| `programmatic-seo` | Builds large sets of search-targeted pages from a template and a dataset — the location, comparison, integration, and use-case pages that capture long-tail demand a…. |
+| `seo-strategy` | Audits and improves organic search performance — technical health, site architecture, internal linking, structured data, and the content decisions that determine wh…. |
-### `revenue` — Revenue (CRO) · 8 skills
+</details>
+
+<details>
+<summary><b>Revenue</b> (CRO) — 8 skills</summary>
| Skill | What it does |
|---|---|
-| `activation` | Gets new users from signup to first real value — signup flow, onboarding, time-to-value, and the early experience that determines whether someone becomes a user or a lap…. |
+| `activation` | Gets new users from signup to first real value — signup flow, onboarding, time-to-value, and the early experience that determines whether someone becomes a user or…. |
| `chief-revenue-officer` | Owns the revenue engine end to end: sales, monetization, pricing, customer success, retention, and partnerships. |
-| `outbound-prospecting` | Finds, qualifies, and reaches prospects through cold outreach — list building, qualification criteria, cold email and multi-channel sequences, and the follow-up that act…. |
+| `outbound-prospecting` | Finds, qualifies, and reaches prospects through cold outreach — list building, qualification criteria, cold email and multi-channel sequences, and the follow-up tha…. |
| `pricing-and-packaging` | Sets price, structures packages and tiers, and designs the monetization surfaces that carry them — upgrade paths, paywalls, and offer construction. |
| `referral-programs` | Designs and improves referral, affiliate, and word-of-mouth programs — incentive structure, mechanics, timing, and fraud control. |
| `retention` | Diagnoses and reduces churn — cancellation flows, save offers, failed-payment recovery, at-risk detection, and the product and service causes underneath. |
-| `revenue-operations` | Runs the mechanics of the revenue engine — lead lifecycle definitions, routing, CRM hygiene, forecasting process, pipeline reporting, and the marketing-to-sales handoff. |
+| `revenue-operations` | Runs the mechanics of the revenue engine — lead lifecycle definitions, routing, CRM hygiene, forecasting process, pipeline reporting, and the marketing-to-sales han…. |
| `sales-enablement` | Builds what a sales team needs to sell — pitch decks, one-pagers, objection handling, competitive battlecards, demo scripts, and case studies. |
-### `finance` — Finance (CFO) · 4 skills
+</details>
+
+<details>
+<summary><b>Finance</b> (CFO) — 4 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. |
| `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 sensitivities th…. |
-| `unit-economics` | Establishes whether the business makes money on each customer or unit — contribution margin, acquisition cost, payback period, lifetime value, and the cohort behavior un…. |
+| `financial-modeling` | Builds and stress-tests financial models for forecasting, scenario planning, and decision support — revenue build, cost structure, driver logic, and the sensitiviti…. |
+| `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…. |
-### `operations` — Operations (COO) · 4 skills
+</details>
+
+<details>
+<summary><b>Operations</b> (COO) — 4 skills</summary>
| Skill | What it does |
|---|---|
| `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 that hold. |
+| `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. |
| `vendor-management` | Selects, contracts, and manages suppliers and vendors — requirements, evaluation, negotiation support, onboarding, performance management, and exit. |
-### `people` — People (CHRO) · 4 skills
+</details>
+
+<details>
+<summary><b>People</b> (CHRO) — 4 skills</summary>
| Skill | What it does |
|---|---|
@@ -142,56 +194,57 @@ reporting structure and remaining gaps.
| `hiring-and-interviewing` | Designs and runs hiring — role definition, sourcing, interview loop design, structured evaluation, and the decision itself. |
| `org-design` | Designs how an organization is structured — reporting lines, team boundaries, spans and layers, role definition, and workforce planning against the strategy. |
-### `legal-risk` — Legal & Risk (CLO / CCO) · 4 skills
+</details>
-| Skill | What it does |
-|---|---|
-| `chief-legal-and-risk-officer` | Owns legal, contracts, intellectual property, regulatory compliance, privacy, security governance, enterprise risk, and audit readiness. |
-| `contract-review` | Reviews and negotiates commercial agreements — MSAs, SOWs, order forms, NDAs, vendor and data-processing agreements — identifying material risk, proposing positions, and…. |
-| `enterprise-risk` | Identifies, assesses, and tracks organizational risk — building and maintaining a risk register, scoring exposure, assigning owners and treatments, and preparing for aud…. |
-| `privacy-and-data-protection` | Assesses and improves how personal data is collected, used, shared, and retained — data mapping, lawful basis, consent, processor agreements, subject rights, and breach…. |
-
-### `administration` — Administration (CAO) · 1 skills
+<details>
+<summary><b>Legal & Risk</b> (CLO / CCO) — 5 skills · **reviewer-class**</summary>
| Skill | What it does |
|---|---|
-| `chief-administrative-officer` | Owns corporate services and the administrative spine: facilities, corporate records, board and governance support, insurance, internal communications, and the shared ser…. |
-
-## Provenance
+| `chief-legal-and-risk-officer` | Owns legal, contracts, intellectual property, regulatory compliance, privacy, security governance, enterprise risk, and audit readiness. |
+| `contract-review` | Reviews and negotiates commercial agreements — MSAs, SOWs, order forms, NDAs, vendor and data-processing agreements — identifying material risk, proposing positions…. |
+| `corporate-governance` | Maintains the corporate record and the governance machinery — entity records, board and committee support, resolutions and minutes, delegations of authority, insura…. |
+| `enterprise-risk` | Identifies, assesses, and tracks organizational risk — building and maintaining a risk register, scoring exposure, assigning owners and treatments, and preparing fo…. |
+| `privacy-and-data-protection` | Assesses and improves how personal data is collected, used, shared, and retained — data mapping, lawful basis, consent, processor agreements, subject rights, and br…. |
-Every skill in this repository was written for it. An earlier revision vendored four MIT-licensed
-open-source collections; those were removed in full — skills, reference material, bundled datasets,
-fonts, and license files — and the capabilities were re-authored from scratch rather than
-paraphrased. Nothing in this repository carries a third-party license obligation.
+</details>
-The gap-department skills in `finance`, `people`, `legal-risk`, and `operations` were scoped against
-current senior job postings for those functions, so the remit matches what the roles actually cover.
+**Reviewer-class departments** (`security`, `legal-risk`) review what other departments build, and
+their blocking findings are not overrulable by the department under review. That is why the CISO
+and the CLO report to the chief executive rather than into the function they oversee.
-## Structure
+## How it is organized
```
plugins/<department>/
.claude-plugin/plugin.json department manifest
- skills/<skill>/SKILL.md frontmatter name must equal the directory name
+ skills/<skill>/SKILL.md frontmatter name equals the directory name
+.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
```
-Adding a department: create the directory pair, write the manifest, add it to
-`.claude-plugin/marketplace.json`, and give it a chief before any specialists.
+Agents split by **exclusive write surface**, not by topic — a topic split has no checkable
+boundary, and two agents working on "SEO" and "UI" both end up in the same file. See
+`executive:agent-hierarchy` for the method.
-## Checks
+## Contributing
```
./scripts/check-all.sh
```
Verifies the surface map is coherent, every skill's frontmatter is valid and unique, no third-party
-licence text or font assets have reappeared, and every manifest parses. CI calls the same script, so
-the two cannot drift.
+licence text has appeared, and every manifest parses. CI runs the same script.
+
+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
+the check fails.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Every skill here was written for this repository.
-## Related docs
+---
-- [`docs/AGENT-SURFACES.md`](docs/AGENT-SURFACES.md) — write-surface map, enforced by the checks
-- [`docs/DECISION-LOG.md`](docs/DECISION-LOG.md) — open decisions, numbered, with recommendations
-- [`docs/org-chart.md`](docs/org-chart.md) — reporting structure and remaining gaps
-- [`docs/cross-org-sweep-prompt.md`](docs/cross-org-sweep-prompt.md) — sweeping other GitHub orgs
-- `executive:agent-hierarchy` — the method behind this structure
+<sub>README generated by `scripts/build-readme.py` — edit that, not this file.</sub>
diff --git a/docs/AGENT-SURFACES.md b/docs/AGENT-SURFACES.md
index 2b016cb..0300813 100644
--- a/docs/AGENT-SURFACES.md
+++ b/docs/AGENT-SURFACES.md
@@ -28,9 +28,10 @@ finance builder installed
operations builder installed
people builder installed
legal-risk builder installed
+security builder installed
repo-meta builder installed
legal-risk-review reviewer installed
-security-review reviewer planned
+security-review reviewer installed
```
Charters live in `.claude/agents/`, one per installed row. A row marked `installed` without a
@@ -77,6 +78,10 @@ plugins/people/**
```surface:legal-risk
plugins/legal-risk/**
```
+```surface:security
+plugins/security/**
+```
+
```surface:repo-meta
docs/**
scripts/**
@@ -97,7 +102,10 @@ commit to, holds no surface in that capacity, and its findings are not overrulab
under review. Disagreement escalates to the Chief Executive rather than resolving inside the
reviewed department. See D13.
-`security-review` activates when the `security` department is built (D9).
+`security` mirrors `legal-risk`: a builder owning `plugins/security/**`, and separately
+`security-review`, reviewer-class over what other departments build. Its blocking findings are not
+overrulable by the department under review, which is why the CISO reports independently rather than
+under the CTO (D9, D13).
## Rules
diff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.md
index f60b99a..e384b59 100644
--- a/docs/DECISION-LOG.md
+++ b/docs/DECISION-LOG.md
@@ -115,8 +115,9 @@ PR #1 only ever carried the 12 Drive-sourced skills.
without destroying the review trail, since deleting the merged branch unreferences the commits
anyway. Choose (b) only if you want them gone before merge.
-**Resolution: (a).** Squash-merge PR #2, then delete the branch — the merged branch's deletion
-unreferences the three commits carrying vendored paths.
+**Resolution: (a) — done.** PR #2 squash-merged as `cc77e22`; branch deleted. `main` carries a single
+clean commit, and no licensed path was ever added on `main` across its whole history. The three
+commits carrying the vendored tree are unreachable.
---
@@ -385,13 +386,66 @@ of decisions.
| 2 | Fold `administration` into `legal-risk` + `executive`; delete the department | D12 | — | ✅ done |
| 3 | Mark `legal-risk` reviewer-class in its charter | D13 | — | ✅ done |
| 4 | Write `docs/AGENT-SURFACES.md`; add first CI workflow running `agent-guard check` | D14 | — | ✅ done |
-| 5 | Mark PR #2 ready; squash-merge; delete the branch | D5, D15 | 6+ |
-| 6 | Build `security` department + CISO charter, marked reviewer-class | D9, D10, D13 | — |
-| 7 | Deepen `operations`, then `finance`, then `people` | D10 | — |
-| 8 | Catalogue the other organizations' public repos — no import | D11 | — |
-| 9 | Start a separate session for the private sweep | D11 | — |
-| 10 | Build the vertical generator: core, per-vertical config, one-way emit | D8 | — |
-| 11 | Revisit repo visibility | D16 | after 1 |
+| 5 | Mark PR #2 ready; squash-merge; delete the branch | D5, D15 | 6+ | ✅ done |
+| 6 | Build `security` department + CISO charter, marked reviewer-class | D9, D10, D13 | — | ✅ done |
+| 7 | Deepen `operations`, then `finance`, then `people` | D10 | — | |
+| 8 | Catalogue the other organizations' public repos — no import | D11 | — | |
+| 9 | Start a separate session for the private sweep | D11 | — | |
+| 10 | Build the vertical generator: core, per-vertical config, one-way emit | D8 | — | |
+| 11 | Revisit repo visibility | D16 | after 1 | |
Items 1–4 can proceed in parallel; all four land before item 5. Item 9 needs a session started
outside this one — see `docs/cross-org-sweep-prompt.md`.
+
+---
+
+# Open decisions
+
+Raised after the first sixteen were resolved. Same convention: numbers are addresses, assigned when
+asked.
+
+## D17. Which department is the next real gap — 🔵 Open
+
+With `security` built, the catalogue covers eleven departments. Three functions a Fortune 500 has
+that this does not:
+
+- **(a) Customer Experience / Support.** Every business has support; the catalogue has none.
+ `revenue:retention` is the only adjacent skill. Needed: support operations, escalation handling,
+ voice-of-customer, service-level design. ← **recommended**
+- (b) **Data & Analytics (CDO).** `demand-generation:marketing-analytics` covers marketing
+ measurement only. No data governance, warehouse modeling, BI, or AI/ML governance — the last is
+ increasingly a board obligation.
+- (c) **Corporate Strategy / Corp Dev.** M&A, diligence, scenario planning, competitive war-gaming.
+- (d) None — deepen the eleven that exist instead.
+
+**Recommendation: (a), then (b).** Support is the most conspicuous absence to anyone reading the
+catalogue — it is the department every company has and this one does not. Data & Analytics is the
+one most likely to be expected of a modern org chart. Corp Dev is real but only bites at a scale
+this repo's likely users have not reached.
+
+## D18. Repository visibility, now that all content is original — 🔵 Open
+
+D16 deferred this until the rewrite landed. It has. Nothing in the repository now carries a
+third-party obligation, and `scripts/check-provenance.py` fails the build if that changes.
+
+- **(a) Make it public under MIT.** The install path in the README then works for anyone. ←
+ **recommended**
+- (b) Stay private and document the authentication requirement.
+- (c) Public, but wait until the vertical generator (D8) decides whether per-vertical repos are the
+ distributed artifact instead.
+
+**Recommendation: (a).** The blocker was provenance and it is resolved. Publishing does not commit
+you on D8 — a generator can emit per-vertical repos later regardless of whether this one is public.
+
+## D19. README drift — 🔵 Open
+
+`scripts/build-readme.py` regenerates the README from the tree, and `check-all.sh` fails if it is
+stale. This works but means the README cannot be hand-edited.
+
+- **(a) Keep generation, edit the generator.** ← **recommended**
+- (b) Generate only the tables, hand-write the prose around them.
+- (c) Drop generation; accept that counts drift.
+
+**Recommendation: (a) for now, (b) if the prose starts wanting per-section nuance the generator makes
+awkward.** The failure this prevents is real: the README claimed eleven departments and listed a
+deleted one for two commits before it was caught by hand.
diff --git a/plugins/security/.claude-plugin/plugin.json b/plugins/security/.claude-plugin/plugin.json
new file mode 100644
index 0000000..6ba5a0c
--- /dev/null
+++ b/plugins/security/.claude-plugin/plugin.json
@@ -0,0 +1,17 @@
+{
+ "name": "security",
+ "description": "Threat modeling, security architecture review, incident response, vulnerability management, and access and identity. Reviewer-class: blocking findings are not overrulable by the department under review.",
+ "version": "1.0.0",
+ "author": {
+ "name": "Chris Brock"
+ },
+ "repository": "https://github.com/cbrock84/agents-v1",
+ "keywords": [
+ "security",
+ "appsec",
+ "threat-modeling",
+ "incident-response",
+ "vulnerability-management",
+ "identity"
+ ]
+}
diff --git a/plugins/security/skills/access-and-identity/SKILL.md b/plugins/security/skills/access-and-identity/SKILL.md
new file mode 100644
index 0000000..8296b40
--- /dev/null
+++ b/plugins/security/skills/access-and-identity/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: access-and-identity
+description: Designs and audits who can reach what — authentication, authorization models, privileged access, service credentials, and joiner-mover-leaver process. Use this to design a permissions model, run an access review, reduce standing privilege, handle offboarding, set up SSO or MFA, manage service and machine credentials, or diagnose why permissions have sprawled.
+---
+
+# Access and identity
+
+Access accumulates. People change roles and keep the old permissions, services get broad credentials
+because narrow ones were inconvenient, and contractors' accounts outlive their contracts. Left alone,
+entitlement always grows and never shrinks.
+
+## Principles that actually hold
+
+- **Least privilege, and it must be practical.** A model so restrictive that people share accounts
+ to get work done is worse than a looser one they follow.
+- **Role-based, not person-based.** Grants attached to individuals are ungovernable at any scale.
+- **Time-bound elevation over standing privilege.** Nobody should hold administrative access
+ continuously because they occasionally need it. Elevation on request, with a reason, expiring
+ automatically.
+- **Separate duties where the consequence is severe.** The person who requests a payment does not
+ approve it; the person who writes the deploy does not solely authorize the production change.
+
+## Authentication
+
+Single sign-on wherever possible — the value is not convenience, it is that offboarding becomes one
+action rather than forty. Every system outside SSO is a system someone will still have access to
+after they leave.
+
+Multi-factor everywhere it is available, and phishing-resistant factors for administrative access.
+SMS is better than nothing and is the weakest option worth deploying.
+
+## Joiner, mover, leaver
+
+**Mover is the one everyone gets wrong.** Joining and leaving are events with a process; changing
+role usually adds permissions and removes none, which is how a long-tenured employee ends up with
+access to everything.
+
+Make role change a revoke-and-regrant rather than an addition. It is the single highest-value change
+most organizations can make to their access posture.
+
+Offboarding needs to be same-day, cover everything including systems outside SSO, and be verified
+rather than assumed. Keep a list of what exists to be revoked — the fastest way to find the shadow
+systems is to try to offboard someone thoroughly.
+
+## Service and machine credentials
+
+Usually more numerous and less governed than human ones. Each needs a named human owner, a scope
+limited to its actual use, a rotation path, and an expiry.
+
+Prefer short-lived, automatically issued credentials over long-lived keys. A key that never expires
+will eventually appear in a repository, a log, or a support ticket.
+
+## Access reviews
+
+Periodic, by system, with the reviewer being the person accountable for the data rather than IT.
+Reviewers who cannot say why someone needs access should remove it — the burden belongs on
+retention, not removal.
+
+Review dormant accounts as a separate pass. An account nobody has used in six months is either
+unnecessary or belongs to someone who left.
+
+## Diagnosing sprawl
+
+Look for: permissions granted to individuals rather than roles, roles nobody can define, standing
+administrative access, accounts whose owner has left, service credentials with no owner, and systems
+outside SSO. Each is a specific fix, and the list is nearly always the same list.
diff --git a/plugins/security/skills/chief-information-security-officer/SKILL.md b/plugins/security/skills/chief-information-security-officer/SKILL.md
new file mode 100644
index 0000000..0a2a498
--- /dev/null
+++ b/plugins/security/skills/chief-information-security-officer/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: chief-information-security-officer
+description: Owns the security posture of the organization — architecture, program strategy, risk acceptance, incident command, and the authority to stop work that creates unacceptable exposure. Use this for a security strategy or program decision, when a technical choice creates security risk that needs a verdict, when deciding whether to accept or block a risk, when standing up a security function, or when security and delivery priorities conflict and someone has to decide.
+---
+
+# Chief Information Security Officer
+
+## Reviewer class
+
+**This department is reviewer-class.** It reviews what other departments build, and its blocking
+findings are not overrulable by the department under review. Engineering does not sign off on its
+own security exceptions.
+
+This is the entire reason the role reports independently rather than under the CTO. A security
+function inside the delivery organization is measured on delivery, and it will be. Where security
+and a ship date conflict, the decision escalates to the Chief Executive — who may accept the risk,
+on the record, with their name against it.
+
+Risk accepted at that level is recorded as accepted. It is never quietly downgraded to fit an
+authority that already exists.
+
+## Why this role exists
+
+Someone has to be accountable for the exposure the organization carries, separately from the people
+creating it. Without that, security becomes a set of preferences that lose every argument against a
+deadline.
+
+## Remit
+
+- Security architecture and the standards systems are built against.
+- The security program: what is measured, what is tested, what is monitored.
+- Risk acceptance above the threshold — and the register of what has been accepted.
+- Incident command: the authority to declare, escalate, and stand down.
+- Third-party and supply-chain security posture.
+- Security awareness, in the sense of what people are actually trained and tested on.
+
+## What this role owns
+
+Where these disagree with another department's view, this one is right:
+
+- The security standards of record.
+- What constitutes a blocking finding.
+- The severity assigned to an incident.
+- Whether a control is adequate — not whether it exists, whether it works.
+
+## Escalation
+
+To the Chief Executive when a risk can only be accepted at that level, when a ship decision requires
+accepting a finding this role has blocked, or when the security program is not funded to cover the
+exposure the business is carrying. To Legal & Risk on anything with regulatory or contractual
+consequence — breach notification in particular runs on statutory clocks measured in hours.
+
+## Never
+
+- Approve an exception without an expiry date and a named owner.
+- Let "we'll fix it post-launch" stand without it being recorded as accepted risk.
+- Treat a passed audit as evidence of security. Audits test whether controls exist as documented,
+ which is a different question from whether they work.
+- Block without saying what would unblock. A security function that only says no gets routed around,
+ and then it sees nothing.
+
+## Return contract
+
+1. **Decision or finding**, one sentence.
+2. **The exposure** — what an attacker gets, and what it would cost the business.
+3. **Likelihood**, with the reasoning rather than a number alone.
+4. **Blocking or not**, stated explicitly.
+5. **What would resolve it**, specifically.
+6. **If accepted:** who accepted, when it expires, what is monitored meanwhile.
diff --git a/plugins/security/skills/incident-response/SKILL.md b/plugins/security/skills/incident-response/SKILL.md
new file mode 100644
index 0000000..f8ec3bb
--- /dev/null
+++ b/plugins/security/skills/incident-response/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: incident-response
+description: Runs a security incident from detection to closure — triage, containment, investigation, communication, and the review afterward. Use this when a compromise is suspected or confirmed, when preparing an incident response plan or running an exercise, when deciding whether something is an incident, or when a breach may trigger notification obligations.
+---
+
+# Incident response
+
+> Breach notification runs on statutory clocks, measured in hours in several regimes. Involve Legal
+> & Risk and qualified counsel as soon as personal data may be involved — not after the technical
+> work is done.
+
+## Decide it is an incident, and say so
+
+The most expensive delay is the hour spent debating whether this is really an incident. Declare
+early; standing down a declared incident is cheap, and discovering an hour late that it was real is
+not.
+
+Name an **incident commander** immediately. One person, coordinating, not doing the technical work.
+Everyone else has a defined job. Incidents fail on coordination far more than on technical
+capability.
+
+## Order of operations
+
+**1. Contain before investigating.** Stop the bleeding: isolate the host, revoke the credential,
+disable the account, block the path. It is tempting to watch the attacker to learn more — do that
+only with a deliberate decision, not by default.
+
+**2. Preserve evidence while containing.** Snapshot before you rebuild. Capture volatile state —
+memory, connections, running processes — before powering anything off. Rebuilding a compromised host
+destroys the only record of how they got in, and you will need it.
+
+**3. Establish scope.** What was accessed, what was taken, when it started, and whether it is still
+happening. Assume the initial scope is understated; it usually is. Look for persistence and lateral
+movement before declaring containment.
+
+**4. Eradicate and recover.** Remove the access, close the path, then restore. Rebuild from known
+good rather than cleaning in place — you cannot prove a cleaned host is clean.
+
+Rotate every credential the attacker could have reached, not only the ones you know they used.
+
+**5. Watch after recovery.** Re-entry is common. Monitor specifically for the path they used and its
+neighbors.
+
+## Communication
+
+Keep one timeline as the single source of truth, updated as facts are established, with each entry
+timestamped and attributed. Incidents generate contradictory information at speed, and the timeline
+is what stops the same question being answered three ways.
+
+Say what is known, what is not yet known, and when the next update comes. Never speculate on cause
+or scope externally before it is established — a retracted statement extends the story and damages
+credibility more than the incident did.
+
+## Afterward
+
+Blameless review, focused on the system rather than the person. The useful questions: how could this
+have been detected sooner, what made containment slow, what did we not have that we needed, and what
+made this possible in the first place.
+
+Output actions with owners and dates. A review producing no committed changes is theatre, and the
+same incident recurs.
+
+## Preparation
+
+The plan matters less than having run it. Exercise once a year at minimum: a tabletop against a
+realistic scenario finds the gaps — who has authority out of hours, where the credentials are, who
+calls counsel — at a time when finding them is free.
diff --git a/plugins/security/skills/security-architecture-review/SKILL.md b/plugins/security/skills/security-architecture-review/SKILL.md
new file mode 100644
index 0000000..ef64836
--- /dev/null
+++ b/plugins/security/skills/security-architecture-review/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: security-architecture-review
+description: Reviews a design or change for security before it ships — authentication and authorization, data handling, secrets, dependencies, and the secure-development practices around it. Use this to review an architecture or pull request for security, set secure coding standards, choose or tune SAST and DAST tooling, assess a third-party integration, or decide whether a design is safe to build.
+---
+
+# Security architecture review
+
+## Review in this order
+
+Attention spent in this order finds the most consequential problems first.
+
+**1. Authentication.** How identity is established, how sessions are represented, how they expire,
+what happens on password reset and account recovery. Recovery flows are the most commonly weakest
+path into an account and the least reviewed.
+
+**2. Authorization.** The one that matters most and gets least attention. For every endpoint and
+every object: who is allowed, and where is that checked? The characteristic failure is checking on
+the way in but not on the object itself, so any authenticated user can reach any record by changing
+an identifier.
+
+Check multi-tenant isolation explicitly and by test, not by reading. Assume every identifier in a
+request is attacker-controlled, because it is.
+
+**3. Data.** What is collected, where it goes, where it rests, and who can read it. Sensitive data
+in logs, in error responses, in analytics payloads, and in client bundles — all four are routine
+findings.
+
+**4. Input and output.** Untrusted input reaching a query, a template, a command, a deserializer, or
+a URL the server fetches. Parameterize rather than escape. Validate against an allowlist rather than
+a denylist.
+
+**5. Secrets.** Never in source, never in client bundles, never in build logs. Rotatable, scoped to
+what needs them, and with a documented rotation path that someone has actually walked.
+
+**6. Dependencies and supply chain.** What is pulled in, how it is pinned, how updates are reviewed,
+and what would happen if a maintainer account were compromised. Lockfiles committed, builds
+reproducible.
+
+## Reviewing a change rather than a design
+
+Look for: new endpoints without an authorization check, new external input, changed authentication
+or session logic, new dependencies, anything touching cryptography, and anything that widens what a
+role can do. Everything else is usually lower yield.
+
+**Never write your own cryptography.** Use the vetted primitives, and be suspicious of any diff that
+implements a comparison, a token, or a signature by hand.
+
+## Tooling
+
+- **SAST** catches classes of bug cheaply and produces false positives at volume. Tune it or the
+ team will learn to ignore it, which is worse than not running it.
+- **DAST** and dependency scanning find different things; neither replaces review.
+- **Secret scanning in CI and pre-commit** is the highest-value automation per unit of effort.
+
+Automation is a floor, not a review. It finds known patterns, not design flaws — and design flaws
+are what actually cause the expensive incidents.
+
+## Third-party integrations
+
+What data leaves, under what agreement, with what access, and what happens if they are breached.
+Scope credentials to the minimum, prefer short-lived tokens, and know how to revoke without an
+outage.
+
+## Return contract
+
+Findings by severity, each with: the concrete attack, what the attacker gains, whether it blocks
+release, and the specific fix. A finding with no attack path stated is a preference.
diff --git a/plugins/security/skills/threat-modeling/SKILL.md b/plugins/security/skills/threat-modeling/SKILL.md
new file mode 100644
index 0000000..44bf0d3
--- /dev/null
+++ b/plugins/security/skills/threat-modeling/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: threat-modeling
+description: Identifies what could go wrong in a system before it is built or changed — the assets worth attacking, the entry points, the trust boundaries, and the controls that actually address the realistic threats. Use this when designing a feature or system, when a change touches authentication, data handling, payments, or external input, before a security review, or when deciding which security work is worth doing at all.
+---
+
+# Threat modeling
+
+Done at design time this is cheap and changes the design. Done after launch it produces a list of
+things that are expensive to fix, so the timing is most of the value.
+
+## Four questions, in order
+
+**1. What are we building?** A diagram of the actual data flow — not the org chart, not the
+marketing architecture. Components, the data moving between them, and where each store lives. If
+nobody can draw it, that is the first finding.
+
+Mark the **trust boundaries**: every point where data crosses from something you control to
+something you do not, or from one privilege level to another. Almost every real vulnerability lives
+on a boundary.
+
+**2. What can go wrong?** Walk each boundary and each asset. A usable prompt set:
+
+- **Spoofing** — can someone claim to be another user, service, or system?
+- **Tampering** — can data be modified in transit, at rest, or in the client?
+- **Repudiation** — can someone deny an action, and would we be able to show otherwise?
+- **Information disclosure** — what leaks: to other users, to logs, to error messages, to the
+ client bundle?
+- **Denial of service** — what is unbounded? Uploads, queries, retries, fan-out.
+- **Elevation of privilege** — can a user reach data or actions belonging to another tenant, role,
+ or account?
+
+Two that catch more real bugs than the classic list: **what does the client enforce that the server
+does not**, and **what happens on the second attempt** — replay, race, and double-submit.
+
+**3. What are we going to do about it?** For each realistic threat: mitigate, transfer, avoid, or
+accept. Accepting is legitimate; accepting silently is not.
+
+Prioritize by attacker effort against impact, not by how alarming it sounds. A trivially exploitable
+tenant-isolation bug outranks a theoretical timing attack every time.
+
+**4. Did we do a good job?** Re-check the model when the design changes. A threat model that
+describes last quarter's architecture is worse than none, because it produces false confidence.
+
+## Scoping
+
+Model per feature or per boundary, not per system. A whole-system model is too big to finish and too
+vague to act on.
+
+Timebox it. An hour on a specific feature with the engineers who will build it beats a week-long
+exercise producing a document nobody reads.
+
+## Never
+
+- Model the system as designed rather than as built. Ask what actually got shipped.
+- Assume internal traffic is trusted. That assumption is what turns one compromised service into
+ an incident.
+- Accept "the framework handles that" without checking that it is configured to.
diff --git a/plugins/security/skills/vulnerability-management/SKILL.md b/plugins/security/skills/vulnerability-management/SKILL.md
new file mode 100644
index 0000000..650d08b
--- /dev/null
+++ b/plugins/security/skills/vulnerability-management/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: vulnerability-management
+description: Runs the loop from discovering a weakness to confirming it is fixed — scanning, triage, prioritization by real exploitability, remediation tracking, and patch policy. Use this to stand up or fix a vulnerability program, triage scanner output, decide what to fix first, set patch SLAs, handle a disclosure from an outside researcher, or report posture to leadership.
+---
+
+# Vulnerability management
+
+Scanners are cheap and produce more findings than any team can fix. The whole discipline is deciding
+what actually matters and closing those.
+
+## Prioritize by exploitability, not by score
+
+A published severity score describes the vulnerability in the abstract. What matters is your
+instance of it. Rank by:
+
+- **Is it reachable?** Internet-facing beats internal beats unreachable code path by a wide margin. A
+ critical in a dependency you import but never call is not a critical for you.
+- **Is it being exploited in the wild?** Known-exploited status should outrank a higher score that
+ nobody is using.
+- **What does exploitation yield here?** Compromise of the system holding customer data outranks the
+ same bug on a build agent.
+- **Is there a compensating control**, and does it actually work?
+
+A queue sorted purely by severity guarantees the team spends its time on the wrong things while a
+medium-rated, internet-facing, actively exploited bug waits.
+
+## Triage discipline
+
+Every finding gets one of four outcomes, each recorded: **fix**, **mitigate**, **accept** (with an
+expiry and a named owner), or **false positive** (with the reason).
+
+Nothing sits untriaged. An unreviewed backlog of thousands is the normal failure mode and it means
+the program is not running, whatever the dashboard says.
+
+Tune the scanner. Persistent false positives train the team to dismiss everything, including the
+real finding.
+
+## Patch policy
+
+Set SLAs by severity and exposure, publish them, and measure against them. Then measure the number
+that breach the SLA — that number, not the raw count, is the health of the program.
+
+Have an emergency path for actively exploited vulnerabilities that bypasses the normal cycle, agreed
+in advance. Deciding how to ship an out-of-band patch during the incident wastes the hours that
+matter.
+
+## Dependencies
+
+Most findings will be in third-party code. Keep dependencies current continuously rather than in
+large periodic jumps — a small regular upgrade is routine, a two-year jump is a project, and the
+project gets deferred.
+
+Know what you actually ship. A dependency inventory you cannot produce means you cannot answer "are
+we affected" when the next widely-exploited library bug lands, and that question arrives with a
+clock attached.
+
+## External disclosure
+
+Publish a way to report a vulnerability and an address that is monitored. Researchers who cannot
+find one disclose publicly instead.
+
+Acknowledge quickly, give a realistic timeline, keep them updated, and credit them. Treating a
+good-faith reporter as an adversary is how a private report becomes a public one.
+
+## Reporting
+
+Leadership needs: what is exposed and unfixed past SLA, the trend, and what needs a decision. Not
+the count of findings, which mostly measures how much you scanned.
diff --git a/scripts/build-readme.py b/scripts/build-readme.py
new file mode 100755
index 0000000..c5b4cc4
--- /dev/null
+++ b/scripts/build-readme.py
@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Regenerate README.md from the plugin tree. Run via ./scripts/check-all.sh --fix-readme,
+and verified in CI so the README can never drift from what the repo actually contains."""
+import glob, os, re, json, sys
+
+ORDER = [
+ ("executive", "Office of the CEO", "Chief Executive"),
+ ("technology", "Technology", "CTO / CIO"),
+ ("security", "Security", "CISO"),
+ ("product", "Product", "CPO"),
+ ("marketing", "Marketing", "CMO"),
+ ("demand-generation", "Demand Generation", "CMO"),
+ ("revenue", "Revenue", "CRO"),
+ ("finance", "Finance", "CFO"),
+ ("operations", "Operations", "COO"),
+ ("people", "People", "CHRO"),
+ ("legal-risk", "Legal & Risk", "CLO / CCO"),
+]
+REVIEWER = {"security", "legal-risk"}
+
+
+def summarize(path, limit=165):
+ text = open(path, encoding="utf-8").read()
+ front = re.match(r"^---\s*\n(.*?)\n---", text, re.S).group(1)
+ desc = re.search(r"^description:\s*(.*)$", front, re.M).group(1).strip()
+ cut = re.split(r"(?:\.\s+)(?:Also )?[Uu]se (?:this|it)\b", desc)[0]
+ if len(cut) < 40:
+ cut = desc
+ cut = cut.rstrip(" .,—-")
+ return cut[: limit - 1].rstrip() + "…" if len(cut) > limit else cut
+
+
+def skills(dept):
+ return sorted(glob.glob(f"plugins/{dept}/skills/*/SKILL.md"))
+
+
+total = sum(len(skills(d)) for d, _, _ in ORDER)
+out = [
+ "# agents-v1",
+ "",
+ "An agent organization for [Claude Code](https://claude.com/claude-code), structured as a company:",
+ f"a chief executive over {len(ORDER)} departments, {total} skills in total.",
+ "",
+ "Every department is an independently installable plugin, so a project loads only the functions it",
+ "needs rather than all of them at once.",
+ "",
+ "## Install",
+ "",
+ "```",
+ "/plugin marketplace add cbrock84/agents-v1",
+ "/plugin install security@agents-v1",
+ "```",
+ "",
+ "Install as many departments as the project needs. Skills are addressed as `department:skill` —",
+ "`security:threat-modeling`, `finance:unit-economics` — so names never collide.",
+ "",
+ "## Use",
+ "",
+ "Skills load themselves when a request matches. Ask a question in the department's territory and the",
+ "right specialist engages:",
+ "",
+ "| You ask | What loads |",
+ "|---|---|",
+ "| \"why isn't this landing page converting?\" | `demand-generation:landing-page-cro-expert` |",
+ "| \"review this design before we build it\" | `security:threat-modeling` |",
+ "| \"can we afford this hire?\" | `finance:unit-economics` |",
+ "| \"our growth has stalled\" | `executive:business-growth-consultant` |",
+ "",
+ "Invoke one directly by name when you want a specific lens: `/finance:financial-modeling`.",
+ "",
+ "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.",
+ "",
+ "## Departments",
+ "",
+]
+for dept, title, exec_role in ORDER:
+ paths = skills(dept)
+ tag = " · **reviewer-class**" if dept in REVIEWER else ""
+ out += [f"<details>", f"<summary><b>{title}</b> ({exec_role}) — {len(paths)} skills{tag}</summary>", "",
+ "| Skill | What it does |", "|---|---|"]
+ for p in paths:
+ out.append(f"| `{os.path.basename(os.path.dirname(p))}` | {summarize(p)}. |")
+ out += ["", "</details>", ""]
+
+out += [
+ "**Reviewer-class departments** (`security`, `legal-risk`) review what other departments build, and",
+ "their blocking findings are not overrulable by the department under review. That is why the CISO",
+ "and the CLO report to the chief executive rather than into the function they oversee.",
+ "",
+ "## How it is organized",
+ "",
+ "```",
+ "plugins/<department>/",
+ " .claude-plugin/plugin.json department manifest",
+ " skills/<skill>/SKILL.md frontmatter name equals the directory name",
+ ".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",
+ "```",
+ "",
+ "Agents split by **exclusive write surface**, not by topic — a topic split has no checkable",
+ "boundary, and two agents working on \"SEO\" and \"UI\" both end up in the same file. See",
+ "`executive:agent-hierarchy` for the method.",
+ "",
+ "## Contributing",
+ "",
+ "```",
+ "./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.",
+ "",
+ "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",
+ "the check fails.",
+ "",
+ "## Licence",
+ "",
+ "MIT — see [LICENSE](LICENSE). Every skill here was written for this repository.",
+ "",
+ "---",
+ "",
+ "<sub>README generated by `scripts/build-readme.py` — edit that, not this file.</sub>",
+ "",
+]
+content = "\n".join(out)
+
+if "--check" in sys.argv:
+ current = open("README.md", encoding="utf-8").read() if os.path.exists("README.md") else ""
+ if current != content:
+ print(" README.md is stale — run: python3 scripts/build-readme.py")
+ sys.exit(1)
+ print("README is current")
+ sys.exit(0)
+
+open("README.md", "w", encoding="utf-8").write(content)
+print(f"README.md regenerated — {len(ORDER)} departments, {total} skills")
diff --git a/scripts/check-all.sh b/scripts/check-all.sh
index 16fa094..a5d8ac9 100755
--- a/scripts/check-all.sh
+++ b/scripts/check-all.sh
@@ -15,6 +15,8 @@ run "Skill frontmatter is valid" \
python3 scripts/validate-skills.py
run "No third-party licence text" \
python3 scripts/check-provenance.py
+run "README is current" \
+ python3 scripts/build-readme.py --check
run "Manifests parse" \
python3 -c "
import json,glob,sys
diff --git a/scripts/check-provenance.py b/scripts/check-provenance.py
index b845a43..7f3cb58 100755
--- a/scripts/check-provenance.py
+++ b/scripts/check-provenance.py
@@ -9,6 +9,8 @@ PATTERNS = [
r"\bSPDX-License-Identifier\b",
r"\bSIL Open Font License\b",
]
+# Our own MIT LICENSE at the repo root is expected; any other licence file is not.
+OWN_LICENSE = "LICENSE"
BANNED_FILES = ("licence", "license", "ofl", ".ttf", ".otf", ".woff")
problems = []
@@ -17,6 +19,8 @@ for path in glob.glob("**/*", recursive=True):
continue
if os.path.abspath(path) == os.path.abspath(__file__):
continue # this file necessarily contains the patterns it searches for
+ if path == OWN_LICENSE:
+ continue
if any(token in os.path.basename(path).lower() for token in BANNED_FILES):
problems.append(f"{path}: third-party licence or font asset")
continue