continuous-improvement 3.1.0 → 3.9.1

package/README.md

@@ -5,170 +5,130 @@
 <h1 align="center">The 7 Laws of AI Agent Discipline</h1>
 
 <p align="center">
-  <b>Stop your AI agent from skipping steps, guessing, and declaring "done" without verifying.</b>
+  <b>Stop your Claude Code agent from skipping steps, guessing, and declaring "done" without verifying.</b>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/v/continuous-improvement" alt="npm"></a>
-  <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/dm/continuous-improvement" alt="downloads"></a>
-  <a href="https://github.com/naimkatiman/continuous-improvement/stargazers"><img src="https://img.shields.io/github/stars/naimkatiman/continuous-improvement?style=social" alt="stars"></a>
-  <a href="https://github.com/naimkatiman/continuous-improvement/network/members"><img src="https://img.shields.io/github/forks/naimkatiman/continuous-improvement?style=social" alt="forks"></a>
-  <a href="https://github.com/naimkatiman/continuous-improvement/graphs/contributors"><img src="https://img.shields.io/github/contributors/naimkatiman/continuous-improvement" alt="contributors"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
-  <a href="test/"><img src="https://img.shields.io/badge/tests-104%20passing-brightgreen" alt="tests"></a>
-</p>
-
-<p align="center">
   <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Claude%20Code-skill-blueviolet" alt="Claude Code"></a>
-  <a href="https://cursor.sh"><img src="https://img.shields.io/badge/Cursor-compatible-blue" alt="Cursor"></a>
-  <a href="https://openai.com/codex"><img src="https://img.shields.io/badge/Codex-compatible-blue" alt="Codex"></a>
-  <a href="https://ai.google.dev/gemini-api/docs/gemini-cli"><img src="https://img.shields.io/badge/Gemini%20CLI-compatible-blue" alt="Gemini CLI"></a>
-  <a href="https://github.com/naimkatiman/continuous-improvement/actions"><img src="https://img.shields.io/github/actions/workflow/status/naimkatiman/continuous-improvement/ci.yml?label=CI" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
+  <a href="test/"><img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="tests"></a>
 </p>
 
 <p align="center">
-  <a href="docs/README.zh-CN.md">简体中文</a> |
-  <a href="docs/README.ja.md">日本語</a>
+  <b>New here?</b> → <a href="QUICKSTART.md">QUICKSTART.md</a> (2 minutes)
 </p>
 
 ---
 
-## The Problem
+## The problem this solves
 
-AI agents are great at individual steps. They're terrible at **discipline**.
+You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern.
 
-They skip research. They plan loosely. They declare "done" before verifying. They add features mid-task. They never reflect. Each session, they repeat the same mistakes.
+| You ask the agent to... | What actually happens |
+|---|---|
+| Add a feature | It edits five files, never runs the build, says "done" |
+| Fix a bug | It reinvents a helper that already exists in the repo |
+| Refactor a module | It bundles three unrelated changes into one commit |
+| Pick up where last session ended | It re-explores from zero — the prior session's lessons are gone |
+| Verify the change works | It claims "this should work" without running a single test |
 
-**The 7 Laws** fix that — plus a **learning system** (Mulahazah) that builds instincts over time. No config, no daemon, no manual setup.
+Every one of those failures is the agent skipping a step a disciplined engineer would not skip. The 7 Laws of AI Agent Discipline names each step, gives it a hook or a skill that enforces it, and feeds the captured patterns back into the agent so the same mistake gets harder to repeat next session.
 
-### Before vs After
+## What you get
 
-<details>
-<summary><b>Without continuous-improvement</b> — agent skips research, declares "done" without verifying</summary>
+- **A 7-step discipline** the agent must follow every task — research → plan → execute one thing → verify → reflect → learn → iterate. Each Law has at least one skill or hook that enforces it.
+- **14 bundled skills + a runtime PreToolUse hook** that turn the Laws into enforced behavior — `gateguard` runs as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit/Write/destructive Bash until the agent presents fact-list investigation. `tdd-workflow` enforces RED → GREEN → REFACTOR, `verification-loop` runs build/types/tests/security before "done", `deploy-receipt` closes the merge-to-production gap (deployed SHA + healthcheck), `proceed-with-the-recommendation` walks any agent's recommendation list top-to-bottom with per-item verification. The runtime hook catches the "skipped investigation" failure mode at the tool-call layer; the skills run model-side once the gate clears. See [§ How enforcement works](#how-enforcement-works) for the two-layer model.
+- **Mulahazah, the auto-leveling instinct engine** — hooks capture every tool call; after ~20 observations the agent analyzes patterns and creates instincts with confidence scores. Suggestions appear at 0.5+, auto-apply at 0.7+, decay when ignored. Project-scoped, promote to global after 2+ projects. You configure nothing.
+- **A GitHub Action transcript linter** that catches skipped Laws in CI — writes without prior research, edits without verification, too many files at once.
+- **Two install paths** — Beginner is two slash commands inside Claude Code (no Node, no bash, ~90% of users). Expert adds the MCP server, observation hooks, instinct packs, and the linter.
 
