agentleFS
akimisri17akimisri17/idea-to-app-kit/AGENTS.md

idea-to-app-kit

AGENTS.md0 starsChanged 39 days agoMITView on GitHub

[One line: what this is and who it's for. Filled in during setup.] Mode: [non-technical / technical] · [quick / full] Non-technical: I'm not a developer. Talk to me in plain words and explain any technical term in one short sentence. Run everything yourself; never ask me to type commands or edit settings or permissions. If you need my permission, tell me which button to click and what it allows. Technical: I've built software before. Use proper technical terms, show…

The file

We split this AGENTS.md into the rules it gives an agent

12 rules. About 1 is common, 11 are distinctive, and 0 are very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use one of two shapes. Full, plain sentences in both: no shorthand or dropped words, and no jargon without a one-line explanation.

    line 19
  2. Distinctive:

    Use them whenever their moment comes.

    line 61
  3. Distinctive:

    write-handoff: after every wave and whenever we stop.

    line 65
  4. Distinctive:

    make-full: when the person wants the full version.

    line 66
  5. Distinctive:

    go-live: before the app goes online for other people.

    line 68
  6. Distinctive:

    feedback-review: when the person shares customer messages, reviews or complaints.

    line 69
  7. Distinctive:

    Check reality before planning: Read the real code and settings, or the service's official page, before planning anything that depends on …

    line 78
  8. Common:

    Keep it handover-ready: Use a mainstream stack, keep doc 4's "Developer handover" current after every wave, and don't leave secrets in the …

    line 83
  9. Distinctive:

    One checkpoint per wave, at least: Never bundle two waves into one checkpoint.

    line 86
  10. Distinctive:

    Never make up facts, numbers, prices or quotes: If you don't know, say so.

    line 92
  11. Distinctive:

    After every wave, and whenever I say "write a handoff" or we're stopping, use the write-handoff skill, so a usage limit never loses our …

    line 105
  12. Distinctive:

    If a doc is wrong or out of date, fix it right away and tell me.

    line 109

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “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
AGENTS.md

Project: [name]

[One line: what this is and who it's for. Filled in during setup.]

Mode: [non-technical / technical] · [quick / full]

About me

<!-- Setup keeps the paragraph that matches the Mode line and deletes the other. -->

Non-technical: I'm not a developer. Talk to me in plain words and explain any technical term in one short sentence. Run everything yourself; never ask me to type commands or edit settings or permissions. If you need my permission, tell me which button to click and what it allows.

Technical: I've built software before. Use proper technical terms, show me the commands you run, and follow normal engineering practice: the Engineering setup in doc 4, tests with every wave, a branch and PR per wave.

Either way: when I need to decide something, give me 2–3 options and say which you recommend and why. If I say "make this the full version", follow "Upgrading later" in prompts/1-SETUP.md. Never restart.

How to reply

Use one of two shapes. Full, plain sentences in both: no shorthand or dropped words, and no jargon without a one-line explanation. These apply whatever other style settings are active.

1. Answer first (default, for almost every reply)

  • Bold opening line: the answer or outcome, in one or two sentences. Then one line on what was checked and what wasn't.
  • 2–4 bullets of detail, only if needed.
  • End with the one thing you need from me, if anything: a single decision or question, with your recommendation. With options, give each in one line and say which you'd pick.

Wave 1 is done: customers can order from the link, and a full day says no. I tested it with 58 checks; I couldn't check how it looks on a real phone.

  • Orders show up in your list right away.
  • A day closes automatically at 4 kg.

One decision before Wave 2: should you type each order's price in the app? I'd say yes.

2. Step-by-step (whenever I have to do something myself)

  • One line saying what this is for and how long it takes.
  • Numbered steps. Each starts with a bold verb and says what I'll see.
  • Close with what to tell you afterwards.

Your check for Wave 1 takes about 2 minutes:

  1. Open http://localhost:8765. You'll see your 4 cakes.
  2. Order a 2 kg cake for Saturday twice. Both should go through.
  3. Try a third. You should see "That day is full".
  4. Tell me anything that looked wrong.

Anything the app says to customers follows the voice in doc 2 ("Messages people see").

Every session

A start-up check (tools/session-start.sh) tells you what to read. It runs automatically where the tool supports start-up hooks; otherwise run sh tools/session-start.sh yourself first. Read, in order:

  1. docs/1-PRD.md: what we're building and why: requirements (R#), metrics (M#), what we're not doing, what must never happen.
  2. docs/2-APP-FLOW.md: screens (S#) and each person's journey.
  3. docs/3-DATA-AND-RULES.md: what we store, who can do what, how things move between steps.
  4. docs/4-HOW-IT-WORKS.md: how it's built and run.
  5. docs/5-BUILD-PLAN.md: which wave we're on.
  6. The newest file in docs/handoffs/: where we stopped.
  7. Open rows in docs/lessons.md: mistakes we've made here before, so they don't happen again.

Then tell me in 2–3 lines where we are and what's next.

Skills (step-by-step flows in .agents/skills/)

Use them whenever their moment comes; don't improvise these flows:

  • start-app: whenever the person should see the app ("start the app", "show me").
  • check-wave: at the end of every wave, before calling it done.
  • log-lesson: the moment the person corrects you or a check fails, before fixing.
  • write-handoff: after every wave and whenever we stop.
  • make-full: when the person wants the full version.
  • new-idea: whenever the person asks for something not in the plan ("can we also add…").
  • go-live: before the app goes online for other people.
  • feedback-review: when the person shares customer messages, reviews or complaints.
  • results-check: on the "Check results on" date in doc 1, or when asked "did it work?".

Building

  • Build only what the docs say. A new ability or rule goes through the new-idea skill: doc 1 first (a Must needs a metric it helps), then doc 2, doc 3 and a wave, with my OK. Never build anything under "Not doing".
  • Small look-and-feel tweaks inside an existing screen (wording, colours, layout): just do them, then note them in the handoff.
  • Never break anything under "Must never happen" in doc 1. Stop and ask.
  • After changing any doc, run sh tools/check-plan.sh and fix what it reports.
  • Check reality before planning. Read the real code and settings, or the service's official page, before planning anything that depends on them. Never from memory.
  • Build a real app, end to end. Every wave goes screen → server → database, with tests. Every limit, permission, money, date and status rule runs in server code. Nothing important lives only in the browser, in browser storage or in one HTML file. docs/mockup.html is a throwaway preview and never becomes the app.
  • Rules first, AI only as an optional layer. Follow the processing steps in doc 4. The app works fully with no AI key. An AI step stays off until it's switched on, runs only when rules can't decide or someone clicks it, and never decides money, limits, permissions or status.
  • Use the helper roles in harness/roles/ for self-contained jobs: researcher (facts, prices, terms), mockup-maker (preview), plan-reviewer (second opinion), wave-checker (end of every wave). Run each as a sub-agent with a fresh context where your tool supports it. That keeps this conversation small and cheap.
  • Match the model to the job (harness/models.md): checks and scripts first (no model), the standard tier for most work, and the deep tier only where a mistake is expensive (full-mode plan review, data/permission/money design, a fix that failed twice). Cheap work is safe because tests and checks catch its mistakes.
  • Keep it handover-ready. Use a mainstream stack, keep doc 4's "Developer handover" current after every wave, and don't leave secrets in the code.
  • One wave at a time. A wave is done only when the check-wave skill passes.
  • Show me the result with the start-app skill. Never say the app is running unless that skill's check just passed.
  • One checkpoint per wave, at least. Never bundle two waves into one checkpoint.

Safety

  • Ask before installing anything, signing up for a service, spending money, deleting files, or changing anything outside this folder.
  • Never put passwords, keys or personal data in the code or the docs.
  • Never make up facts, numbers, prices or quotes. If you don't know, say so.
  • When something breaks, explain what happened in plain words before fixing it.
  • Changing a big decision (what it's built with, where data lives, hosting) needs a line in doc 4's decision log first.

Learning from mistakes

  • When something goes wrong, write it down first, then fix it (log-lesson skill): a wave check fails, the plan review finds a gap, I correct you or report a problem ("that's wrong", "it should be…"), or a bug appears after a wave was done. Even if the fix takes one minute.
  • Turn every lesson into a guard, cheapest reliable one first: a test or check that runs → a hook → a rule that loads only for that part of the code (Claude Code: .claude/rules/ with paths:; Cursor: .cursor/rules/*.mdc with globs; other tools: a short AGENTS.md inside that folder) → one line here as a last resort. Then mark the row "guarded" and say where.
  • Project lessons go in docs/lessons.md (shared in git), not in a tool's personal memory.
  • Keep this file under ~200 lines (and under 32 KB, so every tool reads all of it). Don't repeat a rule that a test or hook already enforces.

Ending a session

After every wave, and whenever I say "write a handoff" or we're stopping, use the write-handoff skill, so a usage limit never loses our place.

Keeping docs true

If a doc is wrong or out of date, fix it right away and tell me. A wrong doc is worse than no doc. Keep this file short: rules that last, nothing about today's task.

<!-- Built with the Idea to App Kit by Akhil Misri (@noonchai.dev · github.com/akimisri17). -->

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.