claude-skills/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Purpose

This is a **comprehensive skills library** for Claude AI and Claude Code - reusable, production-ready skill packages that bundle domain expertise, best practices, analysis tools, and strategic frameworks. The repository provides modular skills that teams can download and use directly in their workflows.

**Current Scope:** 388 production-ready skills across 20 domains with 727 Python automation tools, 842 reference guides, 118 agents (cs-* + 7 personas), and 150 slash commands, distributed as 99 marketplace plugins. Headline counters are derived from the tree by `scripts/derive_counters.py` (run with `--check` to verify the docs still match). **v2.11.2 (current)** vendors **engineering/skillopt-sleep/** — started as a verbatim, byte-for-byte copy of `microsoft/SkillOpt`'s `skillopt_sleep` engine (stdlib-only, zero third-party deps) and its Claude Code plugin surface (`skills/`, `hooks/`, `commands/`, `scripts/`), then received 23 targeted patches after ten rounds of adversarial review (see `engineering/skillopt-sleep/README.md`'s numbered "Deviations from upstream" list, the authoritative source — re-apply all 23 on re-vendor). Gives a local agent a nightly "sleep cycle": read-only harvest of past Claude Code session transcripts → mine recurring tasks → replay offline on the user's own API budget → consolidate into `CLAUDE.md`/`SKILL.md` edits behind a held-out validation gate → stage for review; nothing live changes until an explicit `/skillopt-sleep adopt` (which backs up first). Default `mock` backend spends no API budget. The heavier `skillopt` *training* package (benchmark-driven, needs `numpy`/`openai`/`azure-*` + hand-labeled train/val/test data per task) was deliberately **not** vendored — it optimizes one narrow, scoreable task at a time, which doesn't fit this repo's broad domain-expertise skills or its no-ML-in-scripts/no-test-framework conventions; `skillopt_sleep` mines its "benchmark" from real usage instead, which does fit. Attribution preserved in `.claude-plugin/authoring-notes.json` + `LICENSE` + `README.md` (MIT, © Microsoft Corporation / Yifan Yang), following the same verbatim-vendor pattern as `loop-library/`. **Unreleased (post-v2.11.2, PR #961 merged)** adds the **agent-launcher/** top-level domain — a plugin re-implementation of Anthropic's `launch-your-agent` reference skill (Apache-2.0; independent, not a fork) for building **Claude Managed Agents (CMA)** in the user's own account. Every session starts with a goal (`./my-agent/goal.json`, surfaced by an opt-in `AGENT_LAUNCHER_SESSION=1` SessionStart hook + `/cs:goal`); `loop_compiler.py` compiles that goal into a **bounded grade→iterate loop** (CMA `user.define_outcome` self-grading, `max_iterations` 1..20), a **recurring POSIX-cron scheduled-deployment loop**, or a **single-pass interview→stage→launch workflow**. 6 skills (orchestrator `context: fork` + interview + stage-launch + grade-iterate + run-without-you + wrap-up), 18 stdlib-only deterministic scaffolder tools (NO network/API calls — live launches emitted as BYOK curl that never prints the key), 4 agents, 8 `/cs:*` commands, opt-in hooks, 5 shared references, 4 assets; validators enforce CMA limits (≤20 skills/session, ≤8 memory stores, depth-1 multiagent, `max_iterations` ≤20, ≤1000 deployments/org). Distinct from `engineering/agent-harness` (generic bounded loop over any domain) and `engineering/write-a-skill` (authors Claude Code skills, not CMAs). **Unreleased (post-v2.11.2)** ships the **productivity coverage expansion** — public audit record `audit/productivity-2026-07/` (all 7 legacy skills scored, 24/24 scripts smoke-tested, coverage map vs the personal-productivity canon) + 3 gap-filling plugins, each with a cs-* agent, /cs:* commands, 3 stdlib scripts and 3 cited references: **weekly-review** (GTD loop; review-gate refuses COMPLETE while a mandatory GET CURRENT step is missing), **deep-work** (time-block planner refusing >4h deep demand, shallow-work budget auditor, focus-session logger), **meetings** (MEET/ASYNC/NOT-READY cost gate, outcome-required agenda builder, action-item extractor with ORPHAN/NO-DUE flags). **Unreleased (post-v2.11.1)** added **productivity/fable-goal** — converts a rambling description of a desired outcome into one polished, copy-paste `/goal` prompt for a fresh autonomous session (ported from `duncan-buildroom/freeskills`). **v2.11.1 (complete)** upgrades **product-team/** and **project-management/** into agent-harness domains: both prose routers rebuilt as `context: fork` orchestrators with deterministic goal routers (exit-code route/ask/refuse), a Jira MCP snapshot bridge (Kanban-Guide-2025 flow metrics + seeded Monte Carlo forecasts, verified end-to-end into velocity_analyzer), a delegation-governance loop gate (human owner / reviewer / machine-checkable acceptance / close refusal), a Torres continuous-discovery cadence tracker + Opportunity Solution Tree linter, cs-pm-orchestrator + cs-product-orchestrator agents, and /cs:pm|grill-pm|pm-loop + /cs:product|grill-product|product-loop commands — plus the public audit record `audit/pm-product-agentic-2026-07/` (AR-rubric scores for all 26 skills, research-backed improvement fields, executable verification criteria). **v2.9.0 (complete)** added the **research-ops/** top-level domain — enterprise Research Operations (orchestrator + clinical-research + research-finance + market-research + product-research), the managed counterpart to the academic research/ domain, with `context: fork` orchestration and a Matt Pocock "Forcing-question library" in every SKILL.md plus `/cs:grill-research-ops`. **v2.8.0 (complete)** added 2 new top-level domains — **business-operations/** (7 internal-ops skills: orchestrator + process-mapper + vendor-management + capacity-planner + internal-comms + knowledge-ops + procurement-optimizer) and **commercial/** (8 per-deal-economics skills: orchestrator + pricing-strategist + deal-desk + partnerships-architect + channel-economics + commercial-policy + rfp-responder + commercial-forecaster) — with orchestrator skills using `context: fork` for chaining, Matt Pocock docs-anchored "Forcing-question library" in every SKILL.md, plus `/cs:grill-bizops` and `/cs:grill-commercial`. **v2.8.2** adds a productivity-shaped `handoff` skill (sibling to engineering/handoff) inspired by Matt Pocock — first-run setup with configurable save location, redaction linter, SessionStart + SessionEnd hooks, fidelity self-check, `--refresh` flag. **v2.8.1** upgraded the engineering role-skills (senior-fullstack / senior-frontend / senior-backend) with karpathy-coder + Matt Pocock decision engines + per-role forcing questions. v2.7.3 ports `alirezarezvani/aeo-box` — AEO (Answer Engine Optimization) skill into marketing-skill/ + security-guidance PreToolUse hook into engineering/. v2.7.0 added 13 Path-B skills across 3 top-level domains (productivity, marketing, research). v2.6.0 added 4 Matt Pocock-derived productivity skills.

**Key Distinction**: This is NOT a traditional application. It's a library of skill packages meant to be extracted and deployed by users into their own Claude workflows.

## Maintainer-Local Folders (gitignored)

The following exist on the maintainer's disk but are excluded from the public GitHub tree so cloners only see production skill packages:

- `documentation/` — sprint plans, strategy, implementation roadmaps
- `eval-workspace/` — Tessl evaluation outputs
- `megaprompts/` — pre-skill draft specs (Path-B source material)
- `tests/` — pytest suite (run locally; not in CI)
- `.autoresearch/` — autoresearch agent workspace
- `AUDIT_REPORT.md` — internal audit snapshots

**Distinct from the above:** the top-level `audit/` directory (e.g.
`audit/newgen-2026-06/`) is an **intentional, public** audit record — rubric +
per-domain reports with per-skill verification criteria that follow-up PRs use
as acceptance gates. It is excluded from headline counters by
`scripts/derive_counters.py`, but it is committed and visible to cloners.
`AUDIT_REPORT.md` (gitignored, above) is the older internal-snapshot format.

In-repo references to paths under these folders (e.g. `documentation/implementation/...`) resolve locally for the maintainer but appear as dead links on GitHub. This is intentional.

## Navigation Map

This repository uses **modular documentation**. For domain-specific guidance, see:

| Domain | CLAUDE.md Location | Focus |
|--------|-------------------|-------|
| **Agent Development** | [agents/CLAUDE.md](agents/CLAUDE.md) | cs-* agent creation, YAML frontmatter, relative paths |
| **Marketing Skills** | [marketing-skill/CLAUDE.md](marketing-skill/CLAUDE.md) | Content creation, SEO, ASO, demand gen, campaign analytics |
| **Product Team** | [product-team/CLAUDE.md](product-team/CLAUDE.md) | RICE, OKRs, user stories, UX research, SaaS scaffolding |
| **Engineering (Core)** | [engineering-team/CLAUDE.md](engineering-team/CLAUDE.md) | Fullstack, AI/ML, DevOps, security, data, QA tools |
| **Engineering (POWERFUL)** | [engineering/](engineering/) | Agent design, RAG, MCP, CI/CD, database, observability |
| **C-Level Advisory** | [c-level-advisor/CLAUDE.md](c-level-advisor/CLAUDE.md) | CEO/CTO strategic decision-making |
| **Project Management** | [project-management/CLAUDE.md](project-management/CLAUDE.md) | Atlassian MCP, Jira/Confluence integration |
| **RA/QM Compliance** | [ra-qm-team/CLAUDE.md](ra-qm-team/CLAUDE.md) | ISO 13485, MDR, FDA, GDPR, ISO 27001 compliance |
| **Business & Growth** | [business-growth/CLAUDE.md](business-growth/CLAUDE.md) | Customer success, sales engineering, revenue operations |
| **Finance** | [finance/CLAUDE.md](finance/CLAUDE.md) | Financial analysis, DCF valuation, budgeting, forecasting, SaaS metrics |
| **Research Operations** | [research-ops/CLAUDE.md](research-ops/CLAUDE.md) | Clinical study design, R&D finance, market research, product research (enterprise counterpart to academic research/) |
| **Markdown → HTML** | [markdown-html/CLAUDE.md](markdown-html/CLAUDE.md) | Markdown-to-interactive-HTML converter (orchestrator + design-system foundation; md-document/review/slides v2.10.1). Inspired by Shihipar's "Claude Code HTML output" essay |
| **Agent Launcher** | [agent-launcher/CLAUDE.md](agent-launcher/CLAUDE.md) | Claude Managed Agent (CMA) launcher — session-goal orchestrator + interview / stage-launch / grade-iterate / run-without-you / wrap-up; deterministic BYOK-curl scaffolders; bounded grade→iterate + cron deployment loops. Re-implements anthropics/launch-your-agent (Apache-2.0) |
| **Standards Library** | [standards/CLAUDE.md](standards/CLAUDE.md) | Communication, quality, git, security standards |
| **Templates** | [templates/CLAUDE.md](templates/CLAUDE.md) | Template system usage |

## Architecture Overview

### Repository Structure

```
claude-code-skills/
├── .claude-plugin/            # Plugin registry (marketplace.json)
├── agents/                    # 32 standalone agents (cs-* + 7 personas); 51+ cs-* agents repo-wide
├── commands/                  # slash commands (changelog, tdd, saas-health, prd, code-to-prd, plugin-audit, sprint-plan, slo-design, etc.); 87+ repo-wide
├── engineering-team/          # 51 core engineering skills + Playwright Pro + Self-Improving Agent + Security Suite
├── engineering/               # 81 POWERFUL-tier advanced skills (incl. AgentHub, autoresearch-agent, self-eval, llm-wiki, tc-tracker, ship-gate, slo-architect, write-a-skill, caveman, grill-me, handoff, agent-harness)
├── product-team/              # 17 product skills (incl. apple-hig-expert) + Python tools
├── marketing-skill/           # 46 marketing skills (8 pods) + Python tools
├── c-level-advisor/           # 66 C-level advisory skills (full C-suite + founder-mode agents + orchestration)
├── project-management/        # 9 PM skills + bundled Atlassian Remote MCP (.mcp.json)
├── ra-qm-team/                # 18 RA/QM compliance skills
├── compliance-os/             # 9 compliance-OS skills
├── business-growth/           # 5 business & growth skills + Python tools
├── business-operations/       # 7 internal-ops skills (orchestrator + 6 sub-skills)
├── commercial/                # 8 per-deal-economics skills (orchestrator + 7 sub-skills)
├── finance/                   # 4 finance skills + Python tools
├── research/                  # 8 academic research skills (orchestrator + 7 specialists)
├── research-ops/              # 5 research-ops skills (orchestrator + clinical-research + research-finance + market-research + product-research)
├── markdown-html/             # 2 markdown-to-HTML skills v2.10.0 foundation (orchestrator + design-system); md-document/review/slides land in v2.10.1
├── agent-launcher/            # 6 CMA-launcher skills (session-goal orchestrator + 5 phase skills; 18 BYOK-curl scaffolder tools, opt-in SessionStart goal hook)
├── eval-workspace/            # Skill evaluation results (Tessl)
├── standards/                 # 5 standards library files
├── templates/                 # Reusable templates
├── docs/                      # MkDocs Material documentation site
├── scripts/                   # Build scripts (docs generation)
└── documentation/             # Implementation plans, sprints, delivery
```

### Skill Package Pattern

Each skill follows this structure:
```
skill-name/
├── SKILL.md              # Master documentation
├── scripts/              # Python CLI tools (no ML/LLM calls)
├── references/           # Expert knowledge bases
└── assets/               # User templates
```

**Design Philosophy**: Skills are self-contained packages. Each includes executable tools (Python scripts), knowledge bases (markdown references), and user-facing templates. Teams can extract a skill folder and use it immediately.

**Key Pattern**: Knowledge flows from `references/` → into `SKILL.md` workflows → executed via `scripts/` → applied using `assets/` templates.

## Git Workflow

**Branch Strategy:** feature → dev → main (PR only)

> **⛔ HARD RULE — PR TARGET IS ALWAYS `dev`, NEVER `main`.**
> Every PR (human or AI-created) must use `--base dev`. Nothing merges into `main`
> directly — `main` only receives periodic `dev → main` promotion PRs opened by the
> maintainer. If you find a PR targeting `main`, retarget it to `dev` before review.
> AI agents (Claude Code included): set the base branch explicitly when creating PRs;
> never rely on the repository default branch.

**Branch Protection Active:** Main branch requires PR approval. Direct pushes blocked.

### Quick Start

```bash
# 1. Always start from dev
git checkout dev
git pull origin dev

# 2. Create feature branch
git checkout -b feature/agents-{name}

# 3. Work and commit (conventional commits)
feat(agents): implement cs-{agent-name}
fix(tool): correct calculation logic
docs(workflow): update branch strategy

# 4. Push and create PR to dev
git push origin feature/agents-{name}
gh pr create --base dev --head feature/agents-{name}

# 5. After approval, PR merges to dev
# 6. Periodically, dev merges to main via PR
```

**Branch Protection Rules:**
- ✅ Main: Requires PR approval, no direct push
- ✅ Dev: Unprotected, but PRs recommended
- ✅ All: Conventional commits enforced

See [documentation/WORKFLOW.md](documentation/WORKFLOW.md) for complete workflow guide.
See [standards/git/git-workflow-standards.md](standards/git/git-workflow-standards.md) for commit standards.

## Development Environment

**No build system or test frameworks** - intentional design choice for portability.

**Python Scripts:**
- Use standard library only (minimal dependencies)
- CLI-first design for easy automation
- Support both JSON and human-readable output
- No ML/LLM calls (keeps skills portable and fast)

**If adding dependencies:**
- Keep scripts runnable with minimal setup (`pip install package` at most)
- Document all dependencies in SKILL.md
- Prefer standard library implementations

## Current Version

**Version:** v2.12.0 (consolidated release — 20 domains, 380 skills; full reported-issue triage sweep; first tag since v2.9.0. See CHANGELOG.md [2.12.0].)

---

**Previously: v2.11.2** (skillopt-sleep — vendored nightly self-improvement plugin from microsoft/SkillOpt)

**v2.11.2 highlights — engineering/skillopt-sleep/:**

Vendors `engineering/skillopt-sleep/` — a byte-for-byte start from [microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)'s `skillopt_sleep` engine (32 files, stdlib-only, zero third-party deps) and its Claude Code plugin surface (`skills/`, `hooks/`, `commands/`, `scripts/`), following the same verbatim-vendor pattern as `loop-library/`. Gives a local agent a nightly gated self-improvement cycle: read-only harvest of past Claude Code session transcripts → mine recurring tasks → replay offline on the user's own API budget → consolidate into `CLAUDE.md`/`SKILL.md` edits behind a held-out validation gate → stage for review; nothing live changes until an explicit `/skillopt-sleep adopt` (which backs up first). Default `mock` backend spends no API budget.

- **Deliberately not vendored:** the heavier `skillopt` *training* package (benchmark-driven, needs `numpy`/`openai`/`azure-*` + hand-labeled train/val/test data per task) — it optimizes one narrow, scoreable task at a time, which doesn't fit this repo's broad domain-expertise skills or its no-ML-in-scripts/no-test-framework conventions; `skillopt_sleep` mines its "benchmark" from real usage instead, which does fit.
- **23 deviations from upstream (6 cosmetic, 17 safety/hardening)**, found across ten rounds of adversarial code review rather than assumed safe from the surface docs. The **numbered list in `engineering/skillopt-sleep/README.md`'s "Deviations from upstream" section is the single source of truth** — the plugin's `authoring-notes.json` `attribution.derivation_note` and this bullet are both summaries of it, kept in sync by hand; if any of the three ever disagree on the count again, README.md wins. Highlights: `redact_secrets()` now covers every artifact that goes live or persists — `proposed_SKILL.md`/`proposed_CLAUDE.md`, the cross-night task archive (`state.json`), `report.md`/`report.json` (previously only `diagnostics.json` was scrubbed, despite `report.md` being the file the SKILL.md's own workflow tells a human to read *first*), and — the gap that survived seven review rounds because every earlier fix was file-level — the CLI's own `cmd_run`/`cmd_harvest` console/`--json`/`--output` output, which read the same unredacted in-memory `Report`/`TaskRecord` objects and (via `scheduler.py`'s cron redirect) could leak straight into `cron.log`; the generated crontab line is fully `shlex.quote()`-d including the `extra` flags param, and `cron.log` itself is now `chmod 600` (previously uncovered by the state/staging chmod pass); `scheduler.py`'s per-project cron-line marker match is now anchored on end-of-line rather than a bare substring test, closing a real bug where scheduling/unscheduling one project could silently drop a sibling project's job whose path happened to be a prefix of it; the previously-dead `max_tokens_per_night` config key now sizes `dream_rollouts` down via the engine's own `plan_depth()` heuristic; a hardcoded internal Azure OpenAI backend (5 internal-looking endpoint hostnames + a Managed Identity client ID) was removed rather than carried forward; tool-shim names reachable via `--tasks-file` are now validated against a safe-identifier allowlist before use as a filename or shell text; `commands/skillopt-sleep.md` now tells the agent to confirm with the user before `schedule` (which installs a real crontab entry immediately, unlike every other action); every directory/file `state.py`/`staging.py` create is `chmod 0700`/`0600` rather than left at the world-readable process umask default.
- One documented, opt-in exception to CLAUDE.md's "no LLM calls in scripts" anti-pattern (see that section) — `backend.py`'s `claude`/`codex` backends shell out to those CLIs only when a non-`mock` backend is explicitly selected.
- Registered as its own installable marketplace plugin; **counters:** skills 358 → 359; tools 603 → 635; refs 732 (unchanged); commands 110 → 111; plugins 84 → 85 (derived via `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.12.0) — engineering/deep-learning-book (companion, not compilation):**

New `engineering/deep-learning-book/` plugin: a study companion for *Deep Learning* by
Goodfellow, Bengio & Courville (MIT Press, 2016), free to read at deeplearningbook.org.
Requested as "convert this book into a skill"; built as a **companion** instead, and the
reasoning is the reusable part.

- **Why not `book-to-skill`.** That skill's rights gate refuses a `shareable` package without
  `public-domain` / `open-license` / `internal-docs` / `author-permission` — none applies to an
  MIT Press title whose own site states the HTML-only format exists as a friction against
  copying under the authors' contract — and its `rights_and_provenance.md` lists publishing a
  compiled skill of a copyrighted book to a public marketplace under **Do not**. Its hard rule 1
  also forbids scraping a book from the web, so the pipeline could not have run against a URL.
  **The rule this sets:** when a user asks to convert a copyrighted work into a *shareable*
  skill, build a companion that indexes and updates the source, not a compilation that
  reproduces it; compile only when the gate clears, and keep the output local when it does not.
  Recorded in `skills/deep-learning-book/references/rights_and_use.md`.
- **What it is.** The compiled-skill *shape* (master SKILL.md at ~2.0k tokens with a chapter
  index and topic index, `chapters/ch01..ch20`, glossary, patterns, cheatsheet) filled with
  original synthesis — no passages, figures, or per-paragraph paraphrase — each chapter file
  linking to the official free chapter. Passes `book_to_skill`'s own `book_skill_validator.py`
  clean and every file is inside `token_budget_estimator.py`'s caps.
- **The differentiator is the delta layer.** A static compilation freezes a source at its
  publication date; this one dates it. Every chapter carries "What changed after 2016", and
  `references/book_to_2026_delta.md` gives five corrections with primary citations and per-claim
  confidence levels: double descent qualifying Ch 5's U-curve, AdamW splitting weight decay from
  L2 (Ch 7 treats them as interchangeable), transformers displacing Ch 10's recurrence (keep the
  gradient analysis, drop the architecture advice), diffusion growing out of Ch 14's denoising
  autoencoders and Ch 18's score matching, and self-supervised learning vindicating Ch 15 while
  replacing every method it names. Two claims are marked contested rather than propagated (batch
  norm's "internal covariate shift" mechanism; the strong lottery-ticket form) and two named as
  folklore. The stated rule: **the conflict is almost always in the recommendation, not the
  analysis.**
- **4 stdlib tools, each with a real refusal.** `reading_path_planner.py` (goal → prerequisite
  closure over the book's actual dependency graph, ordered, priced in weeks; exit 3 for a goal
  the book does not cover, naming what does; exit 4 with forcing questions when unroutable),
  `training_diagnostics.py` (Ch 11's rules in priority order, so a NaN is never reported as
  overfitting; exit 4 rather than diagnosing with no instruments), `capacity_planner.py`
  (regularization ladder in cost order, with "shrink the model" pushed **last** in the
  overparameterized regime per double descent; exit 4 on a val-below-train split),
  `model_arithmetic.py` (params/FLOPs/activation memory per example for conv, linear, MHA and
  LSTM/GRU stacks; exit 5 naming the layer whose shapes do not connect).
- 4 references citing 7-8 sources each, 3 assets, `cs-deep-learning-tutor` agent, `/cs:deep-learning`
  + `/cs:dl-reading-path` + `/cs:dl-diagnose`. **Counters:** skills 386 → 387; tools 723 → 727;
  refs 838 → 842; agents 116 → 117; commands 146 → 149; plugins 97 → 98 (verified via
  `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.12.0) — marketing/linkedin (organic LinkedIn presence, platform rules in code):**

New `marketing/linkedin/` plugin answering [discussion #934](https://github.com/alirezarezvani/claude-skills/discussions/934), which asked for a strategic assistant for growing a LinkedIn presence organically rather than a post generator. Six skills (orchestrator + profile + strategy + content + engagement + analytics), 17 stdlib-only tools, 15 references, 2 agents, 8 `/cs:*` commands.

- **The design constraint is the differentiator.** No LinkedIn credentials, no API calls, no scraping, nothing auto-sent — automated posting/connecting/commenting are prohibited by LinkedIn's User Agreement §8.2, and a restricted account ends a compounding asset. `linkedin_policy_gate.py` runs before any drafting and refuses seven request classes (automation, scraping, engagement pods, bulk messaging, fake identity, fabricated proof, named third-party automation platforms), each carrying the policy anchor **and a compliant substitute** — the gate never just says no. Orchestrator is `context: fork` with a deterministic five-lane router (route 0 / ask 2 / no-signal 3) and cross-lane prerequisites.
- **Refusals are real, not warnings.** Cadence under 90 min/week returns a comment-only plan rather than a schedule that dies in week five; a newsletter whose six-month cost exceeds the budget is refused before the promise is made; an experiment needing more posts than a quarter allows is reported infeasible rather than quietly re-sized; the pattern miner refuses to test anything below 10 posts and reports `NOTHING_SURVIVED` as a finding.
- **Evidence discipline — two popular claims corrected rather than propagated** (the `andreessen` precedent). (1) "A personalised note triples connection acceptance (~45% vs ~15%)" is not supported by the largest samples, which show acceptance close to identical either way (~26.4%); what a note actually moves is the **post-accept reply rate** (~5.4% → ~9.4%) — which is why `outreach_message_builder.py` refuses an ask in a first-touch note. (2) The ~19% in-body external-link reach reduction has **never been confirmed by LinkedIn as a penalty** and has a plausible dwell-time explanation, so it is a warning, not a block. Every reference carries per-claim confidence levels (🟢 LinkedIn-official / 🟡 third-party study / 🔴 folklore, named as folklore).
- **Accessibility is a blocking lint finding, not a footnote.** Unicode pseudo-bold (the output of "bold text generators") fails the linter: screen readers announce those characters as mathematical symbols and LinkedIn search does not index them as words. Engagement bait is also blocking, per the Professional Community Policies. `pattern_miner.py` adds multiple-comparisons accounting and mirrored-candidate de-duplication that no comparable tool implements.
- All six SKILL.md files are a full **6/6 PASS** on the write-a-skill checklist (binding for post-v2.6.0 skills). Every tool supports `--help`/`--sample`/`--output json` with typed exit codes. **Counters:** skills 380 → 386; tools 706 → 723; refs 823 → 838; agents 114 → 116; commands 138 → 146; plugins 96 → 97 (verified via `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.12.0) — engineering/spinning-up-deep-rl (the first book compiled by book-to-skill):**

The first knowledge-base plugin produced end-to-end by `engineering/book-to-skill`, from OpenAI's
[Spinning Up in Deep RL](https://spinningup.openai.com/) (MIT, © 2018 OpenAI; primarily developed by
Joshua Achiam). Source obtained by cloning `openai/spinningup` and compiling its `docs/` reStructuredText
tree — 38 files, ~37k words, ~49K tokens — through the full pipeline: `extract_document.py --mode technical`
→ analysis → 20 chapter files → glossary / patterns / cheatsheet → master `SKILL.md` → `book_skill_validator.py`
→ `skill_plugin_emitter.py`. Validator passes clean **in `--strict` mode**; every file is inside budget
(resident core 2,101 / 4,000 tokens; 20 chapters averaging ~1,256 tokens each, loaded on demand).

- **Rights basis is `open-license`, not fair use.** The emitter's Step-11 gate refuses a shareable package
  without one; MIT permits derivative distribution. Upstream's notice is reproduced in full in the plugin's
  `LICENSE` alongside this package's own, and the README names the source, the author and the commit-era —
  a sidecar JSON is not a license notice.
- **Chapter structure follows the source's own `toctree`**, not a heading scan: user documentation (ch01-06),
  Introduction to RL Parts 1-3 (ch07-09), resources — the researcher essay, key papers, exercises, benchmarks
  (ch10-13), one chapter per algorithm in lineage order (ch14-19: VPG → TRPO → PPO, DDPG → TD3 → SAC), and the
  logger/MPI/ExperimentGrid utilities (ch20).
- **The cheatsheet carries what a glossary cannot**: the debug-turnaround threshold (under 5 minutes), the seed
  minimums (3, ideally 10+), the benchmark network defaults that differ by algorithm family ((64,32)/tanh
  on-policy vs (256,256)/relu off-policy), and Spinning Up's own **parity disclosure** — DDPG/TD3/SAC are
  research-grade, VPG/TRPO/PPO are not, and the docs say to use OpenAI Baselines for those instead.
- **One emitter defect found and fixed in the same change.** `skill_plugin_emitter.py` was writing its `source`
  provenance block into `plugin.json`, which this repo's own `scripts/check_plugin_json.py` hard-fails
  (issue #954 — Claude Code rejects the whole manifest on any unrecognized key). Its inline comment claimed
  `source`/`attribution` were "approved extension fields," which had been true and no longer was. The manifest
  builder now emits spec fields only and a new `_authoring_notes()` writes `.claude-plugin/authoring-notes.json`.
  Every future `book-to-skill` package gets a manifest that passes CI; the one emitted here was the first to
  catch it.
- **write-a-skill checklist: 4/6, and the two remaining are structural, not defects.** A compiled
  knowledge base is not a hand-authored instruction skill. (2) "SKILL.md under 100 lines" conflicts
  with the format's mandatory 20-row Chapter Index plus Topic Index; the binding budget here is
  `book_skill_validator.py`'s 4,000-token cap, and the file sits at 2,101 — trimming to 100 lines
  would delete exactly the navigation that `budget.over_cap` exists to protect. (3) "no
  time-sensitive info" fires on "January 2020", which is a **provenance pin on a frozen source**
  (Spinning Up's last update), not a staleness claim — removing it would make the skill less honest
  about what it covers. (5) was a real gap and is fixed: the resident core now carries a worked
  invocation block.
- **No new Python tools** — a compiled knowledge base ships notes, not scripts, so the tools and references
  counters are unchanged. **Counters:** skills 387 → 388; agents 117 → 118; commands 149 → 150; plugins
  98 → 99, on top of `deep-learning-book` which merged into `dev` first (verified via
  `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.11.2) — engineering/skill-doctor (grade the agent setup from real sessions):**

Rebuild of [warpdotdev/common-skills](https://github.com/warpdotdev/common-skills)' `skill-doctor` (MIT, © Denver Technologies, Inc., pinned at `f3b58c81`) as a full plugin. Harvests the last N days of local Claude Code / Codex sessions scoped to one repo, has the agent judge each condensed transcript against two verbatim-preserved rubrics (efficiency, code quality — labels only, closed tables), measures which installed skills actually fired, and proposes only the skill edits the evidence justifies — one local, self-contained HTML report; nothing is ever uploaded.

- **22 numbered deviations from upstream** — `engineering/skill-doctor/README.md`'s list is authoritative; `authoring-notes.json` summarizes it. Headline additions: **`score_aggregator.py`, a deterministic gate with no upstream counterpart** — upstream let the scoring LLM average its own scores and assemble `report.json`; here labels map to scores via embedded tables mirroring the rubrics, scores for unsampled sessions are rejected as fabrications, reasons are length-checked, and a suggestion that cites no scored session id (or carries no diff) fails at exit 4. **Collector hardening:** always-on 12-pattern secret redaction before any transcript touches disk (no off switch; per-label counts land in the inventory and report), `chmod 0700/0600` artifacts, plugin-layout skill discovery (`*/skills/*/SKILL.md`), slash-command usage detection mined from `<command-name>` markers before the injection filter drops them. **Renderer replaced:** zero JavaScript (upstream embeds a 1,531-line prebuilt diff bundle + canvas share-image) — pure-CSS diff coloring, native `<details>` collapse, `prefers-color-scheme`, print-to-PDF; Warp branding and the `warp.dev/factories` CTA removed. **Dropped:** the Warp `warp.sqlite` source and its 388-line hand-rolled protobuf decoder (unauditable vendored binary-format code; Warp users should run upstream).
- Preserved verbatim: both scoring rubrics (`scorers/`) and the skill-improvement filing bar ("would a competent agent with the current instructions still fail this way?"), now §1–§2 of `references/skill_edit_governance.md`. Zero suggestions clearing the bar is a valid, reportable success; proposed edits stay staged under the run's scratch dir until an explicit per-skill yes, and proposals for this repo's skills must pass write-a-skill's 6-item checklist.
- 3 stdlib tools (all `--help`/`--sample`/`--output json`, typed exit codes; the pipeline smoke-tests end-to-end from `--sample` fixtures including a planted fake secret), 3 references citing 7 sources each, 3 handoff-shape assets, `cs-skill-doctor` agent, `/cs:skill-doctor` command. SKILL.md is a full 6/6 PASS on the write-a-skill checklist. Distinct from `skillopt-sleep` (automated nightly loop; this is one interactive graded pass), `write-a-skill` (authors from expertise; this improves from evidence), and self-eval (grades the current session; this grades a window). **Counters** (this branch merged `dev` after `agent-memory` landed, so these deltas sit on top of it): skills 378 → 379; tools 703 → 706; refs 820 → 823; agents 110 → 111; commands 130 → 131; plugins 95 → 96 (verified via `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.11.2) — engineering/book-to-skill (document → knowledge-base skill → plugin):**

Derived from [virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill) (MIT). Compiles a book, documentation folder, or spec collection (PDF, EPUB, DOCX, HTML, Markdown, RST, AsciiDoc, RTF, MOBI/AZW) into an agent skill: a resident master `SKILL.md` (core frameworks + chapter index + topic index, capped at 4k tokens) plus on-demand `chapters/chNN-*.md`, `glossary.md`, `patterns.md`, and a decision `cheatsheet.md`. The agent reads the core, then one chapter — never the whole source again.

- **Vendored close to verbatim:** the extraction library (`scripts/book_to_skill/` — config, exceptions, sanitize, dependencies, utils + 7 per-format parsers) keeps upstream's format chains, chapter detection across Latin/Roman/Chinese/Thai/Korean heading styles, invisible-Unicode (Trojan Source) sanitization and DOCX entity-expansion guard.
- **26 numbered deviations from upstream** — the list in `engineering/book-to-skill/README.md` is authoritative; the plugin's `authoring-notes.json` `attribution.derivation_note` summarizes it. Highlights: (5) `--install-missing` now defaults to `report` — it prints the pip command and uses the stdlib fallback instead of upstream's TTY prompt that runs `pip install` into the caller's environment; (6) a **rights gate** — `skill_plugin_emitter.py --distribution shareable` refuses without `--rights` from `public-domain|open-license|internal-docs|author-permission`, with `fair-use` deliberately excluded (a defence, not a licence); (10) the two upstream validators merged into one four-family gate, adding **budget** and **index** families — dead chapter links, unindexed chapter files and dangling topic refs are the failure that silently breaks navigation while the skill still looks complete, and upstream had no check for it; (11) folded YAML scalars now parse, so a wrapped description no longer under-reports its length past the 1024-char cap; (12) `discovery_tax.py` → `token_budget_estimator.py` with the optional `tiktoken` path dropped, a post-flight budget audit added, and an explicit **worth-converting verdict** that says "just read it" when the source is under ~3× the compiled skill.
- **Repo-native addition with no upstream counterpart — Step 11 / `/cs:book-to-plugin`:** upstream stops at a bare folder in `~/.claude/skills/`, which this library cannot route to. `skill_plugin_emitter.py` wraps a compiled skill as a full plugin package (manifest + `cs-<slug>` agent + `/cs:<slug>` command + README) and prints the marketplace entry; it never edits `marketplace.json` itself, and refuses to wrap a skill carrying validation errors.
- **Cross-linked into `engineering/write-a-skill`** ("author first, compile second" — that skill authors from expertise in your head, this one compiles from a document on disk).
- 4 stdlib-only tools (all `--help` / `--sample` / `--output json`), 5 references citing 7–8 sources each, 3 assets, `cs-book-to-skill` agent, 2 commands. **Counters:** skills 362 → 363; tools 644 → 663; refs 741 → 746; agents 102 → 103; commands 116 → 118; plugins 88 → 89 (derived via `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.11.2) — engineering/memory-engineering (engineer the forgetting, not the remembering):**

New `engineering/memory-engineering/` plugin. Fills a real gap: the repo had no
skill for designing, pricing, or auditing an **agent memory system** (nearest
neighbours `llm-wiki`, `skillopt-sleep`, `agent-harness` all bound something
else — a vault, a loop, a task plan). Framing synthesized from *"How to be a
Memory Engineer, from the perspective of Stanford, Microsoft, Anthropic and
Nvidia"* by [@N01ennn](https://x.com/N01ennn/status/2083971749079581120), with
every quantitative claim re-cited to the primary source.

- **4 stdlib scripts, one per lens.** `memory_cost_profiler.py` (construction vs
  query split, **cost per correct answer**, amortization, co-location warning →
  WRITE-PATH-DOMINANT / UNDER-AMORTIZED / NEEDS-SCHEDULING-FIX);
  `memory_architecture_picker.py` (scores the paper's four paradigm families,
  disqualifies on hard constraints, **names the cost the choice makes you pay**,
  and exits 2 refusing to pick when the top two are within 0.06 — printing the
  tie-breaking question instead); `memory_density_auditor.py` (classifies every
  record **FACT / SKILL / LOG / PROSE**, near-duplicates via word-shingle
  Jaccard, staleness + volatile-wording flags, knowledge density per 1k tokens;
  runs on a real `--dir` **or** `--jsonl`); `forgetting_policy_linter.py` — **the
  gate**: 8 checks with **F1** (explicit forgetting rule) and **F4**
  (contradictions surfaced, never auto-merged) blocking at exit 4.
- **Evidence discipline — two of the source article's paraphrases are corrected
  in the references rather than propagated.** (1) The 47× energy figure is the
  *spread across ten evaluated systems* (BM25 at 4,145 J/correct answer vs
  A-Mem/MIRIX at 115–197 kJ, a "28–47× premium"), **not** "two systems with
  identical accuracy." (2) The 97% first-pass-error reduction is **Rakuten's
  named vendor-published customer testimonial** (Yusuke Kaji, at 27% lower cost
  / 34% lower latency), not a controlled study or a general property of the
  approach. Every reference carries per-claim confidence levels, per the
  `andreessen` precedent.
- **Two classifier defects found and fixed during the build**, both of which
  would have produced garbage on any real repo: markdown headings *inside*
  fenced code blocks were splitting records (fixed by masking fences before
  heading detection — dropped 258 phantom records to 107 on a real directory),
  and short fragments trivially matched at 1.00 Jaccard (fixed with a
  20-word floor for duplicate candidacy, eliminating 41 false-positive
  "duplicates"). A third fix added the **PROSE** class: an earlier version
  labeled every signal-less block LOG, firing LOG_HEAVY at 74% on a prose
  documentation folder.
- 4 references citing 7 sources each (arXiv:2606.06448 Stanford characterization;
  MSR PlugMem; arXiv:2604.09852 MEMENTO + OpenMementos; Anthropic managed-agents
  memory), 3 assets (seven-question forcing worksheet, combined example spec
  consumed by all three spec-taking scripts, fillable F1–F8 policy template),
  `cs-memory-engineer` agent, `/cs:memory-engineering` + `/cs:forgetting-audit`.
- **SKILL.md is a full 6/6 PASS** on the write-a-skill checklist (binding for
  post-v2.6.0 skills). **Counters** (this branch merged `dev` after
  `book-to-skill` landed, so these deltas sit on top of it): skills 363 → 364;
  tools 663 → 667; refs 746 → 750; agents 103 → 104; commands 118 → 120;
  plugins 89 → 90 (verified via `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.11.2) — engineering/agent-memory (promotion is earned, not asserted):**

New `engineering/agent-memory/` plugin. Concept derived from
[TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
(MIT) — **no upstream code included**. A four-tier ladder over Claude Code's own
hooks: **L0** raw transcripts (never injected) → **L1** candidate atoms
(gitignored, recalled on lexical relevance per prompt) → **L2** project context
(committed after adopt, loaded every session start) → **L3** stable persona
(always loaded). Tiers are distinguished by *injection policy*, not storage
format.

- **Three upstream choices deliberately rejected**, each for a repo rule rather
  than taste: the managed **database** (self-contained-package rule → one
  append-oriented JSONL per project, capped at 500 atoms); a **proxy layer**
  between agent and model (Claude Code already exposes the three interception
  points — adding a proxy to obtain hooks the platform provides buys nothing and
  adds a failure mode on the critical path); **LLM-based extraction** (the
  no-LLM-in-scripts anti-pattern, and a model call cannot run in an async
  teardown hook on a latency budget, nor reproduce its output from the
  transcript, which would break "cite, don't invent").
- **The gates are the design.** L1→L2 needs ≥3 distinct sessions spanning ≥2
  distinct calendar days (`stated` = 2 sessions, day rule *still applies*;
  `verified` = 1 observation and is the only day-exempt path); L2→L3 needs ≥2
  distinct projects + 30 days. Thresholds are tuned toward refusing because the
  error costs are asymmetric: under-promotion is self-healing (the user restates
  it, which is itself an observation), over-promotion silently steers every
  future session.
- **Two gates refuse rather than guess.** `redacted: true` blocks promotion on
  *any* volume of evidence — a **durability-independent barrier**, since a
  secret restated over five sessions passes every recurrence gate; the flag
  firing means the text was altered, and a lexical filter finding one secret is
  not proof it found all of them, while L2/L3 are committed to git. An open
  contradiction freezes both claims, found by **reverse join** (the newer atom
  carries no flag) rather than a mirrored field.
- **Three hooks, all fail-open.** `SessionStart` injects L2+L3 and marks
  L2↔L3 collisions the project-scoped detector structurally cannot see;
  `UserPromptSubmit` recalls on a **100 ms internal budget** against a monotonic
  clock (the 1 s hook `timeout` is a wedged-process backstop, not the budget);
  `SessionEnd` is async and captures → redacts → merges → detects → stages.
  Measured: spawn+recall p50 ≈ 29 ms / p95 ≈ 31 ms, scoring itself 2–3 ms over
  500 atoms — **interpreter cold start is the entire cost**, which is why the
  in-script loop is not worth optimizing further.
- **Nothing reaches a `CLAUDE.md` without a human.** Promotions land in
  `.memory/staged/`; `/cs:memory adopt` walks them one at a time and backs both
  files up first. `cs-memory-curator` refuses to adopt a redacted claim, an
  unresolvable citation, or to resolve a contradiction itself.
- 5 stdlib scripts + 3 hooks (`memory_core.py` is a deviation from `DESIGN.md`
  §10's four-script tree — the **`README.md` deviations list is authoritative**,
  and §10.1's stale `+6` tool estimate is corrected to `+8` there and in
  `DESIGN.md`), 3 references citing 6–7 sources each with per-claim confidence
  levels, a 69-check example validator, and `DESIGN.md` — ~1,400 lines, 44
  review rounds, open decisions ranked by what they gate, including the one that
  permits deleting the folder if rule-based recall proves too low.
- **SKILL.md is a full 6/6 PASS** on the write-a-skill checklist. **Counters:**
  skills 377 → 378; tools 695 → 703 (+8: 5 scripts + 3 hooks); refs 817 → 820;
  agents 109 → 110; commands 129 → 130; plugins 94 → 95 (verified via
  `scripts/derive_counters.py --check`).

---

**Unreleased (post-v2.11.1) — productivity/fable-goal (ramble → autonomous /goal prompt):**

Improved port of `duncan-buildroom/freeskills` `fable-goal` (informal "free to use and modify" grant — quoted, not relicensed; see the `attribution` block). Converts a rambling description of a desired outcome into one polished, copy-paste /goal prompt for a fresh autonomous session — the prompt is the deliverable, never the build. Adds over upstream: wrong-tool check, observable-done principle, six-slot extraction (deliverable/quantity/stakes/tools/quality/destination), per-medium verification defaults, six-point pre-delivery self-check, anti-pattern list + failure-mode catalog reference, second worked example in a non-web medium. Ships `goal_prompt_self_check.py` (stdlib runner for the mechanically checkable self-check subset — word count 150–350, goal line, autonomy directive, verification/freedom/destination language; exit 0/1, `--sample`, `--output json`), `/cs:fable-goal` command. Intentionally no `agents/`/`assets/` (single reasoning pass; see plugin README design notes). SKILL.md is a full PASS on the write-a-skill 6-item checklist. Counters: skills 357 → 358 (this PR also trues up pre-existing engineering-row drift 355 → 357); tools 602 → 603; refs 731 → 732; commands 109 → 110; plugins 83 → 84.

---

**Version:** v2.11.1 (pm/product agent-harness domains — deep audit + orchestrated loops for product-team & project-management)

**v2.11.1 highlights — both PM/product routers become agent harnesses:**

Extends the v2.11.0 agent-harness layer to the two people-process domains. Public audit record at `audit/pm-product-agentic-2026-07/` (AR-rubric scores for all 26 skills, research-backed improvement fields, executable verification criteria).

- **project-management → delivery loop:** `pm-skills` rebuilt as a `context: fork` orchestrator with 3 stdlib tools — `pm_goal_router.py` (8 lanes, exit-code route/ask/refuse), `jira_snapshot_bridge.py` (saved `searchJiraIssuesUsingJql` output → Kanban-Guide-2025 flow metrics with SLE + aging-WIP alerts + seeded Monte Carlo forecasts that sample zero-throughput weeks, or the scrum-master sprint schema — verified end-to-end into `velocity_analyzer.py`), `delivery_loop_gate.py` (delegation governance G1–G6: human owner, reviewer for agent tasks, machine-checkable acceptance, evidence-before-done, close refusal, exhausted-budget-is-escalation). Five reusable PM loops documented with named terminal states. Agent `cs-pm-orchestrator`; commands `/cs:pm`, `/cs:grill-pm`, `/cs:pm-loop`.
- **product-team → discovery loop:** `product-skills` rebuilt as a `context: fork` orchestrator with 3 stdlib tools — `product_goal_router.py` (16 lanes incl. the 4 standalone plugins), `discovery_cadence_tracker.py` (Torres weekly-habit health 0–100 with named gaps + `next_loop_action`), `ost_linter.py` (Opportunity Solution Tree rules O1–O5; exit 2 blocks an unsound tree from driving a roadmap). Agent `cs-product-orchestrator`; commands `/cs:product`, `/cs:grill-product`, `/cs:product-loop`.
- **6 new references** citing 6–7 sources each (flow/forecasting canon, agentic delivery governance, PM loop playbook, continuous discovery, product operating model, AI product evals) + pinned fixtures; fixed the two CLI-noncompliant product tools (`user_story_generator.py`, `persona_generator.py` — real argparse `--help`, seeded determinism); regenerated both domain harness manifests (orchestrators now score all five `agentic_signals`; manifest builder now truncates descriptions on word boundaries).
- **Counters:** tools 596 → 602; refs 725 → 731; agents 97 → 99; commands 103 → 109 (derived via `scripts/derive_counters.py --check`).

---

**Version:** v2.11.0 (agent-harness — turn any domain into a bounded, self-verifying agent loop + engineering agentic-readiness audit)

**v2.11.0 highlights — agent-harness skill + AR audit of both engineering folders:**

New `engineering/agent-harness/` skill — the thin unifying layer that lets an agent or subagent pick up a goal for any of the repo's 18 (now 19) domains, decompose it into verifiable tasks, execute them with the domain's own tools, verify each with machine-run checks, retry within caps, escalate to a human on exhausted budgets, and refuse to close until every task is verified or explicitly waived.

- **3 stdlib tools:** `harness_manifest_builder.py` (scans a domain folder → `manifest.v1` JSON: skills, tools, exact `--help`/`--sample` checks, static agentic signals), `goal_compiler.py` (goal + manifest → `plan.v1` task plan via deterministic keyword scoring; refuses vague goals exit 3 with forcing questions, no-match exit 4 with nearest candidates), `loop_controller.py` (JSON-backed `init/next/record/verify/close/status` state machine — runs verification checks itself via subprocess to prevent verification theater, caps attempts + iterations with escalation, refuses close while any task is unverified; atomic state writes via `os.replace`).
- **18 committed per-domain manifests** under `assets/harnesses/` (the whole repo, machine-readable), a JSON schema, `harness-runner` agent, `/cs:harness <domain> <goal>` command, and 3 references citing the 2024–2026 harness canon (Anthropic long-running-agents harness, verifier's law, SWE-agent, Ralph loop, Cognition serialize-writers, plus the repo's own tc-tracker / autoresearch locked-evaluator / loop-library stop-state primitives — reuse, not reinvention).
- **Agentic-readiness audit** at `audit/engineering-agentic-2026-07/` — both `engineering/` (63 skills) and `engineering-team/` (52 skills) re-scored on a 6-dimension AR rubric (goal intake, decomposition, deterministic execution, verification, loop discipline, close-out) plus a delta check against the June 2026 baseline. Combined: 26 HARNESS-READY · 39 LOOP-CAPABLE · 43 TOOL-ONLY · 7 PROSE-ONLY. Headline finding: **AR5 (loop discipline) is the repo-wide gap** — a one-sentence iteration-cap sweep across ~15 skills would roughly double HARNESS-READY. New defects logged (ship-gate orphaned scanner + table drift, senior-data-engineer CLI mismatch, senior-ml-engineer stale 2024 pricing).
- **Marketplace + counters:** 82 → 83 plugins; skills 354 → 355; tools 593 → 596; refs 722 → 725 (derived via `scripts/derive_counters.py --check`).

---

**Version:** v2.10.3 (md-slides — slide-deck converter; completes the markdown-html/ domain)

**v2.10.3 highlights — md-slides (markdown deck → single-file HTML presentation):**

Completes the `markdown-html/` domain at 5 skills. The Tier-3 use case from Shihipar's essay ("Slide Decks"): a markdown deck (slides separated by `---` HR boundaries or `# ` H1 headings, with optional `<!-- notes: ... -->` presenter notes blocks) becomes a single-file HTML presentation that runs in any browser with keyboard nav, presenter mode, and print-to-PDF.

- **`md-slides` skill** — three stdlib tools pipeline together (slide_splitter → presenter_notes_parser → deck_html_renderer):
  - **`slide_splitter.py`** — splits markdown on `---` HR or `# ` H1 boundaries (or `--boundary auto`: HR wins ≥ 3, else H1 ≥ 5). Extracts the first heading per slide as the title. Hard rule: refuses 1-slide decks (exit 5 — it's a poster) and no-boundary input (exit 6 — route to md-document). Soft-warns slides > 40 source lines (signal-to-noise; renders anyway).
  - **`presenter_notes_parser.py`** — extracts `<!-- notes: ... -->` blocks (also `speaker-notes:` and `presenter:` aliases) from each slide, attaches as a separate `notes` field, strips from the body so the slide renders cleanly. Tracks `notes_coverage_pct` for the optional `--strict-notes` gate (refuses < 50% coverage).
  - **`deck_html_renderer.py`** — single-file HTML deck. All slides as `<section class="slide">` elements, one visible at a time (CSS-controlled). Vanilla JS keyboard handlers: `→`/`Space`/`PgDn` advance; `←`/`PgUp` previous; `Home`/`End` first/last; `P` toggles presenter mode; `Esc` exits presenter. URL-hash deep linking (`#3` jumps to slide 3, browser back/forward walks slides). Progress bar at top (3px); slide counter bottom-right. Presenter mode = split view: current slide (60% width) + panel (40% width with clock + speaker notes + next-slide preview). `@media print { section { display: block; page-break-after: always; } }` → `Cmd+P` produces PDF with one slide per page. `prefers-reduced-motion` honored. Reuses `md-document/scripts/markdown_parser.py` for slide-body content rendering. Prism.js is **opt-in via `--syntax`** (off by default — most decks don't need it; keeps the file tiny).
- **3 reference docs** each citing 5-7 sources: `presentation_ux.md` (Atkinson *Beyond Bullet Points* + Reynolds *Presentation Zen* + Tufte *Cognitive Style of PowerPoint* + NN/g + Weinschenk + Marp/reveal.js/Big convergence + Tom MacWright), `keyboard_nav_patterns.md` (reveal.js / Big / Spectacle keymap + WCAG 2.1.1 + 2.4.3 + MDN KeyboardEvent + NN/g), `single_file_deck_conventions.md` (Big + Marp + Pandoc + reveal.js standalone + WCAG 2.3.3 + `@media print`).
- **1 template asset** documenting the canonical single-file deck shape.
- **`/cs:md-slides` slash command** with 6 pre-flight gates + pipeline + output digest.
- **Empirical footprint**: 5-slide sample deck (3 with presenter notes) → 12.2 KB single-file HTML with keyboard nav + presenter mode + print-to-PDF. By comparison, equivalent Google Slides / Keynote / reveal.js multi-file exports are 200 KB+ of CSS/JS chrome.
- **Plugin manifest:** `markdown-html-skills` plugin.json `skills` array now lists 5 paths (orchestrator + design-system + md-document + md-review + md-slides). Marketplace counters updated (trued up 2026-06-10 via `scripts/derive_counters.py`): 77 plugins, 17 domains, **345 skills**, **580 Python tools**, **702 references**, **99 slash commands**.
- **Domain status: COMPLETE.** All 5 planned skills shipped across 4 PRs (#780 foundation, #793 md-document, #795 md-review, this PR md-slides). The markdown-html/ domain operationalizes Shihipar's central claim — markdown collapses past 100 lines; HTML restores density, clarity, shareability, and lightweight interaction — across all three layout families (long-form documents, code reviews, slide decks).

---

**Version:** v2.10.2 (md-review — code-review converter for the markdown-html/ domain)

**v2.10.2 highlights — md-review (code-review markdown → 2-col HTML):**

Adds the fourth skill to `markdown-html/`. The Tier-2 use case from Shihipar's essay ("Code Review and PR Writeups"): a markdown PR writeup with ```diff blocks and `> [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT]` severity callouts becomes a single-file 2-column HTML review with a top jump-nav, diff on the left, severity-tagged annotation cards on the right, and a mandatory named reviewer footer.

- **`md-review` skill** — three stdlib tools pipeline together (diff_parser → annotation_extractor → review_html_renderer):
  - **`diff_parser.py`** — scans markdown for ```diff fenced blocks, parses each as a unified diff (`--- a/file`, `+++ b/file`, `@@ -10,7 +10,8 @@`, ` ` / `+` / `-` body lines), assigns per-line numbers on both old (`lo`) and new (`ln`) sides, preserves the per-hunk @@ header context. Supports `--infer-diff` for unfenced/language-less blocks. Stdlib regex + state machine.
  - **`annotation_extractor.py`** — extracts severity callouts (GFM `> [!BLOCKER]` style) and inline markers (`nit:`, `blocker:`, etc.). Default convention BLOCKER/MAJOR/MINOR/NIT per Google's *Code Review Developer Guide*; overridable via `--severity-convention "critical,important,suggestion,nit"`. Attaches each annotation to the nearest preceding diff block by source-line index; unanchored annotations go to a "general comments" section. Also captures `LGTM`/`👍`/`approved` markers separately as approvals.
  - **`review_html_renderer.py`** — emits single-file 2-col HTML. Top jump-nav lists every annotation with severity badge + 80-char preview + jump link + counts in heading ("3 BLOCKER · 2 MAJOR · 1 NIT"). Each hunk-row is a CSS grid with diff on the left (per-line numbers, +/− marks, addition/deletion bg tints from `--md-success` / `--md-warn` via `color-mix`) and annotation cards on the right (severity badges that ship color + icon + aria-label + text per WCAG 1.4.1; BLOCKER danger color computed by hue-rotating the design-system accent 120° toward red). Approval bar surfaces when LGTM markers present and no findings. Collapses to stacked on viewports < 900px. Mandatory `--reviewer` (refuses with exit 3 otherwise — research-ops named-owner discipline). Refuses with exit 4 if no hunks present (wrong skill → route to md-document). No Prism CDN (diff coloring conflicts with syntax highlighting).
- **3 reference docs** each citing 5-7 sources: `diff_rendering_canon.md` (POSIX diff + GitHub/GitLab + difftastic + *SWE at Google* ch. 9), `severity_coding.md` (WCAG 1.4.1 + Google review taxonomy + Don Norman *Design of Everyday Things* + NN/g color UX), `pr_annotation_ux.md` (convergent 2-col UX from GitHub/GitLab/Reviewable/CodeStream + *SWE at Google* + NN/g F-shape).
- **1 template asset** documenting the canonical 2-col review HTML shape.
- **`/cs:md-review` slash command** ships the 4 pre-flight gates (under-100-lines, no-onboarding, missing-reviewer, no-hunks) + pipeline + output digest.
- **Empirical footprint**: 2-hunk sample review with 2 annotations → 11.3 KB single-file HTML.
- **Plugin manifest:** `markdown-html-skills` plugin.json `skills` array now lists 4 paths. Marketplace counters updated: 64 plugins, 17 domains, **342 skills** (was 341 after v2.10.1).

**Coming in v2.10.3:** `md-slides` — slide splitter + presenter-notes parser + arrow-key/space-bar nav + `@media print` for PDF export. Reuses `md-document`'s renderer scaffolding + `design-system/scripts/config_loader.py`.

---

**Version:** v2.10.1 (md-document — long-form converter for the markdown-html/ domain)

**v2.10.1 highlights — md-document (long-form markdown → single-file HTML):**

Adds the third skill to `markdown-html/` (foundation shipped in v2.10.0). The 90%-case converter: any markdown spec, plan, RFC, report, or explainer becomes a single-file, lightly-interactive HTML document with the user's onboarded brand.

- **`md-document` skill** — three stdlib tools pipeline together (markdown_parser.py → html_renderer.py → interactivity_injector.py):
  - **`markdown_parser.py`** — CommonMark subset → section AST (headings 1-6 with slug anchors, paragraphs with inline bold/italic/code/links/images, fenced code with language tag, GFM tables with per-column alignment, GFM callouts NOTE/TIP/IMPORTANT/WARNING/CAUTION, blockquotes, ordered + unordered lists, horizontal rules). Stdlib regex + state machine, no `markdown` dependency.
  - **`html_renderer.py`** — section AST + design-system config → single-file HTML. Inlines the 12 derived CSS custom properties from `~/.config/markdown-html/design-system.json`, applies the user's `design_style` (editorial/technical/minimal/playful) via body-class CSS overrides, renders Google Fonts CDN link + Prism.js theme link per `code_theme`, emits sticky-sidebar / collapsible-top / inline / none TOC per `toc.behavior`. Smoke-tested: changing design_style actually changes max-width, line-height, callout shape, and code font-size — customization is in-use, not decorative.
  - **`interactivity_injector.py`** — vanilla-JS payload injected before `</body>`: search filter on H2 sections (Esc clears), code-copy buttons (navigator.clipboard with execCommand fallback), smooth-scroll on TOC links, scrollspy via IntersectionObserver (sets `aria-current="location"` on the matching TOC entry). Idempotent (marker check). Feature subset selectable via `--features search,copycode,smoothscroll,scrollspy`.
- **3 reference docs**, each citing 5-7 sources: `information_density_patterns.md` (Shihipar + Tufte + Wattenberger + Appleton + Ciechanowski + Bret Victor + Jakob Nielsen), `toc_and_nav_ux.md` (NN/g + WCAG 2.2 + ARIA APG + Vitepress/Docusaurus/mdBook convergence + GOV.UK design system + MDN IntersectionObserver), `single_file_html_discipline.md` (Shihipar + Tom MacWright's Big + Google Fonts API + Prism.js + Anil Dash's *The Web We Lost*).
- **1 template asset** (`md_document_template.html`) documenting the canonical output shape for renderer reference.
- **`/cs:md-document` slash command** ships the pre-flight gates + 3-tool pipeline + output digest.
- **Empirical footprint**: ~150-line markdown → 11 KB HTML / 15 KB with JS; ~470-line markdown → 17 KB / 23 KB with JS. By comparison, equivalent Notion/Confluence/GitBook exports are 200 KB+ of CSS chrome.
- **Plugin manifest:** `markdown-html-skills` plugin.json `skills` array now lists 3 paths (orchestrator + design-system + md-document). Marketplace + root CLAUDE.md counters updated: 64 plugins, 17 domains, **341 skills** (was 338 before v2.10.0). Cleans up stale 338/63 counters left by v2.10.0 PR #780.

**Coming in v2.10.2:** `md-review` (2-col diff + severity-tagged margin annotations + jump-nav) and `md-slides` (arrow-key nav + presenter mode + print-to-PDF). Both will reuse `md-document`'s renderer scaffolding and `design-system/scripts/config_loader.py`.

---

**Version:** v2.10.0 (foundation released — `markdown-html/` domain: markdown-to-interactive-HTML converter)

**v2.10.0 foundation highlights — markdown-html/ domain (new top-level domain):**

New `markdown-html/` top-level domain — operationalizes Thariq Shihipar's central claim from his Medium essay *Claude Code HTML output: Why Markdown Lost and How to Switch* (2026): **markdown collapses past ~100 lines for agent-generated artifacts; HTML restores information density, visual clarity, shareability, and lightweight interaction.** Foundation PR (v2.10.0) ships 2 of 5 planned skills; converters land in v2.10.1.

- **`markdown-html-orchestrator`** (`context: fork`) — deterministic doctype classifier scores filename hints (2 points each) + content signals (1 point each) across three lanes (DOCUMENT / REVIEW / SLIDES). Silent-routes when winner ≥ 3 AND (runner-up = 0 OR winner ≥ 2× runner-up); below threshold asks one question with a recommended answer. Three pre-flight refusals: input < 100 lines (Shihipar threshold), design-system not onboarded, output dir unwritable. 3 stdlib tools: `doctype_classifier.py`, `route_explainer.py` (the "never silently chain" enforcer; also gates on design-system status), `output_path_resolver.py` (kebab slug + collision suffix). Canon: Shihipar; Tufte; Bret Victor; Maggie Appleton; Bartosz Ciechanowski; Amelia Wattenberger.
- **`design-system`** — one-time onboarding wizard (10 questions: `default_output_dir`, brand primary/accent HEX, heading + body Google Fonts from 12 safe defaults, design style `editorial/technical/minimal/playful`, syntax theme `light/dark/auto`, TOC behavior `sticky-sidebar/collapsible-top/inline/none`, optional company name + logo URL). WCAG-AA-validated 12-token CSS custom-property palette derived in HSL space — primary's luminance branch decides whether bg = primary (dark-mode docs) or bg = near-neutral light (vibrant primary as accent); link contrast iteratively walked to 4.5:1. 3 stdlib tools: `onboard.py` (interactive + `--defaults/--set/--show/--reset/--scope`), `config_loader.py` (project > global > defaults, deep merge, `MARKDOWN_HTML_NO_CONFIG=1` bypass), `brand_palette_validator.py` (WCAG 2.2 §1.4.3/§1.4.11 + HSL derivation, 12 tokens: `--md-bg/surface/border/text/text-muted/accent/accent-soft/code-bg/link/link-hover/success/warn`). Refuses to save if body-text or link contrast fails AA 4.5:1, or if output dir is unwritable. Canon: WCAG 2.2; Ellen Lupton *Thinking with Type*; Adobe Spectrum; Sara Soueidan accessible color tokens; Material Design 3.
- **`cs-markdown-html-orchestrator` agent + 3 slash commands:** `/cs:markdown-html <path>.md` (router), `/cs:grill-markdown-html <path>.md` (Matt-Pocock 5-question grill, one per turn with recommended answer + canon citation), `/cs:design-system` (surfaces onboarding). Forcing-question library in every SKILL.md.
- **Hard rules:** refuse < 100 lines (Shihipar); refuse without onboarding; refuse unwritable save dir; single-file HTML only (Google Fonts + Prism.js CDN are the only permitted externals; no JS framework runtimes); never silently chain converters; customization must change behavior (not decoration).
- **Coming in v2.10.1:** `md-document` (sticky TOC + collapsibles + search + code-copy + scrollspy), `md-review` (2-col diff + severity-tagged margin annotations + jump-nav), `md-slides` (arrow-key nav + presenter mode + print-to-PDF). All three import `design-system/scripts/config_loader.py` for shared tokens.
- **6 stdlib-only Python tools** (3 per skill, all pass `--help` + `--sample`), **6 reference docs** each citing 5-7 authoritative sources, **1 JSON schema asset** for the customization config. Distinct from Anthropic's official Playground plugin (interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from `marketing/landing/` (landing-page generator from scratch).
- **Marketplace + Codex registry:** 63 → 64 plugins; 16 → 17 domains; new `documentation` category.

---

**Version:** v2.9.0 (research-ops/ domain: enterprise Research Operations)

**v2.9.0 highlights — research-ops/ domain (new top-level domain):**

New `research-ops/` top-level domain — the enterprise / cross-functional counterpart to the academic `research/` domain (which finds literature, grants, patents). Single domain plugin (commercial/ + business-operations/ pattern): orchestrator (`context: fork`) + 4 managed sub-skills.

- **`clinical-research`** — prospective clinical STUDY design (not regulatory submission, which stays in `ra-qm-team`). 3 stdlib tools: `sample_size_estimator.py` (closed-form power/n for means/proportions/survival with a built-in z-table, dropout inflation, "ESTIMATE — confirm with a biostatistician" banner), `endpoint_selector.py` (5-dimension scoring → PRIMARY/KEY-SECONDARY/EXPLORATORY, penalizes unvalidated surrogates), `phase_gate_scorer.py` (feasibility 0-100 → GO/GO-WITH-CONDITIONS/REDESIGN/NO-GO + named owner chain). Canon: ICH E8/E9/E9(R1), CONSORT, SPIRIT, FDA Multiple Endpoints, Cohen, Schoenfeld.
- **`research-finance`** — internal R&D PROGRAM/portfolio finance (not corporate close `finance/`, not grant discovery `research/grants`). 3 tools: `program_budget_planner.py` (multi-period budget + F&A/MTDC split + assumptions block), `burn_runway_tracker.py` (trailing burn, runway, milestone-vs-cash), `capex_vs_opex_router.py` (IAS 38 / ASC 730 routing → CAPITALIZE-CANDIDATE/EXPENSE/FINANCE-OWNER-REVIEW, never auto-decides). Canon: IAS 38, ASC 730/985-20, 2 CFR 200, Cooper stage-gate, rNPV.
- **`market-research`** — upstream sizing/survey/segmentation methodology (not campaign analytics `marketing-skill`). 3 tools: `market_sizer.py` (TAM/SAM/SOM both top-down AND bottoms-up + triangulation flag, never a single number), `sample_size_planner.py` (survey n + FPC + per-segment minima), `segmentation_scorer.py` (Kotler 5-criteria + substantiality/accessibility gate). Canon: Cochran, Dillman, Groves, Kotler, Bessemer/a16z sizing.
- **`product-research`** — product/user research method + insight-repository discipline (not persona/journey/live-A-B `product-team`). 3 tools: `study_designer.py` (goal×stage → method + plan skeleton), `saturation_planner.py` (Nielsen-5 / Guest-12 with explicit confidence), `insight_synthesizer.py` (clusters coded observations, flags single-source anecdotes — never promotes them). Canon: Portigal, JTBD, Rohrer (NN/g), Nielsen, Guest et al., ResearchOps/Polaris.
- **Hard rules:** clinical outputs are estimates + named clinical owner (never fact); finance surfaces assumptions and routes treatment to a named finance owner (never auto-decides); market sizes show method + assumptions (never a single number); product insights require recurrence across independent participants. `cs-research-ops-orchestrator` agent + `/cs:research-ops` router + `/cs:grill-research-ops` (Matt docs-anchored grilling) + 4 per-skill commands.
- **Onboarding + customization + autoresearch (per sub-skill, isolated):** each sub-skill ships `onboard.py` (its own question set), `config_loader.py` (a customization config consumed by every tool, project>global>defaults precedence, `RESEARCH_OPS_NO_CONFIG=1` bypass), and `ar_evaluator.py` — an opt-in, locked-ground-truth bridge to `engineering/autoresearch-agent` (loop edits the skill's input file; metrics: clinical `feasibility_composite`↑, finance `runway_months`↑, market `tam_divergence`↓, product `validated_insights`↑). 24 stdlib tools total (12 analysis + 12 onboarding/customization/autoresearch; all pass `--help`/`--sample`), 12 reference docs (5-7 sources each). Marketplace 61 → 62 plugins; domains 15 → 16.

**v2.8.3** shipped the Mistral Vibe cross-platform sync (`scripts/sync-vibe-skills.py`, `~/.vibe/skills/claude-skills/`) — bringing first-class tool support to 13 coding agents.

**v2.8.4 highlights — productivity/andreessen skill, Marc Andreessen-mode:**

New `productivity/andreessen/` plugin — the Andreessen-lens counterpart to a founder-operating-system plugin. A blunt, market-first operator that pressure-tests ventures/ideas/features/career-bets through Andreessen's documented frameworks (market > team > product; product/market fit is the only milestone; bias to build) and runs his 3x5-card + Anti-Todo daily routine.

- **Runs on a fixed anti-sycophancy operating prompt** (user-supplied, preserved verbatim in `references/operating_prompt.md`): leads with the strongest counterargument, never validates premises, no disclaimers, no morals lectures, explicit confidence levels (high/moderate/low/unknown), never apologizes for disagreeing, no capitulation without new evidence. The user's second emphasis block is operationalized as a posture-mapping table so each instruction changes behavior rather than sitting as decoration.
- **3 stdlib deterministic tools:** `market_first_evaluator.py` (market weighted 0.55, sub-4 market is a hard kill gate → BUILD-POUR-FUEL / MARKET-FIRST-DERISK / KILL-OR-REPICK-MARKET), `pmf_signal_scorer.py` (felt-signals + the Sean Ellis 40% gate, labeled as Ellis's not Andreessen's → BEFORE/APPROACHING/AFTER-PMF), `anti_todo_card.py` (3x5 card with enforced 3-5 cap + Anti-Todo log).
- **4 references** (each citing 5-7 sources with explicit confidence levels on every Andreessen attribution, incl. the documented reversal of "don't keep a schedule"), **5 assets** (worked examples + fillable worksheet + blank card), `cs-andreessen` agent, `/cs:andreessen` + `/cs:pmf-check` commands.
- **8-phase plugin audit:** PASS WITH WARNINGS → structure 91.3/EXCELLENT, quality 65.7 (after asset/example additions), scripts 3/3, security PASS (0 critical, 0 high). Marketplace 60 → 61 plugins; productivity domain 5 → 6 skills.

---

**v2.8.2 highlights — productivity/handoff skill, Matt Pocock-inspired:**

Single-skill point release after v2.8.1. New `productivity/handoff/` skill is a sibling to the existing `engineering/handoff/`. Both preserve Matt Pocock's seven-sentence body verbatim; the productivity variant adds the wrappers the engineering port deliberately skipped:

- **First-run setup** (`scripts/setup.py`) — 5-question Q&A. No pre-selected default for save location: user explicitly picks OS temp / home folder / per-project `.handoff/` / custom path on first run. Prompt-once-then-default model: declining setup drops a sentinel so the prompt never re-appears.
- **Redaction linter** (`scripts/redaction_linter.py`) — 17 stdlib regex patterns (AWS / GitHub / OpenAI / Anthropic / Slack / Stripe / JWT / private-key blocks / env-style secret assignments / DB connection strings / bearer tokens / URL token params / email / phone). Strict-by-default with inline `<!-- handoff:allow secret -->` whitelist marker. Operationalizes Matt's redaction sentence.
- **SessionStart auto-load + SessionEnd reminder hooks** — paired routine-integration. SessionStart surfaces latest handoff as `<handoff_from_previous_session>` data; SessionEnd reminds if no handoff in the last 30 minutes. Disable per-session via `HANDOFF_SESSIONSTART=0` / `HANDOFF_SESSIONEND=0`.
- **Mandatory checklist** (`references/handoff_prompt.md`) + **self-check script** (`scripts/handoff_self_check.py`) — 7-step checklist enforced by 6-check script (all 5 sections present, Goal non-empty, State references artifacts, Decisions present when git is dirty, 3-5 Skills with `— why`, Artifacts are paths only). Strict mode exits 1 on high-severity findings.
- **mtime-guarded cleanup** — auto-cleanup never deletes a handoff the user edited as a working surface.
- **`--refresh` flag** — reuses the most recent handoff in the configured location instead of creating a new file; keeps save location uncluttered.

Ships 7 stdlib-only Python tools, 5 reference docs (each citing 5-6 sources), `cs-handoff-author` agent, `/cs:handoff` + `/cs:handoff-setup` commands. Plugin audit (8 phases): structure 86.0/100, quality 63.0/100, security PASS (0 critical, 0 high). 2 PRs merged: #724 (v1.0) + #728 (v1.1).

**v2.8.2 master plan:** in-conversation design + 8-phase audit applied twice (after each PR).

---

**v2.8.0 highlights — two new top-level domains: business-operations + commercial:**

Designed and shipped under the `/goal` directive to expand BizOps + Commercial surface area. Both domains follow the Path-B 11-file contract per skill, are top-level domain folders (not subfolders inside an existing domain), and ship with orchestrator skills that use `context: fork` to chain sub-skills.

- **`business-operations/`** (new top-level domain) — internal-ops skills for BizOps leads, COO direct reports, vendor management, IT ops. Sprint 1 ships:
  - `business-operations-skills/` (orchestrator, `context: fork`) — routes inquiries via Matt Pocock grill discipline (one question per turn, recommended answer, canon citation)
  - `process-mapper` — BPMN-style swim-lane mapping + bottleneck detection + cycle-time/VA% analysis. 3 stdlib tools, 4 industry profiles, Lean / TOC canon (Womack & Jones, Goldratt, Rother & Shook, Reinertsen, Anderson, Pyzdek, Ohno, Liker).
  - `vendor-management` (`context: fork`) — vendor scoring (5 weighted dimensions, 4 industry profiles), SLA compliance tracker (lower-is-better aware), third-party risk classifier (4 risk vectors, Shared Assessments SIG-Lite). Canon: NIST SP 800-161, ISO/IEC 27036, Gartner TPRM.
  - `cs-bizops-orchestrator` agent + `/cs:bizops` router + `/cs:grill-bizops` (Matt docs-anchored grilling) + per-skill commands.

- **`commercial/`** (new top-level domain) — per-deal-and-packaging skills for deal desk, pricing teams, partner managers, RFP responders. Sprint 1 ships:
  - `commercial-skills/` (orchestrator, `context: fork`) — routes inquiries via Matt grill discipline
  - `pricing-strategist` — 5-model pricing picker, full Van Westendorp PSM (OPP/IDP/PMC/PME + RAP, monotonicity screening), packaging designer with 7 anti-pattern detectors. Canon: Ramanujam (Monetizing Innovation), Skok, Tunguz, Campbell/ProfitWell, Bessemer, Poyar, Sawtooth methodology.
  - `deal-desk` — 5-dimension deal scorer with named approver chain, discount approval router (5-band policy + 4 industry variants), terms redliner detecting 10 patterns (uncapped indemnity, MFN, missing DPA, etc.). **Never auto-approves**; every verdict names the human(s). Canon: SaaStr, Winning by Design, OpenView, Forrester, KeyBanc, IACCM/WorldCC.
  - `cs-commercial-orchestrator` agent + `/cs:commercial` router + `/cs:grill-commercial` (Matt docs-anchored grilling) + per-skill commands.

- **Matt Pocock grill-with-docs pattern adopted** at the SKILL-level — each Sprint 1 SKILL.md ships a "Forcing-question library" section: 5-7 questions, walked one at a time, with a recommended answer and a canon citation per question. The discipline prevents skills from running on fuzzy inputs.

- **Hard rules per domain (enforced by agent personas):**
  - BizOps: every output is a recommendation, never an auto-decision. Vendor scoring routes to a human reviewer.
  - Commercial: pricing outputs model + range (never a single number); deal outputs route to a named human approver (never auto-approve); forecast outputs surface the conversion assumption explicitly.

- **Marketplace + Codex registry:** 57 → 59 plugins. Sprint 2 will add 4 BizOps sub-skills (capacity-planner, internal-comms, knowledge-ops, procurement-optimizer) and 5 Commercial sub-skills (partnerships-architect, channel-economics, commercial-policy, rfp-responder, commercial-forecaster), bringing the new domains to 13 sub-skills total + 2 orchestrators.

- **Verification:** all 12 new Python tools (4 skills × 3 tools each) pass `--help` and `--sample` smoke tests, exit 0. Stdlib-only across the board. Industry profiles verified on the 8 profile-aware tools.

- **PR:** opened against `claude/skills-plugins-framework-XjTjh` (this branch) as draft.

**v2.8.0 master plan:** `documentation/implementation/bizops-commercial-expansion-plan.md`

---



**v2.7.3 Highlights — aeo-box port: AEO skill + security-guidance PreToolUse hook + master prompt preserved:**

Ported `alirezarezvani/aeo-box` after a full component audit. Distilled the valuable parts into our conventions; skipped repo-specific infra (generic agents, GH workflows, TS scripts).

- **`marketing-skill/skills/aeo/`** (new, 8 files, ~3,200 LOC) — Answer Engine Optimization skill, a discipline distinct from SEO. 3 stdlib Python tools: `aeo_audit.py` (E-E-A-T + structure scoring, 0-100 composite, 8 industries with calibrated thresholds where YMYL industries hit 85+, SaaS/b2b/media 70, ecommerce 65), `aeo_optimizer.py` (conservative/balanced/aggressive rewrites + schema.org JSON-LD injection), `citation_tracker.py` (local-first citation ledger at `~/.aeo-data/citations.json` with verdict EARLY/EMERGING/STRONG). 3 references each citing 8 sources: E-E-A-T canon, per-LLM citation patterns (Perplexity / ChatGPT / Claude / Gemini / Mistral with 73% cross-LLM correlation analysis), AEO vs. SEO strategic choice. New `cs-aeo` agent + `/cs:aeo` slash command. New 8th pod ("AEO") added to marketing-skill.
- **`engineering/security-guidance/`** (new, 5 files) — PreToolUse security reminder hook ported from David Dworken @ Anthropic (MIT). Preserves 9 upstream patterns verbatim (eval, pickle, dangerouslySetInnerHTML, innerHTML, document.write, new Function, child_process.exec, os.system, GH Actions workflow injection) + adds 3 new patterns (subprocess shell=True, SQL f-string injection, yaml.unsafe_load). Session-state caching prevents nagging (warn once per file+rule combo), 30-day auto-cleanup, disable via `ENABLE_SECURITY_REMINDER=0`. `attribution` block in `.claude-plugin/authoring-notes.json` credits upstream. Reference doc `pretooluse_hook_canon.md` cites 8 sources on hook design discipline.
- **`megaprompts/14-aeo-agentic-megaprompt.md`** — 1,579-line multi-agent AEO application spec preserved verbatim. Keeps Path-B option open for future "build the full agentic AEO app" work.
- **Marketplace + Codex registry:** 55 → 57 plugins; 303 → 305 indexed skills; `marketing-skill/.claude-plugin/plugin.json` description updated from 7 → 8 pods.
- **Verification:** all 4 new Python tools pass `--help` and `--sample`; security hook smoke-tested (exits 2 on detection, 0 on cached/clean); all 3 cross-platform syncs (.codex / .gemini / .hermes) re-ran clean.
- **PRs:** #678 (Hermes first-class integration, merged) → #679 (aeo-box port + Hermes install guide, merged).

**Total scope after v2.7.3:** 313 skills across 12 domain folders, ~402 Python automation tools, ~542 reference guides, 46+ agents, 60+ slash commands.

**Version:** v2.7.0

**v2.7.0 Highlights — v2 megaprompt-to-skill conversion sweep: 13 new skills across productivity + marketing + research:**

This release ships the complete v2 megaprompt collection (`megaprompts/01-13`) as production-ready skills using the **Path-B direct-conversion pattern**. Three new top-level domain folders created (`productivity/`, `marketing/`, `research/`) hosting 13 skills, 142 files, 23,698 lines of code + documentation.

- **`productivity/`** (3 skills) — `capture` (brain-dump-to-action workspace, megaprompt 05), `email` (paired inbox-setup + inbox-triage with 7-file KB contract, megaprompts 06+07), `reflect` (light-prompt sibling, megaprompt 08).
- **`marketing/`** (1 skill) — `landing` (single-file HTML generator with 4 design styles, brand palette validator, GSAP patterns, megaprompt 04).
- **`research/`** (8 skills) — 7 specialists (`pulse`, `litreview`, `grants`, `dossier`, `patent`, `syllabus`, `notebooklm`) + 1 hybrid router (`research/research/` orchestrator). Megaprompts 01-03, 09-13.
- **Research orchestrator** — deterministic SIGNALS classification routes to 6 specialists at ≥2-signal confidence, else runs own 8-step plan-decompose-search-synthesize-cite fallback. Routing transparency mandatory. Distinct from `engineering/autoresearch-agent` (Karpathy's file-optimization loop) — disambiguation surfaced in 5 places.
- **Marketplace + Codex registry:** 43 → 55 plugins; 290 → 303 indexed skills; new categories `productivity` + `research`; `scripts/sync-codex-skills.py` extended to recognize the 3 new top-level domains.
- **Path-B convention formalized** — megaprompt body → SKILL.md verbatim, 11-file plugin layout, 3 stdlib Python scripts per skill, 3 reference docs each citing 7+ authoritative sources, `cs-*` agent + `/cs:*` command, `source` field documents spec + build_pattern + distinct_from.
- **Verification:** 39/39 scripts pass `--help`; 8-phase plugin audit on orchestrator → PASS WITH WARNINGS (structure 84.1/GOOD, scripts 3/3, 0 critical/high security findings); bulk audit on 12 siblings → all 79.5-86.4 structure, 0 critical/high findings.
- **PRs:** #659 (capture) → #660 (pulse) → #661 (email pair) → #662 (landing) → #663 (litreview) → #664 (grants+dossier) → #666 (patent+syllabus) → #667 (domain-folder cleanup) → #668 (reflect) → #669 (notebooklm) → #671 (research orchestrator) → #672 (v2.7.0 release prep).

**Total scope after v2.7.0:** 311 skills across 12 domain folders, ~398 Python automation tools, ~538 reference guides, 45+ agents, 59+ slash commands. (Superseded by v2.7.3 totals above.)

**Version:** v2.6.1

**v2.6.1 Highlights — Meta-skill maturity: validator expansion + 21 placeholder description fixes + audit tool:**
- **`scripts/audit_skills.py`** (new) — repo-wide write-a-skill validator runner. Stdlib-only orchestration: walks every SKILL.md, runs `skill_review_checklist_runner.py`, aggregates PASS/WARN/FAIL counts + failure-by-rule + top-10 worst offenders. ~30s on 298 real skills.
- **Validator trigger pattern expansion** — `skill_description_validator.py` + `skill_review_checklist_runner.py` now recognize `Use before/during/after/while`, `Invoke before/after`, `Apply when`, `Run when/before` (not just `Use when`). 30 legacy skills reclassified FAIL → WARN/PASS automatically.
- **21 placeholder descriptions fixed** — skills whose description field was literally just the skill name (e.g., `description: "Migration Architect"`) from a v2.0.0 batch import. Top-10 POWERFUL-tier engineering (#647): migration-architect, dependency-auditor, codebase-onboarding, ci-cd-pipeline-builder, mcp-server-builder, observability-designer, api-design-reviewer, performance-profiler, changelog-generator, runbook-generator. Remaining 11 across 4 domains (#648): executive-mentor/challenge, executive-mentor/board-prep, git-worktree-manager, skill-tester, monorepo-navigator, env-secrets-manager, agent-workflow-designer, incident-commander, email-template-builder, stripe-integration-expert, contract-and-proposal-writer.
- **Quality gates: binding-for-new vs advisory-for-legacy split** — `quality_gates_for_skills.md` formalizes that Matt's 6-item checklist is BLOCKING for post-v2.6.0 skills and ADVISORY for the 298 legacy SKILL.md files.
- **Aggregate audit improvement (vs v2.6.0 baseline):** PASS 4 → 9 (+5); WARN 111 → 137 (+26); FAIL 183 → 152 (-31); "Missing trigger" failures 119 → 68 (-51). 31 skills total lifted from FAIL.
- **PRs:** #646 (audit tool, merged) → #647 (validator + 10 descriptions, merged) → #648 (remaining 11 descriptions, merged).

**Version:** v2.6.0

**v2.6.0 Highlights — Matt Pocock productivity skills (4 new, all MIT-licensed derivations):**
- **write-a-skill** (`./engineering/write-a-skill/`) — skill-author meta-skill. Matt's 3-phase workflow preserved verbatim. Wrapper adds 3 stdlib validators (description, structure, 6-item review-checklist runner), 4 references citing 7-8 sources each, `cs-skill-author` agent, `/cs:write-a-skill` command.
- **caveman** (`./engineering/caveman/`) — token-compression mode (20-50% typical, 75% upper bound). 3 stdlib tools: deterministic compressor, $/Mtok savings estimator, lint with code-block + exception-zone whitelisting. Matt's persistence rules + auto-clarity exception preserved verbatim.
- **grill-me** (`./engineering/grill-me/`) — relentless plan-interrogator. 3 stdlib tools: decision-tree extractor (6 branch kinds), forcing-question generator with recommendations + dependency-aware ordering, JSON-backed session tracker for multi-day grills. Matt's one-at-a-time discipline preserved verbatim.
- **handoff** (`./engineering/handoff/`) — conversation-continuity generator. 3 stdlib tools: 5-emphasis template generator (deploy/review/debug/design/test/default) honoring Matt's `mktemp` convention, artifact deduplicator across 5 categories, skill recommender matching 14 repo skills. Matt's no-duplication discipline preserved verbatim.
- **Hybrid voice pattern established** for future MIT-licensed external skill imports: preserve upstream voice verbatim in SKILL.md + add wrapper (validators + references citing ≥ 5 sources + cs-* agent + /cs:* command) + karpathy gate + attribution in every file.
- **Karpathy-coder validation:** 100/100 complexity across all 12 new Python tools (0 findings). 13 references cite 7-8 authoritative sources each (well over the ≥ 5 floor).
- **PRs:** #642 (write-a-skill, merged) → #643 (caveman + grill-me + handoff batch, merged). Test suite caught a missing-H1 issue on PR 2; fixed in follow-up commit before merge.

**Version:** v2.5.5

**v2.5.5 Highlights — vpe-advisor: throughput-first VP of Engineering:**
- **vpe-advisor** skill (new, `./c-level-advisor/skills/vpe-advisor/`) — opinionated throughput-first VPE skill covering 4 specific decisions distinct from CTO. 3 stdlib Python tools with deterministic logic: `delivery_throughput_analyzer.py` (DORA 4 metrics with Elite/High/Medium/Low verdict per metric + cycle-time bottleneck identification with typical fix per stage), `eng_hiring_funnel_calculator.py` (7-stage funnel conversion + healthy/leaky verdict per stage + end-to-end conversion + required top-of-funnel volume + weakest-stage fixes), `eng_team_structure_designer.py` (headcount-to-structure map + squad-size assessment + manager-trigger + director-trigger + span-of-control). 4 in-depth references each citing 5+ authoritative sources (DORA / Forsgren / Kim, Spotify squad model, Conway's Law, Will Larson, Camille Fournier, Google SRE Workbook).
- **cs-vpe-advisor** agent (new) — throughput-first operator. Voice: "What's your cycle time, and where does the work spend most of its time waiting?" Distinguishes "what to build" (CTO) from "how to ship it" (VPE) with hard discipline.
- **/cs:vpe-review** (new slash command) — 6-question forcing interrogation: cycle time + waits, DORA 4 metrics, hiring funnel leakage, team structure health, production discipline maturity, VPE-vs-CTO scope.
- **Dual-published from the start:** standalone marketplace plugin AND bundled in c-level-skills.
- **Karpathy-coder discipline maintained (5th consecutive PR):** assumptions surfaced upfront, verifiable success criteria, deterministic tool logic, no scope creep into engineering tactical skills.

