bama-improve-loop
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.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- bama-improve-loop
- 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.
- argument-hint
- [milestone, e.g. M1]
02 资源文件 1
- 参考文档agents/openai.yaml101 B
03 SKILL.md 正文
<!-- Version-Timestamp: 2026-10-27 07:36:32 AST -->
Adapted execution contract
This is the pinned, MIT-attributed BAMA capability adapted for the owned design kit. Read ADAPTATION.md at the BAMA package root before executing helpers. Project instructions, approved DESIGN.md and canonical tokens take precedence. Use supported Codex or Claude Code tools. Resolve this skill's sibling files relative to its installed SKILL.md; skill_dir is a task-local shell variable that you set to that resolved directory before running the examples in either host. Invoke a named bama-* skill through the host's supported skill mechanism.
Stage local builds by default. Installation, signing identity selection, launch, CLI linking, MCP registration, system setting changes and capture access are separate explicit operations. Existing task authorization applies; ask only for an action not already authorized. Stage or commit only when the current task or repository workflow authorizes it. Stage explicit paths and include required attribution. The helpers do not commit. Preserve the feature, story and testing workflow below using the hardened helpers. Legacy installed-app paths in examples must be replaced by the staged binary returned by build.sh.
Before a new scaffold exists, keep planning evidence under the selected <AppName>-planning/docs/ sibling or an existing approved planning folder. Treat docs paths below as relative to that planning folder until the fresh app is scaffolded, then copy the planning docs explicitly without replacing existing files. For an existing app, keep its current project layout.
The upstream acceptance statements describe checks to perform, never completed results. Screenshots, runtime behavior, permissions and cross-host acceptance require actual evidence. Use synthetic data and owned temporary test roots. Do not run a hosted session over real app data without project authorization.
Improve loop
One pass through the loop takes one story from todo to done:
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, invoke the host-supported skill bama-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 bama-swift-swiftui and bama-mac-design skills, the story's UX:
block, and design/DESIGN-SYSTEM.md if the app has one. System hooks follow
bama-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 bama-build-and-verify skill. If the story has logic, add a test
or a self-test step (bama-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:
- Missing or wrong behavior from the acceptance criteria.
- Words and flow: names, surface, and states that differ from the
UX:block ordocs/GLOSSARY.md. - Layout: wrong column, wrong order, missing element, and every FAIL from the grid checks.
- Hierarchy: what is biggest, boldest, first.
- Spacing and alignment.
- Color and details.
Follow the selected reconstruction contract. For a faithful reconstruction, preserve observed structure, behavior and visual treatment, using semantic native controls styled to match where possible. Replacing the reference with platform defaults is a deliberate adaptation, not an automatic improvement. Record an unavoidable platform difference, its evidence and the accepted target decision. An explicitly adapted native version can use native conventions while retaining the observed task model.
No reference screenshot (no app was cloned)? Compare against the story's
acceptance lines and the bama-mac-design rules instead.
Snapshot only the pages a story touches (APP_SNAPSHOT_PAGES), and the
full set 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 diff --check # review scoped changes; do not stage automatically
# Commit only under the project workflow with required attribution.
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. M1 may
land as one commit when its stories share one skeleton (model, pages,
list, persistence); from M2 on, one story per reviewed change.
7. Report
At the end of the loop, report to the user:
- Stories done, with one line each and the snapshot paths that show them.
- Stories blocked, and why.
- Anything the user should try by hand (shortcuts, drag and drop).
- The next story in line.
Then ./build.sh --open so the user can try the new build.
Milestone check-in
When the last story of a milestone is done, invoke the host-supported skill
bama-improve-architecture before you start the next milestone. Unattended, do
its top recommendation only if it is Strong, and leave the rest in the
review file for the user.
When a story fixes a bug, add an entry to docs/FIXLOG.md: symptom,
cause, fix, and a last line Rule: <what to always or never do>. The fix
log outlives squashed history, and the check-in reads it.
Running it unattended
The loop works with no one watching, because every step checks itself: the build, the snapshots, 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.
04 同仓库更多 Skills
web-design
Load before planning, designing, auditing or launching any website, landing page, cinematic hero, microsite or above-the-fold layout, or a prompt for Lovable, Bolt or v0 to build one, including regulated (prescription drug, health, finance), multilingual or market-specific launches. Covers page types (home, product, pricing, about, blog), conversion and ethical persuasion, responsive and fluid layouts, Core Web Vitals, SEO and structured data, localization and language-law requirements, stack and CMS choice (Astro, Next.js, WordPress, Webflow, Framer) and launch QA.
ux-design
Load before designing or reviewing any flow, form, onboarding, navigation or content for real users, especially low-literacy, older, neurodivergent, child or other specific audiences. Covers research and usability tests, heuristic reviews, personas and jobs to be done, journeys and service blueprints, information architecture, UX laws, SUS, SEQ and HEART metrics, plain language and reading level, and microcopy and error messages.
ui-design
Load before designing or specifying any interface screen or component, even a quick one: forms, tables, navigation, dashboards, onboarding, auth and passkeys, pricing, checkout, search and filters, settings, empty, loading and error states, notifications, consent and age-appropriate flows, and AI chat and agent interfaces, all to WCAG 2.2 AA. Also picks React UI libraries (toasts, drawers, command menus). Gives component specs, state matrices, sizes, density and keyboard and accessibility behavior.
typography
Choose, pair, size and set type for brand, web, app, print, slides, signage and motion: modular scales, fluid clamp() type, measure, leading, tracking, OpenType features, font licensing and web font loading, and multiscript setting for CJK, Arabic, Hebrew, Devanagari and Thai. Use when selecting or pairing fonts, building a type scale or type tokens, fixing weak hierarchy or bad line breaks, setting long-form text or numbers, loading web fonts, or localizing type for another market.
reference-reconstruction
Reconstructs the observed interface and behavior of a supplied app, site or screenshot set using a screen index, measurements, state and command maps, reusable components and matched-condition comparisons. Use when asked to reverse engineer, clone, reproduce or match a reference product, then adapt it if requested.
print-packaging-social
Load before any print, packaging, label, barcode, social, out-of-home, slide-deck or email design question, even a quick one, and before making finished collateral files. Specs: bleed, safe zones, 300ppi, CMYK, PDF/X preflight, dielines, barcodes, social formats with 9:16 safe areas, billboard letter heights, 16:9 decks, bulletproof email. Renders token-driven brand books, sell sheets, cards, carousels and decks to PDF and PNG with a Canva editable twin.