-```
-You: Add rate limiting to the /api/users endpoint
+The whole thing is MIT, free, and lives in this one repo. No service, no account, no telemetry leaves your machine.
 
-Agent: I'll add rate limiting now.
-       *writes express-rate-limit middleware*
-       Done! I've added rate limiting to the /api/users endpoint.
-
-You: Did you check if we already have rate limiting somewhere?
-Agent: Let me check... oh, there's already a rate limiter in middleware/rateLimit.ts.
-       I've created a duplicate. Let me fix that.
+---
 
-You: Did you test it?
-Agent: Let me run the tests... they're failing. The import path is wrong.
-       *fixes import*
-       Now it works!
+## Install
 
-You: You also broke the /api/auth endpoint — it was sharing that middleware.
-Agent: I see. Let me fix that too...
-```
+**If you don't know which to pick, use Beginner.** It is enough for ~90% of users and adds no Node or bash dependency.
 
-**Result:** 4 back-and-forth corrections. Duplicate code. Broken endpoint. 15 minutes wasted.
-</details>
+### Beginner — inside Claude Code, two commands (plus one optional companion)
 
-<details>
-<summary><b>With continuous-improvement</b> — agent follows the 7 laws</summary>
+You get the 7 Laws skill, the hooks that enforce it, and the slash commands. Nothing else to install.
 
+```bash
+# Inside Claude Code (no shell needed)
+/plugin marketplace add naimkatiman/continuous-improvement
+/plugin install continuous-improvement@continuous-improvement
 ```
-You: Add rate limiting to the /api/users endpoint
-
-Agent: **[Law 1: Research]** Searching for existing rate limiting...
-       Found: middleware/rateLimit.ts — already applies to /api/auth.
-       Found: express-rate-limit already in package.json.
-
-       **[Law 2: Plan]**
-       WILL: Extend existing rateLimit middleware to cover /api/users
-       WILL NOT: Create new middleware or change existing /api/auth behavior
-       VERIFY: Run tests + curl /api/users 101 times to confirm 429 response
 
-       **[Law 3: Execute one thing]** Adding /api/users to the route list
-       in middleware/rateLimit.ts...
+The doubled name is correct: it reads as `<plugin>@<marketplace>`.
 
-       **[Law 4: Verify]**
-       ✓ npm test — 47/47 passing
-       ✓ curl test — 429 after 100 requests
-       ✓ /api/auth still works — 200 OK
+**Optional companion (recommended).** The `/superpowers` dispatcher routes per-task to specialist skills (`writing-plans`, `test-driven-development`, `using-git-worktrees`, `dispatching-parallel-agents`, `finishing-a-development-branch`, etc.) shipped by Obra's `superpowers` plugin, which is vendored into this same marketplace as a pinned-SHA snapshot. Install it with one extra line:
 
-       Done. Extended existing rate limiter to cover /api/users.
-       One file changed: middleware/rateLimit.ts (+1 line).
+```bash
+/plugin install superpowers@continuous-improvement
 ```
 
-**Result:** Correct on first attempt. No duplicate code. No broken endpoints. 2 minutes.
-</details>
-
----
+Without the companion the dispatcher still works — every routing target has a concrete inline fallback — but specialist quality is fallback-quality, not dedicated-skill-quality.
 
-## Install
+Verify: run `/discipline` in Claude Code — you should see the 7 Laws card.
+If the command is not recognized, restart your Claude Code session first; the marketplace did pick the plugin up but commands load on session start.
 
-### Beginner (default) — just hooks, no setup needed
+**Second-stage verify (proves the runtime gate is firing — i.e. `hooks/gateguard.mjs` is invoked — not just docs claiming it).** Ask Claude to write a throwaway file with no research first:
 
