# Improve Loop

> Autonomous improvement loop for any codebase. Uses git worktrees to run every experiment in isolation — the main branch is never touched until a winning change is explicitly merged. Reads .claude/autoimprove/config.md for the measurement suite, then iterates: create worktree → propose → implement in worktree → measure → merge if improved, delete if not → log → repeat.

- **Type:** Skill
- **Install:** `agentstack add skill-benmarte-autoimprove-improve-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [benmarte](https://agentstack.voostack.com/s/benmarte)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [benmarte](https://github.com/benmarte)
- **Source:** https://github.com/benmarte/autoimprove/tree/main/skills/improve-loop

## Install

```sh
agentstack add skill-benmarte-autoimprove-improve-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AutoImprove Loop Skill

Every experiment runs in an isolated git worktree. The main codebase is **never modified** during experiments. Only winning changes get squash-merged back.

```
Main branch ──────────────────────────────────── (never touched mid-session)
                 │              │
           experiment-001  experiment-002
           (kept ✅ → merge) (discarded ❌ → deleted)
```

---

## Pre-flight checks

Before the first iteration, print each check as you run it:

```
━━━ Pre-flight ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Config found
✓ Git working tree clean
✓ Base commit: abc1234
✓ Worktree directory ready
✓ Baseline score: XX/100
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

1. Check `.claude/autoimprove/config.md` exists. If not, stop: "Run /autoimprove:setup first."
2. Check git is available: `git status`
3. Confirm main working tree is clean. If not, stop: "Please commit or stash changes before running autoimprove."
4. Record the base commit: `git rev-parse HEAD` — all experiments branch from here.
5. Run the worktree skill's **setup** step to create `.claude/autoimprove/worktrees/` and update `.gitignore`.
6. Run the measure skill in the **main directory** to get the BASELINE score.
7. Report: "Baseline: XX/100. All experiments will run in isolated worktrees. Main branch is safe."

---

## Session Header

After pre-flight passes, write a session header to `.claude/autoimprove/log.md`:

```
## Session — [ISO 8601 timestamp]
**Planned:** N iterations
**Focus:** "focus string" (or "all improvement areas" if none)
**Baseline:** XX/100
**Base commit:** [full SHA]
**Status:** IN_PROGRESS (0/N completed)
```

If the log file doesn't exist, create it with the project header first:

```
# .claude/autoimprove/log.md

