continuous-improvement 1.0.0

package/agents/start-observer.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# start-observer.sh — Start the Mulahazah background observer
+# Checks for an existing instance, cleans up stale PIDs, and launches observer-loop.sh.
+
+set -euo pipefail
+
+MULAHAZAH_DIR="${HOME}/.claude/mulahazah"
+PID_FILE="${MULAHAZAH_DIR}/observer.pid"
+LOG_FILE="${MULAHAZAH_DIR}/observer.log"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOOP_SCRIPT="${SCRIPT_DIR}/observer-loop.sh"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+print_status() {
+  local pid="$1"
+  echo "Mulahazah observer is running (PID ${pid})"
+  echo ""
+  echo "  Force immediate analysis:  kill -USR1 ${pid}"
+  echo "  Stop observer:             kill ${pid}"
+  echo "  View logs:                 tail -f ${LOG_FILE}"
+  echo "  PID file:                  ${PID_FILE}"
+}
+
+# ---------------------------------------------------------------------------
+# Validate dependencies
+# ---------------------------------------------------------------------------
+if ! command -v jq &>/dev/null; then
+  echo "Error: jq is required but not installed." >&2
+  exit 1
+fi
+
+if ! command -v claude &>/dev/null; then
+  echo "Error: claude CLI is required but not installed." >&2
+  exit 1
+fi
+
+if [[ ! -f "$LOOP_SCRIPT" ]]; then
+  echo "Error: observer-loop.sh not found at ${LOOP_SCRIPT}" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Check for existing running instance
+# ---------------------------------------------------------------------------
+if [[ -f "$PID_FILE" ]]; then
+  EXISTING_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+
+  if [[ -n "$EXISTING_PID" ]] && kill -0 "$EXISTING_PID" 2>/dev/null; then
+    # Process is alive
+    echo "Mulahazah observer is already running."
+    echo ""
+    print_status "$EXISTING_PID"
+    exit 0
+  else
+    # Stale PID file — process is gone
+    echo "Cleaning up stale PID file (PID ${EXISTING_PID:-unknown} is no longer running)"
+    rm -f "$PID_FILE"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Ensure Mulahazah directory structure exists
+# ---------------------------------------------------------------------------
+mkdir -p "${MULAHAZAH_DIR}/projects"
+mkdir -p "${MULAHAZAH_DIR}/instincts/global"
+
+# ---------------------------------------------------------------------------
+# Initialize config.json if it doesn't exist
+# ---------------------------------------------------------------------------
+CONFIG_FILE="${MULAHAZAH_DIR}/config.json"
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  # Check if a repo-level config exists next to this script's parent
+  REPO_CONFIG="$(dirname "$SCRIPT_DIR")/config.json"
+  if [[ -f "$REPO_CONFIG" ]]; then
+    cp "$REPO_CONFIG" "$CONFIG_FILE"
+    echo "Initialized config from ${REPO_CONFIG}"
+  else
+    cat > "$CONFIG_FILE" <<'EOF'
+{
+  "version": "2.0",
+  "observer": {
+    "enabled": true,
+    "run_interval_minutes": 5,
+    "min_observations_to_analyze": 20,
+    "model": "haiku"
+  }
+}
+EOF
+    echo "Created default config at ${CONFIG_FILE}"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Launch observer-loop.sh in background with nohup
+# ---------------------------------------------------------------------------
+nohup bash "$LOOP_SCRIPT" >> "$LOG_FILE" 2>&1 &
+OBSERVER_PID=$!
+
+# Write PID file
+printf '%d\n' "$OBSERVER_PID" > "$PID_FILE"
+
+# Brief pause to confirm the process started
+sleep 1
+if ! kill -0 "$OBSERVER_PID" 2>/dev/null; then
+  echo "Error: observer-loop.sh failed to start. Check logs:" >&2
+  echo "  ${LOG_FILE}" >&2
+  rm -f "$PID_FILE"
+  exit 1
+fi
+
+echo "Mulahazah observer started."
+echo ""
+print_status "$OBSERVER_PID"

package/config.json

@@ -0,0 +1,9 @@
+{
+  "version": "2.0",
+  "observer": {
+    "enabled": true,
+    "run_interval_minutes": 5,
+    "min_observations_to_analyze": 20,
+    "model": "haiku"
+  }
+}

package/docs/failure-taxonomy.md

