Quick start

Inside Claude Code — two commands, no Node, no bash:

/plugin marketplace add naimkatiman/continuous-improvement
/plugin install continuous-improvement@continuous-improvement

If you don't know which to pick, use Beginner. That is the install above — enough for ~90% of users. Want the MCP server, observation hooks, and instinct packs too? See Expert install below.

Verify it is live: run /discipline in Claude Code and you should see the 7 Laws card. (Commands load on session start — if it is not recognized, restart Claude Code once.)

What this is not: a prompt template, a CLAUDE.md, or a vibes-based reminder. It is a runtime hook (hooks/gateguard.mjs) plus a bundled skill set that makes the agent ground every change in real facts — it physically blocks Edit / Write / destructive Bash until the investigation is done, so edits land on understanding instead of guesses.

What this does

Claude Code is powerful but leaves intelligence on the table: it edits before reading, guesses instead of checking, stacks five concerns into one commit, and says "done" without running tests. Continuous Improvement adds three layers that make it sharper:

Before an edit — gateguard ships as a PreToolUse hook (hooks/gateguard.mjs) that physically blocks Edit / Write / MultiEdit and destructive Bash until the agent presents a fact-list investigation.
During work — bundled skills enforce planning, one-thing-at-a-time execution, TDD (tdd-workflow), and a six-phase verification ladder (verification-loop) before "done".
After work — /seven-laws reflection plus the Mulahazah instinct engine capture lessons, and the opt-in recall-briefing hook resurfaces the most relevant past fix on the next related prompt, so the same mistake does not repeat next session.

See it in action

Without Continuous Improvement, "fix the login redirect bug" looks like this:

Claude edits Login.tsx, LoginForm.tsx, useAuth.ts, authRouter.ts, redirects.ts, and useNavigate.ts — six files, no plan, no investigation. Says "done". The redirect still loops. You roll back six files.

With Continuous Improvement, the same prompt is forced through the gate:

gateguard blocks the first Edit until Claude presents a fact list. Claude reads useAuth.ts, finds the existing redirectAfterLogin helper, traces why the redirect loops (a stale from query param), and edits one line in one file. verification-loop runs the tests. The reply names the file, the line, the cause.

Same agent. Same model. Different intelligence.

The 7 Laws

#	Law	What it gives the agent
1	Research Before Executing	builds on what already exists instead of reinventing it
2	Plan Is Sacred	lands effort on the goal with success defined up front
3	One Thing at a Time	ships each change on a known-good base
4	Verify Before Reporting	backs every "done" with evidence you can trust
5	Reflect After Sessions	turns each session into a captured lesson
6	Iterate One Change	keeps debugging isolated and the signal clean
7	Learn From Every Session	compounds knowledge so next week's agent is sharper

Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate

Full spec, reflection-block format, and anti-examples: SKILL.md. Full Law-to-tool alignment matrix: CONTRIBUTING.md § Law Coverage Matrix.

Install

Beginner (recommended) is the two-command Quick start above — the 7 Laws skill, the hooks that enforce it, and the slash commands. Nothing else to install.

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:

/plugin install superpowers@continuous-improvement

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.

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:

Edit a new file scratch.txt and put the word "hello" in it. Don't research anything first.

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.)

The 7 Laws are enforced at two layers:

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. 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. A second runtime hook, goal-drift-stop (hooks/goal-drift-stop.mjs), fires on Stop: it scores each turn against the stated ## Goal and, on a substantive wrap-up that has drifted off-goal, warns by default (or re-prompts under CLAUDE_GOAL_DRIFT_GATE=block) — so a drifted session can't quietly declare "done". Fail-open.
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.

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.

Pick this if you want the MCP tools (19 of them, including ci_plan_init / ci_plan_status for task_plan.md-style planning), the session hooks that feed Mulahazah, and starter packs.

Precondition: Node 18 / 20 / 22. Observation and session hooks execute Node directly, so Git Bash and jq are not required. Re-run the installer once after upgrading to migrate installer-owned observe.sh and session.sh rows to the Node entrypoints.

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.

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. When you run the npx installer, it makes one throttled, fail-open read of the public npm registry and prints a one-line notice if a newer version is published (no telemetry — nothing about you is sent). Silence it with CLAUDE_CI_UPDATE_CHECK=off.

