claudenv 1.1.0 → 1.2.1

package/README.md

@@ -27,15 +27,18 @@ Claude AI will:
 2. Detect your tech stack, frameworks, and tooling
 3. Ask you about the project (description, deployment, conventions)
 4. Generate all documentation files
-5. Install slash commands for ongoing maintenance
+5. Search the [MCP Registry](https://registry.modelcontextprotocol.io) and configure MCP servers
+6. Install slash commands for ongoing maintenance
 
-**Step 3.** You now have three commands available in Claude Code:
+You now have five commands available in Claude Code:
 
 | Command | What it does |
 |---------|-------------|
 | `/init-docs` | Regenerate documentation from scratch |
 | `/update-docs` | Scan for changes and propose updates |
 | `/validate-docs` | Check that documentation is complete and correct |
+| `/setup-mcp` | Recommend and configure MCP servers |
+| `/improve` | Analyze and make one improvement |
 
 ## What Gets Generated
 
@@ -43,6 +46,7 @@ Claude AI will:
 your-project/
 ├── CLAUDE.md                              # Project overview, commands, architecture
 ├── _state.md                              # Session memory (decisions, focus, issues)
+├── .mcp.json                              # MCP server configuration
 └── .claude/
     ├── rules/
     │   ├── code-style.md                  # Coding conventions (scoped by file paths)
@@ -52,7 +56,9 @@ your-project/
     ├── commands/
     │   ├── init-docs.md                   # /init-docs
     │   ├── update-docs.md                 # /update-docs
-    │   └── validate-docs.md              # /validate-docs
+    │   ├── validate-docs.md              # /validate-docs
+    │   ├── setup-mcp.md                  # /setup-mcp
+    │   └── improve.md                    # /improve
     ├── skills/
     │   └── doc-generator/                 # Auto-triggers when docs need updating
     └── agents/
@@ -68,6 +74,145 @@ your-project/
 | `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, subagents, git discipline |
 | `.claude/rules/code-style.md` | Language and framework-specific coding conventions |
 | `.claude/rules/testing.md` | Test framework patterns and commands |
+| `.mcp.json` | MCP server configuration with `${ENV_VAR}` placeholders |
+
+## MCP Server Recommendations
+
+`/claudenv` automatically recommends MCP servers based on your tech stack. You can also run `/setup-mcp` independently at any time.
+
+**How it works:**
+
+1. Claude analyzes your project's dependencies, databases, cloud services, and tools
+2. Searches the [official MCP Registry](https://registry.modelcontextprotocol.io) for matching servers
+3. Verifies trust via npm download counts (filters out servers with <100 monthly downloads)
+4. Presents recommendations grouped as **Essential** / **Recommended** / **Optional**
+5. Generates `.mcp.json` with selected servers
+
+**Example output** (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "env": {}
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres@latest", "${POSTGRES_CONNECTION_STRING}"],
+      "env": {}
+    }
+  }
+}
+```
+
+Secrets use `${ENV_VAR}` placeholders — configure them with:
+
+```bash
+claude config set env.POSTGRES_CONNECTION_STRING "postgresql://..."
+```
+
+`.mcp.json` is safe to commit — it never contains actual secrets.
+
+Run `/setup-mcp --force` to auto-select Essential + Recommended servers without prompting.
+
+## Iterative Improvement Loop
+
+`claudenv loop` spawns Claude Code in headless mode to analyze and improve your project iteratively. Each run creates a git safety tag so you can always rollback.
+
+**How it works:**
+
+1. **Planning** (iteration 0) — Claude analyzes the project and generates `.claude/improvement-plan.md` with prioritized hypotheses
+2. **Execution** (iterations 1-N) — each iteration picks the top unfinished item from the plan, implements it, runs tests, and commits
+3. **Convergence** — the loop stops when the plan is complete, max iterations are reached, or the loop detects it's stuck
+
+**Usage:**
+
+```bash
+claudenv loop                              # Interactive, pauses between iterations
+claudenv loop --trust                      # Full trust, no pauses, no permission prompts
+claudenv loop --trust -n 5                 # 5 iterations in full trust
+claudenv loop --goal "add test coverage"   # Focused improvement
+claudenv loop --trust --model opus -n 3    # Use Opus, 3 iterations
+claudenv loop --budget 1.00 -n 10          # Budget cap per iteration
+claudenv loop --rollback                   # Undo all loop changes
+```
+
+| Flag | Description |
+|------|-------------|
+| `-n, --iterations <n>` | Max iterations (default: unlimited) |
+| `--trust` | Full trust mode — no pauses, skip permission prompts |
+| `--goal <text>` | Focus area for improvements |
+| `--profile <name>` | Autonomy profile: safe, moderate, full, ci |
+| `--no-pause` | Don't pause between iterations |
+| `--max-turns <n>` | Max agentic turns per iteration (default: 30) |
+| `--model <model>` | Model to use (default: sonnet) |
+| `--budget <usd>` | Budget cap per iteration in USD |
+| `-d, --dir <path>` | Target project directory |
+| `--allow-dirty` | Allow running with uncommitted changes |
+| `--rollback` | Undo all changes from the most recent loop |
+| `--unsafe` | Remove default tool restrictions |
+
+**Git safety:** Before the first iteration, a `claudenv-loop-<timestamp>` git tag is created. Each iteration commits separately. Use `claudenv loop --rollback` to reset everything, or cherry-pick individual commits.
+
+**Single iteration:** Use `/improve` inside Claude Code for a one-shot improvement without the full loop.
+
+## Autonomous Agent Mode
+
+`claudenv autonomy` configures Claude Code for autonomous operation with predefined security profiles. Inspired by [trailofbits/claude-code-config](https://github.com/trailofbits/claude-code-config).
+
+**Usage:**
+
+```bash
+claudenv autonomy                          # Interactive profile selection
+claudenv autonomy --profile moderate       # Non-interactive, writes files directly
+claudenv autonomy --profile moderate -y    # Same — -y only needed for profile selection
+claudenv autonomy --profile ci --dry-run   # Preview generated files
+claudenv autonomy --profile full           # Full autonomy — requires typing "full" to confirm
+claudenv autonomy --profile full --yes     # Full autonomy, skip confirmation
+```
+
+### Profiles
+
+| Profile | Description | Permissions | Credentials |
+|---------|-------------|-------------|-------------|
+| `safe` | Read-only + limited bash | Allow-list only | Blocked |
+| `moderate` | Full dev with deny-list | Allow + deny lists | Blocked |
+| `full` | Unrestricted + audit logging | `--dangerously-skip-permissions` | Warn-only |
+| `ci` | Headless CI/CD (50 turns, $5 budget) | `--dangerously-skip-permissions` | Warn-only |
+
+All profiles hard-block `rm -rf`, force push to main/master, and `sudo`.
+
+### Generated files
+
+```
+.claude/
+├── settings.json               # Permissions + hooks config
+├── hooks/
+│   ├── pre-tool-use.sh         # PreToolUse guard (blocks dangerous ops)
+│   └── audit-log.sh            # PostToolUse audit → audit-log.jsonl
+└── aliases.sh                  # Shell aliases: claude-safe, claude-yolo, claude-ci, claude-local
+```
+
+CI profile also generates `.github/workflows/claude-ci.yml`.
+
+### Loop integration
+
+Use `--profile` with `claudenv loop` to apply profile settings:
+
+```bash
+claudenv loop --profile moderate --goal "add types"   # Uses profile's deny-list
+claudenv loop --profile ci -n 5                       # CI defaults: 50 turns, $5 budget
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --profile <name>` | Profile: safe, moderate, full, ci |
+| `-d, --dir <path>` | Project directory (default: `.`) |
+| `--overwrite` | Overwrite existing files |
+| `-y, --yes` | Skip prompts |
+| `--dry-run` | Preview without writing |
 
 ## Tech Stack Detection
 
@@ -83,14 +228,21 @@ Claude AI reads your actual code, but the following are auto-detected for contex
 ## CLI Reference
 
 ```
-claudenv                Install /claudenv into ~/.claude/ (default)
-claudenv install        Same as above (explicit)
-claudenv install -f     Reinstall, overwriting existing files
-claudenv uninstall      Remove /claudenv from ~/.claude/
-claudenv init [dir]     Legacy: static analysis + terminal prompts (no AI)
-claudenv init -y        Legacy: skip prompts, auto-detect everything
-claudenv generate       Templates only, no scaffold
-claudenv validate       Check documentation completeness
+claudenv                  Install /claudenv into ~/.claude/ (default)
+claudenv install          Same as above (explicit)
+claudenv install -f       Reinstall, overwriting existing files
+claudenv uninstall        Remove /claudenv from ~/.claude/
+claudenv init [dir]       Legacy: static analysis + terminal prompts (no AI)
+claudenv init -y          Legacy: skip prompts, auto-detect everything
+claudenv generate         Templates only, no scaffold
+claudenv validate         Check documentation completeness
+claudenv loop             Iterative improvement loop (spawns Claude)
+claudenv loop --trust     Full trust mode, no pauses
+claudenv loop --profile moderate  Use autonomy profile in loop
+claudenv loop --rollback  Undo all loop changes
+claudenv autonomy         Configure autonomous agent mode (interactive)
+claudenv autonomy -p moderate     Apply moderate profile
+claudenv autonomy -p ci --dry-run Preview CI config without writing
 ```
 
 ## Alternative: Run Without Installing

package/bin/cli.js

@@ -2,7 +2,7 @@
 
 import { Command } from 'commander';
 import { resolve, join } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile, chmod } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 import { detectTechStack } from '../src/detector.js';
@@ -10,6 +10,9 @@ import { generateDocs, writeDocs, installScaffold } from '../src/generator.js';
 import { validateClaudeMd, validateStructure, crossReferenceCheck } from '../src/validator.js';
 import { runExistingProjectFlow, runColdStartFlow, buildDefaultConfig } from '../src/prompts.js';
 import { installGlobal, uninstallGlobal } from '../src/installer.js';
+import { runLoop, rollback, checkClaudeCli } from '../src/loop.js';
+import { generateAutonomyConfig, printSecuritySummary, getFullModeWarning } from '../src/autonomy.js';
+import { getProfile, listProfiles } from '../src/profiles.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgJson = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -113,6 +116,95 @@ program
     }
   });
 