@@ -0,0 +1,153 @@
+# Failure Taxonomy: How AI Agents Break
+
+A structured classification of AI agent failure modes, organized by root cause.
+
+---
+
+## Category 1: Scope Failures
+
+Failures where the agent does the wrong amount of work.
+
+### 1.1 Feature Sprawl
+- **Description:** Agent expands scope far beyond the request
+- **Trigger:** Open-ended tasks like "add X" or "improve Y"
+- **Example:** Asked to add dark mode, builds a full theme engine
+- **Prevention:** Law 2 — Plan with explicit anti-scope
+- **Severity:** High — creates technical debt and introduces bugs in unrelated code
+
+### 1.2 Gold Plating
+- **Description:** Agent adds unnecessary polish, optimization, or features
+- **Trigger:** Agent completes the task and keeps going
+- **Example:** Adding error handling to functions that can't fail, optimizing code that runs once
+- **Prevention:** Law 3 — One thing at a time; Law 6 — Iterate means one change
+- **Severity:** Medium — wastes time, may introduce bugs
+
+### 1.3 Under-Delivery
+- **Description:** Agent delivers less than requested but reports completion
+- **Trigger:** Complex tasks where the agent loses track of requirements
+- **Example:** Implementing 3 of 5 requested endpoints and saying "done"
+- **Prevention:** Law 4 — Verify against the original request before reporting
+- **Severity:** High — user trusts the completion report
+
+---
+
+## Category 2: Execution Failures
+
+Failures in how the agent carries out the work.
+
+### 2.1 Blind Execution
+- **Description:** Agent writes code without researching constraints
+- **Trigger:** Any task involving external APIs, libraries, or services
+- **Example:** Setting polling interval to 10s on an API with 100 req/hour limit
+- **Prevention:** Law 1 — Research rate limits, constraints, and existing implementations
+- **Severity:** Critical — can cause production incidents
+
+### 2.2 Compounding Changes
+- **Description:** Agent makes multiple changes before testing any of them
+- **Trigger:** Refactoring, bug fixes, feature additions
+- **Example:** Changing the ORM, query logic, and pagination in one commit
+- **Prevention:** Law 6 — One change, verify, next change
+- **Severity:** High — makes debugging extremely difficult
+
+### 2.3 Session Explosion
+- **Description:** Agent spawns parallel tasks that conflict or duplicate work
+- **Trigger:** Tasks that seem decomposable
+- **Example:** Launching 3 different caching approaches simultaneously
+- **Prevention:** Law 3 — One thing at a time; pick the simplest approach
+- **Severity:** High — multiplies complexity and failure points
+
+### 2.4 Workaround Cascades
+- **Description:** Agent encounters an error and builds around it instead of fixing it
+- **Trigger:** Errors that seem hard to fix directly
+- **Example:** Adding a proxy to avoid CORS instead of adding the header server-side
+- **Prevention:** Law 4 — Report errors honestly; Law 1 — Research the actual fix
+- **Severity:** High — creates architectural debt
+
+---
+
+## Category 3: Verification Failures
+
+Failures in confirming the work is correct.
+
+### 3.1 Premature Completion
+- **Description:** Agent reports "done" without running the code
+- **Trigger:** Any task completion
+- **Example:** "The function is implemented!" — but it has a syntax error
+- **Prevention:** Law 4 — Run it, check output, confirm build passes
+- **Severity:** Critical — user trusts the agent's report
+
+### 3.2 Assumed Success
+- **Description:** Agent checks partial output and assumes the rest is correct
+- **Trigger:** Long-running tasks, tasks with multiple outputs
+- **Example:** Checking that the API returns 200 but not checking the response body
+- **Prevention:** Law 4 — Check the actual result, not a proxy for the result
+- **Severity:** High — bugs hide in unchecked outputs
+
+### 3.3 Confirmation Bias
+- **Description:** Agent interprets ambiguous output as success
+- **Trigger:** Tasks where "correct" is subjective or loosely defined
+- **Example:** "The output looks right" when it's missing a field
+- **Prevention:** Law 2 — Define verification criteria in the plan
+- **Severity:** Medium — subtle bugs that emerge later
+
+---
+
+## Category 4: Communication Failures
+
+Failures in how the agent reports its work.
+
+### 4.1 Silent Error Masking
+- **Description:** Agent encounters errors and doesn't mention them
+- **Trigger:** Errors during execution that the agent works around
+- **Example:** Import fails, agent rewrites the import path without mentioning it
+- **Prevention:** Law 4 — Report all errors, even ones you fix
+- **Severity:** High — user doesn't know about fragile workarounds
+
+### 4.2 Overconfident Reporting
+- **Description:** Agent presents uncertain results as definitive
+- **Trigger:** Complex tasks with partial success
+- **Example:** "Everything works!" when 2 of 5 tests are skipped
+- **Prevention:** Law 4 — Specific verification, not general claims
+- **Severity:** High — erodes trust when issues surface later
+
+### 4.3 Missing Context
+- **Description:** Agent completes work but doesn't explain trade-offs or limitations
+- **Trigger:** Tasks with multiple valid approaches
+- **Example:** Choosing in-memory cache without mentioning it won't survive restarts
+- **Prevention:** Law 5 — Reflect on decisions and trade-offs
+- **Severity:** Medium — user makes uninformed decisions
+
+---
+
+## Category 5: Learning Failures
+
+Failures in adapting from experience.
+
+### 5.1 Repeated Mistakes
+- **Description:** Agent makes the same error across sessions
+- **Trigger:** Any error that isn't captured in system instructions
+- **Example:** Hitting the same rate limit three sessions in a row
+- **Prevention:** Law 5 — Reflect and generate rules for the system prompt
+- **Severity:** High — wastes time and erodes trust
+
+### 5.2 Pattern Blindness
+- **Description:** Agent doesn't recognize that a current situation matches a past one
+- **Trigger:** Similar tasks in different contexts
+- **Example:** Over-engineering a feature after learning not to in a different project
+- **Prevention:** Law 5 — Generate transferable rules, not situation-specific notes
+- **Severity:** Medium — slower convergence on good behavior
+
+---
+
+## Cross-Reference: Laws to Failures
+
+| Law | Prevents |
+|-----|----------|
+| Law 1: Research | 2.1, 2.4, 3.3 |
+| Law 2: Plan | 1.1, 1.3, 3.3 |
+| Law 3: One Thing | 1.1, 1.2, 2.3 |
+| Law 4: Verify | 1.3, 3.1, 3.2, 4.1, 4.2 |
+| Law 5: Reflect | 4.3, 5.1, 5.2 |
+| Law 6: Iterate | 1.2, 2.2 |
+
+Every failure mode maps to at least one law. Every law prevents at least two failure modes.

