# Improve Loop

Autonomous loop that works through docs/STORIES.md one story at a time for a macOS app...

- Repository: https://github.com/daveebbelaar/bama (1284 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add daveebbelaar/bama --skill improve-loop -g -a claude-code -y`
Codex: `npx skills add daveebbelaar/bama --skill improve-loop -g -a codex -y`
Cursor: `npx skills add daveebbelaar/bama --skill improve-loop -g -a cursor -y`
Gemini CLI: `npx skills add daveebbelaar/bama --skill improve-loop -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add daveebbelaar/bama`

## Description

Autonomous loop that works through docs/STORIES.md one story at a time for a macOS app, building, snapshotting, comparing against reference screenshots, fixing, and committing, until a milestone is done. Use when the user says "keep going", "work through the backlog", "make it match the reference", or wants an unattended improvement loop.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Improve loop

One pass through the loop takes one story from `todo` to `done`:

```text
pick story -> plan -> code -> ./build.sh -> snapshot -> compare -> fix -> commit -> update STORIES.md
```

Stop after the milestone the user named, or after the current milestone if
they named none. Then report.

## 1. Pick

Open `docs/STORIES.md`. Take the first `todo` story in the current
milestone whose dependencies are `done`. Set it to `doing`.

## 2. Plan

If the story adds a screen, an action, or words and has no `UX:` block
yet, call the Skill tool with `ux-design` first.

Write two to five lines in your head or in the commit body: which files
change, which model fields are new, which menu command and shortcut it adds,
which snapshot page shows it. If the story needs a new SwiftData field, give
it a default value so existing databases keep loading.

## 3. Code

Follow the `swift-swiftui` and `mac-design` skills, the story's `UX:`
block, and `design/DESIGN-SYSTEM.md` if the app has one. System hooks follow
`os-integrations`. Keep each view file under about 300 lines.
Put new pages in the `SidebarItem` enum so snapshot mode visits them.

## 4. Build and snapshot

Follow the `build-and-verify` skill. If the story has logic, add a test
or a self-test step (`test-mac-app` skill). Use seed data (`APP_SEED=1`) so pages
show real content.

## 5. Compare

Open your snapshot and the story's reference screenshot side by side with
the Read tool. Write down the differences that matter, in this order:

1. Missing or wrong behavior from the acceptance criteria.
2. Words and flow: names, surface, and states that differ from the `UX:`
   block or `docs/GLOSSARY.md`.
3. Layout: wrong column, wrong order, missing element, and every FAIL from
   the grid checks.
4. Hierarchy: what is biggest, boldest, first.
5. Spacing and alignment.
6. Color and details.

The rest: https://github.com/daveebbelaar/bama/blob/HEAD/skills/ship/improve-loop/SKILL.md