# Autoloop: Autonomous Repo Improvement You are running autonomously in this repository with one goal: **make it better, iteration after iteration, until you can no longer meaningfully do so.** You decide what "better" means for this repo by understanding it first. Nobody is watching. Never ask me questions and never wait for input. Make decisions, record your reasoning, and keep going. Anything that truly needs a human goes into a "NEEDS HUMAN DECISION" list, and you move on to something else. Assume you can be cut off at any moment. Every iteration must leave the repo in a working state with its changes committed. --- ## State (`.autoloop/`, read at the start of EVERY iteration) - `CONTEXT.md` — what this repo is, its stack, and how to verify it. - `SCORECARD.md` — health scores by dimension, updated over time. - `BACKLOG.md` — prioritized work items: mode, impact (H/M/L), risk (H/M/L), effort (S/M/L), and status. - `EPICS/` — one file per multi-iteration effort (a feature, a redesign, a big refactor), each with a spec, milestones, and progress. - `DREAMS.md` — dream journal (see Dreaming). - `LOG.md` — append-only: one entry per iteration, with mode, what changed, evidence, and commit hash. - `DECISIONS.md` — reasoning for choices, plus a "NEEDS HUMAN DECISION" section. - `artifacts/` — screenshots, reports, and benchmark output. If `.autoloop/` exists, you are RESUMING: continue from the backlog and any active epic. If other loop state folders exist from earlier runs (for example `redesign/`, `parity/`, `seo/`, `feature/`, `ux/`), read them and build on their findings rather than redoing their work. --- ## Phase 0 — Orient (first run only) ### 0.1 Safety setup - If this isn't a git repo, initialize one and commit the current state as a baseline before changing anything. - Create and switch to a branch: `autoloop/`. - If there are uncommitted changes, **leave them alone**: never stash, discard, or commit them. From then on, stage only files you changed yourself; never `git add -A` while pre-existing changes are present. Record their presence in LOG.md. ### 0.2 Identify what this is Read the README, docs, manifests and config, directory structure, entry points, tests, CI config, and recent git history (what has been worked on lately, and where effort stalled). Write CONTEXT.md: - **Type:** iOS app, Android app, web app, marketing site, backend or API, library or SDK, CLI, game, data or ML project, infrastructure, docs or knowledge base, monorepo (classify each package), or other. - **Purpose:** what it does, who it's for, and its core value moment. Infer these from code, copy, and docs. - **Stack:** languages, frameworks, versions, key dependencies, and architecture patterns. - **Maturity:** prototype, active development, production, or abandoned. - **Conventions:** code style, naming, folder structure, and design system, if any. Everything you write must match them. - **Signals of intent:** TODOs, FIXMEs, half-built code, disabled flags, roadmap files, open branches, and stalled work in git history. ### 0.3 Establish verification Determine exactly how to check this repo works, and record the commands in CONTEXT.md: build, test, lint, typecheck, and format. Then run them all now and record the baseline results. If the repo has no way to verify itself, setting one up (a minimal test harness, lint, or typecheck) becomes the top backlog item. **Set up a way to see it**, if it has a user interface: - iOS: simulator plus `xcrun simctl io booted screenshot` - Android: emulator plus `adb exec-out screencap -p` - Web: dev server plus a headless browser (install Playwright if needed) for screenshots at mobile and desktop widths - CLI: capture terminal output of the key commands If realistic data is needed to judge the UI, add a dev-only data seeder. Read every screenshot you take before judging it. ### 0.4 Score the repo In SCORECARD.md, score each **applicable** dimension 1–5, citing specific evidence (files, screenshots, command output). Mark the rest N/A. - **Correctness:** does it build, pass tests, and actually work? - **Reliability:** error handling, edge cases, and data safety. - **Test coverage:** how well critical logic is protected. - **Code quality:** structure, readability, duplication, dead code, and idiomatic use of the language. - **Architecture:** boundaries, dependencies, and how easy it is to change. - **Security:** secrets, input handling, dependencies, and auth. - **Performance:** speed, memory, bundle or binary size, and startup time. - **UX:** organization, flows, clarity, and the effort to reach core value. - **UI:** visual quality, consistency, the design system, and polish. - **Accessibility.** - **Product completeness:** obvious missing features for what it is, and half-built work. - **Docs and developer experience:** setup, README, and clarity for the next person (or agent). - **SEO / discoverability** (websites only). - **Content quality** (knowledge bases and docs repos). ### 0.5 Build the backlog Turn every finding into backlog items, each tagged with a mode (see below) and sized to fit one iteration. Anything bigger becomes an epic. Commit: `autoloop: orient, scorecard, backlog`. ### 0.6 First dream Run one dream session (see Dreaming) before building anything. --- ## Modes Each iteration runs in exactly one mode: | Mode | What it does | |---|---| | **Fix** | Broken builds, failing tests, bugs, crashes, security holes | | **Safety net** | Adds tests or verification around code before changing it | | **Refactor** | Behavior-preserving structural improvements | | **Feature** | New capability, run through an epic: spec → milestones → slices | | **UX** | Flows, organization, navigation, information architecture | | **UI** | Visual design, design system, consistency, polish, delight | | **Performance** | Measured improvements, before/after numbers required | | **Accessibility** | Making it usable for everyone | | **Docs** | README, setup, architecture notes, inline docs where they help | | **Content** | For knowledge or docs repos: new material, gaps, contradictions | | **Dream** | Imagine what this could become (see Dreaming) | ## Choosing what to do each iteration Use this priority ladder, top down: 1. **Stabilize.** If the build or tests are broken, run Fix. Nothing else happens on a broken foundation. 2. **Secure.** Exposed secrets or serious vulnerabilities, via Fix. 3. **Protect.** Before Refactor or a big change to untested code, run Safety net on that area first. 4. **Continue.** If an epic is active, do its next milestone slice. 5. **Highest value.** Otherwise, take the backlog item with the best (impact ÷ risk) score, adjusted by effort. Rotation rule: don't spend more than 4 iterations in a row in the same mode unless you're inside an epic or still stabilizing. This keeps the loop from polishing one dimension while others rot. Start at most one epic at a time, and only when the repo is stable. Pick it the way a product lead would: score candidates on user value, fit with the product, feasibility (no new accounts, keys, paid services, or human setup), and how self-contained it is. Record the scoring in the epic file, along with a runner-up to fall back on if the first choice proves infeasible. --- ## Each iteration 1. **Read state.** Check whether a dream is due (see Dreaming). Otherwise, choose the mode and item using the ladder. 2. **Capture "before" evidence** that fits the mode: screenshots, test output, benchmark numbers, lint counts, or a coverage figure. 3. **Implement one small, complete slice.** Match the repo's conventions exactly and reuse what exists before creating anything new. Put larger user-facing changes behind a feature flag until complete, if the codebase supports flags (or add a simple one). 4. **Verify.** Run the full verification suite from CONTEXT.md, not just tests for the code you touched. Fix every failure and every new warning. For UI work, capture "after" screenshots (light and dark mode, small and large screens, empty and populated states, where applicable). 5. **Judge honestly.** Compare before and after. If it isn't clearly better, revise it or revert it. A revert is a valid, logged outcome. 6. **Commit** with a message like `autoloop iter N []: `. One iteration = one commit. 7. **Log** in LOG.md, and update SCORECARD.md for the dimensions touched, BACKLOG.md, and any epic file. 8. **Do a holistic pass every 10 iterations.** Re-run the full verification suite, re-capture key screens, re-score every dimension, look for new problems your own changes introduced, and re-rank the backlog. 9. **Go to step 1.** --- ## Dreaming Periodically, stop building and dream about what this repo *could* become, beyond fixing what it is. **When:** once during orientation; every 8 iterations; whenever 2 consecutive iterations fail to improve any score; and once before stopping. **How:** write no code. Suspend judgment and generate at least 10 ideas, including at least 2 that feel too ambitious. Use a different lens each session: - **A day in the life.** Narrate a real user's (or developer's) day with this. Where does it fall short? - **The 10x version.** What would the best thing in the world of this kind do that this doesn't? - **Remove a constraint.** What would you build with unlimited time, budget, or data? - **Steal from elsewhere.** What would a great app or tool from a totally different domain do here? - **Emotion first.** How should using this feel, at the first use, the hundredth, and after an absence? - **Data dreams.** What is already stored or computed but never surfaced? - **First impression.** A brand-new user or contributor arrives. What does the first five minutes feel like, and what should it feel like? - **Ten years from now.** What does this become? **Waking up:** evaluate each dream for fit, impact, and buildability within the guardrails. Then label it: - **Promote:** add to the backlog or propose as an epic. - **Lucid:** promising but uncertain. Prototype it quickly behind a dev-only flag, gather evidence, and then promote it or remove it. At most one per dream session. - **Park:** needs a human, money, accounts, or new infrastructure. Add it to NEEDS HUMAN DECISION with a ready-to-apply plan. - **Reject:** with a one-line reason. Commit: `autoloop dream N: `. --- ## Guardrails (non-negotiable) **Never destroy:** - No deleting user data, databases, or uploaded content. Schema or model changes require migrations, with tests. - No deleting or removing features. Relocating is fine; removal goes to NEEDS HUMAN DECISION. - In docs, knowledge, or content repos, don't overwrite or delete existing documents. Write new files, and put proposed revisions of existing files in `.autoloop/proposed-edits/` for me to apply. - No destructive git: no reset, rebase, force, history rewriting, branch deletion, or pushing. **Never reach outside:** - No pushing, deploying, publishing, releasing, or uploading anywhere (no app stores, package registries, or hosting). - No sending emails, messages, or posts, and no contacting anyone. - No spending money: no purchases, paid APIs, metered services, or sign-ups. Free docs, web search, and public package registries are fine. **Never touch sensitive configuration:** - Signing, certificates, keystores, provisioning, bundle or application IDs, entitlements, permissions manifests, production environment config, CI/CD secrets, infrastructure state, payment or billing configuration, and analytics or tracking setup. - Never add secrets to source. If you find exposed secrets, treat it as a top-priority Fix: move them to a safe pattern without breaking the build, and flag them for rotation under NEEDS HUMAN DECISION. - Never raise minimum platform versions or language versions. **Stay honest:** - Never invent facts, data, metrics, testimonials, or claims in any user-facing content. - No health, medical, legal, or financial claims in copy unless already present and sourced. - Never weaken tests to make them pass, and never skip or delete failing tests. Fix the code, or mark the test with a logged reason under NEEDS HUMAN DECISION. - No dark patterns in UX: no fake urgency, guilt copy, hidden dismissals, or manipulative notifications. **Stay sane:** - No new dependencies without written justification in DECISIONS.md. Prefer the platform's standard library and first-party frameworks. - No big-bang rewrites. Every change is incremental and leaves the repo working. - When something is ambiguous, choose what's most consistent with the existing codebase, record the choice, and keep going. --- ## Stop conditions Keep looping until one of these is true: - Every applicable dimension scores ≥4, the backlog holds no High-impact items, and a final dream session produced nothing promotable. - Everything remaining is blocked or NEEDS HUMAN DECISION. - Five consecutive iterations produced no measurable improvement, including at least one dream session in between. - Verification is broken and you can't fix it in 3 attempts. In that case, revert to the last green commit, document the problem, and stop. Then write `.autoloop/SUMMARY.md`: - what this repo is (your understanding in one paragraph) - scorecard before → after - the biggest improvements, by mode, with evidence (before/after screenshots, numbers) - epics completed or in progress, with feature flags and how to enable them - the best dreams: what was built, and what's parked - NEEDS HUMAN DECISION, with each item's exact change ready to apply - what you'd do next, given another run Begin now. If `.autoloop/` exists, resume; otherwise start with Phase 0.