Three failures account for nearly every install support thread. Try them in order:

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
Hooks report Bash path errors after upgrading	Stale installer-owned `observe.sh` or `session.sh` rows remain in `settings.json`	Re-run `npx continuous-improvement install --mode expert`; the installer migrates those rows to Node and preserves foreign hooks
`/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

If none of those apply, paste the output of npx continuous-improvement install into a GitHub issue — that surface logs every step.

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).
`CLAUDE_GOAL_DRIFT_GATE`	`goal-drift-stop.mjs` (a `Stop` hook) scores each turn's activity against the `## Goal` in `task_plan.md` and acts on drift. `warn` (default) prints a one-line stderr notice and never blocks; `block` re-prompts a substantive wrap-up that has drifted off-goal so the goal gates the close; `off` disables it. Reads the same observation feed as Mulahazah; fails open on any error.	bash/zsh: `export CLAUDE_GOAL_DRIFT_GATE=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_GOAL_DRIFT_GATE='block'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_GOAL_DRIFT_GATE','block','User')` (persistent).
`CLAUDE_TYPECHECK_GATE`	`hooks/typecheck-stop.mjs` (a `Stop` hook) runs the project typecheck (the `typecheck` npm script, else a local `tsc --noEmit`) on changed TS files at turn end and feeds a failure back to the model. `off` (default) is a no-op — the global advisory `typecheck-changed.sh` stays the default layer; `warn` prints a one-line stderr notice; `block` re-prompts with the tsc output so a headless/autonomous `-p` loop fixes its own type errors before ending the turn. Skips non-TS repos and turns where no TS file changed; fails open on any error or timeout.	bash/zsh: `export CLAUDE_TYPECHECK_GATE=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_TYPECHECK_GATE='block'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_TYPECHECK_GATE','block','User')` (persistent).
`CLAUDE_RECALL_BRIEFING=1`	`hooks/recall-briefing.mjs` (a UserPromptSubmit hook) makes episodic memory proactive: on the first substantive prompt of a session it searches this project's past observations (BM25) and injects a one-time `<system-reminder>` with the most relevant prior activity, so the agent reuses a past fix instead of re-deriving it. Opt-in and default off; it is an amplifier, never a gate — it cannot block a prompt and fails open. The `ci_recall` MCP tool stays available for explicit, deeper searches.	bash/zsh: `export CLAUDE_RECALL_BRIEFING=1` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_RECALL_BRIEFING=1` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_RECALL_BRIEFING','1','User')` (persistent).
`CLAUDE_WORKFLOW_DISTILL_NUDGE=on`	`hooks/workflow-distill.mjs` (a `Stop` hook) closes the orchestration-to-memory loop: when a native Workflow run's output then passed a verify in the same session, it prints a one-line stderr nudge to run the `ci_distill_from_workflow` MCP tool, so an expensive multi-agent run leaves a durable Mulahazah draft instinct instead of evaporating. `on` enables it; default (unset or any other value) is off. Opt-in amplifier, never a gate — it cannot block the Stop, dedupes per run, and fails open.	bash/zsh: `export CLAUDE_WORKFLOW_DISTILL_NUDGE=on` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_WORKFLOW_DISTILL_NUDGE='on'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_WORKFLOW_DISTILL_NUDGE','on','User')` (persistent).
`CLAUDE_QUERY_COST_NUDGE=on`	`hooks/query-cost-nudge.mjs` (a `Stop` hook) guards against surprise DB bills: when the working tree has changed DB/query files (`.sql`, `.prisma`, `migrations/`, `/db/`, `schema.*`, `drizzle`) at turn end, it injects a once-per-session `additionalContext` reminder to run a D1-aware cost audit — dispatch the `database-reviewer` agent or check EXPLAIN QUERY PLAN, index coverage, N+1, and D1 `rows_read` billing before finishing. `on` enables it; default (unset) is off. Opt-in amplifier, never a gate; dedupes per session and fails open.	bash/zsh: `export CLAUDE_QUERY_COST_NUDGE=on` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_QUERY_COST_NUDGE='on'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_QUERY_COST_NUDGE','on','User')` (persistent).

