continuous-improvement 3.8.0 → 3.9.2

package/instinct-packs/react.json

@@ -1,58 +1,58 @@
-[
-  {
-    "id": "react-check-existing-components",
-    "trigger": "when creating a new React component",
-    "body": "Search the codebase for existing components that solve the same problem before creating new ones. Check shared/, components/, and ui/ directories.",
-    "confidence": 0.65,
-    "domain": "workflow"
-  },
-  {
-    "id": "react-prefer-server-components",
-    "trigger": "when creating components in Next.js App Router",
-    "body": "Default to Server Components. Only add 'use client' when the component needs useState, useEffect, event handlers, or browser APIs.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-key-prop-lists",
-    "trigger": "when rendering lists with .map()",
-    "body": "Always use a stable, unique key prop. Never use array index as key unless the list is static and never reordered.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-effect-cleanup",
-    "trigger": "when writing useEffect with subscriptions or timers",
-    "body": "Always return a cleanup function from useEffect when setting up subscriptions, event listeners, or timers to prevent memory leaks.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-memo-expensive",
-    "trigger": "when a component re-renders with expensive calculations",
-    "body": "Use useMemo for expensive computations and React.memo for components that receive the same props frequently. Don't memo everything — only what's measurably slow.",
-    "confidence": 0.6,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-form-validation",
-    "trigger": "when building forms",
-    "body": "Check if react-hook-form or zod is already in the project before building custom form validation. Prefer library solutions over hand-rolled validation.",
-    "confidence": 0.65,
-    "domain": "tooling"
-  },
-  {
-    "id": "react-error-boundary",
-    "trigger": "when adding a new page or route",
-    "body": "Ensure error boundaries exist around new pages/routes. In Next.js App Router, add error.tsx. In other React apps, wrap with ErrorBoundary component.",
-    "confidence": 0.6,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-test-user-behavior",
-    "trigger": "when writing React component tests",
-    "body": "Test user behavior, not implementation details. Use @testing-library/react. Query by role, label, or text — not by class name or test ID.",
-    "confidence": 0.65,
-    "domain": "testing"
-  }
-]
+[
+  {
+    "id": "react-check-existing-components",
+    "trigger": "when creating a new React component",
+    "body": "Search the codebase for existing components that solve the same problem before creating new ones. Check shared/, components/, and ui/ directories.",
+    "confidence": 0.65,
+    "domain": "workflow"
+  },
+  {
+    "id": "react-prefer-server-components",
+    "trigger": "when creating components in Next.js App Router",
+    "body": "Default to Server Components. Only add 'use client' when the component needs useState, useEffect, event handlers, or browser APIs.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-key-prop-lists",
+    "trigger": "when rendering lists with .map()",
+    "body": "Always use a stable, unique key prop. Never use array index as key unless the list is static and never reordered.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-effect-cleanup",
+    "trigger": "when writing useEffect with subscriptions or timers",
+    "body": "Always return a cleanup function from useEffect when setting up subscriptions, event listeners, or timers to prevent memory leaks.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-memo-expensive",
+    "trigger": "when a component re-renders with expensive calculations",
+    "body": "Use useMemo for expensive computations and React.memo for components that receive the same props frequently. Don't memo everything — only what's measurably slow.",
+    "confidence": 0.6,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-form-validation",
+    "trigger": "when building forms",
+    "body": "Check if react-hook-form or zod is already in the project before building custom form validation. Prefer library solutions over hand-rolled validation.",
+    "confidence": 0.65,
+    "domain": "tooling"
+  },
+  {
+    "id": "react-error-boundary",
+    "trigger": "when adding a new page or route",
+    "body": "Ensure error boundaries exist around new pages/routes. In Next.js App Router, add error.tsx. In other React apps, wrap with ErrorBoundary component.",
+    "confidence": 0.6,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-test-user-behavior",
+    "trigger": "when writing React component tests",
+    "body": "Test user behavior, not implementation details. Use @testing-library/react. Query by role, label, or text — not by class name or test ID.",
+    "confidence": 0.65,
+    "domain": "testing"
+  }
+]