package/docs/integration-guide.md

@@ -0,0 +1,105 @@
+# Integration Guide
+
+## Fast path
+
+```bash
+npx continuous-improvement install
+```
+
+If auto-detect does not hit the right target:
+
+```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
+```
+
+## Targets
+
+### Claude Code
+
+Project-level:
+
+```bash
+npx continuous-improvement install --claude
+```
+
+Global:
+
+```bash
+npx continuous-improvement install --claude --global
+```
+
+This appends the continuous-improvement rules to `CLAUDE.md`.
+
+### Codex / AGENTS.md flows
+
+```bash
+npx continuous-improvement install --codex
+```
+
+This appends the rules to `AGENTS.md` in the current project.
+
+### Cursor
+
+```bash
+npx continuous-improvement install --cursor
+```
+
+This appends the rules to `.cursorrules`.
+
+### OpenClaw skill
+
+```bash
+npx continuous-improvement install --openclaw
+```
+
+This installs:
+
+```text
+~/.openclaw/skills/continuous-improvement/SKILL.md
+```
+
+### ChatGPT
+
+```bash
+npx continuous-improvement install --chatgpt
+```
+
+This prints the exact text to paste into ChatGPT Custom Instructions.
+
+## Uninstall
+
+```bash
+npx continuous-improvement uninstall --claude
+npx continuous-improvement uninstall --codex
+npx continuous-improvement uninstall --cursor
+npx continuous-improvement uninstall --openclaw
+```
+
+## Manual fallback
+
+Use these files directly if you do not want the installer:
+
+- `prompts/coding-agent.md`
+- `prompts/core.md`
+- `prompts/minimal.md`
+- `skills/continuous-improvement/SKILL.md`
+
+## How to verify it worked
+
+Give the agent a task like:
+
+> Add a caching layer to the API.
+
+If continuous-improvement is working, the agent should:
+
+1. research first
+2. define scope and anti-scope
+3. state verification steps
+4. execute one thing at a time
+5. reflect after the task
+
+If it skips straight to coding and declares victory without checks, it is not installed correctly.

package/docs/philosophy.md

