continuous-improvement 3.1.0 → 3.9.1

package/llms.txt

@@ -1,10 +1,10 @@
 # continuous-improvement
 
-> The 7 Laws of AI Agent Discipline — stop your agent from skipping steps, guessing, and declaring "done" without verifying.
+> 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 teaches agents structured thinking through 7 laws and builds behavioral instincts over time via the Mulahazah learning system.
+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
 
@@ -18,23 +18,48 @@ npx continuous-improvement install
 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 and what failed
+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)
-- Cursor, Zed, Windsurf, VS Code (MCP server)
-- Codex, Gemini CLI, OpenClaw (skill only)
-- Any LLM (paste SKILL.md into system prompt)
+- Claude Code (full support: skill + hooks + MCP server + slash commands + auto-leveling instincts)
 
 ## Links
 

package/package.json

@@ -1,32 +1,20 @@
 {
   "name": "continuous-improvement",
-  "version": "3.1.0",
-  "description": "The 7 Laws of AI Agent Discipline — stop your agent from skipping steps, guessing, and declaring 'done' without verifying. Auto-leveling instinct learning with MCP server, GitHub Action transcript linter, and starter instinct packs for Claude Code, Cursor, Codex, Gemini CLI.",
+  "version": "3.9.1",
+  "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",
     "claude-code-skill",
     "ai-agent",
     "agent-skill",
-    "codex",
-    "cursor",
-    "gemini-cli",
     "ai-discipline",
-    "workflow",
-    "productivity",
     "mulahazah",
     "instinct",
-    "learning",
     "hooks",
-    "continuous-improvement",
     "mcp",
     "mcp-server",
-    "plugin",
     "github-action",
-    "transcript-linter",
-    "agent-discipline",
-    "developer-tools",
-    "anthropic",
-    "llm"
+    "transcript-linter"
   ],
   "author": "naimkatiman",
   "license": "MIT",
@@ -40,13 +28,28 @@
   },
   "bin": {
     "continuous-improvement": "bin/install.mjs",
-    "ci-lint-transcript": "bin/lint-transcript.mjs"
+    "ci-lint-transcript": "bin/lint-transcript.mjs",
+    "ci": "bin/unified-cli.mjs"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "lint": "node bin/lint-transcript.mjs --help"
+    "build": "tsc -p tsconfig.json && node bin/generate-plugin-manifests.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "node -e \"const fs=require('node:fs'); for (const dir of ['bin','test','lib']) { if (!fs.existsSync(dir)) continue; for (const file of fs.readdirSync(dir)) { if (file.endsWith('.mjs')) fs.rmSync(dir + '/' + file, { force: true }); } }\"",
+    "hooks:stats": "node bin/hook-stats.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "lint": "node bin/lint-transcript.mjs --help",
+    "verify:generated": "npm run build && git diff --exit-code -- .claude-plugin bin test lib plugins",
+    "verify:skill-mirror": "node bin/check-skill-mirror.mjs",
+    "verify:skill-tiers": "node bin/check-skill-tiers.mjs",
+    "verify:skill-law-tag": "node bin/check-skill-law-tag.mjs",
+    "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: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/",
     "SKILL.md",
     "QUICKSTART.md",
     "CHANGELOG.md",
@@ -54,10 +57,17 @@
     "llms.txt",
     "action.yml",
     "bin/",
+    "lib/",
     "hooks/",
     "commands/",
+    "skills/",
+    "templates/",
     "plugins/",
     "instinct-packs/"
   ],
-  "type": "module"
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  }
 }

package/plugins/beginner.json

