git:20260906.3e80e82 to git:20260906.fca30a4

1 added, 1 removed. Audit A to A.

# continuous-improvement

- > The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.

+ > The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.

## What This Is

The persistent-memory and discipline layer for AI coding agents. It carries the corrections Claude has already received from one session into the next, grounds each edit in real facts before it lands, and learns from every session so its competence compounds over time — research, plan, execute one thing at a time, verify, reflect, iterate, learn — building behavioral instincts via the Mulahazah learning system, so the same correction never has to be given twice and each run starts smarter than the last. Orchestration tools run a task; this is the layer that makes the lessons survive the run.

Why these seven: every red flag an agent says ("this should work", "I'll remember", "next time I'll") is a wish standing in for a check. The Laws are one old sentence turned into checks an agent can run on itself: the wise one takes account of himself and works for what comes after; the weak one follows his impulse and merely wishes (Jami` at-Tirmidhi 2459). Before saying done: did I check, or did I hope? Sources and the mapping to each Law: docs/philosophy.md.

What the gate can and cannot do: hooks/gateguard.mjs denies the first Edit/Write/MultiEdit per file until a four-item fact list is presented and the printed clear command is run (honor system, 50 files per session); destructive Bash on a fixed blocklist is denied on every call with no clearance route; Bash file writes are not gated. Goal-drift warns by default (CLAUDE_GOAL_DRIFT_GATE=block to refuse), typecheck gate and recall briefing are opt-in.

Smarter models do not retire this product. Planning etiquette and "remember to verify" reminders merge into the model over time. The runtime gate, this-repo memory, and proof that a change worked do not. Keep goal-driven execution plus research / verify / learn guardrails; retire scaffolding when the native harness covers it (see skills/model-forward.md).

How you actually benefit:

1. Beginner install (or `npx continuous-improvement install`) — gateguard fires on Edit/Write; no prompt prefix required.

2. After a real session run `/seven-laws` — capture is silent; instincts form when you close the loop. `/recall` for "have I hit this before?". `/planning-with-files` writes `task_plan.md`.

3. Expert mode for MCP tools, `/harvest`, `/distill`, and optional `CLAUDE_RECALL_BRIEFING=1`. Empty harvest/distill on day 1 means missing observation history, not a broken command.

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