@@ -0,0 +1,127 @@
+# Philosophy: Why continuous-improvement Works
+
+---
+
+## The Core Insight
+
+AI agents fail not because they lack capability, but because they lack discipline.
+
+A language model trained on code completions will complete things. That's what it's optimized for. Whether the completion is correct, scoped, or verified is orthogonal to the training signal.
+
+continuous-improvement doesn't add capability. It adds structure. And structure, it turns out, is the bottleneck.
+
+---
+
+## Structure Beats Intelligence
+
+Consider two agents:
+
+**Agent A:** State-of-the-art model, unlimited context, no framework.
+**Agent B:** Previous-gen model, standard context, continuous-improvement installed.
+
+Give both the task: "Fix the login bug."
+
+Agent A will investigate, find the bug, fix it, refactor the surrounding code, add error handling, update the tests, add a new feature it noticed was missing, and report "done" — having introduced two new bugs in the code it didn't need to touch.
+
+Agent B will investigate, find the bug, fix it, verify the fix, and stop. It will report what it found, what it changed, and what it didn't change.
+
+Agent B ships. Agent A creates a follow-up ticket.
+
+This is not hypothetical. This happens every day in codebases using AI agents.
+
+---
+
+## Why Agents Over-Execute
+
+Three forces drive agents to do too much:
+
+### 1. Completion Bias
+
+Language models are trained to complete. An open-ended task is an invitation to keep going. "Add caching" becomes "add caching, monitoring, warming, invalidation, distributed sync, and a management CLI" because each addition is a natural completion of the previous one.
+
+The cure: anti-scope. Explicitly stating what you will NOT build creates a boundary that completion bias can't cross.
+
+### 2. Helpfulness Gradient
+
+Agents are trained to be helpful. More features feels more helpful. "While I'm here, I'll also..." is the agent equivalent of a developer gold-plating a feature.
+
+The cure: one thing at a time. When the task is singular, the helpfulness gradient points at completing that task, not expanding it.
+
+### 3. Verification Avoidance
+
+Verification is boring. The agent has already "solved" the problem in its internal representation. Running the build, checking the output, and confirming the results is mechanical work that doesn't exercise the model's strengths.
+
+The cure: making verification a non-negotiable step. "Done" has a checklist, and the checklist includes actual verification — not assumed verification.
+
+---
+
+## Why Reflection Matters
+
+Agents don't learn between sessions. Your context window is their entire universe. When the session ends, the lessons vanish.
+
+This is a fundamental limitation that no amount of model improvement will fix. Even with perfect memory, an agent that doesn't explicitly reflect won't extract transferable lessons.
+
+Structured reflection solves this by creating artifacts:
+
+```
+## Reflection
+- What worked: In-memory cache was simpler than Redis for single-server
+- What failed: nothing
+- What I'd do differently: nothing
+- Rule to add: For single-server deployments, start with in-memory. Upgrade to Redis only when you add a second server.
+```
+
+That "rule to add" becomes a system prompt addition, a CLAUDE.md entry, or a team convention. The agent that reflects today fails differently tomorrow. The agent that doesn't reflects makes the same mistake forever.
+
+---
+
+## The Loop Is the Product
+
+```
+Research → Plan → Execute (one thing) → Verify → Reflect → Iterate
+```
+
+This loop is not novel. It's a formalization of what good engineers do naturally:
+- Understand the problem before solving it
+- Define what you're building and what you're not
+- Do one thing, check it works, do the next thing
+- Confirm the result before claiming victory
+- Learn from the experience
+
+The novelty is applying it to AI agents — entities that are powerful enough to skip every step and confident enough to never notice.
+
+---
+
+## Why "One Thing at a Time" Is the Most Important Law
+
+If you could only install one law, install Law 3.
+
+Every other failure mode is amplified by doing multiple things at once:
+- Feature sprawl is multiple features without verification
+- Compounding iteration is multiple changes without testing
+- Session explosion is multiple approaches without completion
+- Silent failure is multiple workarounds without reporting
+
+"One thing at a time" is the circuit breaker. It limits the blast radius of every mistake to exactly one change. When something breaks, you know what caused it. When something works, you know what to keep.
+
+It's slower per-step. It's faster to correct completion. Always.
+
+---
+
+## Design Principles
+
+### Opinionated Over Flexible
+
+"It depends" doesn't belong in a system prompt. Agents need clear rules, not frameworks for making decisions. The 6 laws are deliberately prescriptive.
+
+### Practical Over Theoretical
+
+Every law exists because its absence caused a real failure. No law was added for theoretical completeness or because it "seemed right."
+
+### Minimal Over Comprehensive
+
+The prompt must fit in a context window alongside actual work. Every word competes with code, docs, and conversation for attention. The laws are as short as they can be while remaining unambiguous.
+
+### Universal Over Tool-Specific
+
+The core prompt works in any agent. The variants optimize for specific tools but the principles are the same. Research, plan, execute, verify, reflect, iterate. The loop doesn't care about your IDE.