@@ -1,8 +1,8 @@
 {
   "name": "continuous-improvement",
-  "version": "3.1.0",
+  "version": "3.9.0",
   "mode": "beginner",
-  "description": "3 simple tools: check status, view instincts, reflect on sessions. No config needed.",
+  "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": [
     {
       "name": "ci_status",
@@ -22,7 +22,11 @@
       "mcpServers": {
         "continuous-improvement": {
           "command": "node",
-          "args": ["<install-path>/bin/mcp-server.mjs", "--mode", "beginner"]
+          "args": [
+            "<install-path>/bin/mcp-server.mjs",
+            "--mode",
+            "beginner"
+          ]
         }
       }
     },
@@ -30,13 +34,20 @@
       "mcpServers": {
         "continuous-improvement": {
           "command": "node",
-          "args": ["<install-path>/bin/mcp-server.mjs", "--mode", "beginner"]
+          "args": [
+            "<install-path>/bin/mcp-server.mjs",
+            "--mode",
+            "beginner"
+          ]
         }
       }
     }
   },
   "hooks": {
-    "included": ["PreToolUse", "PostToolUse"],
-    "description": "Silently captures every tool call as observations. <50ms, never blocks."
+    "included": [
+      "PreToolUse",
+      "PostToolUse"
+    ],
+    "description": "Silently captures every tool call as observations. Lightweight and non-blocking."
   }
 }

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

@@ -0,0 +1,20 @@
+{
+  "name": "continuous-improvement-dev",
+  "description": "Development marketplace for the Continuous Improvement Claude Code plugin.",
+  "owner": {
+    "name": "naimkatiman"
+  },
+  "plugins": [
+    {
+      "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.9.0",
+      "source": "./",
+      "author": {
+        "name": "naimkatiman"
+      },
+      "category": "productivity",
+      "homepage": "https://github.com/naimkatiman/continuous-improvement"
+    }
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "name": "continuous-improvement",
+  "version": "3.9.0",
+  "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",
+    "url": "https://github.com/naimkatiman"
+  },
+  "homepage": "https://github.com/naimkatiman/continuous-improvement#readme",
+  "repository": "https://github.com/naimkatiman/continuous-improvement",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "claude-code-skill",
+    "ai-agent",
+    "agent-skill",
+    "ai-discipline",
+    "mulahazah",
+    "instinct",
+    "hooks",
+    "mcp",
+    "mcp-server",
+    "github-action",
+    "transcript-linter"
+  ]
+}

package/plugins/continuous-improvement/LICENSE

@@ -0,0 +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.

package/plugins/continuous-improvement/README.md

@@ -0,0 +1,57 @@
+# Continuous Improvement Plugin Bundle (Claude Code)
+
+This directory is generated by `npm run build`.
+Do not edit files here manually; edit the source files in the repo root and rebuild.
+
+Included surfaces:
+- `.claude-plugin/plugin.json`
+- `.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`
+- `bin/backfill.mjs`
+- `lib/plugin-metadata.mjs`
+- `lib/observe-event.mjs`
+- `instinct-packs/`
+- `templates/planning-with-files/`
+
+## Required vs Optional companions
+
+The `proceed-with-the-recommendation` skill (bundled here) routes each
+recommendation it walks to a specialist skill. Some specialists ship in
+this bundle; the rest live in external plugins. Every external routing
+target has a concretely-worded inline fallback in the orchestrator skill,
+so the plugin works on a clean install with no other plugins present —
+the trade-off is fallback quality vs dedicated-skill quality.
+
+**Bundled with this plugin (no extra install needed):**
+
+- `continuous-improvement` — core 7 Laws skill
+- `proceed-with-the-recommendation` — the orchestrator itself
+- `ralph` — autonomous PRD-scale loop
+- `tdd-workflow` — RED/GREEN/REFACTOR + 80% coverage gate
+- `workspace-surface-audit` — environment + capability audit
+- Tier-1/Tier-2 enforcement skills (`gateguard`, `verification-loop`,
+  `para-memory-files`, `safety-guard`, `token-budget-advisor`,
+  `strategic-compact`, `wild-risa-balance`)
+
+**Optional companions the orchestrator routes to (install separately if
+you want the dedicated skill instead of the inline fallback):**
+
+| Source plugin | Routing targets | Notes |
+|---|---|---|
+| `obra/superpowers` | `superpowers:brainstorming`, `:writing-plans`, `:systematic-debugging`, `:test-driven-development`, `:requesting-code-review`, `:verification-before-completion`, `:dispatching-parallel-agents`, `:finishing-a-development-branch`, `simplify`, `schedule`, `loop`, `update-config` | Largest external surface; covers planning, debugging, parallel dispatch, branch-finish |
+| Claude Code host (Anthropic built-in) | `security-review` | Ships with the host CLI itself, not a separate plugin install |
+| `code-review` plugin | `code-review` | Diff walk + severity tagging |
+| `documentation-lookup` agent / `context7` MCP | `documentation-lookup` | Library docs lookup with citations |
+| `frontend-design` plugin | `frontend-design:frontend-design` | Distinctive UI generation |
+| `commit-commands` plugin | `commit-commands:commit`, `:commit-push-pr` | Conventional-commit + push-PR helpers |
+
+Full per-target audit (license status, bundled flag, inline fallback,
+risk-if-absent) lives in `docs/audits/2026-05-06-routing-target-gap.md`.
+Per-target inline fallbacks are spelled out in the orchestrator skill at
+`skills/proceed-with-the-recommendation/SKILL.md` § "Routing Table
+(with Inline Fallbacks)".

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.

