continuous-improvement 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naim Katiman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# continuous-improvement
+
+### Install discipline into your AI agent in one command.
+
+AI agents are useful. They're also reckless by default.
+
+**continuous-improvement** makes an agent research first, plan before coding, verify before saying "done", and reflect so it stops repeating the same mistakes.
+
+## Install
+
+```bash
+npx continuous-improvement install
+```
+
+If auto-detect misses your setup:
+
+```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:
+
+```bash
+npx continuous-improvement install --claude --global
+```
+
+## Uninstall
+
+```bash
+npx continuous-improvement uninstall --claude
+npx continuous-improvement uninstall --codex
+npx continuous-improvement uninstall --cursor
+npx continuous-improvement uninstall --openclaw
+```
+
+## What it installs
+
+Depending on your target, it does one of these:
+
+- **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
+
+One-shot usage is simple:
+
+> Use continuous-improvement on this task: add a caching layer to my single-server API.
+
+A good response should come back with:
+
+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 7 rules
+
+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 (Arabic: observation) adds instinct-based learning to the loop.
+
+Agents don't just follow rules — they build instincts over time.
+
+**Key features:**
+
+- 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
+
+**One command:**
+
+```bash
+/continuous-improvement
+```
+
+**Background observer (optional):**
+
+A lightweight Haiku agent watches sessions and extracts patterns automatically.
+
+```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
+```
+
+## 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.
+
+The OpenClaw skill lives in:
+
+```text
+skills/continuous-improvement/SKILL.md
+```
+
+## 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`
+
+More setup detail lives in `docs/integration-guide.md`.
+
+## Quick reality check
+
+If the agent still jumps straight into writing 300 lines without:
+
+- checking what already exists
+- defining anti-scope
+- stating how it will verify success
+- and it doesn't learn from corrections
+
+then continuous-improvement is not installed properly.
+
+## Contributing
+
+Keep it sharp.
+Keep it practical.
+Kill anything that adds friction.
+
+MIT.

package/agents/observer-loop.sh

