/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, and promotes stable entries to project memory (CLAUDE.md, AGENTS.md, or references/). 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", "promote learnings", "capture session state", or "enable proactive mode".
argument-hint: "[init [global|local]|log [LRN|ERR|FEAT]|promote <ID>|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` |

Promotion targets (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`) always remain project-local regardless of scope — only the capture files follow `LEARNINGS_BASE`.

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

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. Detect the user's platform and offer to wire all three hooks in `~/.claude/settings.json`:

• **macOS / Linux / WSL / Git Bash** → bash scripts (`session-end.sh`, `session-start-reminder.sh`) + inline bash PostToolUse; point to `settings.json.example`
• **Windows native (PowerShell)** → PS1 scripts (`session-end.ps1`, `session-start-reminder.ps1`) + inline PowerShell PostToolUse; point to `settings-windows.json.example`
• **Alpine or minimal Linux** → same as macOS/Linux but remind the user to install bash first: `apk add bash`
• All scripts are in `examples/agent-self-improve/scripts/`; PostToolUse hook must use absolute path to `.pending-errors.log` (global setup)

6. Offer to create `~/.claude/CLAUDE.md` from the template at `examples/agent-self-improve/global-claude.md` 7. Print bootstrap summary:

   ✓ ~/.claude/.learnings/LEARNINGS.md        — positive learnings
   ✓ ~/.claude/.learnings/ERRORS.md           — mistakes and root causes
   ✓ ~/.claude/.learnings/FEATURE_REQUESTS.md — recurring unmet needs
   ✓ ~/.claude/memory/working-buffer.md       — WAL scratchpad and task state
   ✓ ~/.claude/memory/SESSION-STATE.md        — always-on session capture
   ✓ ~/.claude/memory/YYYY-MM-DD.md           — daily notes (created on first use)

8. Remind the user to run `/platform-skills:self-improve review` after a few sessions

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

---

Mode: init local

Scaffold a project-local workspace in the current working directory — learnings live in the repo.

/platform-skills:self-improve init local

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

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

4. Seed each file with the correct header and an example entry marked `Status: example` 5. Check `.gitignore` — ask the user:

• **Gitignore** (recommended for personal notes): add `.learnings/` and `memory/` to `.gitignore`
• **Commit**: leave untracked so the team can share and build on them; note that `memory/` daily notes grow fast

6. Offer to add hooks to `.claude/settings.json` (this project only):

• **PostToolUse** → inline command writing to `.learnings/.pending-errors.log` (relative path is safe here — hooks run from project root)
• Note: Stop and PreTool