Continuous Improvement

The problem this solves

You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern.

Every one of those failures is the agent skipping a step a disciplined engineer would not skip. The 7 Laws of AI Agent Discipline names each step, gives it a hook or a skill that enforces it, and feeds the captured patterns back into the agent so the same mistake gets harder to repeat next session.

What you get

• A 7-step discipline the agent must follow every task — research → plan → execute one thing → verify → reflect → learn → iterate. Each Law has at least one skill or hook that enforces it.
• 13 bundled skills that turn the Laws from a doc into runtime behavior — gateguard blocks unverified Edit/Write/destructive Bash, tdd-workflow enforces RED → GREEN → REFACTOR, verification-loop runs build/types/tests/security before "done", proceed-with-the-recommendation walks any agent's recommendation list top-to-bottom with per-item verification.
• Mulahazah, the auto-leveling instinct engine — hooks capture every tool call; after ~20 observations the agent analyzes patterns and creates instincts with confidence scores. Suggestions appear at 0.5+, auto-apply at 0.7+, decay when ignored. Project-scoped, promote to global after 2+ projects. You configure nothing.
• A GitHub Action transcript linter that catches skipped Laws in CI — writes without prior research, edits without verification, too many files at once.
• Two install paths — Beginner is two slash commands inside Claude Code (no Node, no bash, ~90% of users). Expert adds the MCP server, observation hooks, instinct packs, and the linter.

The whole thing is MIT, free, and lives in this one repo. No service, no account, no telemetry leaves your machine.

Install

If you don't know which to pick, use Beginner. It is enough for ~90% of users and adds no Node or bash dependency.

Beginner — inside Claude Code, two commands

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-improvement

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

Expert — adds MCP server, observation hooks, and instinct packs

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, plus bash on Windows (Git Bash or WSL — hooks/observe.sh is a bash script and silently no-ops without it). jq is no longer required: as of v3.6.0, observe.sh prefers the Node observer (bin/observe.mjs) which writes the rich event schema natively without external dependencies. The bash thin-schema path is kept as a two-phase shim, so legacy installs that have not re-run npx continuous-improvement install since v3.5.x will still degrade silently without jq (winget install jqlang.jq on Windows, brew install jq on macOS, apt install jq on Debian/Ubuntu) — re-running the installer is the cleaner fix and removes the dependency entirely. See CHANGELOG.md [3.6.0] for the migration details.

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.

Troubleshooting install

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

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

Operator modes

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.

The 7 Laws

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

Full spec, reflection-block format, and anti-examples: SKILL.md.

Mulahazah: Auto-Leveling Learning

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

Slash Commands

/seven-laws                       Reflect, analyze, show status (brand-aligned name)
/continuous-improvement           Same workflow as /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
/planning-with-files              Create task_plan.md, findings.md, progress.md
/discipline                       Quick reference card of the 7 Laws
/dashboard                        Visual instinct health dashboard
/ralph                            Autonomous PRD story-by-story loop (expert)
/learn-eval                       Capture session patterns into new skills (expert)

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

Law Coverage

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.

All 13 Skills

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.

The orchestrator skill proceed-with-the-recommendation also routes to optional companion skills from external plugins (e.g. obra/superpowers, code-review, frontend-design, commit-commands). Each routing target has an inline fallback in the orchestrator, so the plugin works on a clean install with nothing else present — install the dedicated companion only when you want a specialist over the fallback. Full target list with source-plugin and risk-if-absent: plugins/continuous-improvement/README.md § Required vs Optional companions.

Beginner gets — by default

Tier 1 + featured + companion. Auto-installed when you run the plugin install commands above. No flags, no choices.

Expert gets — additionally

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.

Drop-in single-file install

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

Evolution — adding a new skill

Drop one .md file into skills/, run npm run build, and the plugin bundle, manifests, and bundled-skills README regenerate from that source. Seven lints (verify:all + verify:generated) block the merge if anything drifts.

The 5-step recipe

# 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"

What the build does for you automatically

• Mirrors source → bundle (bin/generate-plugin-manifests.mjs): copies skills/<name>.md to plugins/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)

What the lints enforce so you cannot ship a half-wired skill

When to fold a new external skill into the 7 Laws

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.

What is not automated (the honest limits)

• 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 → 1 after it proves itself) is a manual edit to the frontmatter tier: field, by design — the maintainer should make that call deliberately.

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

@v3 is a floating major-version tag that retargets on every v3.x.y release. Pin to a specific tag (@v3.7.0) if you need byte-reproducible CI; use @v3 to ride patch and minor bumps automatically. See CONTRIBUTING.md § Release for the retarget policy.

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

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:

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, 189 stars, Apache 2.0)

F-07 discover-market-sizing - 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 (lint-skills-frontmatter, validate-agents-md, validate-commands, check-count-consistency, check-nav-completeness, check-generated-content-untouched, check-generated-freshness, validate-meeting-skills-family, validate-plugin-install).

More

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