package/lib/gateguard-state.mjs

@@ -0,0 +1,85 @@
+/**
+ * Gateguard per-session state.
+ *
+ * State file: <sessionDir>/gateguard-session.json. sessionDir resolves to
+ * GATEGUARD_SESSION_DIR (env override, used by tests) or
+ * ~/.claude/instincts/<projectHash>/ in production.
+ *
+ * V1 limitations (documented for honesty, not mitigated in code):
+ * - Honor system: clearance is granted whenever the agent sets
+ *   `_gateguard_facts_presented: true` in tool_input or has a prior per-file
+ *   marker. The hook cannot verify that real investigation occurred.
+ * - State-file deletion: rm'ing the state file resets every gate in the
+ *   session. Defensible because the session itself is the trust boundary;
+ *   the cap below limits cumulative damage.
+ * - Concurrency: two parallel hook invocations can race the read+write.
+ *   Acceptable trade-off vs OS-specific atomic-rename complexity on Windows.
+ * - Cap: MAX_CLEARED_FILES caps the number of distinct files a single
+ *   session can clear, bounding stuck-loop / rogue-agent damage.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const MAX_CLEARED_FILES = 50;
+export function resolveSessionDir() {
+    const fromEnv = process.env.GATEGUARD_SESSION_DIR;
+    if (fromEnv)
+        return fromEnv;
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    const projectRoot = resolveProjectRoot();
+    const projectHash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    return join(home, ".claude", "instincts", projectHash);
+}
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            return root;
+    }
+    catch {
+        // not in a git repo
+    }
+    return "global";
+}
+export function loadState(sessionDir) {
+    const path = join(sessionDir, "gateguard-session.json");
+    if (!existsSync(path)) {
+        return { created_at: new Date().toISOString(), cleared_files: {} };
+    }
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            created_at: parsed.created_at ?? new Date().toISOString(),
+            cleared_files: parsed.cleared_files ?? {},
+        };
+    }
+    catch {
+        return { created_at: new Date().toISOString(), cleared_files: {} };
+    }
+}
+export function saveState(sessionDir, state) {
+    if (!existsSync(sessionDir))
+        mkdirSync(sessionDir, { recursive: true });
+    writeFileSync(join(sessionDir, "gateguard-session.json"), `${JSON.stringify(state, null, 2)}\n`);
+}
+export function isCapReached(state) {
+    return Object.keys(state.cleared_files).length >= MAX_CLEARED_FILES;
+}
+export function markFileCleared(state, filePath) {
+    return {
+        ...state,
+        cleared_files: {
+            ...state.cleared_files,
+            [filePath]: { cleared_at: new Date().toISOString() },
+        },
+    };
+}

package/lib/plugin-metadata.mjs

@@ -1,5 +1,9 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 export const PACKAGE_NAME = "continuous-improvement";
-export const VERSION = "3.8.0";
+const PKG_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+export const VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
 export const PLUGIN_MODES = ["beginner", "expert"];
 const REPOSITORY_URL = "https://github.com/naimkatiman/continuous-improvement";
 const HOMEPAGE_URL = `${REPOSITORY_URL}#readme`;
@@ -23,11 +27,17 @@ const KEYWORDS = [
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
 const SHARED_PLUGIN_DESCRIPTION = "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.";
-// Five vendored upstream companions registered alongside the CI plugin.
+// Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
 // OUR_NOTES.md for integration scope and overlap matrices. The unified
-// /superpowers dispatcher (skills/superpowers.md) routes across all five.
+// /superpowers dispatcher (skills/superpowers.md) routes across all four.
+// Product-management coverage is supplied by phuryn/pm-skills as an
+// out-of-band marketplace install — see docs/THIRD_PARTY.md for the
+// `claude plugin marketplace add phuryn/pm-skills` recipe and the eight
+// installable plugins (pm-toolkit, pm-product-strategy, pm-product-discovery,
+// pm-market-research, pm-data-analytics, pm-marketing-growth,
+// pm-go-to-market, pm-execution).
 const THIRD_PARTY_COMPANIONS = [
     {
         name: "superpowers",
@@ -75,18 +85,6 @@ const THIRD_PARTY_COMPANIONS = [
         category: "orchestration",
         homepage: "https://github.com/Yeachan-Heo/oh-my-claudecode",
     },
-    {
-        name: "pm-skills",
-        description: "Product management skills for AI agents — 41 skills + 47 commands across the full product lifecycle (discover, define, develop, deliver, measure, iterate). Includes Meeting Skills Family v2.11.0 (5 cross-cutting skills under a shared contract with enforcing CI), OKR Skills v2.12.0 (foundation-okr-writer + measure-okr-grader for the quarterly OKR write-and-score cycle), lean canvas, persona, JTBD, PRD, user stories, acceptance criteria, hypothesis, experiment design, retrospective, launch checklist, release notes, and pm-skill-builder for authoring new skills. Follows the agentskills.io specification. Vendored snapshot at third-party/pm-skills/ pinned to upstream SHA 8d23508 (v2.13.1).",
-        version: "2.13.1",
-        source: "./third-party/pm-skills",
-        author: {
-            name: "product-on-purpose",
-            url: "https://github.com/product-on-purpose",
-        },
-        category: "product",
-        homepage: "https://github.com/product-on-purpose/pm-skills",
-    },
 ];
 export function isPluginMode(value) {
     return value === "beginner" || value === "expert";
@@ -358,6 +356,11 @@ export function getClaudePluginManifest() {
     };
 }
 export function getPluginHooksConfig() {
+    const gateguardCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gateguard.mjs\"",
+        timeout: 5,
+    };
     const observeCommand = {
         type: "command",
         command: "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
@@ -374,9 +377,13 @@ export function getPluginHooksConfig() {
         timeout: 5,
     };
     return {
-        description: "Observation, session lifecycle, and 3-section-close discipline hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, observation, session lifecycle, and 3-section-close discipline hooks for continuous-improvement.",
         hooks: {
-            PreToolUse: [{ hooks: [observeCommand] }],
+            // gateguard runs FIRST so its block decision short-circuits before
+            // observe.sh records the tool call. observe.sh stays in PreToolUse for
+            // the observation feed; the Claude Code host runs both regardless of
+            // gateguard's decision.
+            PreToolUse: [{ hooks: [gateguardCommand, observeCommand] }],
             PostToolUse: [{ hooks: [observeCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
@@ -409,7 +416,7 @@ export function getClaudePluginMarketplaceManifest() {
 export function getClaudeRepoMarketplaceManifest(extraPlugins = []) {
     return {
         name: PACKAGE_NAME,
-        description: "Marketplace for the Continuous Improvement Claude Code plugin and five vendored upstream companions (Obra superpowers, addyosmani/agent-skills, ruflo-swarm, oh-my-claudecode, product-on-purpose/pm-skills). All five companions are pinned-SHA snapshots in third-party/ — see third-party/MANIFEST.md for refresh recipes and per-snapshot OUR_NOTES.md for integration scope.",
+        description: "Marketplace for the Continuous Improvement Claude Code plugin and four vendored upstream companions (Obra superpowers, addyosmani/agent-skills, ruflo-swarm, oh-my-claudecode). All four companions are pinned-SHA snapshots in third-party/ — see third-party/MANIFEST.md for refresh recipes and per-snapshot OUR_NOTES.md for integration scope. Product-management coverage is provided out-of-band by phuryn/pm-skills via Claude Code's plugin marketplace — see docs/THIRD_PARTY.md.",
         owner: {
             name: AUTHOR.name,
         },

package/llms.txt

@@ -1,68 +1,68 @@
-# continuous-improvement
-
-> Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.
-
-## What This Is
-
-A discipline framework for AI coding agents. It enforces seven laws — research, plan, execute one thing at a time, verify, reflect, iterate, learn — and builds behavioral instincts over time via the Mulahazah learning system, so the same correction does not have to be given twice.
-
-## Install
-
-```bash
-npx continuous-improvement install
-```
-
-## The 7 Laws
-
-1. Research Before Executing — search before writing
-2. Plan Is Sacred — state WILL/WILL NOT/VERIFY before acting
-3. One Thing at a Time — complete and verify one task before the next
-4. Verify Before Reporting — "done" requires actual proof
-5. Reflect After Sessions — capture what worked, what failed, and the top-3 next moves
-6. Iterate One Change — one change, verify, then next
-7. Learn From Every Session — patterns become instincts
-
-## Reflection Block (Law 5 -> Law 6 Handoff)
-
-Each reflection ends with a ranked top-3 of concrete core-development next moves:
-
-```
-## Reflection
-- What worked:
-- What failed:
-- What I'd do differently:
-- Rule to add:
-- Iteration — Next best recommendations (ranked, top 3):
-  1. <primary>
-  2. <alternative — different angle>
-  3. <alternative — smaller/larger scope>
-```
-
-The Iteration field is build/fix/refactor/investigate moves only — not git steps, not verification re-runs, not deploy actions. Format per item: `<verb> <object at path:line> (<why>)`. Full spec in SKILL.md.
-
-## Key Concepts
-
-- **Mulahazah** — auto-leveling learning system that captures tool usage patterns
-- **Instincts** — YAML-based behavioral rules with confidence scoring (0.0-0.9)
-- **Auto-leveling** — CAPTURE → ANALYZE → SUGGEST → AUTO-APPLY (no config needed)
-- **Project-scoped** — instincts are per-project, promoted to global when seen in 2+ projects
-- **Planning-With-Files** — opt-in project-root memory files: `task_plan.md`, `findings.md`, `progress.md`
-
-## Optional Planning Workflow
-
-When a task needs persistent file-based planning, use the `planning-with-files` workflow to create:
-- `task_plan.md` — phases, status, decisions, errors
-- `findings.md` — research notes and sources
-- `progress.md` — session log and verification notes
-
-This workflow is explicit and opt-in. Files are created in the git root when available, otherwise the current working directory.
-
-## Works With
-
-- Claude Code (full support: skill + hooks + MCP server + slash commands + auto-leveling instincts)
-
-## Links
-
-- GitHub: https://github.com/naimkatiman/continuous-improvement
-- npm: https://www.npmjs.com/package/continuous-improvement
-- Skill file: https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/SKILL.md
+# continuous-improvement
+
+> Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.
+
+## What This Is
+
+A discipline framework for AI coding agents. It enforces seven laws — research, plan, execute one thing at a time, verify, reflect, iterate, learn — and builds behavioral instincts over time via the Mulahazah learning system, so the same correction does not have to be given twice.
+
+## Install
+
+```bash
+npx continuous-improvement install
+```
+
+## The 7 Laws
+
+1. Research Before Executing — search before writing
+2. Plan Is Sacred — state WILL/WILL NOT/VERIFY before acting
+3. One Thing at a Time — complete and verify one task before the next
+4. Verify Before Reporting — "done" requires actual proof
+5. Reflect After Sessions — capture what worked, what failed, and the top-3 next moves
+6. Iterate One Change — one change, verify, then next
+7. Learn From Every Session — patterns become instincts
+
+## Reflection Block (Law 5 -> Law 6 Handoff)
+
+Each reflection ends with a ranked top-3 of concrete core-development next moves:
+
+```
+## Reflection
+- What worked:
+- What failed:
+- What I'd do differently:
+- Rule to add:
+- Iteration — Next best recommendations (ranked, top 3):
+  1. <primary>
+  2. <alternative — different angle>
+  3. <alternative — smaller/larger scope>
+```
+
+The Iteration field is build/fix/refactor/investigate moves only — not git steps, not verification re-runs, not deploy actions. Format per item: `<verb> <object at path:line> (<why>)`. Full spec in SKILL.md.
+
+## Key Concepts
+
+- **Mulahazah** — auto-leveling learning system that captures tool usage patterns
+- **Instincts** — YAML-based behavioral rules with confidence scoring (0.0-0.9)
+- **Auto-leveling** — CAPTURE → ANALYZE → SUGGEST → AUTO-APPLY (no config needed)
+- **Project-scoped** — instincts are per-project, promoted to global when seen in 2+ projects
+- **Planning-With-Files** — opt-in project-root memory files: `task_plan.md`, `findings.md`, `progress.md`
+
+## Optional Planning Workflow
+
+When a task needs persistent file-based planning, use the `planning-with-files` workflow to create:
+- `task_plan.md` — phases, status, decisions, errors
+- `findings.md` — research notes and sources
+- `progress.md` — session log and verification notes
+
+This workflow is explicit and opt-in. Files are created in the git root when available, otherwise the current working directory.
+
+## Works With
+
+- Claude Code (full support: skill + hooks + MCP server + slash commands + auto-leveling instincts)
+
+## Links
+
+- GitHub: https://github.com/naimkatiman/continuous-improvement
+- npm: https://www.npmjs.com/package/continuous-improvement
+- Skill file: https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/SKILL.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.8.0",
+  "version": "3.9.2",
   "description": "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, the Mulahazah auto-leveling instinct engine, and a GitHub Action transcript linter. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
   "keywords": [
     "claude-code",
@@ -45,7 +45,8 @@
     "verify:docs-substrings": "node bin/check-docs-substrings.mjs",
     "verify:everything-mirror": "node bin/check-everything-mirror.mjs",
     "verify:routing-targets": "node bin/check-routing-targets.mjs",
-    "verify:all": "npm run verify:skill-mirror && npm run verify:skill-tiers && npm run verify:skill-law-tag && npm run verify:docs-substrings && npm run verify:everything-mirror && npm run verify:routing-targets && npm run typecheck"
+    "verify:doc-runtime-claims": "node bin/check-doc-runtime-claims.mjs",
+    "verify:all": "npm run verify:skill-mirror && npm run verify:skill-tiers && npm run verify:skill-law-tag && npm run verify:docs-substrings && npm run verify:everything-mirror && npm run verify:routing-targets && npm run verify:doc-runtime-claims && npm run typecheck"
   },
   "files": [
     ".claude-plugin/",

package/plugins/beginner.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.8.0",
+  "version": "3.9.2",
   "mode": "beginner",
   "description": "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles four discipline skills (gateguard, para-memory-files, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default.",
   "tools": [

package/plugins/continuous-improvement/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "continuous-improvement",
       "description": "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.",
-      "version": "3.8.0",
+      "version": "3.9.2",
       "source": "./",
       "author": {
         "name": "naimkatiman"

package/plugins/continuous-improvement/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.8.0",
+  "version": "3.9.2",
   "description": "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.",
   "author": {
     "name": "naimkatiman",

package/plugins/continuous-improvement/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Naim Katiman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Naim Katiman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/continuous-improvement/README.md

@@ -8,6 +8,7 @@ Included surfaces:
 - `.claude-plugin/marketplace.json`
 - `skills/`
 - `commands/`
+- `agents/` — `code-reviewer`, `security-auditor`, `test-engineer` personas (auto-discovered Claude Code subagents; pattern from addy/agent-skills)
 - `hooks/`
 - `bin/mcp-server.mjs`
 - `bin/observe.mjs`

package/plugins/continuous-improvement/agents/README.md

@@ -0,0 +1,120 @@
+# Agent Personas
+
+Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.).
+
+| Persona | Role | Best for |
+|---------|------|----------|
+| [code-reviewer](code-reviewer.md) | Senior Staff Engineer | Five-axis review before merge |
+| [security-auditor](security-auditor.md) | Security Engineer | Vulnerability detection, OWASP-style audit |
+| [test-engineer](test-engineer.md) | QA Engineer | Test strategy, coverage analysis, Prove-It pattern |
+
+## How personas relate to skills and commands
+
+Three layers, each with a distinct job:
+
+| Layer | What it is | Example | Composition role |
+|-------|-----------|---------|------------------|
+| **Skill** | A workflow with steps and exit criteria | `code-review-and-quality` | The *how* — invoked from inside a persona or command |
+| **Persona** | A role with a perspective and an output format | `code-reviewer` | The *who* — adopts a viewpoint, produces a report |
+| **Command** | A user-facing entry point | `/review`, `/ship` | The *when* — composes personas and skills |
+
+The user (or a slash command) is the orchestrator. **Personas do not call other personas.** Skills are mandatory hops inside a persona's workflow.
+
+## When to use each
+
+### Direct persona invocation
+Pick this when you want one perspective on the current change and the user is in the loop.
+
+- "Review this PR" → invoke `code-reviewer` directly
+- "Are there security issues in `auth.ts`?" → invoke `security-auditor` directly
+- "What tests are missing for the checkout flow?" → invoke `test-engineer` directly
+
+### Slash command (single persona behind it)
+Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
+
+- `/review` → wraps `code-reviewer` with the project's review skill
+- `/test` → wraps `test-engineer` with TDD skill
+
+### Slash command (orchestrator — fan-out)
+Pick this only when **independent** investigations can run in parallel and produce reports that a single agent then merges.
+
+- `/ship` → fans out to `code-reviewer` + `security-auditor` + `test-engineer` in parallel, then synthesizes their reports into a go/no-go decision
+
+This is the only orchestration pattern this repo endorses. See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full pattern catalog and anti-patterns.
+
+## Decision matrix
+
+```
+Is the work a single perspective on a single artifact?
+├── Yes → Direct persona invocation
+└── No  → Are the sub-tasks independent (no shared mutable state, no ordering)?
+         ├── Yes → Slash command with parallel fan-out (e.g. /ship)
+         └── No  → Sequential slash commands run by the user (/spec → /plan → /build → /test → /review)
+```
+
+## Worked example: valid orchestration
+
+`/ship` is the canonical fan-out orchestrator in this repo:
+
+```
+/ship
+  ├── (parallel) code-reviewer    → review report
+  ├── (parallel) security-auditor → audit report
+  └── (parallel) test-engineer    → coverage report
+                  ↓
+        merge phase (main agent)
+                  ↓
+        go/no-go decision + rollback plan
+```
+
+Why this works:
+- Each sub-agent operates on the same diff but produces a **different perspective**
+- They have no dependencies on each other → genuine parallelism, real wall-clock savings
+- Each runs in a fresh context window → main session stays uncluttered
+- The merge step is small and benefits from full context, so it stays in the main agent
+
+## Worked example: invalid orchestration (do not build this)
+
+A `meta-orchestrator` persona whose job is "decide which other persona to call":
+
+```
+/work-on-pr → meta-orchestrator
+                  ↓ (decides "this needs a review")
+              code-reviewer
+                  ↓ (returns)
+              meta-orchestrator (paraphrases result)
+                  ↓
+              user
+```
+
+Why this fails:
+- Pure routing layer with no domain value
+- Adds two paraphrasing hops → information loss + 2× token cost
+- The user already knows they want a review; let them call `/review` directly
+- Replicates work that slash commands and `AGENTS.md` intent-mapping already do
+
+## Rules for personas
+
+1. A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona.
+2. **Personas do not invoke other personas.** Composition is the job of slash commands or the user. On Claude Code this is also a hard platform constraint — *"subagents cannot spawn other subagents"* — so the rule is enforced for you.
+3. A persona may invoke skills (the *how*).
+4. Every persona file ends with a "Composition" block stating where it fits.
+
+## Claude Code interop
+
+The personas in this repo are designed to work as Claude Code subagents and as Agent Teams teammates without modification:
+
+- **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/ship` is the canonical example.
+- **As Agent Teams teammates** (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): reference the same persona name when spawning a teammate. The persona's body is **appended to** the teammate's system prompt as additional instructions (not a replacement), so your persona text sits on top of the team-coordination instructions the lead installs (SendMessage, task-list tools, etc.).
+
+Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full mapping.
+
+Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here.
+
+## Adding a new persona
+
+1. Create `agents/<role>.md` with the same frontmatter format used by existing personas.
+2. Define the role, scope, output format, and rules.
+3. Add a **Composition** block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona).
+4. Add the persona to the table at the top of this file.
+5. If the persona enables a new orchestration pattern, document it in `references/orchestration-patterns.md` rather than inventing the pattern in the persona file itself.