+// --- loop ---
+program
+  .command('loop')
+  .description('Iterative improvement loop — spawn Claude to analyze and improve the project')
+  .option('-n, --iterations <n>', 'Max iterations (default: unlimited)', parseInt)
+  .option('--trust', 'Full trust mode — no pauses, no permission prompts')
+  .option('--goal <text>', 'Focus area for improvements')
+  .option('--pause', 'Pause between iterations (default: on unless --trust)')
+  .option('--no-pause', 'Do not pause between iterations')
+  .option('--max-turns <n>', 'Max agentic turns per iteration (default: 30)', parseInt)
+  .option('--model <model>', 'Model to use (default: sonnet)')
+  .option('--budget <usd>', 'Budget cap per iteration in USD', parseFloat)
+  .option('-d, --dir <path>', 'Target project directory')
+  .option('--allow-dirty', 'Allow running with uncommitted git changes')
+  .option('--rollback', 'Undo all changes from the most recent loop run')
+  .option('--unsafe', 'Remove default tool restrictions (allows rm -rf)')
+  .option('--worktree', 'Run each iteration in an isolated git worktree')
+  .option('--profile <name>', 'Autonomy profile: safe, moderate, full, ci')
+  .action(async (opts) => {
+    // --- Rollback mode ---
+    if (opts.rollback) {
+      await rollback({ cwd: opts.dir ? resolve(opts.dir) : process.cwd() });
+      return;
+    }
+
+    // --- Pre-flight: check Claude CLI ---
+    const cli = checkClaudeCli();
+    if (!cli.installed) {
+      console.error('\n  Error: Claude CLI not found.');
+      console.error('  Install it from https://docs.anthropic.com/en/docs/claude-code\n');
+      process.exit(1);
+    }
+    console.log(`\n  claudenv loop v${pkgJson.version}`);
+    console.log(`  Claude CLI: ${cli.version}`);
+
+    // --- Load profile if specified ---
+    let profileDefaults = {};
+    if (opts.profile) {
+      const profile = getProfile(opts.profile);
+      profileDefaults = {
+        trust: profile.skipPermissions,
+        disallowedTools: profile.disallowedTools,
+        maxTurns: profile.maxTurns,
+        budget: profile.maxBudget,
+      };
+      console.log(`  Profile: ${profile.name} — ${profile.description}`);
+    }
+
+    // --- Config summary ---
+    const cwd = opts.dir ? resolve(opts.dir) : process.cwd();
+    const trust = opts.trust || profileDefaults.trust || false;
+    const pause = opts.pause !== undefined ? opts.pause : !trust;
+
+    console.log(`  Directory: ${cwd}`);
+    console.log(`  Mode: ${trust ? 'full trust (--dangerously-skip-permissions)' : 'interactive'}`);
+    if (opts.worktree) console.log(`  Worktree: enabled (each iteration in isolated worktree)`);
+    if (opts.iterations) console.log(`  Max iterations: ${opts.iterations}`);
+    if (opts.goal) console.log(`  Goal: ${opts.goal}`);
+    if (opts.model) console.log(`  Model: ${opts.model}`);
+    if (opts.budget || profileDefaults.budget) console.log(`  Budget: $${opts.budget || profileDefaults.budget}/iteration`);
+    if (opts.maxTurns || profileDefaults.maxTurns) console.log(`  Max turns: ${opts.maxTurns || profileDefaults.maxTurns}`);
+
+    await runLoop({
+      iterations: opts.iterations,
+      trust,
+      goal: opts.goal,
+      pause,
+      maxTurns: opts.maxTurns || profileDefaults.maxTurns || 30,
+      model: opts.model,
+      budget: opts.budget || profileDefaults.budget,
+      cwd,
+      allowDirty: opts.allowDirty || false,
+      unsafe: opts.unsafe || false,
+      worktree: opts.worktree || false,
+      disallowedTools: profileDefaults.disallowedTools,
+    });
+  });
+
+// --- autonomy ---
+program
+  .command('autonomy')
+  .description('Configure autonomous agent mode with safety guardrails')
+  .option('-p, --profile <name>', 'Profile: safe, moderate, full, ci')
+  .option('-d, --dir <path>', 'Project directory', '.')
+  .option('--overwrite', 'Overwrite existing files')
+  .option('-y, --yes', 'Skip prompts')
+  .option('--dry-run', 'Preview without writing')
+  .action(runAutonomy);
+
 // =============================================
 // Install / Uninstall
 // =============================================