**Version:** v2.5.4

**v2.5.4 Highlights — chief-customer-officer-advisor: retention-obsessed CCO:**
- **chief-customer-officer-advisor** skill (new, `./c-level-advisor/skills/chief-customer-officer-advisor/`) — opinionated, retention-obsessed CCO skill covering 4 specific decisions. 3 stdlib Python tools with deterministic logic: `retention_decomposition_analyzer.py` (decomposes ARR retention into GRR / NRR / Logo by cohort, flags leaky-bucket pattern, categorizes churn into 7-category root-cause taxonomy with preventable %), `customer_segmentation_designer.py` (assigns 4-tier segment, scores ICP fit 0-10 across 7 weighted signals, surfaces kill list + upgrade candidates), `cs_coverage_calculator.py` (calculates CSM headcount per tier with ARR ratio + account count constraints, generates 12-month hiring plan with quarterly sequencing + manager-trigger thresholds). 4 in-depth references each citing 5+ authoritative sources (Mehta/Steinman/Murphy, BVP, TSIA, Skok, Tunguz).
- **cs-cco-advisor** agent (new) — retention-obsessed pragmatist orchestrating the skill via `/cs:cco-review`. Distinct voice: "What's your gross retention rate, and what's the #1 reason customers leave?" Trusts gross retention over NRR; refuses to recommend CS hires without naming the customer outcome they unblock.
- **/cs:cco-review** (new slash command) — 6-question forcing interrogation: GRR (not NRR) truth, top churn driver, time-to-value by segment, kill-list candidates, ARR-per-CSM ratio + coverage model, CS comp alignment.
- **Dual-published from the start:** standalone marketplace plugin AND bundled in c-level-skills.
- **Karpathy-coder discipline maintained:** assumptions surfaced upfront, verifiable success criteria, deterministic tool logic, no scope creep into business-growth tactical CS skills.