-```bash
-npx continuous-improvement install
+```
+Edit a new file scratch.txt and put the word "hello" in it. Don't research anything first.
 ```
 
-That's it. For Claude Code, this installs:
-- Observation hooks (captures every tool call, <50ms, jq optional)
-- `/continuous-improvement`, `/discipline`, and `/dashboard` commands
-- Auto-leveling instinct system
+You should see Claude **blocked** by the bundled `gateguard` PreToolUse hook (`hooks/gateguard.mjs`) with a fact-list reason. That block is the proof the hook is wired and enforcing. If Claude writes the file with no pause, the hook did not load — see Troubleshooting below. (To also verify observation hooks, run `/dashboard` and confirm a non-zero `Total` under `Observations`.)
 
-### Expert — full power with MCP server
+### How enforcement works
 
-```bash
-npx continuous-improvement install --mode expert
-```
+The 7 Laws are enforced at **two layers**:
 
-Everything in beginner plus:
-- **MCP server** with 10 tools (instinct management, import/export, dashboard, instinct packs)
-- **Session hooks** (auto-load instincts at start, remind to reflect at end)
-- Works with Claude Code, Claude Desktop, and any MCP client
+- **Runtime layer (hooks).** `gateguard` ships as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit / Write / MultiEdit / destructive Bash on the first mutation per file until the agent presents the facts named in [skills/gateguard.md § Gate Types](skills/gateguard.md). Destructive Bash (`rm -rf`, `git push --force`, `--force-with-lease`, `DROP DATABASE`, Windows `Remove-Item -Recurse`, etc.) is gated on every call, not just first. Read-only and exploratory tools (Read, Grep, Glob, routine Bash like `git status`) bypass the gate. Per-session state at `~/.claude/instincts/<project-hash>/gateguard-session.json` caps cumulative clearances at 50 distinct files to bound stuck-loop damage.
+- **Model layer (skills).** Once the runtime gate clears for a file, the rest of the discipline (`tdd-workflow`, `verification-loop`, `proceed-with-the-recommendation`, etc.) runs model-side — the agent reads each skill and applies it. `observe.sh` / `observe.mjs` records every tool call into the Mulahazah feed for instinct extraction; that surface is observational, not enforcement.
 
-### MCP only — for non-Claude editors
+V1 honest limitations: the runtime gate is honor-system once the agent flips `_gateguard_facts_presented: true` (the hook can't verify the investigation actually happened); the state file is deletable and parallel hook invocations can race. Documented in `src/hooks/gateguard.mts` and `src/lib/gateguard-state.mts` headers.
 
-```bash
-npx continuous-improvement install --mode mcp
-```
+### Expert — adds MCP server, observation hooks, and instinct packs
 
-Registers the MCP server without hooks — for Cursor, Zed, Windsurf, VS Code, or any editor that supports MCP.
+Pick this if you want the MCP tools (12 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, and starter packs.
 
-### Load a starter instinct pack
+Preconditions: Node 18 / 20 / 22, plus bash on Windows (Git Bash or WSL — `hooks/observe.sh` is a bash script and silently no-ops without it). **`jq` is no longer required**: as of v3.6.0, `observe.sh` prefers the Node observer (`bin/observe.mjs`) which writes the rich event schema natively without external dependencies. The bash thin-schema path is kept as a two-phase shim, so legacy installs that have not re-run `npx continuous-improvement install` since v3.5.x will still degrade silently without `jq` (`winget install jqlang.jq` on Windows, `brew install jq` on macOS, `apt install jq` on Debian/Ubuntu) — re-running the installer is the cleaner fix and removes the dependency entirely. See [CHANGELOG.md](CHANGELOG.md) `[3.6.0]` for the migration details.
 
 ```bash
-npx continuous-improvement install --pack react    # React/Next.js instincts
-npx continuous-improvement install --pack python   # Python best practices
-npx continuous-improvement install --pack go       # Go idioms
+npx continuous-improvement install --mode expert
+npx continuous-improvement install --pack react   # optional: react | python | go | meta
+# --pack seeds 5–10 starter instincts so suggestions appear in week 1 instead of week 4.
 ```
 
-### Install to a specific target
+Verify: run `/dashboard` in Claude Code — you should see instinct health and observation count.
+Update later with `/plugin marketplace update continuous-improvement` or by re-running the npx command.
 
-```bash
-npx continuous-improvement install --target claude    # Claude Code + Mulahazah
-npx continuous-improvement install --target openclaw  # OpenClaw (skill only)
-npx continuous-improvement install --target cursor    # Cursor (skill only)
-npx continuous-improvement install --target all       # All targets
-```
+### Troubleshooting install
 
-### Manual install
+Three failures account for nearly every install support thread. Try them in order:
 
-```bash
-mkdir -p ~/.claude/skills/continuous-improvement && \
-curl -fsSL -o ~/.claude/skills/continuous-improvement/SKILL.md \
-  https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/SKILL.md
-```
+| Symptom | Real cause | Fix |
+|---|---|---|
+| `/discipline` says "command not recognized" right after `/plugin install` | Slash commands load on session start; the marketplace did pick the plugin up | Quit and reopen Claude Code, then run `/discipline` again |
+| Expert mode hooks never fire on Windows | `observe.sh` is bash; PowerShell silently no-ops on it | Install Git Bash (or WSL) and re-run `npx continuous-improvement install --mode expert` |
+| `/plugin marketplace add ...` returned nothing visible | Marketplace add was silent; the plugin is not yet selected | Run `/plugin install continuous-improvement@continuous-improvement` to select and activate it |
 
-### Tell your agent
+If none of those apply, paste the output of `npx continuous-improvement install` into a GitHub issue — that surface logs every step.
 
-```
-Fetch and follow the skill at: https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/SKILL.md
-```
+### Operator modes
 
----
+The framework has documented operator-level modes that change hook behavior without rebuilding the plugin. These are first-class — set them once in your shell rc and they persist across sessions.
+
+| Env var | Effect | How to set |
+|---|---|---|
+| `CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` | `three-section-close.mjs` short-circuits before any enforcement or telemetry. Use when end-of-turn reflection should run as internal thinking rather than visible "What has been done / What is next / Recommendation" sections. Public default unchanged — the rule still fires for everyone else. | bash/zsh: `export CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_THREE_SECTION_CLOSE_DISABLED','1','User')` (persistent). |
 
-## The 7 Laws of AI Agent Discipline
+---
 
-> Every skill in the ecosystem adds capabilities. This is the only one that fixes *how agents think*.
+## The 7 Laws
 
 | # | Law | Without it, agents... |
 |---|-----|----------------------|
@@ -178,319 +138,239 @@ Fetch and follow the skill at: https://raw.githubusercontent.com/naimkatiman/con
 | 4 | **Verify Before Reporting** | lie about being "done" |
 | 5 | **Reflect After Sessions** | repeat the same failures |
 | 6 | **Iterate One Change** | debug 5 changes at once |