Claude Code gets the full install (hooks, MCP server, instinct learning). Every other agent platform can still run the 7 Laws as a rules file — one flag writes the skill text into the file that platform reads, at your project root:

npx continuous-improvement install --target gemini,codex

Target	File written
`gemini`	`GEMINI.md` (Gemini CLI context file)
`codex`	`AGENTS.md` (agents.md standard — also read by opencode, Jules, Cursor ≥0.50)
`cursor`	`.cursor/rules/continuous-improvement.mdc` (`alwaysApply: true`)
`windsurf`	`.windsurf/rules/continuous-improvement.md`
`zed`	`.rules`
`aider`	`CONVENTIONS.md` + a minimal `.aider.conf.yml` if none exists
`copilot`	`.github/copilot-instructions.md`

Shared files (GEMINI.md, AGENTS.md, .rules, CONVENTIONS.md, copilot-instructions.md) are merged through a managed marker block — your existing content is preserved and reinstalls are idempotent. Targets can be combined freely (--target claude,gemini,codex runs the full Claude Code install plus the rules files).

Who this is for

Use this if you:

ship from real repositories with real consequences
have been bitten by an agent that edits before understanding
want tests, builds, or healthchecks to pass before "done"
want lessons from yesterday to survive into today

Skip it if you:

only do one-off prompts (no edits, no commits)
do not use Claude Code
dislike any friction before agent edits
want a prompt template, not a runtime gate

(The runtime gate is hooks/gateguard.mjs; full mechanics in How enforcement works above.)

The problem this solves

You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern. Matt Pocock's Skills For Real Engineers names four root failure modes that account for nearly every "the agent didn't help" complaint; the 7 Laws of AI Agent Discipline catch those four at the tool-call boundary plus a fifth that only shows up across sessions.

#	Failure mode	What you see	Which Law fires	What enforces it
1	Misalignment	The agent doesn't do what you want — invents requirements, reinvents helpers that already exist, or builds the wrong thing before anyone challenged the idea	Law 1 (Research)	`roast`, `grill-me`, `grill-with-docs`, `gateguard`, `workspace-surface-audit`
2	No shared language	The agent uses 20 words where 1 would do; jargon decoded fresh every session; variable names drift from domain terms	Law 2 (Plan), Law 7 (Learn)	`grill-with-docs` (writes & maintains `CONTEXT.md`), `token-budget-advisor`, `strategic-compact`
3	No feedback loop	The code doesn't work — agent claims "done" without running build, tests, or healthcheck	Law 4 (Verify)	`tdd-workflow`, `verification-loop`, `deploy-receipt`
4	Design rot	Ball-of-mud accelerates — agent bundles three concerns into one PR, stacks untested changes, ignores prior architectural decisions	Law 2 (Plan), Law 3 (One Thing)	`superpowers:writing-plans`, `safety-guard`, `worktree-safety`, `wild-risa-balance`
5	Forgotten lessons	Next session starts from zero — prior corrections, decisions, instincts are lost; the same mistake repeats next week	Law 5 (Reflect), Law 7 (Learn)	`handoff`, Mulahazah instinct engine

Three of those alignment + reflection skills (grill-me, grill-with-docs, handoff) are MIT-licensed ports from mattpocock/skills; the rest are continuous-improvement-native. Every failure mode has at least one runtime hook or model-side skill that catches it before it lands in the diff.

Mulahazah: auto-leveling learning

Hooks capture every tool call. After ~20 observations Claude analyzes patterns and creates instincts with confidence scores: silent below 0.5, suggested at 0.5–0.69, auto-applied at 0.7+. Corrections drop confidence by 0.1; unused instincts decay. Project-scoped; promoted to global after seen across 2+ projects. You configure nothing.

Slash commands

/seven-laws is the canonical reflect-and-learn command. /continuous-improvement is kept as an alias for backward compatibility — both run the same workflow.