**Version:** v2.5.3
- **chief-ai-officer-advisor** skill (new, `./c-level-advisor/skills/chief-ai-officer-advisor/`) — opinionated, eval-demanding CAIO skill covering 4 specific decisions. 3 stdlib Python tools with deterministic logic: `model_buildvsbuy_calculator.py` (API vs fine-tune vs build with 3-year TCO, balances economic breakeven with practical feasibility), `ai_risk_classifier.py` (EU AI Act tier classification with Article-level citations + US state patchwork: NYC LL 144, CO AI Act, IL HB 53, CA SB 1001, IL BIPA + industry overlays for FDA/NYDFS/NAIC/ECOA), `ai_cost_economics.py` (API vs self-hosted breakeven with 2026 pricing across A100/H100, utilization reality, hidden costs). 4 in-depth references each citing 5+ authoritative sources: model build-vs-buy strategy (decision tree, 6 fine-tuning approaches, failure modes), AI risk governance (full EU AI Act tier map + NIST AI RMF + governance program checklist), AI cost economics (2026 pricing + GPU economics + migration cost + prompt caching), AI team org evolution (5-stage role map + 9-role definition table + AI team vs data team contrast + 7 anti-patterns).
- **cs-caio-advisor** agent (new) — eval-demanding realist orchestrating the skill via `/cs:caio-review`. Distinct voice: "What does this AI need to be good at, and how would you measure it?" Treats every AI use case as a hiring decision; demands eval set, SLO, and fallback before scale.
- **/cs:caio-review** (new slash command) — 6-question forcing interrogation: eval discipline, hallucination SLO, regulatory classification, model selection, cost trajectory, role-that-unblocks.
- **Karpathy-coder discipline maintained:** assumptions surfaced upfront, verifiable success criteria, deterministic tool logic, no scope creep into engineering AI/ML skills, complexity_checker + diff_surgeon clean on staged diff.