package/plugins/continuous-improvement/agents/code-reviewer.md

@@ -0,0 +1,97 @@
+---
+name: code-reviewer
+description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
+---
+
+# Senior Code Reviewer
+
+You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback.
+
+## Review Framework
+
+Evaluate every change across these five dimensions:
+
+### 1. Correctness
+- Does the code do what the spec/task says it should?
+- Are edge cases handled (null, empty, boundary values, error paths)?
+- Do the tests actually verify the behavior? Are they testing the right things?
+- Are there race conditions, off-by-one errors, or state inconsistencies?
+
+### 2. Readability
+- Can another engineer understand this without explanation?
+- Are names descriptive and consistent with project conventions?
+- Is the control flow straightforward (no deeply nested logic)?
+- Is the code well-organized (related code grouped, clear boundaries)?
+
+### 3. Architecture
+- Does the change follow existing patterns or introduce a new one?
+- If a new pattern, is it justified and documented?
+- Are module boundaries maintained? Any circular dependencies?
+- Is the abstraction level appropriate (not over-engineered, not too coupled)?
+- Are dependencies flowing in the right direction?
+
+### 4. Security
+- Is user input validated and sanitized at system boundaries?
+- Are secrets kept out of code, logs, and version control?
+- Is authentication/authorization checked where needed?
+- Are queries parameterized? Is output encoded?
+- Any new dependencies with known vulnerabilities?
+
+### 5. Performance
+- Any N+1 query patterns?
+- Any unbounded loops or unconstrained data fetching?
+- Any synchronous operations that should be async?
+- Any unnecessary re-renders (in UI components)?
+- Any missing pagination on list endpoints?
+
+## Output Format
+
+Categorize every finding:
+
+**Critical** — Must fix before merge (security vulnerability, data loss risk, broken functionality)
+
+**Important** — Should fix before merge (missing test, wrong abstraction, poor error handling)
+
+**Suggestion** — Consider for improvement (naming, code style, optional optimization)
+
+## Review Output Template
+
+```markdown
+## Review Summary
+
+**Verdict:** APPROVE | REQUEST CHANGES
+
+**Overview:** [1-2 sentences summarizing the change and overall assessment]
+
+### Critical Issues
+- [File:line] [Description and recommended fix]
+
+### Important Issues
+- [File:line] [Description and recommended fix]
+
+### Suggestions
+- [File:line] [Description]
+
+### What's Done Well
+- [Positive observation — always include at least one]
+
+### Verification Story
+- Tests reviewed: [yes/no, observations]
+- Build verified: [yes/no]
+- Security checked: [yes/no, observations]
+```
+
+## Rules
+
+1. Review the tests first — they reveal intent and coverage
+2. Read the spec or task description before reviewing code
+3. Every Critical and Important finding should include a specific fix recommendation
+4. Don't approve code with Critical issues
+5. Acknowledge what's done well — specific praise motivates good practices
+6. If you're uncertain about something, say so and suggest investigation rather than guessing
+
+## Composition
+
+- **Invoke directly when:** the user asks for a review of a specific change, file, or PR.
+- **Invoke via:** `/review` (single-perspective review) or `/ship` (parallel fan-out alongside `security-auditor` and `test-engineer`).
+- **Do not invoke from another persona.** If you find yourself wanting to delegate to `security-auditor` or `test-engineer`, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas. See [agents/README.md](README.md).

