/self-improve

name: self-improve
description: Bootstrap and operate a self-improving agent workspace. Scaffolds .learnings/ and memory/ directories, captures errors and learnings during a session, detects recurring patterns, recalls verified lessons, and promotes stable entries to scoped rule files (.claude/rules/ or ~/.claude/rules/). Also implements the Proactive Agent pillars — WAL protocol, working buffer, SESSION-STATE, daily notes, VBR, VFM scoring, ADL decision logic, heartbeat, and reverse prompting. Use when asked to "remember this lesson", "set up agent memory", "log that error", "what did we learn about X", "promote learnings", "revoke that rule", "capture session state", or "enable proactive mode".
argument-hint: "[init [global|local]|log [LRN|ERR|FEAT]|recall <terms>|promote <ID>|revoke <ID> <reason>|migrate [global|local]|status|resume|review|state]"
title: "Self-Improve Command"
sidebar_label: "self-improve"
custom_edit_url: null

Bootstrap and operate a self-improving, proactive agent workspace.

Path Resolution (applies to all modes)

Before executing any mode, resolve `LEARNINGS_BASE`:

1. If mode is `init global` → use `~/.claude/` 2. Else if mode is `init local` → use `.` (current working directory) 3. Else if `~/.claude/.learnings/` exists → use `~/.claude/` as base (global setup) 4. Else if `.learnings/` exists in the current working directory → use `.` as base (project setup) 5. Else if mode is `init` (no argument) → ask the user to choose (see init mode below) 6. Else → default to `~/.claude/`, create the directories, and inform the user that global setup was auto-created

`~/.claude/` resolves consistently across all platforms (macOS, Linux, Windows) because Claude Code uses `os.homedir()` for `~`. On Windows this maps to `C:\Users\<you>\.claude\` — no manual path adjustment needed.

All path references in every mode below use `LEARNINGS_BASE` as the root:

| Logical path | Resolved path (global) | Resolved path (project) | |---|---|---| | `.learnings/LEARNINGS.md` | `~/.claude/.learnings/LEARNINGS.md` | `.learnings/LEARNINGS.md` | | `.learnings/ERRORS.md` | `~/.claude/.learnings/ERRORS.md` | `.learnings/ERRORS.md` | | `.learnings/FEATURE_REQUESTS.md` | `~/.claude/.learnings/FEATURE_REQUESTS.md` | `.learnings/FEATURE_REQUESTS.md` | | `memory/working-buffer.md` | `~/.claude/memory/working-buffer.md` | `memory/working-buffer.md` | | `memory/SESSION-STATE.md` | `~/.claude/memory/SESSION-STATE.md` | `memory/SESSION-STATE.md` | | `memory/YYYY-MM-DD.md` | `~/.claude/memory/YYYY-MM-DD.md` | `memory/YYYY-MM-DD.md` | | `.learnings/.pending-errors.log` | `~/.claude/.learnings/.pending-errors.log` | `.learnings/.pending-errors.log` |

Promoted rules follow the **entry's** `Scope`, not `LEARNINGS_BASE`: a global lesson lands in `~/.claude/rules/<domain>.md`, a project lesson in `.claude/rules/<domain>.md`. The opt-in targets (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`) are always project-local. Only the capture files follow `LEARNINGS_BASE`.

Reference: `references/agent-self-improve.md` → Global vs project scope

Helper Script

Modes below run `bash ~/.claude/scripts/learnings.sh <subcommand>` for anything deterministic (with the `platform-guardrails` plugin enabled, `learnings.sh` is on `PATH` and can be run directly): reading entries, validating them, checking dates, changing a status. If the script is missing, say so once, offer to install it (`init global` step 5), and do the step by hand. Exit code 3 means another session holds `.learnings/.drain.lock`. Wait a few seconds and retry once. Exit code 4 means the helper refused: the entry doesn't exist, or it exists and is not eligible. `promote` also refuses on the wrong status, missing or invalid provenance, a stale or expired entry, an inferred source without `--allow-inferred`, another project's scope, a `Paths` conflict with the target, and an entry already promoted elsewhere; `unpromote` refuses when no rule carries the entry's marker. Never guess which one it was: the helper prints the reason on stderr, so relay that line.

Reference: `references/agent-self-improve.md` → Helper script

Mode: init global

Scaffold the global workspace under `~/.claude/` — learnings persist across all projects.

/platform-skills:self-improve init global

Steps: 1. Set `LEARNINGS_BASE=~/.claude/` 2. If `~/.claude/.learnings/` already exists: report current state, list existing files, and stop — do not overwrite 3. Create the directory structure:

   ~/.claude/.learnings/
     LEARNINGS.md
     ERRORS.md
     FEATURE_REQUESTS.md
   ~/.claude/memory/
     working-buffer.md
     SESSION-STATE.md

4. Seed each file with the correct header and an example entry marked `Status: example` 5. **On Claude Code, offer the plugin first:** `claude plugin install platform-guardrails@platform-skills` wires all four hooks from the plugin and puts `learnings.sh` on `PATH`, and plugin updates deliver fixes to the scripts. If the user takes it, skip the rest of this step, and make sure `~/.claude/settings.json` has no self-improve hooks left (both wirings at once would capture every event twice). Otherwise, detect the user's platform and offer to wire all four hooks (`SessionStart`, `SessionEnd`, `PostToolUseFailure`, `PreCompact`) in `~/.claude/settings.json`:

• **macOS / Linux / WSL / Git Bash** → `self-improve-hook.sh` with the `session-start`, `session-end`, `tool-failure` and `precompact` subcommands; point to `settings.json.example`
• **Windows native (PowerShell)** → `self-improve-hook.ps1`, same four subcommands; point to `settings-windows.json.example`, and have the user replace the literal `C:\Users\alex` with their own profile path
• **Alpine or minimal Linux** → same as macOS/Linux but remind the user to install bash first: `apk add bash`
• Also copy `examples/agent-self-improve/scripts/learnings.sh` to `~/.claude/scripts/` and `chmod +x` it. `log`, `recall`, `review`, `status`, `promote` and