**Version:** v2.5.2
- **chief-data-officer-advisor** skill (new, `./c-level-advisor/skills/chief-data-officer-advisor/`) — opinionated, decision-driven CDO skill covering 4 specific decisions (no generic governance survey). 3 stdlib Python tools with deterministic logic: `ai_training_data_audit.py` (origin × class × use-case matrix → GO/MITIGATE/NO-GO with GDPR Art. 6 and EU AI Act citations), `data_product_strategy_picker.py` (warehouse/lakehouse/mesh recommendation + 6-layer build-vs-buy + 12-month sequencing), `data_asset_valuator.py` (strategic value 0-10, moat strength, M&A multiplier with carve-out penalties, 3 ranked productization paths). 4 references answering one decision each: training rights (decision tree + state patchwork), data product strategy (kill criteria per architecture), customer-data-as-asset (valuation + M&A diligence prep), data team org evolution (stage-to-role map). Karpathy-aligned: explicit anti-patterns, decision-driven (not topic-driven), surgical (does not duplicate engineering data skills).
- **cs-cdo-advisor** agent (new) — decision-driven realist orchestrating the skill via `/cs:cdo-review`. Distinct voice: "What decision does this data drive?" Refuses to recommend tooling before naming the consumer.
- **/cs:cdo-review** (new slash command) — 6-question forcing interrogation: decision being made, consent provenance, internal consumers, M&A diligence impact, model-without-this-source viability, role-that-unblocks-this.
- **Built with Karpathy-coder discipline:** explicit assumptions surfaced upfront, verifiable success criteria locked before code, surgical scope (no edits to unrelated files), deterministic tool logic (not pattern-match prose), kill criteria documented in every recommendation.

