continuous-improvement 2.2.0 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this skill are documented here.
 
 ---
 
+## [2.3.0] — 2026-04-06
+
+### Changed
+- **Public npm** — package name changed from `@naimkatiman/continuous-improvement` to `continuous-improvement`. Removed GitHub Packages publishConfig. `npx continuous-improvement install` now works for everyone.
+- **Expanded keywords** — added `claude-code-skill`, `agent-skill`, `gemini-cli` for better npm discoverability
+- **Improved description** — package description now leads with the value prop, lists supported platforms
+
+### Added
+- **Test suite** — 20 tests covering installer, hook, and SKILL.md validation. Zero dependencies (Node.js built-in test runner).
+- **Before/after examples in README** — collapsible terminal output showing the framework in action vs. without it
+- **Real-world examples** — `examples/` directory with 3 detailed scenarios (bug fix, feature build, refactor)
+- **Platform badges** — Claude Code, Cursor, Codex compatibility badges in README
+- **Gemini CLI** to supported platforms list
+- **Roadmap** — "Roadmap to 1000 Stars" section in README with phased plan
+
+---
+
 ## [2.1.0] — 2026-04-05
 
 ### Changed

package/README.md

@@ -1,38 +1,130 @@
 <p align="center">
-  <img src="assets/combined.gif" alt="Before vs After continuous-improvement" width="700" />
+  <img src="assets/combined.gif" alt="Before vs After — The 7 Laws of AI Agent Discipline" width="700" />
 </p>
 
-# continuous-improvement
+<h1 align="center">The 7 Laws of AI Agent Discipline</h1>
 
-> Stop your AI agent from skipping steps, guessing, and declaring "done" without verifying.
+<p align="center">
+  <b>Stop your AI agent from skipping steps, guessing, and declaring "done" without verifying.</b>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/v/continuous-improvement" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/dm/continuous-improvement" alt="downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
+  <a href="test/"><img src="https://img.shields.io/badge/tests-20%20passing-brightgreen" alt="tests"></a>
+</p>
 
