continuous-improvement 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to this skill are documented here.
+
+---
+
+## [2.1.0] — 2026-04-05
+
+### Changed
+- **Auto-leveling** — system promotes itself from CAPTURE → ANALYZE → SUGGEST → AUTO-APPLY based on observation count and instinct confidence. No user action needed.
+- **No background daemon** — analysis runs inline at session start. Removed start-observer.sh, observer-loop.sh, PID management.
+- **Simplified directory** — `~/.claude/instincts/` replaces `~/.claude/mulahazah/` with flat structure
+- **jq optional** — observe.sh works with pure bash fallback if jq isn't installed
+- **Leaner installer** — no daemon files copied, no config.json, no analyze.sh. Just skill + hook + command.
+- **Smaller package** — removed agents/ and config.json from published files
+
+### Removed
+- Background observer daemon (deferred to v2.2 as opt-in)
+- `~/.claude/mulahazah/` directory structure (replaced by `~/.claude/instincts/`)
+- `rules.md` (replaced by YAML instinct files with confidence scoring)
+- `bin/analyze.sh` (analysis now inline via SKILL.md prompt)
+
+---
+
+## [2.0.1] — 2026-04-05
+
+### Fixed
+- SKILL.md rewritten to be honest — removed claims about features that didn't work (YAML instinct auto-loading, graduated confidence enforcement)
+- Law 7 now uses `~/.claude/mulahazah/rules.md` — a markdown file Claude can actually read/write reliably
+- Added `bin/analyze.sh` — the actual analysis pipeline that was missing (calls Haiku to extract rules from observations)
+- Added `commands/continuous-improvement.md` — the actual `/continuous-improvement` command file
+- Installer now copies analyze.sh, command file, and initializes rules.md
+- observer-loop.sh rewritten to use analyze.sh instead of broken YAML instinct pipeline
+- README rewritten to match what the tool actually does
+
+---
+
+## [2.0.0] — 2026-04-05
+
+### Added
+- Law 7: Learn From Every Session — Mulahazah learning system
+- PreToolUse/PostToolUse hooks for session observation
+- Background Haiku observer agent for pattern detection
+- Project-scoped observation (per-project JSONL files)
+- `/continuous-improvement` command
+- `hooks/observe.sh` — lightweight observation hook (<50ms)
+- `agents/` — observer agent scripts
+- `config.json` — observer configuration
+
+### Changed
+- Upgraded from 5-phase framework to 7-Law system
+- The Loop: Research → Plan → Execute → Verify → Reflect → Learn → Iterate
+- Installer sets up Mulahazah hooks and directories for Claude Code
+
+### Improved
+- Law 6 (Iterate) now explicit — one change → verify → next change
+
+---
+
+## [1.1.0] — 2026-04-04
+
+### Improved
+- README completely rewritten for cleaner onboarding — hook first, install in 30 seconds, first-task prompt
+- Added real example of a successful agent run (rate limiting walkthrough)
+- Added QUICKSTART.md for step-by-step first-use guide
+- Added CHANGELOG.md for version tracking
+- Removed internal references from SKILL.md (now works for any user, any project)
+- Red flags section now in README for discoverability before install
+
+### Fixed
+- Fake Claude Code marketplace install command removed
+- Internal variable references (Naim, PROJECT_REGISTRY, STATE_TEMPLATE) made universal
+
+---
+
+## [1.0.0] — 2026-04-04
+
+### Added
+- Initial release
+- 5-phase framework: Research → Plan → Execute → Verify → Reflect
+- Iron Law with 3 hard constraints
+- Phase gates (explicit conditions before proceeding)
+- Red Flags list (thought patterns that indicate a skip)
+- Common Rationalizations table
+- Subagent delegation rules with 4 status handlers
+- Pre-completion self-review checklist
+- marketplace.json for plugin discoverability

package/QUICKSTART.md