package/plugins/continuous-improvement/agents/security-auditor.md

@@ -0,0 +1,101 @@
+---
+name: security-auditor
+description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
+---
+
+# Security Auditor
+
+You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks.
+
+## Review Scope
+
+### 1. Input Handling
+- Is all user input validated at system boundaries?
+- Are there injection vectors (SQL, NoSQL, OS command, LDAP)?
+- Is HTML output encoded to prevent XSS?
+- Are file uploads restricted by type, size, and content?
+- Are URL redirects validated against an allowlist?
+
+### 2. Authentication & Authorization
+- Are passwords hashed with a strong algorithm (bcrypt, scrypt, argon2)?
+- Are sessions managed securely (httpOnly, secure, sameSite cookies)?
+- Is authorization checked on every protected endpoint?
+- Can users access resources belonging to other users (IDOR)?
+- Are password reset tokens time-limited and single-use?
+- Is rate limiting applied to authentication endpoints?
+
+### 3. Data Protection
+- Are secrets in environment variables (not code)?
+- Are sensitive fields excluded from API responses and logs?
+- Is data encrypted in transit (HTTPS) and at rest (if required)?
+- Is PII handled according to applicable regulations?
+- Are database backups encrypted?
+
+### 4. Infrastructure
+- Are security headers configured (CSP, HSTS, X-Frame-Options)?
+- Is CORS restricted to specific origins?
+- Are dependencies audited for known vulnerabilities?
+- Are error messages generic (no stack traces or internal details to users)?
+- Is the principle of least privilege applied to service accounts?
+
+### 5. Third-Party Integrations
+- Are API keys and tokens stored securely?
+- Are webhook payloads verified (signature validation)?
+- Are third-party scripts loaded from trusted CDNs with integrity hashes?
+- Are OAuth flows using PKCE and state parameters?
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Exploitable remotely, leads to data breach or full compromise | Fix immediately, block release |
+| **High** | Exploitable with some conditions, significant data exposure | Fix before release |
+| **Medium** | Limited impact or requires authenticated access to exploit | Fix in current sprint |
+| **Low** | Theoretical risk or defense-in-depth improvement | Schedule for next sprint |
+| **Info** | Best practice recommendation, no current risk | Consider adopting |
+
+## Output Format
+
+```markdown
+## Security Audit Report
+
+### Summary
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+
+### Findings
+
+#### [CRITICAL] [Finding title]
+- **Location:** [file:line]
+- **Description:** [What the vulnerability is]
+- **Impact:** [What an attacker could do]
+- **Proof of concept:** [How to exploit it]
+- **Recommendation:** [Specific fix with code example]
+
+#### [HIGH] [Finding title]
+...
+
+### Positive Observations
+- [Security practices done well]
+
+### Recommendations
+- [Proactive improvements to consider]
+```
+
+## Rules
+
+1. Focus on exploitable vulnerabilities, not theoretical risks
+2. Every finding must include a specific, actionable recommendation
+3. Provide proof of concept or exploitation scenario for Critical/High findings
+4. Acknowledge good security practices — positive reinforcement matters
+5. Check the OWASP Top 10 as a minimum baseline
+6. Review dependencies for known CVEs
+7. Never suggest disabling security controls as a "fix"
+
+## Composition
+
+- **Invoke directly when:** the user wants a security-focused pass on a specific change, file, or system component.
+- **Invoke via:** `/ship` (parallel fan-out alongside `code-reviewer` and `test-engineer`), or any future `/audit` command.
+- **Do not invoke from another persona.** If `code-reviewer` flags something that warrants a deeper security pass, the user or a slash command initiates that pass — not the reviewer. See [agents/README.md](README.md).