-| 7 | **Learn From Every Session** | lose knowledge when the context window ends |
-
-### The Loop
+| 7 | **Learn From Every Session** | lose knowledge when context ends |
 
 ```
-Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate
+Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
 ```
 
-If your agent is skipping a step, that's the step it needs most.
+<p align="center">
+  <img src="assets/diagram-7-laws-loop.jpg" alt="The 7 Laws of AI Agent Discipline — circular workflow loop" width="820" />
+</p>
+
+Full spec, reflection-block format, and anti-examples: [SKILL.md](SKILL.md).
 
 ---
 
 ## Mulahazah: Auto-Leveling Learning
 
-Mulahazah (Arabic: observation) makes your agent build **instincts** over time. It levels up automatically — you don't configure anything.
+Hooks capture every tool call. After ~20 observations, Claude analyzes patterns and creates **instincts** with confidence scores:
 
-```
-Install:       Hooks start capturing silently. You notice nothing.
-~20 sessions:  Agent analyzes patterns, creates first instincts (silent)
-~50 sessions:  Instincts cross 0.5 → agent starts suggesting behaviors
-~100 sessions: Instincts cross 0.7 → agent auto-applies what it learned
-```
+- **< 0.5** silent (stored, not surfaced)
+- **0.5–0.69** suggested inline when relevant
+- **0.7+** auto-applied
+- User corrections drop confidence by 0.1; unused instincts decay
+- Project-scoped, promoted to global after seen across 2+ projects
 
-### How it works
+<p align="center">
+  <img src="assets/diagram-mulahazah-learning.jpg" alt="Mulahazah pipeline" width="820" />
+</p>
 
-1. **Hooks capture every tool call** — PreToolUse/PostToolUse hooks write JSONL observations (<50ms, never blocks your session, jq not required)
-2. **Analysis runs inline** — when 20+ observations accumulate, Claude analyzes them at session start. No background daemon.
-3. **Instincts carry confidence** — 0.3–0.9 scale with graduated behavior:
-   - **Silent** (< 0.5) — stored, not surfaced
-   - **Suggest** (0.5–0.69) — mentioned inline when relevant
-   - **Auto-apply** (0.7+) — applied automatically
-4. **Self-correcting** — user corrections drop confidence by 0.1. Unused instincts decay. Wrong behaviors fade out.
-5. **Project-scoped** — instincts are per-project by default, promoted to global when seen across 2+ projects
+---
 
-### Starter Instinct Packs
+## Slash Commands
 
-Jump-start your instincts with pre-built packs for popular stacks:
+`/seven-laws` is the canonical reflect-and-learn command. `/continuous-improvement` is kept as an alias for backward compatibility — both run the same workflow.
 