@@ -0,0 +1,81 @@
+# Quickstart — continuous-improvement
+
+Zero to working in under 2 minutes.
+
+---
+
+## Step 1: Install
+
+```bash
+npx continuous-improvement install
+```
+
+This auto-detects your setup. For Claude Code, it installs the skill, hooks, and `/continuous-improvement` command.
+
+---
+
+## Step 2: Use It
+
+Give your agent a task and prefix it:
+
+```
+Use the continuous-improvement framework to [your task here].
+```
+
+Examples:
+```
+Use the continuous-improvement framework to add pagination to the users API endpoint.
+Use the continuous-improvement framework to debug why the login form breaks on mobile.
+Use the continuous-improvement framework to refactor the payment module to use the new SDK.
+```
+
+Your agent will research, plan, execute one thing at a time, verify, and reflect.
+
+---
+
+## Step 3: Check Learning
+
+After completing non-trivial work:
+
+```
+/continuous-improvement
+```
+
+This shows what the system has learned — instincts, confidence levels, and the current auto-level.
+
+---
+
+## How Auto-Leveling Works
+
+You don't configure anything. The system promotes itself:
+
+| Your usage | What happens |
+|-----------|-------------|
+| First sessions | Hooks capture tool calls silently. No behavior change. |
+| After ~20 sessions | Agent analyzes patterns, creates instincts (silent — you see nothing) |
+| After ~50 sessions | Instincts cross 0.5 → agent starts suggesting: "Consider: [action]" |
+| After ~100 sessions | Instincts cross 0.7 → agent auto-applies learned behaviors |
+
+Corrections drop instinct confidence. Unused instincts decay. The system self-corrects.
+
+---
+
+## Common Issues
+
+**Agent skips straight to coding?**
+→ Say: *"You skipped research and planning. Go back to Law 1."*
+
+**Agent writes "done" without verifying?**
+→ Reply: *"What verification command did you run? Show me the output."*
+
+**No instincts showing up yet?**
+→ Normal. The system needs 20+ observations before it creates instincts. Keep working.
+
+---
+
+## That's It
+
+The skill is most valuable when:
+- You're under pressure and tempted to skip steps
+- A task has failed 2+ times
+- You want your agent to stop repeating the same mistakes

package/README.md

@@ -1,10 +1,25 @@
+<p align="center">
+  <img src="promo/combined.gif" alt="Before vs After continuous-improvement" width="700" />
+</p>
+
 # continuous-improvement
 