-[![Version](https://img.shields.io/badge/version-2.1.0-blue)](CHANGELOG.md)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+<p align="center">
+  <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Claude%20Code-skill-blueviolet" alt="Claude Code"></a>
+  <a href="https://cursor.sh"><img src="https://img.shields.io/badge/Cursor-compatible-blue" alt="Cursor"></a>
+  <a href="https://openai.com/codex"><img src="https://img.shields.io/badge/Codex-compatible-blue" alt="Codex"></a>
+  <a href="https://ai.google.dev/gemini-api/docs/gemini-cli"><img src="https://img.shields.io/badge/Gemini%20CLI-compatible-blue" alt="Gemini CLI"></a>
+</p>
 
 ---
 
 ## The Problem
 
-AI agents are great at individual steps. They're terrible at discipline.
+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.
 
-This skill fixes that with **7 laws** and a **learning system** that auto-levels itself — no config, no daemon, no manual setup.
+**The 7 Laws** fix that — plus a **learning system** (Mulahazah) that builds instincts over time. No config, no daemon, no manual setup.
+
+### Before vs After
+
+<details>
+<summary><b>Without continuous-improvement</b> — agent skips research, declares "done" without verifying</summary>
+
+```
+You: Add rate limiting to the /api/users endpoint
+
+Agent: I'll add rate limiting now.
+       *writes express-rate-limit middleware*
+       Done! I've added rate limiting to the /api/users endpoint.
+
+You: Did you check if we already have rate limiting somewhere?
+Agent: Let me check... oh, there's already a rate limiter in middleware/rateLimit.ts.
+       I've created a duplicate. Let me fix that.
+
+You: Did you test it?
+Agent: Let me run the tests... they're failing. The import path is wrong.
+       *fixes import*
+       Now it works!
+
+You: You also broke the /api/auth endpoint — it was sharing that middleware.
+Agent: I see. Let me fix that too...
+```
+
+**Result:** 4 back-and-forth corrections. Duplicate code. Broken endpoint. 15 minutes wasted.
+</details>
+
+<details>
+<summary><b>With continuous-improvement</b> — agent follows the 7 laws</summary>
+
+```
+You: Add rate limiting to the /api/users endpoint
+
+Agent: **[Law 1: Research]** Searching for existing rate limiting...
+       Found: middleware/rateLimit.ts — already applies to /api/auth.
+       Found: express-rate-limit already in package.json.
+
+       **[Law 2: Plan]**
+       WILL: Extend existing rateLimit middleware to cover /api/users
+       WILL NOT: Create new middleware or change existing /api/auth behavior
+       VERIFY: Run tests + curl /api/users 101 times to confirm 429 response
+
+       **[Law 3: Execute one thing]** Adding /api/users to the route list
+       in middleware/rateLimit.ts...
+
+       **[Law 4: Verify]**
+       ✓ npm test — 47/47 passing
+       ✓ curl test — 429 after 100 requests
+       ✓ /api/auth still works — 200 OK
+
+       Done. Extended existing rate limiter to cover /api/users.
+       One file changed: middleware/rateLimit.ts (+1 line).
+```
+
+**Result:** Correct on first attempt. No duplicate code. No broken endpoints. 2 minutes.
+</details>
 
 ---
 
 ## Install
 
+### Beginner (default) — just hooks, no setup needed
+
 ```bash
 npx continuous-improvement install
 ```
 
-That's it. For Claude Code, this also installs:
+That's it. For Claude Code, this installs:
 - Observation hooks (captures every tool call, <50ms, jq optional)
 - `/continuous-improvement` command
 - Auto-leveling instinct system
 
-Install to a specific target:
+### Expert — full power with MCP server
+
+```bash
+npx continuous-improvement install --mode expert
+```
+
+Everything in beginner plus:
+- **MCP server** with 8 tools (instinct management, import/export, observation viewer)
+- **Session hooks** (auto-load instincts at start, remind to reflect at end)
+- Works with Claude Code, Claude Desktop, and any MCP client
+
+### MCP only — for non-Claude editors
+
+```bash
+npx continuous-improvement install --mode mcp
+```
+
+Registers the MCP server without hooks — for Cursor, Zed, Windsurf, VS Code, or any editor that supports MCP.
+
+### Install to a specific target
 
 ```bash
 npx continuous-improvement install --target claude    # Claude Code + Mulahazah
@@ -57,17 +149,19 @@ Fetch and follow the skill at: https://raw.githubusercontent.com/naimkatiman/con
 
 ---
 
-## The 7 Laws
+## The 7 Laws of AI Agent Discipline
+
+> Every skill in the ecosystem adds capabilities. This is the only one that fixes *how agents think*.
 
-| # | 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 |
+| # | 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 the context window ends |
 
 ### The Loop
 
@@ -75,6 +169,8 @@ Fetch and follow the skill at: https://raw.githubusercontent.com/naimkatiman/con
 Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate
 ```
 
+If your agent is skipping a step, that's the step it needs most.
+
 ---
 
 ## Mulahazah: Auto-Leveling Learning
@@ -107,14 +203,28 @@ Install:       Hooks start capturing silently. You notice nothing.
 
 ---
 
+## Real-World Examples
+
+See the [`examples/`](examples/) directory for detailed walkthroughs:
+
+- [**Bug Fix**](examples/01-bug-fix.md) — Double submit bug: 4 rounds without framework → 1 round with it
+- [**Feature Build**](examples/02-feature-build.md) — Adding pagination: 3 rewrites without → correct first attempt with
+- [**Refactor**](examples/03-refactor.md) — SDK migration: cascading failures without → zero regressions with
+
+Each example shows the same task done with and without the 7 laws, highlighting which laws made the difference.
+
+---
+
 ## Files
 
 ```
 continuous-improvement/
 ├── SKILL.md                    # The 7 Laws + instinct behavior
-├── commands/continuous-improvement.md  # The /continuous-improvement command
-├── hooks/observe.sh            # Observation hook (pure bash)
+├── commands/continuous-improvement.md  # /continuous-improvement command
+├── hooks/observe.sh            # Observation hook (pure bash, <50ms)
 ├── bin/install.mjs             # CLI installer
+├── test/                       # 20 tests (node --test)
+├── examples/                   # Real-world before/after scenarios
 ├── QUICKSTART.md               # First-use guide
 ├── CHANGELOG.md
 └── package.json
@@ -126,12 +236,12 @@ continuous-improvement/
 ~/.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)
+├── observe.sh                                       # Hook script
+├── global/                                          # Global instincts (*.yaml)
 └── <project-hash>/
-    ├── project.json                              # Project metadata
-    ├── observations.jsonl                        # Tool call observations
-    └── *.yaml                                    # Project instincts
+    ├── project.json                                 # Project metadata
+    ├── observations.jsonl                           # Tool call observations
+    └── *.yaml                                       # Project instincts
 ```
 
 ---
@@ -142,6 +252,21 @@ continuous-improvement/
 npx continuous-improvement install --uninstall
 ```
 
+Removes the skill, hooks, and command. Your learned instincts in `~/.claude/instincts/` are preserved — delete that directory manually if you want a clean slate.
+
+---
+
+## Works With
+
+| Tool | Support |
+|------|---------|
+| **Claude Code** | Full — skill + hooks + auto-leveling instincts |
+| **Cursor** | Skill only (paste SKILL.md into rules) |
+| **Codex** | Skill only |
+| **Gemini CLI** | Skill only |
+| **OpenClaw** | Skill only |
+| **Any LLM** | Paste SKILL.md into your system prompt |
+
 ---
 
 ## Red Flags
@@ -156,6 +281,38 @@ If your agent says any of these, it's skipping a law:
 
 ---
 
+## Roadmap
+
+### Phase 1: Foundation -- DONE
+
+- [x] Published to public npm (`npx continuous-improvement install` works)
+- [x] 20-test suite (installer, hook, SKILL.md validation)
+- [x] Before/after examples in README + `examples/` directory
+- [x] Gemini CLI support
+- [x] Platform badges and improved npm metadata
+- [ ] **Submit to [awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)** (14K stars)
+
+### Phase 2: Content & Proof (In Progress)
+
+- [ ] **2-min demo video** — side-by-side agent with/without discipline. Post to X + YouTube.
+- [ ] **"Why your AI agent keeps lying about being done"** — X thread / blog post
+- [ ] **"Law of the Week" X series** — 7 weeks of content breaking down each law
+
+### Phase 3: Ecosystem Integration
+
+- [ ] **MCP server** — expose instinct status + law compliance as MCP tools
+- [ ] **GitHub Action** — lint agent transcripts for law compliance
+- [ ] **VS Code extension** — sidebar showing instinct confidence levels
+- [ ] **Aider / Windsurf / Zed** support
+
+### Phase 4: Community
+
+- [ ] **Instinct marketplace** — share learned instincts across teams
+- [ ] **Quick-start instinct packs** — pre-built instincts for React, Python, Go, etc.
+- [ ] **Conference talk on Mulahazah** — the auto-leveling system is genuinely novel
+
+---
+
 ## License
 
 MIT

package/bin/analyze.sh

@@ -118,49 +118,35 @@ fi
 mkdir -p "$PROJECT_DIR"
 
 NEW_COUNT=0
-while IFS= read -r -d '' block; do
-  [[ -z "$block" ]] && continue
-  # Extract id from the block
-  INSTINCT_ID=$(echo "$block" | grep -oP '(?<=^id: ).*' | head -1 | tr -d '"' | tr -d "'")
-  if [[ -n "$INSTINCT_ID" ]]; then
-    DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
-    printf '%s\n' "$block" > "$DEST"
-    echo "  + ${INSTINCT_ID} → ${DEST}"
-    NEW_COUNT=$((NEW_COUNT + 1))
-  fi
-done < <(printf '%s\0' "$RESULT" | sed 's/\n---\n/\x00/g')
-
-# Fallback: if the splitting didn't work, try line-based parsing
-if (( NEW_COUNT == 0 )); then
-  # Try splitting on --- delimiter
-  INSTINCT_ID=""
-  BLOCK=""
-  while IFS= read -r line; do
-    if [[ "$line" == "---" ]] && [[ -n "$BLOCK" ]]; then
-      if [[ -n "$INSTINCT_ID" ]]; then
-        DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
-        printf '%s\n' "$BLOCK" > "$DEST"
-        echo "  + ${INSTINCT_ID} → ${DEST}"
-        NEW_COUNT=$((NEW_COUNT + 1))
-      fi
-      INSTINCT_ID=""
-      BLOCK=""
-    else
-      BLOCK="${BLOCK}${line}"$'\n'
-      if [[ "$line" =~ ^id:\ (.+) ]]; then
-        INSTINCT_ID="${BASH_REMATCH[1]}"
-        INSTINCT_ID="${INSTINCT_ID//\"/}"
-        INSTINCT_ID="${INSTINCT_ID//\'/}"
-      fi
+INSTINCT_ID=""
+BLOCK=""
+
+while IFS= read -r line; do
+  if [[ "$line" == "---" ]] && [[ -n "$BLOCK" ]]; then
+    if [[ -n "$INSTINCT_ID" ]]; then
+      DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
+      printf '%s\n' "$BLOCK" > "$DEST"
+      echo "  + ${INSTINCT_ID} -> ${DEST}"
+      NEW_COUNT=$((NEW_COUNT + 1))
+    fi
+    INSTINCT_ID=""
+    BLOCK=""
+  else
+    BLOCK="${BLOCK}${line}"$'\n'
+    if [[ "$line" =~ ^id:\ (.+) ]]; then
+      INSTINCT_ID="${BASH_REMATCH[1]}"
+      INSTINCT_ID="${INSTINCT_ID//\"/}"
+      INSTINCT_ID="${INSTINCT_ID//\'/}"
     fi
-  done <<< "$RESULT"
-  # Handle last block
-  if [[ -n "$INSTINCT_ID" ]] && [[ -n "$BLOCK" ]]; then
-    DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
-    printf '%s\n' "$BLOCK" > "$DEST"
-    echo "  + ${INSTINCT_ID} → ${DEST}"
-    NEW_COUNT=$((NEW_COUNT + 1))
   fi
+done <<< "$RESULT"
+
+# Handle last block
+if [[ -n "$INSTINCT_ID" ]] && [[ -n "$BLOCK" ]]; then
+  DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
+  printf '%s\n' "$BLOCK" > "$DEST"
+  echo "  + ${INSTINCT_ID} -> ${DEST}"
+  NEW_COUNT=$((NEW_COUNT + 1))
 fi
 
 echo ""