**Version:** v2.5.1
- **general-counsel-advisor** skill (new, `./c-level-advisor/skills/general-counsel-advisor/`) — full standalone C-role skill backing the existing `/cs:gc-review` command. 2 stdlib Python tools: `contract_risk_scanner.py` (scans contract text for 12 founder-killer patterns: auto-renew traps, uncapped indemnity, vague IP, aggressive non-compete, missing DPA, MFN pricing, perpetual license-back, etc.) and `term_sheet_analyzer.py` (scores term sheets 0-100 across 12 dimensions: liquidation preference, anti-dilution, option pool, board composition, vesting, pro-rata, drag-along, protective provisions, info rights, dividends, valuation/dilution, holistic). 3 references: contracts playbook (7 startup contract types), IP + regulatory landscape (patents, trademark, OSS compliance, HIPAA/GDPR/FDA/fintech triggers, SOC 2 → ISO sequencing), term sheet decoder (full glossary + founder-friendly defaults + negotiation strategy).
- **cs-general-counsel-advisor** agent (new) — risk-paranoid persona orchestrating the skill via `/cs:gc-review`. Distinct voice: "Before we sign, three things need to be settled in writing." Always escalates to outside counsel — never substitutes for it.
- **First plugin to outclass gstack on a domain it has zero coverage in.** Software-shipping personas don't include General Counsel; legal exposure is where startups most often discover problems after they're expensive to fix.
- **/cs:gc-review updated** to invoke the new tools and reference the skill.