@@ -263,4 +355,81 @@ function printValidation(label, result) {
   }
 }
 
+// =============================================
+// Autonomy
+// =============================================
+async function runAutonomy(opts) {
+  const { select, input } = await import('@inquirer/prompts');
+  const projectDir = resolve(opts.dir);
+
+  console.log(`\n  claudenv autonomy v${pkgJson.version}\n`);
+
+  // --- Profile selection ---
+  let profileName = opts.profile;
+  if (!profileName && !opts.yes) {
+    const profiles = listProfiles();
+    profileName = await select({
+      message: 'Select autonomy profile:',
+      choices: profiles.map((p) => ({
+        name: `${p.name} — ${p.description}`,
+        value: p.name,
+      })),
+    });
+  } else if (!profileName) {
+    profileName = 'moderate';
+  }
+
+  // --- Full mode confirmation ---
+  if (profileName === 'full') {
+    console.log(getFullModeWarning());
+    if (!opts.yes) {
+      const confirm = await input({ message: 'Type "full" to confirm:' });
+      if (confirm.trim() !== 'full') {
+        console.log('  Cancelled.\n');
+        return;
+      }
+    } else {
+      console.log('  --yes flag set, proceeding without confirmation.\n');
+    }
+  }
+
+  // --- Generate files ---
+  const { files, profile } = await generateAutonomyConfig(profileName, projectDir);
+
+  printSecuritySummary(profile);
+
+  if (opts.dryRun) {
+    console.log('  Dry run — files that would be generated:\n');
+    for (const f of files) {
+      console.log(`  ── ${f.path} ──`);
+      console.log(f.content);
+    }
+    return;
+  }
+
+  // --- Write files ---
+  const { written, skipped } = await writeDocs(projectDir, files, {
+    overwrite: opts.overwrite || false,
+  });
+
+  // Make hook scripts executable
+  for (const f of files) {
+    if (f.path.endsWith('.sh')) {
+      try {
+        await chmod(join(projectDir, f.path), 0o755);
+      } catch { /* ignore */ }
+    }
+  }
+
+  printFileResults(written, skipped);
+
+  console.log(`
+  Next steps:
+    1. Review .claude/settings.json
+    2. Source aliases: source .claude/aliases.sh
+    3. ${profile.skipPermissions ? 'Run: claude --dangerously-skip-permissions' : 'Run: claude'}
+    4. git add .claude/ && git commit -m "Add autonomy config (${profileName})"
+`);
+}
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudenv",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "One command to integrate Claude Code into any project — installs /claudenv command for AI-powered documentation generation",
   "type": "module",
   "bin": {

package/scaffold/.claude/agents/hypothesis-tester.md

@@ -0,0 +1,22 @@
+---
+name: hypothesis-tester
+description: Tests implementation hypotheses in isolation. Use when exploring risky refactors, alternative approaches, or when the current approach might need rollback.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+---
+
+You are testing an implementation hypothesis in an isolated git worktree.
+
+## Your workflow
+1. Read the parent branch context (goal, constraints, current state)
+2. Implement the hypothesis
+3. Run tests to validate
+4. If tests pass — commit with descriptive message, report SUCCESS
+5. If tests fail — report FAILURE with analysis of why, do NOT commit broken code
+
+## Output format
+Report exactly one of:
+- `HYPOTHESIS_SUCCESS: <summary of what worked and why>`
+- `HYPOTHESIS_FAILURE: <summary of what failed and why>`
+
+The parent agent will decide whether to merge your worktree branch.

package/scaffold/.claude/agents/rollback-analyzer.md

@@ -0,0 +1,22 @@
+---
+name: rollback-analyzer
+description: Analyzes past hypothesis branches to understand what was tried and why it failed. Use before retrying a failed approach.
+tools: Read, Glob, Grep, Bash
+model: haiku
+---
+
+You analyze past hypothesis branches to help the parent agent avoid repeating mistakes.
+
+## Your workflow
+1. List branches: `git branch -l "claudenv/*"`
+2. For each relevant branch, show: `git log --oneline <parent>..claudenv/<name>`
+3. Read key changed files: `git diff <parent>...claudenv/<name> --stat`
+4. Summarize: what was tried, what failed, what can be learned
+
+## Output format
+For each hypothesis branch:
+- **Branch:** claudenv/<name>
+- **Goal:** <extracted from commit messages>
+- **Changes:** <file summary>
+- **Result:** SUCCESS/FAILURE
+- **Lesson:** <what to do differently>

package/scaffold/.claude/commands/improve.md

@@ -0,0 +1,60 @@
+---
+description: Analyze this project and make one high-impact improvement — fix bugs, add tests, improve code quality
+allowed-tools: Read, Write, Glob, Grep, Bash
+argument-hint: [area-to-improve]
+---
+
+# /improve — Single Improvement Iteration
+
+You are an expert software engineer. Your job is to analyze this project and make one high-impact improvement.
+
+## Step 1: Read Context
+
+Read these files if they exist:
+- `CLAUDE.md` — project overview and conventions
+- `_state.md` — session memory
+- `.claude/improvement-plan.md` — existing improvement plan (if any)
+
+## Step 2: Choose What to Improve
+
+**If `.claude/improvement-plan.md` exists:**
+- Read the plan and pick the top unfinished item from the "## Pending" section
+- If `$ARGUMENTS` is provided, use it as a focus area instead of the plan
+
+**If no plan exists:**
+- Analyze the project: read manifest files, scan source code, check test coverage
+- If `$ARGUMENTS` is provided, focus on that area
+- Identify the single highest-impact improvement you can make
+
+## Step 3: Implement the Change
+
+- Write the code changes
+- Add or update tests if applicable
+- Follow existing code style and conventions
+
+## Step 4: Verify
+
+- Run tests (if a test command is available)
+- Run linter (if configured)
+- Fix any issues found
+
+## Step 5: Update Plan
+
+If `.claude/improvement-plan.md` exists:
+- Move the completed item from "## Pending" to "## Completed"
+- Add the commit hash and notes about what was done
+- If you discovered new issues, add them to "## Pending"
+
+## Step 6: Commit and Report
+
+- Commit all changes with a descriptive message
+- Report:
+  - What you changed and why
+  - What tests were added/updated
+  - What's next (remaining plan items or suggested improvements)
+
+## Important Rules
+
+- Do NOT delete files unless the deletion IS the improvement
+- Make exactly ONE improvement per invocation
+- If there's nothing left to improve, output: NO_MORE_IMPROVEMENTS

package/scaffold/global/.claude/commands/claudenv.md

@@ -107,6 +107,7 @@ cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/scripts/valid
 cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/detection-patterns.md .claude/skills/doc-generator/templates/detection-patterns.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/mcp-servers.md .claude/skills/doc-generator/templates/mcp-servers.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/commands/setup-mcp.md .claude/commands/setup-mcp.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/commands/improve.md .claude/commands/improve.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/agents/doc-analyzer.md .claude/agents/doc-analyzer.md
 chmod +x .claude/skills/doc-generator/scripts/validate.sh
 ```
@@ -176,6 +177,7 @@ Created:
   + .claude/commands/update-docs.md
   + .claude/commands/validate-docs.md
   + .claude/commands/setup-mcp.md
+  + .claude/commands/improve.md
   + .claude/skills/doc-generator/
   + .claude/agents/doc-analyzer.md
   + .mcp.json (if MCP servers were configured)
@@ -185,6 +187,7 @@ Available commands:
   /update-docs    — Update docs when project changes
   /validate-docs  — Check documentation completeness
   /setup-mcp      — Add or update MCP server configuration
+  /improve        — Analyze and make one improvement
 
 Next steps:
   1. Review and edit CLAUDE.md

package/scaffold/global/.claude/skills/claudenv/SKILL.md

@@ -55,5 +55,6 @@ The following files are available for installation into projects at `~/.claude/s
 - `.claude/skills/doc-generator/scripts/validate.sh` — Bash validation script
 - `.claude/skills/doc-generator/templates/detection-patterns.md` — Detection reference
 - `.claude/commands/setup-mcp.md` — MCP server recommendation and setup
+- `.claude/commands/improve.md` — Single improvement iteration (used by claudenv loop)
 - `.claude/skills/doc-generator/templates/mcp-servers.md` — MCP registry reference
 - `.claude/agents/doc-analyzer.md` — Read-only analysis subagent

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/commands/improve.md

@@ -0,0 +1,60 @@
+---
+description: Analyze this project and make one high-impact improvement — fix bugs, add tests, improve code quality
+allowed-tools: Read, Write, Glob, Grep, Bash
+argument-hint: [area-to-improve]
+---
+
+# /improve — Single Improvement Iteration
+
+You are an expert software engineer. Your job is to analyze this project and make one high-impact improvement.
+
+## Step 1: Read Context
+
+Read these files if they exist:
+- `CLAUDE.md` — project overview and conventions
+- `_state.md` — session memory
+- `.claude/improvement-plan.md` — existing improvement plan (if any)
+
+## Step 2: Choose What to Improve
+
+**If `.claude/improvement-plan.md` exists:**
+- Read the plan and pick the top unfinished item from the "## Pending" section
+- If `$ARGUMENTS` is provided, use it as a focus area instead of the plan
+
+**If no plan exists:**
+- Analyze the project: read manifest files, scan source code, check test coverage
+- If `$ARGUMENTS` is provided, focus on that area
+- Identify the single highest-impact improvement you can make
+
+## Step 3: Implement the Change
+
+- Write the code changes
+- Add or update tests if applicable
+- Follow existing code style and conventions
+
+## Step 4: Verify
+
+- Run tests (if a test command is available)
+- Run linter (if configured)
+- Fix any issues found
+
+## Step 5: Update Plan
+
+If `.claude/improvement-plan.md` exists:
+- Move the completed item from "## Pending" to "## Completed"
+- Add the commit hash and notes about what was done
+- If you discovered new issues, add them to "## Pending"
+
+## Step 6: Commit and Report
+
+- Commit all changes with a descriptive message
+- Report:
+  - What you changed and why
+  - What tests were added/updated
+  - What's next (remaining plan items or suggested improvements)
+
+## Important Rules
+
+- Do NOT delete files unless the deletion IS the improvement
+- Make exactly ONE improvement per invocation
+- If there's nothing left to improve, output: NO_MORE_IMPROVEMENTS