-```bash
-npx continuous-improvement install --pack react    # 8 React/Next.js instincts
-npx continuous-improvement install --pack python   # 8 Python instincts
-npx continuous-improvement install --pack go       # 8 Go instincts
+```
+/seven-laws                       Reflect, analyze, show status (canonical)
+/continuous-improvement           Alias for /seven-laws (kept for backward compat)
+/proceed-with-the-recommendation  Walk any agent's recommendation list top-to-bottom
+/superpowers                      Law activator — route the task to the right specialist
+/workspace-surface-audit          Audit repo + MCP + env, recommend high-value skills
+/planning-with-files              Create task_plan.md, findings.md, progress.md
+/discipline                       Quick reference card of the 7 Laws
+/dashboard                        Visual instinct health dashboard
+/ralph                            Autonomous PRD story-by-story loop
+/learn-eval                       Capture session patterns into new skills (expert)
+/harvest                          Extract reusable patterns from session friction
+/release-train                    Coordinate a multi-PR release sequence
+/swarm                            Fan-out coordination across parallel sub-agents
 ```
 
-Or in expert mode: use the `ci_load_pack` tool to load packs at any time.
+All 13 ship in the marketplace bundle. The Beginner install gets all of them. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
 
-### Check what your agent has learned
+---
 
-```
-/continuous-improvement    # Reflect, analyze, show status
-/discipline                # Quick reference card of the 7 Laws
-/dashboard                 # Visual instinct health dashboard
-```
+## Law Coverage
+
+Every bundled skill, command, and hook enforces at least one of the 7 Laws. The full Law-to-tool alignment matrix lives in [CONTRIBUTING.md → Law Coverage Matrix](CONTRIBUTING.md#law-coverage-matrix); each skill's `description:` also leads with `Enforces Law N (...)` so the tag shows up every time the skill is loaded. Operator-level mode toggles live in the **Operator modes** section above the 7 Laws, alongside install.
 
 ---
 
-## GitHub Action: Agent Transcript Linter
+## All 14 Skills
 
-Lint your AI agent's behavior in CI/CD. The only GitHub Action that checks if your agent followed disciplined workflows.
+The plugin ships **1 core + 1 featured + 5 tier-1 + 4 tier-2 + 3 always-bundled = 14 skills**. Source-of-truth lives in [`skills/`](skills/) (one `.md` per skill); the plugin bundle at [`plugins/continuous-improvement/skills/`](plugins/continuous-improvement/skills/) is regenerated by `npm run build`.
 
-```yaml
-- uses: naimkatiman/continuous-improvement@v3
-  with:
-    transcript-path: agent-log.jsonl
-    strict: true  # Fail build on law violations
-```
+<details>
+<summary>Show the full skill table (14 rows)</summary>
+
+| # | Skill | Tier | Law | What it does |
+|---|-------|------|-----|--------------|
+| 1 | [`continuous-improvement`](SKILL.md) | core | — | The 7 Laws spec itself (research → plan → execute → verify → reflect → learn → iterate) |
+| 2 | [`proceed-with-the-recommendation`](skills/proceed-with-the-recommendation.md) ⭐ | featured | all 7 | Walks any agent's recommendation list top-to-bottom, routes each item, verifies per item, halts on `needs-approval` |
+| 3 | [`gateguard`](skills/gateguard.md) | 1 | 1 | Runtime PreToolUse hook (`hooks/gateguard.mjs`) + skill: physically blocks Edit/Write/MultiEdit and every destructive Bash until fact-list investigation is presented. Read-only and routine Bash bypass. |
+| 4 | [`para-memory-files`](skills/para-memory-files.md) | 1 | 5 + 7 | Durable file-based memory using PARA (Projects/Areas/Resources/Archives) for cross-session context |
+| 5 | [`tdd-workflow`](skills/tdd-workflow.md) | 1 | 3 + 4 | RED → GREEN → REFACTOR enforcement with 80%+ coverage across unit/integration/E2E |
+| 6 | [`verification-loop`](skills/verification-loop.md) | 1 | 4 | Six-phase verification (build, types, lint, tests, security, diff) with PASS/FAIL report |
+| 7 | [`deploy-receipt`](skills/deploy-receipt.md) | 1 | 4 | Closes the merge-to-production gap on auto-deploy targets (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io). "Done" requires the deployed SHA matching merged HEAD + a healthcheck returning 200 — runs after the vendored `finishing-a-development-branch`. |
+| 8 | [`safety-guard`](skills/safety-guard.md) | 2 | 3 | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory |
+| 9 | [`strategic-compact`](skills/strategic-compact.md) | 2 | 5 | Suggests `/compact` at logical phase boundaries instead of arbitrary auto-compaction |
+| 10 | [`token-budget-advisor`](skills/token-budget-advisor.md) | 2 | 2 | Token estimator that offers 25/50/75/100% depth choices before answering |
+| 11 | [`wild-risa-balance`](skills/wild-risa-balance.md) | 2 | 2 | Pairs WILD (bold) generation with RISA (safe) execution; splits recommendation lists into pilots above a baseline |
+| 12 | [`ralph`](skills/ralph.md) | companion | 6 | Autonomous loop that executes a PRD story-by-story with quality checks between iterations |
+| 13 | [`superpowers`](skills/superpowers.md) | companion | activator | Law activator — routes tasks to the correct Law-aligned specialist so the right discipline fires automatically |
+| 14 | [`workspace-surface-audit`](skills/workspace-surface-audit.md) | companion | 1 | Audits the active repo, MCP servers, plugins, env, then recommends high-value skills/workflows |
 
-The linter analyzes tool call patterns and detects:
-- **Law 1 violations** — writes without prior research
-- **Law 3 violations** — too many consecutive edits without verification
-- **Law 4 violations** — code changes without running tests/builds
-- **Law 6 violations** — too many files modified at once
+</details>
 
-Output includes a discipline score (0-100) and detailed violation report.
+The orchestrator skill `proceed-with-the-recommendation` also routes to optional companion skills from external plugins (e.g. `obra/superpowers`, `code-review`, `frontend-design`, `commit-commands`). Each routing target has an inline fallback in the orchestrator, so the plugin works on a clean install with nothing else present — install the dedicated companion only when you want a specialist over the fallback. Full target list with source-plugin and risk-if-absent: [`plugins/continuous-improvement/README.md` § Required vs Optional companions](plugins/continuous-improvement/README.md#required-vs-optional-companions).
 
-```bash
-# Run locally
-node bin/lint-transcript.mjs observations.jsonl
-cat transcript.jsonl | node bin/lint-transcript.mjs --stdin --json
-```
+### Beginner gets — by default
 
----
-
-## Plugin Architecture
-
-continuous-improvement ships as a **plugin** with three layers. Pick what you need:
-
-### Layer 1: Skill Only (any LLM)
-Paste SKILL.md into your system prompt. Your agent follows the 7 Laws. No tools, no hooks, no server.
-
-### Layer 2: Hooks (Claude Code)
-`npx continuous-improvement install` — installs hooks that silently capture every tool call. The instinct system grows automatically. Zero config.
-
-### Layer 3: MCP Server (any MCP client)
-`npx continuous-improvement install --mode expert` — a full MCP server that any editor can connect to.
-
-### Beginner vs Expert
-
-| Feature | Beginner (default) | Expert |
-|---------|-------------------|--------|
-| Observation hooks | Yes | Yes |
-| `/continuous-improvement` command | Yes | Yes |
-| `/discipline` quick reference | Yes | Yes |
-| `/dashboard` visual dashboard | Yes | Yes |
-| Auto-leveling instincts | Yes | Yes |
-| `ci_status` tool | - | Yes |
-| `ci_instincts` tool | - | Yes |
-| `ci_reflect` tool | - | Yes |
-| `ci_reinforce` tool | - | Yes |
-| `ci_create_instinct` tool | - | Yes |
-| `ci_observations` tool | - | Yes |
-| `ci_export` / `ci_import` | - | Yes |
-| `ci_dashboard` tool | - | Yes |
-| `ci_load_pack` tool | - | Yes |
-| Session start/end hooks | - | Yes |
-| MCP server | - | Yes |
-
-**Beginner** is the right choice for 90% of users. It just works — install and forget. The system quietly learns from your sessions.
-
-**Expert** adds the MCP server for programmatic access, manual instinct management, import/export for team sharing, visual dashboard, and instinct packs.
-
-### MCP Tools Reference
-
-| Tool | Description |
-|------|-------------|
-| `ci_status` | Current level, instinct count, observation count |
-| `ci_instincts` | List learned instincts with confidence levels |
-| `ci_reflect` | Generate structured session reflection |
-| `ci_reinforce` | Accept/reject instinct suggestions (expert) |
-| `ci_create_instinct` | Manually create instincts (expert) |
-| `ci_observations` | View raw tool call observations (expert) |
-| `ci_export` | Export instincts as JSON (expert) |
-| `ci_import` | Import instincts from JSON (expert) |
-| `ci_dashboard` | Visual dashboard with confidence distribution (expert) |
-| `ci_load_pack` | Load starter instinct packs (expert) |
+Tier 1 + featured + companion. Auto-installed when you run the plugin install commands above. No flags, no choices.
 
----
+### Expert gets — additionally
 
-## Real-World Examples
+Tier 2 (`safety-guard`, `strategic-compact`, `token-budget-advisor`, `wild-risa-balance`), the MCP server (12 tools incl. `ci_plan_init`/`ci_plan_status`), session-observation hooks for Mulahazah, and `/learn-eval` for capturing session patterns into new skills.
 
-See the [`examples/`](examples/) directory for detailed walkthroughs:
+### Drop-in single-file install
 
-- [**Bug Fix**](examples/01-bug-fix.md) — Double submit bug: 4 rounds without framework → 1 round with it
-- [**Feature Build**](examples/02-feature-build.md) — Adding pagination: 3 rewrites without → correct first attempt with
-- [**Refactor**](examples/03-refactor.md) — SDK migration: cascading failures without → zero regressions with
+Want one skill without the whole plugin? Copy the `.md` file straight into `~/.claude/skills/<name>/SKILL.md`:
 
-Each example shows the same task done with and without the 7 laws, highlighting which laws made the difference.
+```bash
+SKILL=proceed-with-the-recommendation
+mkdir -p ~/.claude/skills/$SKILL
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
+  -o ~/.claude/skills/$SKILL/SKILL.md
+```
 
 ---
 
-## Files
+## Evolution — adding a new skill
 
-```
-continuous-improvement/
-├── SKILL.md                           # The 7 Laws + instinct behavior
-├── bin/
-│   ├── install.mjs                    # CLI installer (--mode beginner|expert|mcp)
-│   ├── mcp-server.mjs                # MCP server (zero dependencies)
-│   └── lint-transcript.mjs           # Agent transcript linter (GitHub Action)
-├── hooks/
-│   ├── observe.sh                     # Observation hook (pure bash, <50ms)
-│   └── session.sh                     # Session start/end hook (expert mode)
-├── plugins/
-│   ├── beginner.json                  # Plugin manifest: 3 tools
-│   └── expert.json                    # Plugin manifest: 10 tools
-├── commands/
-│   ├── continuous-improvement.md     # /continuous-improvement command
-│   ├── discipline.md                 # /discipline quick reference
-│   └── dashboard.md                  # /dashboard visual display
-├── instinct-packs/
-│   ├── react.json                     # React/Next.js starter instincts
-│   ├── python.json                   # Python starter instincts
-│   └── go.json                       # Go starter instincts
-├── test/                              # 104 tests (node --test)
-├── examples/                          # Real-world before/after scenarios
-├── docs/                              # Translations (zh-CN, ja)
-├── .github/
-│   ├── workflows/ci.yml             # CI pipeline (Node 18/20/22)
-│   └── ISSUE_TEMPLATE/              # Bug report + feature request templates
-├── action.yml                        # GitHub Action definition
-├── llms.txt                          # LLM-friendly project description
-├── CONTRIBUTING.md
-├── CODE_OF_CONDUCT.md
-├── SECURITY.md
-├── QUICKSTART.md
-├── CHANGELOG.md
-└── package.json
-```
+Drop one `.md` file into [`skills/`](skills/), run `npm run build`, and the plugin bundle, manifests, and bundled-skills README regenerate from that source. Seven lints (`verify:all` + `verify:generated`) block the merge if anything drifts.
 
-### What gets installed where
+### The 5-step recipe
 
-**Beginner mode** (default):
-```
-~/.claude/skills/continuous-improvement/SKILL.md     # The skill
-~/.claude/commands/continuous-improvement.md          # The command
-~/.claude/commands/discipline.md                     # Quick reference
-~/.claude/commands/dashboard.md                      # Dashboard
-~/.claude/instincts/
-├── observe.sh                                       # Hook script
-├── global/                                          # Global instincts (*.yaml)
-└── <project-hash>/
-    ├── project.json                                 # Project metadata
-    ├── observations.jsonl                           # Tool call observations
-    └── *.yaml                                       # Project instincts
+```bash
+# 1. Create the source file
+touch skills/<your-skill>.md
 ```
 