> Generated by [autoimprove](https://github.com/benmarte/autoimprove) — Claude Code Plugin
> Project: **[project name]** · Stack: [detected stack] · Started: [date]

---
```

Then append the session header.

---

## Continue Mode

When invoked with continue-mode parameters (from the `/autoimprove:continue` command), the loop behavior changes:

- **`start_iteration`** — Start numbering from this value instead of 1
- **`total_iterations`** — Use this as the display total (e.g., "Iteration 5/10")
- **`session_mode`** — If `continue`, skip creating a new session header; instead update the existing one:
  - Update `**Planned:**` to the new total if it changed
  - Update `**Status:**` to `IN_PROGRESS`
- **`baseline_score`** — If provided, skip baseline measurement and use this value
- **`experiment_offset`** — Start experiment numbering from this value to avoid branch name collisions

In continue mode, the pre-flight still runs (clean tree, config check, worktree setup) but skips creating a new session header and optionally skips baseline measurement.

---

## Progress Updates

**CRITICAL:** At the start of every step, you MUST output a visible progress line to the user. Do not silently run tools — always print status first. Use this format:

```
━━━ Iteration N/TOTAL ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔬 STEP_NAME: brief description of what's happening
```

Example progress lines:
```
━━━ Iteration 1/5 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔬 PROPOSE: Targeting error handling in src/api/client.ts
🔬 SNAPSHOT: Measuring BEFORE score...
🔬 IMPLEMENT: Adding try/catch to unhandled async calls
🔬 MEASURE: Measuring AFTER score...
🔬 DECIDE: 85 → 89 (+4 pts) — KEPT ✅
🔬 LOG: Recorded to .claude/autoimprove/log.md
```

Never run more than one step without printing a progress line. The user must always know what iteration you're on and what phase you're in.

---

## The Loop

### Step 1 — CREATE WORKTREE

Use the worktree skill to create a new isolated branch and directory:

```bash
EXPERIMENT_ID=$(printf "%03d" $N)
git worktree add -b "autoimprove/experiment-$EXPERIMENT_ID" \
  ".claude/autoimprove/worktrees/experiment-$EXPERIMENT_ID"
```

All work for this iteration happens inside `.claude/autoimprove/worktrees/experiment-$EXPERIMENT_ID/`.
The main directory is not touched.

### Step 2 — PROPOSE

**If a FOCUS string was provided:** Every iteration targets that specific focus. Break the focus into file-by-file or function-by-function sub-tasks and tackle one per iteration. Do not rotate to other areas — stay on the focus until all iterations are used or the focus is fully addressed.

**If no FOCUS was provided:** Choose one focused improvement from the **Improvement Areas** in `.claude/autoimprove/config.md`. Rotate areas — don't repeat an area that failed last time.

State the hypothesis explicitly:
> "I will [specific change] in [file(s)] because I expect [metric] to improve by ~[X] points."

### Step 3 — SNAPSHOT (BEFORE score)

Measure from inside the worktree directory (same commands, different cwd):
```bash
cd .claude/autoimprove/worktrees/experiment-$EXPERIMENT_ID
# run measurement suite from .claude/autoimprove/config.md
```
Record as **BEFORE**.

### Step 4 — IMPLEMENT

Make the change inside the worktree. The main directory is untouched.
Commit the change to the experiment branch:

```bash
cd .claude/autoimprove/worktrees/experiment-$EXPERIMENT_ID
git add -A
git commit -m "experiment($EXPERIMENT_ID): $HYPOTHESIS_ONE_LINE"
```

### Step 5 — MEASURE (AFTER score)

Run the full measurement suite again from inside the worktree.
Record as **AFTER**.

### Step 6 — DECIDE

**If AFTER > BEFORE — KEEP ✅**

Squash-merge the experiment back to main:
```bash
cd [main project root]
git merge --squash "autoimprove/experiment-$EXPERIMENT_ID"
git commit -m "autoimprove($EXPERIMENT_ID): $HYPOTHESIS_ONE_LINE

Score: $BEFORE → $AFTER (+$DELTA pts)
Files changed: $FILES"

# Clean up
git worktree remove ".claude/autoimprove/worktrees/experiment-$EXPERIMENT_ID"
git branch -D "autoimprove/experiment-$EXPERIMENT_ID"
```

**If AFTER == BEFORE — KEEP ✅ only for clear readability wins, DISCARD otherwise**

Same merge process as above if keeping, discard process if not.

**If AFTER /dev/null
done
git branch | grep "autoimprove/experiment" | xargs git branch -D 2>/dev/null
rm -rf .claude/autoimprove/worktrees
```

Print a final summary table:

```
━━━ Session Complete ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Score: BASELINE → FINAL (+/- DELTA)
🔁 Iterations: N total — X kept ✅, Y discarded ❌
📝 Merged commits:
   • abc1234 autoimprove(001): description
   • def5678 autoimprove(003): description
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Universal Improvement Areas

Rotate through these (add language-specific ones from `.claude/autoimprove/config.md`):

- **Type safety** — fix type errors, replace `any`/`interface{}`/untyped constructs
- **Error handling** — unhandled promises, bare `catch {}`, swallowed errors
- **Dead code** — unused imports, variables, unreachable branches
- **Code duplication** — extract repeated logic (3+ occurrences) into shared utilities
- **Naming & readability** — cryptic names, functions over ~50 lines
- **Performance** — N+1 query patterns, missing memoization, unnecessary allocations
- **Security** — hardcoded secrets, missing input validation, unguarded auth routes
- **Tests** — add a test for the most critical untested function, fix flaky tests

---

## Safety Rules

- **Main branch is never modified** until a winning experiment is explicitly squash-merged
- **Never** modify lock files, generated files, migrations, `.env` — in any worktree
- **Never** run deploy, publish, or push commands
- If the same area fails 3 iterations in a row, skip it and note in the log
- After 10 iterations, pause, clean up worktrees, and wait for human review
- On any unexpected error: run the worktree skill's **cleanup** step, then stop and report

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [benmarte](https://github.com/benmarte)
- **Source:** [benmarte/autoimprove](https://github.com/benmarte/autoimprove)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-benmarte-autoimprove-improve-loop
- Seller: https://agentstack.voostack.com/s/benmarte
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.