**Version:** v2.5.0

**v2.5.0 Highlights — c-level-agents: Founder-Mode Executive Team:**
- **c-level-agents** plugin (new, `./c-level-agents/`) — 8 cs-* persona agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, Chief of Staff) with moderate voice differentiation, plus 17 /cs:* slash commands surfaced as sub-skills.
- **Forcing-question office hours (8):** `/cs:office-hours` (YC-style 6-Q intake), and per-role `/cs:cfo-review`, `/cs:cmo-review`, `/cs:cpo-review`, `/cs:cro-review`, `/cs:cto-review`, `/cs:ciso-review`, `/cs:gc-review` (General Counsel — a lane gstack lacks entirely).
- **Strategic sprint pipeline (5):** `/cs:brief` → `/cs:boardroom` (6-phase deliberation with Phase 2 isolation + devil's-advocate pass) → `/cs:decide` (two-layer memory + preserved dissent) → `/cs:execute` (90-day plan) → `/cs:post-mortem` (scored against pre-committed criteria).
- **Meta + safety (4):** `/cs:founder-mode` (auto-router), `/cs:onboard` (12-Q founder interview), `/cs:cross-eval` (multi-model consensus with graceful Claude-only fallback), `/cs:freeze` (cooldown lock on irreversible decisions).
- **References:** `persona-voices.md` (voice specs) and `llm-wiki-bridge.md` (Markdown-only persistent memory — answer to gstack's gbrain Postgres dependency).
- Positioned as the business-domain answer to YC Garry Tan's gstack: broader role coverage, real frameworks (RICE/JTBD/OKR/ADKAR/Wardley/8-dim health), compliance lane (ra-qm-team), explicit voice differentiation, and stdlib-only memory.

**Version:** v2.4.5

**v2.4.x Highlights — Reliability Portfolio (Phase 1–4):**
- **slo-architect** (Phase 4 — keystone) — SLO/SLI/error-budget discipline per Google SRE Workbook. 3 stdlib Python tools (`slo_designer`, `error_budget_calculator` with multi-window burn-rate alerts, `slo_review`), 4 reference docs, asset templates, `/slo-design` slash command. Engineering-advanced bundle 49 → 50.
- **chaos-engineering** (Phase 3) — experiment designer, blast-radius calculator, postmortem generator. `/chaos-experiment` command.
- **kubernetes-operator** (Phase 2) — CRD validator, reconcile linter, capability auditor. `/operator-audit` command.
- **feature-flags-architect** (Phase 1) — flag debt scanner, rollout planner, kill-switch audit. `/flag-cleanup` command.
- **ship-gate** — pre-production audit skill (89 checks across 8 categories, stdlib-only, MIT). External contribution.
- **Atlassian Remote MCP** — bundled `.mcp.json` in `project-management/` (SSE transport, OAuth handled by Claude Code, no env vars required).
- **Auditor + CI cleanup** — `.mcp.json` allowlist in skill-security-auditor, manifest-only PRs skip audit, README links (toprank).
- 246 total skills, 359 Python tools, 485 references, 27 agents, 33 commands.

**v2.3.0 Highlights:**
- **llm-wiki plugin** — new POWERFUL-tier skill implementing Karpathy's LLM Wiki pattern. Second brain for Claude Code + Obsidian where the LLM incrementally ingests sources into a persistent, interlinked markdown vault. Ships SKILL.md (with `context: fork`), 3 sub-agents (wiki-ingestor, wiki-librarian, wiki-linter), 5 slash commands (/wiki-init, /wiki-ingest, /wiki-query, /wiki-lint, /wiki-log), 8 stdlib-only Python tools, 8 reference guides, full vault templates, and a worked example. Cross-tool compatible with Claude Code, Codex CLI, Cursor, Antigravity, OpenCode, Gemini CLI.
- **tc-tracker** — new engineering skill: task context tracker with lifecycle, handoff format, schema, and 5 Python tools (tc_init, tc_create, tc_update, tc_status, tc_validator) plus `/tc` slash command
- **apple-hig-expert** — new product skill: Apple Human Interface Guidelines expert with Liquid Glass aesthetic focus. Audits iOS/macOS/visionOS apps with `hig_checker` Python tool and comprehensive reference docs on visual design, platform specifics, and accessibility
- 235 total skills, 314 Python tools, 435 references, 28 agents, 27 commands

**Version:** v2.2.0

**v2.2.0 Highlights:**
- **Security skills suite** — 6 new engineering-team skills: adversarial-reviewer, ai-security, cloud-security, incident-response, red-team, threat-detection (5 Python tools, 4 reference guides)
- **Self-eval skill** — Honest AI work quality evaluation with two-axis scoring, score inflation detection, and session persistence
- **Snowflake development** — Data warehouse development, SQL optimization, and data pipeline patterns
- 234 total skills across 9 domains, 306 Python tools, 427 references, 25 agents, 22 commands
- MkDocs docs site expanded to 269 generated pages (301 HTML pages)

**v2.1.2 (2026-03-10):**
- Landing page generator now outputs **Next.js TSX + Tailwind CSS** by default (4 design styles, 7 section generators)
- **Brand voice integration** — landing page workflow uses marketing brand voice analyzer to match copy tone to design style
- 25 Python scripts fixed across all domains (syntax, dependencies, argparse)
- 237/237 scripts verified passing `--help`

**v2.1.1 (2026-03-07):**
- 18 skills optimized from 66-83% to 85-100% via Tessl quality review
- YAML frontmatter (name + description) added to all SKILL.md files
- 6 new agents + 5 slash commands, Gemini CLI support, MkDocs docs site

**v2.0.0 (2026-02-16):**
- 25 POWERFUL-tier engineering skills added (engineering/ folder)
- Plugin marketplace infrastructure (.claude-plugin/marketplace.json)
- Multi-platform support: Claude Code, OpenAI Codex, OpenClaw, Hermes Agent, Gemini CLI, Cursor, and 6 more

**Past Sprints:** See [documentation/delivery/](documentation/delivery/) and [CHANGELOG.md](CHANGELOG.md) for history.

## Roadmap

**Phase 1-4 Complete:** 246 production-ready skills deployed across 9 domains
- Engineering Core (32), Engineering POWERFUL (40), Product (13), Marketing (44), PM (9), C-Level (28), RA/QM (14), Business & Growth (5), Finance (3)
- 359 Python automation tools, 485 reference guides, 27 agents, 33 commands
- Complete enterprise coverage from engineering through regulatory compliance, sales, customer success, and finance
- Reliability portfolio: feature-flags-architect, kubernetes-operator, chaos-engineering, slo-architect (Google SRE Workbook canon)
- MkDocs Material docs site with 293+ indexed pages for SEO

See domain-specific roadmaps in each skill folder's README.md or roadmap files.

## Key Principles

1. **Skills are products** - Each skill deployable as standalone package
2. **Documentation-driven** - Success depends on clear, actionable docs
3. **Algorithm over AI** - Use deterministic analysis (code) vs LLM calls
4. **Template-heavy** - Provide ready-to-use templates users customize
5. **Platform-specific** - Specific best practices > generic advice

## ClawHub Publishing Constraints

This repository publishes skills to **ClawHub** (clawhub.com) as the distribution registry. The following rules are **non-negotiable**:

1. **cs- prefix for slug conflicts only.** When a skill slug is already taken on ClawHub by another publisher, publish with the `cs-` prefix (e.g., `cs-copywriting`, `cs-seo-audit`). The `cs-` prefix applies **only on the ClawHub registry** — repo folder names, local skill names, and all other tools (Claude Code, Codex, Gemini CLI) remain unchanged.
2. **Never rename repo folders or local skill names** to match ClawHub slugs. The repo is the source of truth.
3. **No paid/commercial service dependencies.** Skills must not require paid third-party API keys or commercial services unless provided by the project itself. Free-tier APIs and BYOK (bring-your-own-key) patterns are acceptable.
4. **Rate limit: 5 new skills per hour** on ClawHub. Batch publishes must respect this. Use the drip timer (`clawhub-drip.timer`) for bulk operations.
5. **plugin.json schema** — Required fields: `name`, `description`, `version`, `author`, `homepage`, `repository`, `license`, `skills`. **No extension fields of any kind** — Claude Code's manifest validator rejects the entire `plugin.json` on any unrecognized key, which made 37+ plugins uninstallable (issue #954). Authoring metadata lives in a sibling file the validator never reads: `.claude-plugin/authoring-notes.json`, holding at most two keys:
   - `source` (object) — provenance metadata for skills built via Path-B megaprompt conversion. Recommended shape: `{spec: "megaprompts/NN-name.md", build_pattern: "...", distinct_from: "..."}`. Used by all 13 v2 megaprompt-derived skills (productivity/, marketing/, research/).
   - `attribution` (object) — credit metadata for skills derived from external MIT-licensed work. Used by `engineering/caveman`, `engineering/grill-me`, `engineering/grill-with-docs` (Matt Pocock derivatives), `engineering/skillopt-sleep`, `engineering/book-to-skill`, and others. Upstream credit must also remain in the plugin's `README.md`/`LICENSE` — a sidecar JSON file is not a license notice.

   `scripts/check_plugin_json.py` hard-fails any `plugin.json` still carrying `source`/`attribution` (pointing to the sidecar file) and sanity-checks `authoring-notes.json` where present. Note that `source` **is** a valid key in `marketplace.json`'s `plugins[]` entries — the two schemas are not interchangeable, which is how the key originally leaked into `plugin.json`. The `skills` value depends on the plugin layout. Per the live Claude Code plugin spec ([plugins-reference](https://code.claude.com/docs/en/plugins-reference)), **all paths must be relative to the plugin root and start with `./`**. CC 2.1.144+ returns `Validation errors: skills: Invalid input` on a bare string without the prefix.

   **Canonical forms (CC 2.1.144+):**
   - Single-skill plugin (SKILL.md at root): `"skills": ["./"]` (array form required).
   - Plugin with `skills/` subdir: `"skills": "./skills"` or `"skills": ["./skills"]`.
   - Multi-skill domain plugin (skills are subfolders at root): `"skills": ["./sub1", "./sub2", ...]` (explicit list).

   **Legacy form (still tolerated by the validator):** `"skills": "skills"` (bare subdir name, no `./`). Older versions of CC accepted this; current CC rejects it. The repo has been fully migrated to the canonical form — the validator keeps WARN-level tolerance for the legacy literal as a safety net against accidental regressions in copied templates. Do **not** use this form in new manifests.

   **Historical regressions (now reversed upstream):** The `./` prefix was briefly forbidden between CC v2.1.107 and v2.1.144 (issues #539, #686). That window is closed; the `./` prefix is required again. Do **not** reintroduce the bare-string form for new manifests.

   **Enforcement:** `scripts/check_plugin_json.py --all` runs in `ci-quality-gate.yml` on every PR. It hard-fails on any non-`./`-prefixed string that isn't the legacy `"skills"` literal, on empty strings/arrays, and on non-string array entries. When CC tightens its path validator again in the future, update both the validator (`_check_skills_string` / `_check_skills_array`) and this section together — they must move in lockstep.
6. **Version follows repo versioning.** ClawHub package versions must match the repo release version (currently v2.7.0+).

## Anti-Patterns to Avoid

- Creating dependencies between skills (keep each self-contained)
- Adding complex build systems or test frameworks (maintain simplicity)
- Generic advice (focus on specific, actionable frameworks)
- LLM calls in scripts (defeats portability and speed) — **one documented, opt-in exception:** `engineering/skillopt-sleep/skillopt_sleep/backend.py`'s `claude`/`codex` backends shell out to those CLIs when a real (non-`mock`) backend is explicitly selected. This is the deployment engine for a self-improvement *loop* (harvest → replay → gate), not a stdlib analysis tool, and the default backend (`mock`) is deterministic with zero API spend. Do not cite this as precedent for adding LLM calls to an analysis/reference skill's scripts — those still must stay stdlib-only.
- Over-documenting file structure (skills are simple by design)

## Working with This Repository

**Creating New Skills:** Follow the appropriate domain's roadmap and CLAUDE.md guide (see Navigation Map above).

**Editing Existing Skills:** Maintain consistency across markdown files. Use the same voice, formatting, and structure patterns.

**Quality Standard:** Each skill should save users 40%+ time while improving consistency/quality by 30%+.

## Self-learning

When I correct you, or you catch yourself making a mistake: before continuing add the lesson as a one-line rule under ## Lessons, so it never happens again

## Lessons

- (Claude adds rules here)

## Additional Resources

- **.gitignore:** Excludes .vscode/, .DS_Store, AGENTS.md, PROMPTS.md, .env*
- **Plugin Registry:** [.claude-plugin/marketplace.json](.claude-plugin/marketplace.json) - Marketplace distribution
- **Standards Library:** [standards/](standards/) - Communication, quality, git, documentation, security
- **Implementation Plans:** [documentation/implementation/](documentation/implementation/)
- **Sprint Delivery:** [documentation/delivery/](documentation/delivery/)

---

**Last Updated:** August 24, 2026
**Version:** v2.12.0 (consolidated release — see CHANGELOG.md)
**Status:** 388 production-ready skills across 20 domains, 99 marketplace plugins, docs site live (counters derived via `scripts/derive_counters.py`)