-**Expert mode** adds:
-```
-~/.claude/instincts/session.sh                       # Session hooks
-~/.claude/settings.json                              # + MCP server + session hooks
+```yaml
+# 2. Frontmatter must declare name + tier + Law-tagged description
+---
+name: <your-skill>
+tier: "1"                # core | featured | "1" | "2" | companion
+description: "Enforces Law N (<law name>) of the 7 Laws of AI Agent Discipline. <what it does>."
+---
 ```
 
----
+```bash
+# 3. Regenerate the bundle (also writes plugins/.../skills/<your-skill>/SKILL.md
+#    + the bundled-skills README, which is itself generator-output)
+npm run build
 
-## Uninstall
+# 4. Run all 6 verify lints — must all pass
+npm run verify:all
 
-```bash
-npx continuous-improvement install --uninstall
+# 5. Commit one concern at a time (per CLAUDE.md): the source skill alone first,
+#    then any wiring (hooks, commands, Law-coverage table updates) as separate commits
+git add skills/<your-skill>.md plugins/continuous-improvement/skills/<your-skill>/
+git commit -m "feat(skills): add <your-skill> for Law N enforcement"
 ```
 
-Removes the skill, hooks, and commands. Your learned instincts in `~/.claude/instincts/` are preserved — delete that directory manually if you want a clean slate.
+### What the build does for you automatically
 