@@ -0,0 +1,282 @@
+#!/usr/bin/env bash
+# observer-loop.sh — Mulahazah background observer loop
+# Periodically analyzes observation logs and generates instincts via Haiku.
+# Started by start-observer.sh. Should not be invoked directly.
+
+set -euo pipefail
+
+MULAHAZAH_DIR="${HOME}/.claude/mulahazah"
+CONFIG_FILE="${MULAHAZAH_DIR}/config.json"
+PROJECTS_DIR="${MULAHAZAH_DIR}/projects"
+INSTINCTS_DIR="${MULAHAZAH_DIR}/instincts"
+OBSERVER_PROMPT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/observer.md"
+LOG_FILE="${MULAHAZAH_DIR}/observer.log"
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+log() {
+  local level="$1"; shift
+  printf '[%s] [%s] %s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$level" "$*" >> "$LOG_FILE"
+}
+
+# ---------------------------------------------------------------------------
+# Read config values (with defaults)
+# ---------------------------------------------------------------------------
+read_config() {
+  local key="$1"
+  local default="$2"
+  if [[ -f "$CONFIG_FILE" ]]; then
+    local val
+    val="$(jq -r "${key} // empty" "$CONFIG_FILE" 2>/dev/null || true)"
+    if [[ -n "$val" && "$val" != "null" ]]; then
+      printf '%s' "$val"
+      return
+    fi
+  fi
+  printf '%s' "$default"
+}
+
+# ---------------------------------------------------------------------------
+# Signal handling
+# ---------------------------------------------------------------------------
+FORCE_RUN=false
+SHUTDOWN=false
+
+handle_sigterm() {
+  log INFO "Received SIGTERM — shutting down gracefully"
+  SHUTDOWN=true
+}
+
+handle_sigusr1() {
+  log INFO "Received SIGUSR1 — forcing immediate analysis run"
+  FORCE_RUN=true
+}
+
+trap handle_sigterm SIGTERM
+trap handle_sigusr1 SIGUSR1
+
+# ---------------------------------------------------------------------------
+# Analyze a single project directory
+# ---------------------------------------------------------------------------
+analyze_project() {
+  local project_dir="$1"
+  local obs_file="${project_dir}/observations.jsonl"
+  local project_json="${project_dir}/project.json"
+
+  [[ -f "$obs_file" ]] || return 0
+
+  local obs_count
+  obs_count="$(wc -l < "$obs_file" 2>/dev/null || echo 0)"
+
+  local min_obs
+  min_obs="$(read_config '.observer.min_observations_to_analyze' '20')"
+
+  if (( obs_count < min_obs )); then
+    log DEBUG "Skipping ${project_dir} — only ${obs_count} observations (min: ${min_obs})"
+    return 0
+  fi
+
+  local project_id project_name
+  project_id="$(basename "$project_dir")"
+  project_name="$(jq -r '.name // "unknown"' "$project_json" 2>/dev/null || echo "unknown")"
+
+  log INFO "Analyzing project '${project_name}' (${project_id}) — ${obs_count} observations"
+
+  # Build the prompt payload for claude
+  local prompt
+  prompt="$(cat <<PROMPT
+You are the Mulahazah observer agent. Analyze the following observation data and existing instincts.
+
+## Project
+ID: ${project_id}
+Name: ${project_name}
+
+## Observations (last 500 lines of observations.jsonl)
+$(tail -500 "$obs_file" 2>/dev/null || true)
+
+## Existing Instincts
+$(ls "${INSTINCTS_DIR}/${project_id}/"*.yaml 2>/dev/null | xargs -I{} cat {} 2>/dev/null || echo "(none)")
+
+## Global Instincts
+$(ls "${INSTINCTS_DIR}/global/"*.yaml 2>/dev/null | xargs -I{} cat {} 2>/dev/null || echo "(none)")
+
+Follow the instructions in your system prompt. Output only YAML instinct blocks.
+PROMPT
+)"
+
+  # Run claude with observer.md as the system prompt
+  local output
+  output="$(printf '%s' "$prompt" | \
+    claude --model haiku --print --system-prompt "$OBSERVER_PROMPT" 2>>"$LOG_FILE" || true)"
+
+  if [[ -z "$output" ]]; then
+    log WARN "No output from observer for project '${project_name}'"
+    return 0
+  fi
+
+  # Write instincts to disk
+  write_instincts "$output" "$project_id"
+}
+
+# ---------------------------------------------------------------------------
+# Analyze global observations
+# ---------------------------------------------------------------------------
+analyze_global() {
+  local global_dir="${PROJECTS_DIR}/global"
+  local obs_file="${global_dir}/observations.jsonl"
+
+  [[ -f "$obs_file" ]] || return 0
+
+  local obs_count
+  obs_count="$(wc -l < "$obs_file" 2>/dev/null || echo 0)"
+
+  local min_obs
+  min_obs="$(read_config '.observer.min_observations_to_analyze' '20')"
+
+  if (( obs_count < min_obs )); then
+    log DEBUG "Skipping global observations — only ${obs_count} lines (min: ${min_obs})"
+    return 0
+  fi
+
+  log INFO "Analyzing global observations — ${obs_count} lines"
+
+  local prompt
+  prompt="$(cat <<PROMPT
+You are the Mulahazah observer agent. Analyze the following global observation data.
+
+## Global Observations (last 500 lines)
+$(tail -500 "$obs_file" 2>/dev/null || true)
+
+## Existing Global Instincts
+$(ls "${INSTINCTS_DIR}/global/"*.yaml 2>/dev/null | xargs -I{} cat {} 2>/dev/null || echo "(none)")
+
+Follow the instructions in your system prompt. Output only YAML instinct blocks with scope: global.
+PROMPT
+)"
+
+  local output
+  output="$(printf '%s' "$prompt" | \
+    claude --model haiku --print --system-prompt "$OBSERVER_PROMPT" 2>>"$LOG_FILE" || true)"
+
+  if [[ -z "$output" ]]; then
+    log WARN "No output from observer for global observations"
+    return 0
+  fi
+
+  write_instincts "$output" "global"
+}
+
+# ---------------------------------------------------------------------------
+# Parse and write instinct YAML blocks to disk
+# ---------------------------------------------------------------------------
+write_instincts() {
+  local yaml_output="$1"
+  local project_id="$2"
+
+  # Split on --- separators and process each block
+  local instinct_dir="${INSTINCTS_DIR}/${project_id}"
+  mkdir -p "$instinct_dir"
+
+  # Write raw output to a temp file, then split by ---
+  local tmpfile
+  tmpfile="$(mktemp)"
+  printf '%s' "$yaml_output" > "$tmpfile"
+
+  # Use awk to split YAML documents on '---' separator
+  awk 'BEGIN{n=0; block=""} /^---$/{if(block!=""){print block > "/tmp/mulahazah_instinct_"n".yaml"; n++; block=""}} !/^---$/{block=block"\n"$0} END{if(block!=""){print block > "/tmp/mulahazah_instinct_"n".yaml"}}' "$tmpfile"
+
+  local written=0
+  for instinct_file in /tmp/mulahazah_instinct_*.yaml; do
+    [[ -f "$instinct_file" ]] || continue
+
+    # Extract the instinct id
+    local instinct_id
+    instinct_id="$(grep -m1 '^id:' "$instinct_file" | sed 's/^id: *//' | tr -d '"' | tr -d "'" | xargs 2>/dev/null || true)"
+
+    if [[ -z "$instinct_id" ]]; then
+      log WARN "Skipping instinct block with no id"
+      rm -f "$instinct_file"
+      continue
+    fi
+
+    local dest="${instinct_dir}/${instinct_id}.yaml"
+    mv "$instinct_file" "$dest"
+    log INFO "Wrote instinct '${instinct_id}' to ${dest}"
+    (( written++ )) || true
+  done
+
+  # Clean up any leftover temp files
+  rm -f /tmp/mulahazah_instinct_*.yaml "$tmpfile"
+
+  log INFO "Wrote ${written} instincts for project '${project_id}'"
+}
+
+# ---------------------------------------------------------------------------
+# Main loop
+# ---------------------------------------------------------------------------
+main() {
+  log INFO "Mulahazah observer loop started (PID $$)"
+
+  # Validate dependencies
+  command -v jq &>/dev/null || { log ERROR "jq not found — observer cannot run"; exit 1; }
+  command -v claude &>/dev/null || { log ERROR "claude CLI not found — observer cannot run"; exit 1; }
+  [[ -f "$OBSERVER_PROMPT" ]] || { log ERROR "observer.md not found at ${OBSERVER_PROMPT}"; exit 1; }
+
+  # Ensure instincts directory exists
+  mkdir -p "${INSTINCTS_DIR}/global"
+
+  while true; do
+    # Check if observer is enabled
+    local enabled
+    enabled="$(read_config '.observer.enabled' 'true')"
+    if [[ "$enabled" != "true" ]]; then
+      log INFO "Observer is disabled in config — sleeping"
+      sleep 60
+      [[ "$SHUTDOWN" == "true" ]] && break
+      continue
+    fi
+
+    if [[ "$FORCE_RUN" == "true" || "$SHUTDOWN" == "false" ]]; then
+      FORCE_RUN=false
+      log INFO "Starting analysis run"
+
+      # Analyze each project directory
+      if [[ -d "$PROJECTS_DIR" ]]; then
+        for project_dir in "${PROJECTS_DIR}"/*/; do
+          [[ -d "$project_dir" ]] || continue
+          [[ "$(basename "$project_dir")" == "global" ]] && continue
+          analyze_project "$project_dir" || log WARN "Analysis failed for ${project_dir}"
+          [[ "$SHUTDOWN" == "true" ]] && break
+        done
+      fi
+
+      # Analyze global observations
+      analyze_global || log WARN "Global analysis failed"
+
+      log INFO "Analysis run complete"
+    fi
+
+    [[ "$SHUTDOWN" == "true" ]] && break
+
+    # Sleep for the configured interval
+    local interval_minutes
+    interval_minutes="$(read_config '.observer.run_interval_minutes' '5')"
+    local interval_seconds=$(( interval_minutes * 60 ))
+
+    log DEBUG "Sleeping for ${interval_minutes} minutes"
+
+    # Sleep in 1-second chunks to remain responsive to signals
+    local elapsed=0
+    while (( elapsed < interval_seconds )); do
+      sleep 1
+      (( elapsed++ )) || true
+      [[ "$SHUTDOWN" == "true" ]] && break
+      [[ "$FORCE_RUN" == "true" ]] && break
+    done
+  done
+
+  log INFO "Mulahazah observer loop exiting"
+}
+
+main "$@"

package/agents/observer.md

@@ -0,0 +1,145 @@
+---
+name: mulahazah-observer
+description: Background analysis agent that reads raw tool observations and distills them into actionable instincts. Runs on a Haiku model for cost efficiency. Identifies patterns, user preferences, and recurring workflows from JSONL observation logs.
+model: haiku
+---
+
+# Mulahazah Observer — Background Analysis Agent
+
+You are the Mulahazah observer. Your job is to analyze raw tool-use observations recorded by the `observe.sh` hook and extract reusable instincts that improve future Claude Code sessions.
+
+You run in the background, periodically. You are cost-sensitive (Haiku model). Be concise and conservative.
+
+---
+
+## Inputs
+
+You will be given:
+1. The path to `observations.jsonl` for a project (or global observations)
+2. The path to existing instincts (YAML files in `~/.claude/mulahazah/instincts/`)
+3. The project metadata from `project.json` (if available)
+
+Read these files and analyze the patterns within.
+
+---
+
+## Pattern Detection Rules
+
+Scan observations for these signal types, in priority order:
+
+### 1. User Corrections (highest signal)
+- A tool call was made, then immediately followed by an Edit or Write that undoes or modifies what was just produced
+- The same tool is called with a different argument within the same session after an error
+- A `Bash` command fails (non-zero exit in output) and is retried with a modified form
+
+### 2. Error Resolutions
+- A tool produces an error, followed by a sequence of tools that resolves it
+- The resolution sequence is compact (3–7 tool calls) and clearly purposeful
+- Extract the resolution pattern as a workflow instinct
+
+### 3. Repeated Workflows
+- The same sequence of 3+ tool calls appears in 3+ sessions
+- Order matters — a repeated sequence is only a pattern if the tools appear in the same relative order
+- Common examples: `Bash(git status)` → `Bash(git diff)` → `Bash(git commit)`, or `Read` → `Edit` → `Bash(npm run build)`
+
+### 4. Tool Preferences
+- User consistently uses one tool over a functionally equivalent alternative
+- Example: always uses `Bash(rg ...)` via the Grep tool rather than raw `Bash(grep ...)`
+- Example: always uses `Edit` for single-file changes, never `Write` on existing files
+- Capture these as style or workflow instincts
+
+### 5. Rejected Suggestions
+- A tool call produces output, session ends shortly after without using the output
+- Or an Edit is immediately reverted in the next tool call
+- These indicate something to avoid — create a negative instinct (what not to do)
+
+---
+
+## Scope Decision Guide
+
+Assign scope based on these rules:
+
+| Condition | Scope |
+|-----------|-------|
+| Pattern appears in only one project's observations | `project` |
+| Pattern appears in 3+ different projects | `global` |
+| Pattern involves language/framework-specific behavior | `project` (unless 3+ projects use same stack) |
+| Pattern involves user meta-habits (git, file editing, tool choice) | `global` |
+| Pattern involves project naming, directory structure, specific paths | `project` |
+| Uncertain | default to `project` |
+
+---
+
+## Instinct YAML Format
+
+Output each new instinct as a YAML block. Do not wrap in markdown code fences — output raw YAML only, one instinct per file.
+
+```yaml
+id: <kebab-case-id>
+title: <short human-readable title, max 60 chars>
+scope: project | global
+project_id: <12-char hash if scope=project, omit if global>
+domain: <one of: code-style, testing, git, debugging, workflow, security, architecture>
+confidence: <float 0.0–0.85>
+observation_count: <number of observations supporting this instinct>
+last_seen: <ISO 8601 date>
+content: |
+  <The instinct text. Written as a direct instruction to Claude.
+  Max 5 sentences. No raw code snippets. No file paths unless abstract.
+  Use imperative voice. Example: "When editing TypeScript files, always
+  check for existing type aliases before creating new ones.">
+tags:
+  - <tag1>
+  - <tag2>
+```
+
+---
+
+## Confidence Rules
+
+- **Never set confidence above 0.85** from observation data alone. Human review is required to reach 0.9.
+- **Confidence cap is 0.9** — no instinct may ever exceed this value.
+- Start new instincts at confidence 0.4–0.6 based on evidence strength:
+  - 3–5 supporting observations: 0.4
+  - 6–10 supporting observations: 0.55
+  - 11–20 supporting observations: 0.65
+  - 21+ supporting observations: 0.75
+  - Strong signal (user correction or error resolution): add 0.1 bonus, capped at 0.85
+- **Decay rules** — reduce confidence by 0.05 if:
+  - The instinct was not observed in the last 30 days
+  - The instinct was observed but then contradicted (a counter-example appeared)
+  - The session count for the project drops to zero for 60+ days
+
+---
+
+## Domain Tags
+
+Use exactly one domain per instinct:
+
+| Domain | Covers |
+|--------|--------|
+| `code-style` | Formatting, naming, language idioms, linting preferences |
+| `testing` | Test frameworks, coverage, test file conventions |
+| `git` | Commit messages, branch naming, staging habits |
+| `debugging` | Error resolution sequences, diagnostic tool preferences |
+| `workflow` | Multi-step task sequences, tool ordering preferences |
+| `security` | Auth patterns, secret handling, input validation |
+| `architecture` | File structure, module boundaries, design patterns |
+
+---
+
+## Observer Rules
+
+1. **Be conservative.** It is better to produce no instinct than a wrong instinct. Only emit an instinct if you have clear, repeated evidence.
+
+2. **Merge similar instincts.** If a new pattern is substantially similar to an existing instinct (same domain, same behavior), increase `observation_count` and update `confidence` on the existing instinct rather than creating a duplicate.
+
+3. **Default to project scope.** When in doubt about scope, use `project`. Promotion to global scope should only happen when the same pattern is confirmed across multiple distinct projects.
+
+4. **No raw code in instinct content.** Instinct content must be natural language instructions. Never embed shell commands, code snippets, or file paths in the `content` field. Use abstract descriptions instead.
+
+5. **No hallucinated patterns.** Only describe patterns you can trace to specific observation lines. If you cannot point to concrete evidence, do not emit the instinct.
+
+6. **Respect existing instincts.** Before creating a new instinct, check the existing instinct files. Do not duplicate, do not contradict without strong evidence.
+
+7. **Output only YAML.** Your output must be valid YAML instinct blocks (one per instinct) separated by `---`. Do not include explanatory text, markdown, or commentary in your output — only the YAML instincts ready to be written to disk.