/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
/roast                            5-persona adversarial council — GO / RESHAPE / KILL on an idea
/grill-me                         Interview-mode alignment (one question at a time)
/grill-with-docs                  Grill-me with persistent outcomes — updates CONTEXT.md + ADRs inline
/intent-driven-development        Scope an ambiguous change into verifiable acceptance criteria
/planning-with-files              Create task_plan.md, findings.md, progress.md
/goal-check                       Score recent activity against the task_plan.md goal (drift detector)
/reconcile                        Establish git ground truth before any mutation; verify a push landed
/audit                            Audit recent commits for real defects, confirm each before fixing
/ship                             Single-defect fast path — reconcile, TDD fix, verify, one PR
/production-readiness-review      Parallel readiness gate — severity-ranked punch-list (reports only)
/simplicity-review                Judge the current diff for over-engineering (GO / TRIM, reports only)
/handoff                          End-of-session compaction into mktemp brief for the next agent
/recall                           BM25 search over past observations — "have I hit this before?"
/discipline                       Quick reference card of the 7 Laws
/model-forward                    Restate the model-forward stance — go with the model, not against it
/verify-install                   One-shot post-install check — commands, gateguard, observe
/dashboard                        Visual instinct health dashboard
/companion-preference             Inspect companion-preference hook telemetry
/ralph                            Autonomous PRD story-by-story loop
/learn-eval                       Capture session patterns into new skills (needs observation history)
/harvest                          Extract reusable patterns from session friction (needs observation history)
/distill                          Distill repeated successful sequences into draft instincts (needs observation history)
/release-train                    Coordinate a multi-PR release sequence
/swarm                            Fan-out coordination across parallel sub-agents

All 29 ship in the marketplace bundle. The Beginner install gets all of them — with one caveat: /learn-eval, /harvest, and /distill only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. /swarm and /release-train are orchestration commands aimed at larger multi-agent or multi-PR work. 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).

Skills

The plugin ships 28 skills — 1 core + 1 featured + 6 tier-1 + 17 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: docs/skills.md. Adding a 29th skill: CONTRIBUTING.md § Evolution — adding a new skill.

GitHub Action: Transcript Linter

Lint agent behavior in CI. Detects skipped laws.

- uses: naimkatiman/continuous-improvement@v3
  with:
    transcript-path: agent-log.jsonl
    strict: true

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>. The @v3 floating-tag retarget policy lives in CONTRIBUTING.md § Release.

Portfolio spine

Two standalone commands turn a multi-repo portfolio into scored, auditable evidence. Both are offline: they read local files only, no network.

ci-audit-actions — static GitHub Actions security scan. Flags missing/over-broad permissions:, unpinned actions, missing job timeouts, missing concurrency, untrusted event text interpolated into run:, and dangerous triggers combined with secrets. Writes a markdown report; --strict exits 1 on high-severity findings.

npx -p continuous-improvement ci-audit-actions --repo . --out reports/actions-security.md --strict

ci-portfolio-health — scores every repo in a portfolio/repos.json registry 0-100 from local proof signals (CI presence, release receipts, experiment records, commit freshness, high-severity audit findings) and writes a worst-first table with a named next action per repo.

npx -p continuous-improvement ci-portfolio-health --config portfolio/repos.json --out reports/portfolio-health.md

Proof-format templates ship in templates/: release_receipt_template.md, experiment_template.md, actions_security_checklist.md, and portfolio_event.schema.json.

QUICKSTART.md — 2-minute setup
SKILL.md — full 7 Laws spec
docs/skills.md — full 28-skill catalog
examples/ — bug fix, feature build, refactor walkthroughs
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 — architecture, repo internals, adding a new skill
SECURITY.md

Uninstall

npx continuous-improvement install --uninstall

Removes skill, hooks, commands, MCP server. Learned instincts in ~/.claude/instincts/ are preserved — delete manually for a clean slate.

The brand stack

One product, three names. Use the one that fits the audience:

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`

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.

In the wild

Workflows from this repo, applied to real open-source contributions:

pm-skills (product-on-purpose, Apache 2.0) — F-07 discover-market-sizing, a new domain skill in the Discover phase covering TAM/SAM/SOM market sizing for the 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.

MIT.

Continuous Improvement

README