----
+- **Mirrors source → bundle** (`bin/generate-plugin-manifests.mjs`): copies `skills/<name>.md` to `plugins/continuous-improvement/skills/<name>/SKILL.md`
+- **Regenerates plugin manifests** with the new skill listed in tier order
+- **Re-renders** [`plugins/continuous-improvement/skills/README.md`](plugins/continuous-improvement/skills/README.md) (do not edit by hand — generator output)
 
-## Works With
+### What the lints enforce so you cannot ship a half-wired skill
 
-| Tool | Support |
-|------|---------|
-| **Claude Code** | Full — skill + hooks + MCP server + auto-leveling instincts |
-| **Claude Desktop** | MCP server (expert/mcp mode) |
-| **Cursor** | MCP server (mcp mode) or skill only (paste SKILL.md into rules) |
-| **Zed / Windsurf** | MCP server (mcp mode) |
-| **VS Code** | MCP server (mcp mode) with Copilot MCP support |
-| **Codex** | Skill only |
-| **Gemini CLI** | Skill only |
-| **OpenClaw** | Skill only |
-| **Any LLM** | Paste SKILL.md into your system prompt |
+| Lint | Blocks |
+|------|--------|
+| `verify:skill-mirror` | source `skills/<name>.md` and `plugins/.../<name>/SKILL.md` are out of sync |
+| `verify:skill-tiers` | skill has missing or unrecognized `tier:` value |
+| `verify:skill-law-tag` | skill description does not start with `Enforces Law N` (or `Law activator`, or `all 7 Laws`) |
+| `verify:docs-substrings` | README/QUICKSTART references a removed/renamed skill |
+| `verify:everything-mirror` | non-skill files in `plugins/continuous-improvement/` drift from their root-level source |
+| `verify:routing-targets` | `proceed-with-the-recommendation` names a routing target that is neither bundled nor declared in `optional-companions.json` |
+| `verify:generated` | `npm run build` was not re-run after a source change |
 
----
+### When to fold a new external skill into the 7 Laws
 
-## Red Flags
+A new skill is a fit if it provably enforces (or is a routed activator for) at least one of the 7 Laws. The Law-tag lint will refuse it otherwise. If it sits outside the laws (a domain skill — e.g. SQL optimization), keep it as an external plugin. The 7 Laws plugin stays disciplined about scope; that is the point.
 
-If your agent says any of these, it's skipping a law:
+### What is *not* automated (the honest limits)
 