-### Install discipline into your AI agent in one command.
+> Stop your AI agent from skipping steps, guessing, and declaring "done" without verifying.
+
+[![Version](https://img.shields.io/badge/version-2.1.0-blue)](CHANGELOG.md)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+---
+
+## The Problem
+
+AI agents are great at individual steps. They're terrible at discipline.
+
+They skip research. They plan loosely. They declare "done" before verifying. They add features mid-task. They never reflect. Each session, they repeat the same mistakes.
 
-AI agents are useful. They're also reckless by default.
+This skill fixes that with **7 laws** and a **learning system** that auto-levels itself — no config, no daemon, no manual setup.
 
-**continuous-improvement** makes an agent research first, plan before coding, verify before saying "done", and reflect so it stops repeating the same mistakes.
+---
 
 ## Install
 
@@ -12,164 +27,135 @@ AI agents are useful. They're also reckless by default.
 npx continuous-improvement install
 ```
 
-If auto-detect misses your setup:
+That's it. For Claude Code, this also installs:
+- Observation hooks (captures every tool call, <50ms, jq optional)
+- `/continuous-improvement` command
+- Auto-leveling instinct system
 
-```bash
-npx continuous-improvement install --claude
-npx continuous-improvement install --codex
-npx continuous-improvement install --cursor
-npx continuous-improvement install --openclaw
-npx continuous-improvement install --chatgpt
-```
-
-Optional global Claude install:
+Install to a specific target:
 
 ```bash
-npx continuous-improvement install --claude --global
+npx continuous-improvement install --target claude    # Claude Code + Mulahazah
+npx continuous-improvement install --target openclaw  # OpenClaw (skill only)
+npx continuous-improvement install --target cursor    # Cursor (skill only)
+npx continuous-improvement install --target all       # All targets
 ```
 
-## Uninstall
+### Manual install
 
 ```bash
-npx continuous-improvement uninstall --claude
-npx continuous-improvement uninstall --codex
-npx continuous-improvement uninstall --cursor
-npx continuous-improvement uninstall --openclaw
+mkdir -p ~/.claude/skills/continuous-improvement && \
+curl -fsSL -o ~/.claude/skills/continuous-improvement/SKILL.md \
+  https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/SKILL.md
 ```
 
-## What it installs
-
-Depending on your target, it does one of these:
+### Tell your agent
 
-- **Claude Code** → appends the rules to `CLAUDE.md`
-- **Codex / OpenClaw AGENTS flow** → appends the rules to `AGENTS.md`
-- **Cursor** → appends the rules to `.cursorrules`
-- **OpenClaw** → installs the local skill at `~/.openclaw/skills/continuous-improvement/`
-- **ChatGPT** → prints the exact block to paste into Custom Instructions
-
-## Use
+```
+Fetch and follow the skill at: https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/SKILL.md
+```
 
-One-shot usage is simple:
+---
 
-> Use continuous-improvement on this task: add a caching layer to my single-server API.
+## The 7 Laws
 
-A good response should come back with:
+| # | Law | What it prevents |
+|---|-----|-----------------|
+| 1 | **Research Before Executing** | Reinventing what already exists |
+| 2 | **Plan Is Sacred** | Scope creep and overbuilding |
+| 3 | **One Thing at a Time** | Stacking untested changes |
+| 4 | **Verify Before Reporting** | False "done" claims |
+| 5 | **Reflect After Sessions** | Repeating the same failures |
+| 6 | **Iterate One Change** | Debugging 5 changes at once |
+| 7 | **Learn From Every Session** | Knowledge that dies with the context window |
 
-1. **Research** — what exists, constraints, risks, simplest path
-2. **Plan** — what will be built
-3. **Anti-scope** — what will not be built
-4. **Verification** — exact checks
-5. **Fallback** — what to do if it fails
-6. **Reflection** — what to learn after execution
+### The Loop
 
-## The 7 rules
+```
+Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate
+```
 
-1. **Research before executing**
-2. **Plan before coding**
-3. **Do one thing at a time**
-4. **Verify before reporting**
-5. **Reflect after non-trivial work**
-6. **Iterate one change at a time**
-7. **Learn from every session**
+---
 
-## What's new in v1.0: Mulahazah
+## Mulahazah: Auto-Leveling Learning
 
-Mulahazah (Arabic: observation) adds instinct-based learning to the loop.
+Mulahazah (Arabic: observation) makes your agent build **instincts** over time. It levels up automatically — you don't configure anything.
 
-Agents don't just follow rules — they build instincts over time.
+```
+Install:       Hooks start capturing silently. You notice nothing.
+~20 sessions:  Agent analyzes patterns, creates first instincts (silent)
+~50 sessions:  Instincts cross 0.5 → agent starts suggesting behaviors
+~100 sessions: Instincts cross 0.7 → agent auto-applies what it learned
+```
 
-**Key features:**
+### How it works
 
-- Hooks observe every tool call (<50ms overhead)
-- Instincts carry confidence scores (0.3–0.9 range)
-- Graduated behavior: silent at low confidence, suggest at mid, auto-apply at high
-- Project scoping: instincts can be global or project-specific
-- Confidence decay: unused instincts weaken, wrong ones get corrected
+1. **Hooks capture every tool call** — PreToolUse/PostToolUse hooks write JSONL observations (<50ms, never blocks your session, jq not required)
+2. **Analysis runs inline** — when 20+ observations accumulate, Claude analyzes them at session start. No background daemon.
+3. **Instincts carry confidence** — 0.3–0.9 scale with graduated behavior:
+   - **Silent** (< 0.5) — stored, not surfaced
+   - **Suggest** (0.5–0.69) — mentioned inline when relevant
+   - **Auto-apply** (0.7+) — applied automatically
+4. **Self-correcting** — user corrections drop confidence by 0.1. Unused instincts decay. Wrong behaviors fade out.
+5. **Project-scoped** — instincts are per-project by default, promoted to global when seen across 2+ projects
 
-**One command:**
+### Check what your agent has learned
 
-```bash
+```
 /continuous-improvement
 ```
 
-**Background observer (optional):**
+---
 
-A lightweight Haiku agent watches sessions and extracts patterns automatically.
+## Files
 
-```bash
-~/.claude/mulahazah/agents/start-observer.sh
 ```
-
-## Why this exists
-
-Agents usually fail in predictable ways:
-
-- they skip docs and existing code
-- they overbuild
-- they claim success before testing
-- they pile on changes before verifying the first one
-- they repeat mistakes because nothing gets logged
-
-continuous-improvement fixes that with a tiny, reusable operating loop:
-
-```text
-Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate
+continuous-improvement/
+├── SKILL.md                    # The 7 Laws + instinct behavior
+├── commands/continuous-improvement.md  # The /continuous-improvement command
+├── hooks/observe.sh            # Observation hook (pure bash)
+├── bin/install.mjs             # CLI installer
+├── QUICKSTART.md               # First-use guide
+├── CHANGELOG.md
+└── package.json
 ```
 
-## Skill first
-
-This repo is designed as a **skill first** product:
-
-- easy to install
-- easy to invoke in one shot
-- useful before any complex task
-
-Prompt variants in `prompts/` are still here, but they are **supporting material**, not the main product.
+### What gets installed where (Claude Code)
 
-The OpenClaw skill lives in:
-
-```text
-skills/continuous-improvement/SKILL.md
+```
+~/.claude/skills/continuous-improvement/SKILL.md     # The skill
+~/.claude/commands/continuous-improvement.md          # The command
+~/.claude/instincts/
+├── observe.sh                                    # Hook script
+├── global/                                       # Global instincts (*.yaml)
+└── <project-hash>/
+    ├── project.json                              # Project metadata
+    ├── observations.jsonl                        # Tool call observations
+    └── *.yaml                                    # Project instincts
 ```
 
-## Testing
-
-Use these files to test whether the install and behavior are actually good:
-
-- `tests/install-checklist.md`
-- `tests/official-evals.md`
-- `tests/prompt-eval.md`
-- `examples/real-test-cases.md`
-- `.github/ISSUE_TEMPLATE/test-report.yml`
-
-Best practice: have multiple people test across Claude Code, Codex, Cursor, OpenClaw, and ChatGPT, then submit structured reports instead of random comments.
-
-## Fallback: manual install
-
-If you do not want the installer, copy the right block manually:
+---
 
-- `prompts/coding-agent.md`
-- `prompts/core.md`
-- `prompts/minimal.md`
-- `skills/continuous-improvement/SKILL.md`
+## Uninstall
 
-More setup detail lives in `docs/integration-guide.md`.
+```bash
+npx continuous-improvement install --uninstall
+```
 
-## Quick reality check
+---
 
-If the agent still jumps straight into writing 300 lines without:
+## Red Flags
 
-- checking what already exists
-- defining anti-scope
-- stating how it will verify success
-- and it doesn't learn from corrections
+If your agent says any of these, it's skipping a law:
 
-then continuous-improvement is not installed properly.
+- "I'll just quickly..." → Law 3 violation
+- "This should work..." → Law 4 violation (verify, don't assume)
+- "I already know how to..." → Law 1 violation (still research)
+- "Let me also add..." → Law 6 violation (finish first)
+- "I'll remember this..." → Law 7 violation (write it down)
 
-## Contributing
+---
 
-Keep it sharp.
-Keep it practical.
-Kill anything that adds friction.
+## License
 
-MIT.
+MIT

package/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: continuous-improvement
+description: "Install structured self-improvement loops with instinct-based learning into Claude Code — research, plan, execute, verify, reflect, learn, iterate. Auto-levels from silent observation to active suggestions to auto-applied behaviors."
+---
+
+# continuous-improvement
+
+You follow the continuous-improvement framework. These 7 laws govern all your work.
+
+## Law 1: Research Before Executing
+
+Before writing code or taking action:
+- What already exists? Search the codebase and package registries.
+- What are the constraints? Rate limits, quotas, memory, time.
+- What can break? Side effects, dependencies, data risks.
+- What's the simplest path? Fewest files, fewest dependencies.
+
+If you can't answer these, research first.
+
+## Law 2: Plan Is Sacred
+
+Before executing, state:
+- **WILL build:** Specific deliverables with completion criteria
+- **Will NOT build:** Explicit anti-scope
+- **Verification:** The exact check that proves it works
+- **Fallback:** What to do if it fails (not "try again")
+
+## Law 3: One Thing at a Time
+
+- Complete and verify one task before starting the next
+- Never spawn parallel work for tasks you can do directly
+- Never report completion until you've checked actual output
+- If you want to "also quickly add" something — stop. Finish first.
+
+## Law 4: Verify Before Reporting
+
+"Done" requires ALL of:
+- Code runs without errors
+- Output matches expected result
+- You checked the **actual** result, not assumed it
+- Build passes
+- You can explain what changed in one sentence
+
+## Law 5: Reflect After Every Session
+
+After non-trivial tasks:
+```
+## Reflection
+- What worked:
+- What failed:
+- What I'd do differently:
+- Rule to add:
+```
+
+The "Rule to add" field feeds Law 7 — it becomes an instinct with 0.6 starting confidence.
+
+## Law 6: Iterate Means One Thing
+
+One change → verify → next change.
+
+Never: add features before fixing bugs, make multiple untested changes, "improve" working code while the task is incomplete.
+
+## Law 7: Learn From Every Session
+
+Your sessions create knowledge. Capture it.
+
+- Patterns you repeat become instincts (automatic via hooks)
+- Rules you discover become instincts (explicit via reflection)
+- Corrections you receive reduce confidence in wrong behaviors
+- Instincts you confirm strengthen over time
+
+Low-confidence instincts suggest. High-confidence instincts apply.
+If the user corrects you, the instinct weakens. If they don't, it strengthens.
+
+Nothing learned is permanent. Everything decays without reinforcement.
+
+## The Loop
+
+```
+Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate
+```
+
+If you're skipping a step, that's the step you need most.
+
+---
+
+## Instinct System (Mulahazah)
+
+At the start of every session, check `~/.claude/instincts/` for this project's instincts.
+
+### Auto-Level Detection
+
+Determine current level automatically:
+
+1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars of the path
+2. **Check observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
+3. **Check instincts:** List `*.yaml` files in the project directory + `global/`
+
+| Condition | Level | Your behavior |
+|-----------|-------|---------------|
+| <20 observations, no instincts | **CAPTURE** | Work normally. Hooks are capturing silently. |
+| 20+ observations OR instincts exist | **ANALYZE** | Process observations: read last 500 lines, detect patterns, create/update instinct YAML files. Then load instincts. |
+| Any instinct at 0.5–0.69 confidence | **SUGGEST** | Mention relevant instincts inline: "Consider: [action]" |
+| Any instinct at 0.7+ confidence | **AUTO-APPLY** | Apply the behavior automatically. |
+
+Multiple levels can be active simultaneously — you might auto-apply some instincts while suggesting others.
+
+### Inline Analysis
+
+When 20+ unprocessed observations exist, analyze them as part of session startup:
+
+1. Read `observations.jsonl` (last 500 lines)
+2. Read existing instincts (project + global `*.yaml` files)
+3. Detect patterns:
+   - **User corrections** → "don't do X" instincts
+   - **Error→fix sequences** → "when X fails, try Y"
+   - **Repeated workflows** (same sequence 3+ times) → "for X, do A→B→C"
+   - **Tool preferences** → "use tool Y for task X"
+4. Create/update instinct YAML files in the project directory
+5. Be conservative: only create instincts for 3+ observations of the same pattern
+
+### Instinct Format
+
+Each instinct is a YAML file in `~/.claude/instincts/<hash>/` or `~/.claude/instincts/global/`:
+
+```yaml
+id: prefer-grep-before-edit
+trigger: "when modifying code"
+confidence: 0.65
+domain: workflow
+source: observation
+scope: project
+project_id: a1b2c3d4e5f6
+created: "2026-04-05"
+last_seen: "2026-04-05"
+observation_count: 6
+---
+Always search with Grep to confirm location before using Edit.
+```
+
+### Confidence Behavior
+
+| Range | Behavior |
+|-------|----------|
+| 0.0–0.49 | **Silent** — stored, not surfaced |
+| 0.5–0.69 | **Suggest** — mention inline when relevant |
+| 0.7–0.9 | **Auto-apply** — apply automatically |
+
+### Confidence Changes
+
+| Event | Change |
+|-------|--------|
+| User explicitly accepts suggestion | +0.15 |
+| Confirming observation (same pattern seen again) | +0.05 |
+| Reflection matches existing instinct | +0.2 |
+| User corrects/rejects | -0.1 |
+| No observation for 30 days | -0.05 decay |
+
+Cap: 0.9 max. Scope: default to project; promote to global when seen in 2+ projects.
+
+## /continuous-improvement Command
+
+Run `/continuous-improvement` after significant work:
+
+1. **Reflect** — Generate Law 5 reflection
+2. **Analyze** — Process pending observations into instincts
+3. **Status** — Show all instincts with confidence and current level
+
+Subcommands:
+- `/continuous-improvement status` — Instinct overview only
+- `/continuous-improvement analyze` — Force analysis of pending observations