agentleFS
mannobeatsmannobeats/hyper-taste/skills/improve-loop/SKILL.md

improve-loop

Skill1 starsChanged 4 days agoMITView on GitHub

Work through docs/STORIES.md one story at a time - plan, build, test, run and look, compare, fix, commit - until a milestone is done, unattended if needed. Use when the user says "keep going", "work through the backlog", "build M1", "make it match the reference", or wants an autonomous build loop.

7 other projects use a version of this, 3 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use app-brief, design-from-app and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • StijnusSkill

    app-brief

    One-page brief (docs/BRIEF.md) for a new macOS app, written before any code. Use when the user has an app idea, wants to replace an app they pay for, or the research and clone skills are done.

    Also in 3 projects that use this

  • StijnusSkill

    design-from-app

    Rebuild the look of an app the user likes as a native SwiftUI design kit, by measuring its screenshots (sizes, spacing, type, colors, icons), building its parts, and comparing pixel by pixel until they match. Use when the user names an app whose look they want, shares screenshots of one, or says "make it look like X".

    Also in 3 projects that use this

  • launchapp-devSkill

    layout-grid

    Define responsive layout grid systems with columns, gutters, margins, and breakpoint behavior.

    Also in 3 projects that use this

  • timeplus-ioSkill

    build-and-verify

    Build, compile, run server/client/cluster, execute unit/stateless/SQL tests, verify results, and troubleshoot build/test failures. Make sure to use this skill whenever the user mentions building, compiling, ninja, cmake, running tests, test failures, starting the server, or pre-commit checks, even if they just say 'it doesn't build' or 'the test broke'.

    Also in 3 projects that use this

  • CrystalPlatformsSkill

    agent-cli

    Design and audit CLIs that AI agents (Claude Code, Codex, automated pipelines) consume. Applies ten agent-native principles in two tiers — Tier 1 table stakes (non-interactive default, structured output, errors that enumerate, safe retries, bounded responses) and Tier 2 compounding (cross-CLI vocabulary, three-layer introspection, async-aware execution, persistent profiles, two-way I/O) — with a Blocker / Friction / Optimization severity rubric across six command classes (read, mutate, stream, bootstrap, async, config). Use when building, reviewing, or specifying a CLI for agent invocation, mentions argparse, click, cobra, clap, commander, yargs, oclif, thor, agent-friendly or agent-native CLI design, --json output, exit codes, idempotent commands, --wait flags, agent-context introspection, persistent profiles, --deliver routing, --force bypass, vocabulary consistency, or repos with cli.py, main.go, src/cli.rs, bin/<tool>. Skip general shell scripting and human-only TUIs.

    Also in 3 projects that use this

  • bborok1234Skill

    design-kit

    새 프로젝트/화면의 디자인 시스템을 프로덕션급으로 빠르게 세우고(부트스트랩), 이미 만든 UI의 퀄이 안 잡힐 때 진단→교정하고, AI 슬롭 없이 폴리싱하는 개인 디자인 게이트. "디자인 시스템 잡아줘", "랜딩/UI 만들어", "슬롭 잡아줘", "이 화면 폴리싱", "퀄리티가 안 잡혀/디자인 고쳐줘/왜 싸구려 같지", 새 프론트엔드 시작 시 적용. 미학(팔레트·폰트·정체성)은 인터뷰로 함께 설계하고, 시스템 구성법·판단룰·안티슬롭·진단교정·빌드루프는 프로젝트 무관하게 재사용.

    Also in 3 projects that use this

  • +1 more from Stijnus

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 14
  2. Very specific:

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

    line 24
  3. Distinctive:

    Write two to five lines: which files change, what already exists that you will reuse, which data fields are new, which command and shortcut …

    line 27
  4. Very specific:

    Follow the build skill (tests first), the story's UX: block, CONSTRAINTS.md and DESIGN-SYSTEM.md if the project has them, and the …

    line 33
  5. Very specific:

    Run the tests and the checks in CONSTRAINTS.md.

    line 39
  6. Distinctive:

    Look at your screenshots and the story's reference screenshots side by side.

    line 45
  7. Very specific:

    No reference screenshot (no app was cloned)?

    line 59
  8. Very specific:

    When the last story of a milestone is done, call the Skill tool with review on the milestone's code before you start the next one.

    line 92

“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Improve loop

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

pick story -> plan -> test and code -> run and look -> 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: which files change, what already exists that you will reuse, which data fields are new, which command and shortcut it adds, which screen shows it. A new stored field gets a default value, so existing data keeps loading.

3. Test and code

Follow the build skill (tests first), the story's UX: block, CONSTRAINTS.md and DESIGN-SYSTEM.md if the project has them, and the platform's skill (mac-app and mac-design, or ui-director). Keep each file small enough to read in one go.

4. Test, run and look

Run the tests and the checks in CONSTRAINTS.md; a failure whose cause isn't obvious goes to debug. Run the app with sample data, and capture the screens the story touches, light and dark, the way the platform's skill says (mac-app or ui-director).

5. Compare

Look at your screenshots and the story's reference screenshots side by side. 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, off-grid spacing.
  4. Hierarchy: what is biggest, boldest, first.
  5. Spacing and alignment.
  6. Color and details.

The goal is the same structure and behavior, built from the platform's own controls. It is not a pixel copy. When the reference uses a custom control and the platform has a native one, use the native one.

No reference screenshot (no app was cloned)? Compare against the story's acceptance lines and the design skill's rules (mac-design or ui-director) instead.

Capture only the screens a story touches, and every screen at the end of each milestone.

Fix, rebuild, and compare again. Three rounds per story at most. If it still does not match, set the story to todo again with a note that says what is blocking, and move on.

6. Commit and record

git add -A
git commit -m "Complete tasks with Command-Return"

Set the story to done in docs/STORIES.md and commit that with the code. One story per commit, so any story can be reverted on its own.

7. Report

At the end of the loop, report to the user:

  • Stories done, with one line each and the evidence: the passing test output and the screenshots that show them.
  • Stories blocked, and why.
  • Anything the user should try by hand (shortcuts, drag and drop).
  • The next story in line.

Then open the new build so the user can try it.

Milestone check-in

When the last story of a milestone is done, call the Skill tool with review on the milestone's code before you start the next one. Unattended, fix its Must fix findings, and leave the rest in docs/REVIEW.md for the user.

A story that fixes a bug follows debug, including its entry in docs/FIXLOG.md, which the check-in reads.

Running it unattended

The loop works with no one watching, because every step checks itself: the build, the tests, the screenshots, the acceptance criteria. To let it run longer, start it with a clear limit ("finish M2, then stop"), make sure the tree is committed before you start, and never let it touch the user's real database. Each story is a separate commit, so the user can review the history in the morning and revert anything they do not like.

Done when every story in the milestone is done or named in the report as blocked with a reason, each done story has its own commit, and the user has the report.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.