-- "I'll just quickly..." → Law 3 violation
-- "This should work..." → Law 4 violation (verify, don't assume)
-- "I already know how to..." → Law 1 violation (still research)
-- "Let me also add..." → Law 6 violation (finish first)
-- "I'll remember this..." → Law 7 violation (write it down)
+- The Law-coverage matrix above (`## Law Coverage`) is hand-maintained — add your new skill to the right Law row when you ship it.
+- The "All 14 Skills" count in the section header is a literal — bump it when N changes.
+- Promotion between tiers (e.g. `2` → `1` after it proves itself) is a manual edit to the frontmatter `tier:` field, by design — the maintainer should make that call deliberately.
 
 ---
 
-## Roadmap
+## GitHub Action: Transcript Linter
+
+Lint agent behavior in CI. Detects skipped laws.
 
-### Phase 1: Foundation -- DONE
+```yaml
+- uses: naimkatiman/continuous-improvement@v3
+  with:
+    transcript-path: agent-log.jsonl
+    strict: true
+```
 
-- [x] Published to public npm (`npx continuous-improvement install` works)
-- [x] 104-test suite (installer, hook, MCP server, linter, packs, community files)
-- [x] Before/after examples in README + `examples/` directory
-- [x] Gemini CLI support
-- [x] Platform badges and improved npm metadata
-- [ ] **Submit to [awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)** (14K stars)
+`@v3` is a floating major-version tag that retargets on every `v3.x.y` release. Pin to a specific tag (`@v3.7.0`) if you need byte-reproducible CI; use `@v3` to ride patch and minor bumps automatically. See [CONTRIBUTING.md § Release](CONTRIBUTING.md#release) for the retarget policy.
 
-### Phase 2: Plugin Architecture -- DONE
+Catches: writes without prior research (Law 1), too many edits without verification (Law 3), code changes without tests/builds (Law 4), too many files at once (Law 6). Run locally with `node bin/lint-transcript.mjs <file>`.
 
-- [x] **MCP server** — 10 tools (beginner: 3, expert: 7 more) with zero dependencies
-- [x] **Beginner / Expert separation** — simple defaults, power when you need it
-- [x] **Plugin manifests** — `plugins/beginner.json` and `plugins/expert.json`
-- [x] **Session hooks** — auto-load instincts at session start, remind to reflect at end
-- [x] **`--mode` flag** — `beginner` | `expert` | `mcp` installation modes
-- [x] **Import/export** — share instincts as JSON between team members
-- [x] **Multi-editor MCP support** — Claude Desktop, Cursor, Zed, Windsurf, VS Code
+---
 
-### Phase 2.5: Visibility & Ecosystem -- DONE
+## Uninstall
 
-- [x] **GitHub Action** — lint agent transcripts for law compliance (`action.yml`)
-- [x] **Starter instinct packs** — React, Python, Go (pre-built instincts)
-- [x] **`/discipline` command** — quick reference card of the 7 Laws
-- [x] **`/dashboard` command** — visual instinct health dashboard
-- [x] **Community files** — CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md
-- [x] **llms.txt** — LLM-friendly project description for discoverability
-- [x] **CI pipeline** — GitHub Actions testing on Node 18/20/22
-- [x] **Issue templates** — bug report + feature request
-- [x] **Translations** — Chinese (简体中文) and Japanese (日本語)
+```bash
+npx continuous-improvement install --uninstall
+```
 
-### Phase 3: Content & Proof
+Removes skill, hooks, commands, MCP server. Learned instincts in `~/.claude/instincts/` are preserved — delete manually for a clean slate.
 
-- [ ] **2-min demo video** — side-by-side agent with/without discipline. Post to X + YouTube.
-- [ ] **"Why your AI agent keeps lying about being done"** — X thread / blog post
-- [ ] **"Law of the Week" X series** — 7 weeks of content breaking down each law
+---
 
-### Phase 4: Ecosystem Growth
+## The Brand Stack
 
-- [ ] **VS Code extension** — sidebar showing instinct confidence levels
-- [ ] **More instinct packs** — TypeScript, Rust, Java, Django, Laravel
-- [ ] **Instinct marketplace** — share learned instincts across teams
+One product, three names. Use the one that fits the audience:
 
-### Phase 5: Community
+| Layer | Name | When you say it |
+|-------|------|-----------------|
+| **Brand** | The 7 Laws of AI Agent Discipline | Tweets, talks, docs, "what is this" |
+| **Engine** | Mulahazah | The auto-leveling instinct system inside it |
+| **Package** | `continuous-improvement` | `npm install`, `/plugin install`, `settings.json` |
 
-- [ ] **Conference talk on Mulahazah** — the auto-leveling system is genuinely novel
-- [ ] **Leaderboard / badges** — "100 sessions" achievement system
-- [ ] **Custom domain** — landing page with interactive demo
+Every skill description leads with `Enforces Law N (...)` so the discipline tag shows up the moment the skill is loaded; the lint `verify:skill-law-tag` blocks any skill that drops the tag.
 
 ---
 
-## Contributing
+## In the wild
+
+Workflows from this repo, applied to real open-source contributions:
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome.
+### pm-skills (product-on-purpose, 189 stars, Apache 2.0)
 
-## Security
+[F-07 discover-market-sizing](https://github.com/product-on-purpose/pm-skills/pull/141) - new domain skill in the Discover phase covering TAM/SAM/SOM market sizing for the [pm-skills](https://github.com/product-on-purpose/pm-skills) library.
+
+Authored end-to-end with `/superpowers` and `/proceed-with-the-recommendation`: surface audit before any code, brainstorm gate with WILD/RISA framing, branch isolation off the upstream fork, single-skill PR scope per the upstream maintainer's curated-contributions model, count cascade across 23 docs files, and 9 local validators green before push (`lint-skills-frontmatter`, `validate-agents-md`, `validate-commands`, `check-count-consistency`, `check-nav-completeness`, `check-generated-content-untouched`, `check-generated-freshness`, `validate-meeting-skills-family`, `validate-plugin-install`).
+
+---
 
-See [SECURITY.md](SECURITY.md) for the security policy and how to report vulnerabilities.
+## More
 
-## License
+- [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
+- [SKILL.md](SKILL.md) — full 7 Laws spec
+- [examples/](examples/) — bug fix, feature build, refactor walkthroughs
+- [templates/insights-claude-md.md](templates/insights-claude-md.md) — paste-in CLAUDE.md blocks for verification discipline, environment notes, think-before-acting, and git/deploy workflow (sourced from the 28-day usage report)
+- [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals
+- [SECURITY.md](SECURITY.md)
 
-MIT
+MIT.