Stop your Claude Code agent from skipping steps, guessing, and declaring "done" without verifying.
New here? → QUICKSTART.md (2 minutes)
If you don't know which to pick, use Beginner. It is enough for ~90% of users and adds no Node or bash dependency.
You get the 7 Laws skill, the hooks that enforce it, and the slash commands. Nothing else to install.
# Inside Claude Code (no shell needed)
/plugin marketplace add naimkatiman/continuous-improvement
/plugin install continuous-improvement@continuous-improvementThe doubled name is correct: it reads as <plugin>@<marketplace>.
Verify: run /discipline in Claude Code — you should see the 7 Laws card.
If the command is not recognized, restart your Claude Code session first; the marketplace did pick the plugin up but commands load on session start.
Pick this if you want the MCP tools (12 of them, including ci_plan_init / ci_plan_status for task_plan.md-style planning), the session hooks that feed Mulahazah, and starter packs.
Preconditions: Node 18 / 20 / 22, bash, and jq. On Windows, install Git Bash or WSL first — the observation hooks are bash scripts and will silently no-op without them. Install jq too (winget install jqlang.jq on Windows, brew install jq on macOS, apt install jq on Debian/Ubuntu) — without it, observe.sh falls back to a thin schema that the Mulahazah analysis pass cannot turn into instincts. The hook itself still runs and exits 0, but the captured rows lack tool_input so pattern detection produces nothing. See the Known Issues section in CHANGELOG.md for the full gap description.
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.
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 |
| Expert mode hooks never fire on Windows | observe.sh is bash; PowerShell silently no-ops on it |
Install Git Bash (or WSL) and re-run npx continuous-improvement install --mode expert |
/plugin marketplace add ... returned nothing visible |
Marketplace add was silent; the plugin is not yet selected | Run /plugin install continuous-improvement@continuous-improvement to select and activate it |
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). |
| # | Law | Without it, agents... |
|---|---|---|
| 1 | Research Before Executing | reinvent what already exists |
| 2 | Plan Is Sacred | scope-creep and overbuild |
| 3 | One Thing at a Time | stack untested changes |
| 4 | Verify Before Reporting | lie about being "done" |
| 5 | Reflect After Sessions | repeat the same failures |
| 6 | Iterate One Change | debug 5 changes at once |
| 7 | Learn From Every Session | lose knowledge when context ends |
Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
Full spec, reflection-block format, and anti-examples: SKILL.md.
Hooks capture every tool call. After ~20 observations, Claude analyzes patterns and creates instincts with confidence scores:
- < 0.5 silent (stored, not surfaced)
- 0.5–0.69 suggested inline when relevant
- 0.7+ auto-applied
- User corrections drop confidence by 0.1; unused instincts decay
- Project-scoped, promoted to global after seen across 2+ projects
/seven-laws Reflect, analyze, show status (brand-aligned name)
/continuous-improvement Same workflow as /seven-laws (kept for backward compat)
/planning-with-files Create task_plan.md, findings.md, progress.md
/discipline Quick reference card of the 7 Laws
/dashboard Visual instinct health dashboard
In expert mode, the same planning workflow is also available programmatically 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).
Every bundled skill, command, and hook enforces at least one of the 7 Laws. The full Law-to-tool alignment matrix lives in CONTRIBUTING.md → Law Coverage Matrix; each skill's description: also leads with Enforces Law N (...) so the tag shows up every time the skill is loaded. Operator-level mode toggles live in the Operator modes section above the 7 Laws, alongside install.
The plugin ships 1 core + 1 featured + 4 tier-1 + 4 tier-2 + 3 always-bundled = 13 skills. Source-of-truth lives in skills/ (one .md per skill); the plugin bundle at plugins/continuous-improvement/skills/ is regenerated by npm run build.
Show the full skill table (13 rows)
| # | Skill | Tier | Law | What it does |
|---|---|---|---|---|
| 1 | continuous-improvement |
core | — | The 7 Laws spec itself (research → plan → execute → verify → reflect → learn → iterate) |
| 2 | proceed-with-the-recommendation ⭐ |
featured | all 7 | Walks any agent's recommendation list top-to-bottom, routes each item, verifies per item, halts on needs-approval |
| 3 | gateguard |
1 | 1 | PreToolUse gate that blocks Edit/Write/destructive Bash until concrete investigation is presented |
| 4 | para-memory-files |
1 | 5 + 7 | Durable file-based memory using PARA (Projects/Areas/Resources/Archives) for cross-session context |
| 5 | tdd-workflow |
1 | 3 + 4 | RED → GREEN → REFACTOR enforcement with 80%+ coverage across unit/integration/E2E |
| 6 | verification-loop |
1 | 4 | Six-phase verification (build, types, lint, tests, security, diff) with PASS/FAIL report |
| 7 | safety-guard |
2 | 3 | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory |
| 8 | strategic-compact |
2 | 5 | Suggests /compact at logical phase boundaries instead of arbitrary auto-compaction |
| 9 | token-budget-advisor |
2 | 2 | Token estimator that offers 25/50/75/100% depth choices before answering |
| 10 | wild-risa-balance |
2 | 2 | Pairs WILD (bold) generation with RISA (safe) execution; splits recommendation lists into pilots above a baseline |
| 11 | ralph |
companion | 6 | Autonomous loop that executes a PRD story-by-story with quality checks between iterations |
| 12 | superpowers |
companion | activator | Law activator — routes tasks to the correct Law-aligned specialist so the right discipline fires automatically |
| 13 | workspace-surface-audit |
companion | 1 | Audits the active repo, MCP servers, plugins, env, then recommends high-value skills/workflows |
Tier 1 + featured + companion. Auto-installed when you run the plugin install commands above. No flags, no choices.
Tier 2 (safety-guard, strategic-compact, token-budget-advisor, wild-risa-balance), the MCP server (12 tools incl. ci_plan_init/ci_plan_status), session-observation hooks for Mulahazah, and /learn-eval for capturing session patterns into new skills.
Want one skill without the whole plugin? Copy the .md file straight into ~/.claude/skills/<name>/SKILL.md:
SKILL=proceed-with-the-recommendation
mkdir -p ~/.claude/skills/$SKILL
curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
-o ~/.claude/skills/$SKILL/SKILL.mdDrop one .md file into skills/, run npm run build, and the plugin bundle, manifests, and bundled-skills README regenerate from that source. Six lints (verify:all) block the merge if anything drifts.
# 1. Create the source file
touch skills/<your-skill>.md# 2. Frontmatter must declare name + tier + Law-tagged description
---
name: <your-skill>
tier: "1" # core | featured | "1" | "2" | companion
description: "Enforces Law N (<law name>) of the 7 Laws of AI Agent Discipline. <what it does>."
---# 3. Regenerate the bundle (also writes plugins/.../skills/<your-skill>/SKILL.md
# + the bundled-skills README, which is itself generator-output)
npm run build
# 4. Run all 6 verify lints — must all pass
npm run verify:all
# 5. Commit one concern at a time (per CLAUDE.md): the source skill alone first,
# then any wiring (hooks, commands, Law-coverage table updates) as separate commits
git add skills/<your-skill>.md plugins/continuous-improvement/skills/<your-skill>/
git commit -m "feat(skills): add <your-skill> for Law N enforcement"- Mirrors source → bundle (
bin/generate-plugin-manifests.mjs): copiesskills/<name>.mdtoplugins/continuous-improvement/skills/<name>/SKILL.md - Regenerates plugin manifests with the new skill listed in tier order
- Re-renders
plugins/continuous-improvement/skills/README.md(do not edit by hand — generator output)
| Lint | Blocks |
|---|---|
verify:skill-mirror |
source skills/<name>.md and plugins/.../<name>/SKILL.md are out of sync |
verify:skill-tiers |
skill has missing or unrecognized tier: value |
verify:skill-law-tag |
skill description does not start with Enforces Law N (or Law activator, or all 7 Laws) |
verify:docs-substrings |
README/QUICKSTART references a removed/renamed skill |
verify:everything-mirror |
everything/ reference docs drift from source |
verify:generated |
npm run build was not re-run after a source change |
A new skill is a fit if it provably enforces (or is a routed activator for) at least one of the 7 Laws. The Law-tag lint will refuse it otherwise. If it sits outside the laws (a domain skill — e.g. SQL optimization), keep it as an external plugin. The 7 Laws plugin stays disciplined about scope; that is the point.
- The Law-coverage matrix above (
## Law Coverage) is hand-maintained — add your new skill to the right Law row when you ship it. - The "All 13 Skills" count in the section header is a literal — bump it when N changes.
- Promotion between tiers (e.g.
2→1after it proves itself) is a manual edit to the frontmattertier:field, by design — the maintainer should make that call deliberately.
Lint agent behavior in CI. Detects skipped laws.
- uses: naimkatiman/continuous-improvement@v3
with:
transcript-path: agent-log.jsonl
strict: trueCatches: 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>.
npx continuous-improvement install --uninstallRemoves skill, hooks, commands, MCP server. Learned instincts in ~/.claude/instincts/ are preserved — delete manually for a clean slate.
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.
- QUICKSTART.md — 2-minute setup
- SKILL.md — full 7 Laws spec
- examples/ — bug fix, feature build, refactor walkthroughs
- CONTRIBUTING.md — architecture, repo internals
- SECURITY.md
MIT.