continuous-improvement 3.1.0 → 3.8.0

package/llms.txt

@@ -1,43 +1,68 @@
-# continuous-improvement
-
-> The 7 Laws of AI Agent Discipline — stop your agent from skipping steps, guessing, and declaring "done" without verifying.
-
-## 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.
-
-## 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 and what failed
-6. Iterate One Change — one change, verify, then next
-7. Learn From Every Session — patterns become instincts
-
-## 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
-
-## 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)
-
-## 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,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.8.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, 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,27 @@
   },
   "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: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"
   },
   "files": [
+    ".claude-plugin/",
     "SKILL.md",
     "QUICKSTART.md",
     "CHANGELOG.md",
@@ -54,10 +56,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.8.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.8.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.8.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,56 @@
+# 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/`
+- `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/bin/backfill.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// backfill.mts — Tag legacy thin-schema observation rows for skip-clean
+// consumption by the analysis pass.
+//
+// Walks ~/.claude/instincts/<hash>/observations.jsonl files and writes a
+// `schema: "thin" | "rich"` field on every row that doesn't already have one.
+// Per the plan doc: this is a flag-pass, not a content-recovery — the original
+// thin rows lack the input we'd need to fabricate richer fields. Tagging lets
+// the analysis pass cleanly skip thin rows and surface a "X% of observations
+// were thin" stat to operators so they understand why their auto-instinct
+// pipeline historically produced nothing.
+//
+// Output:
+//   - <home>/.claude/instincts/<hash>/observations.jsonl   (rewritten in place
+//     with schema field appended; original preserved as .bak)
+//   - <home>/.claude/instincts/backfill-summary.json       (per-project digest)
+//
+// Flags:
+//   --dry-run  Read everything, write nothing; print counts to stdout.
+//
+// Idempotent: re-running on already-tagged rows is a no-op.
+// Exit code: always 0. Failures land on stderr only.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes("--dry-run");
+const HELP = args.includes("--help") || args.includes("-h");
+if (HELP) {
+    console.log(`
+backfill — Tag legacy thin-schema observation rows.
+
+Usage:
+  npx continuous-improvement backfill            Tag rows in place
+  npx continuous-improvement backfill --dry-run  Report counts, write nothing
+
+What it does:
+  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
+  schema field ("thin" or "rich") to every row that lacks one. Thin rows
+  came from the legacy bash fallback (jq missing) and have no input_summary;
+  rich rows came from the Node observer and have full tool_input.command /
+  Edit.file_path / etc.
+
+Output:
+  - observations.jsonl rewritten in place (original kept as .bak)
+  - backfill-summary.json with per-project counts
+
+Idempotent. Always exits 0 — failures go to stderr only.
+`);
+    process.exit(0);
+}
+main();
+function main() {
+    try {
+        runBackfill();
+    }
+    catch (error) {
+        process.stderr.write(`[backfill] ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    process.exit(0);
+}
+function runBackfill() {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    const instinctsDir = join(home, ".claude", "instincts");
+    if (!existsSync(instinctsDir)) {
+        if (!DRY_RUN)
+            mkdirSync(instinctsDir, { recursive: true });
+        return;
+    }
+    const projectDirs = listProjectDirs(instinctsDir);
+    const summary = {
+        total: 0,
+        thin: 0,
+        rich: 0,
+        projects: {},
+        generated_at: new Date().toISOString(),
+    };
+    for (const dir of projectDirs) {
+        const obsFile = join(dir, "observations.jsonl");
+        if (!existsSync(obsFile))
+            continue;
+        const projectId = basename(dir);
+        const stat = { total: 0, thin: 0, rich: 0 };
+        const newLines = [];
+        const corruptLines = [];
+        let mutated = false;
+        const raw = readFileSync(obsFile, "utf8");
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            let row;
+            try {
+                row = JSON.parse(trimmed);
+            }
+            catch {
+                process.stderr.write(`[backfill] skipped corrupt row in ${projectId}: ${trimmed.slice(0, 80)}\n`);
+                // Drop from main file but preserve in observations.corrupt.jsonl
+                // so the operator never silently loses data.
+                corruptLines.push(trimmed);
+                mutated = true;
+                continue;
+            }
+            stat.total++;
+            summary.total++;
+            const previousSchema = row.schema;
+            const isRich = typeof row.input_summary === "string" && row.input_summary.length > 0;
+            const newSchema = isRich ? "rich" : "thin";
+            if (previousSchema !== newSchema) {
+                row.schema = newSchema;
+                mutated = true;
+            }
+            if (newSchema === "thin") {
+                stat.thin++;
+                summary.thin++;
+            }
+            else {
+                stat.rich++;
+                summary.rich++;
+            }
+            newLines.push(JSON.stringify(row));
+        }
+        summary.projects[projectId] = stat;
+        if (mutated && !DRY_RUN) {
+            // Atomic-ish write: backup → write → keep .bak for one cycle.
+            const backup = obsFile + ".bak";
+            renameSync(obsFile, backup);
+            writeFileSync(obsFile, newLines.join("\n") + "\n", "utf8");
+            if (corruptLines.length > 0) {
+                // Quarantine corrupt rows so operator data is never silently lost.
+                const corruptFile = join(dir, "observations.corrupt.jsonl");
+                const existing = existsSync(corruptFile) ? readFileSync(corruptFile, "utf8") : "";
+                writeFileSync(corruptFile, existing + corruptLines.join("\n") + "\n", "utf8");
+            }
+        }
+    }
+    if (DRY_RUN) {
+        process.stdout.write(formatReport(summary, true));
+        return;
+    }
+    const summaryPath = join(instinctsDir, "backfill-summary.json");
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + "\n", "utf8");
+    process.stdout.write(formatReport(summary, false));
+}
+function listProjectDirs(instinctsDir) {
+    // Real project-hash dirs are sha256[:12] (hex). Test fixtures use 12-char
+    // alpha labels (g/h/i are not hex but make tests readable). Both are
+    // matched here; the broader pattern is harmless because real instincts/
+    // sub-dirs only ever contain hex hashes plus 'global' / loose dotfiles.
+    return readdirSync(instinctsDir)
+        .filter((name) => /^[0-9a-z]{12}$/.test(name))
+        .map((name) => join(instinctsDir, name))
+        .filter((dir) => {
+        try {
+            return statSync(dir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function formatReport(summary, isDryRun) {
+    const projects = Object.keys(summary.projects);
+    const lines = [
+        isDryRun ? "[backfill --dry-run] would tag the following:" : "[backfill] tagged:",
+        `  total rows: ${summary.total}`,
+        `  thin rows:  ${summary.thin}`,
+        `  rich rows:  ${summary.rich}`,
+        `  projects:   ${projects.length}`,
+    ];
+    return lines.join("\n") + "\n";
+}