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…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository19 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- check-waveSkill
- feedback-reviewSkill
- go-liveSkill
- log-lessonSkill
- make-fullSkill
- new-ideaSkill
- results-checkSkill
- start-appSkill
- write-handoffSkill
- check-waveSkill
- feedback-reviewSkill
- go-liveSkill
- log-lessonSkill
- make-fullSkill
- new-ideaSkill
- results-checkSkill
- start-appSkill
- write-handoffSkill
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
- Distinctive: line 19
Use one of two shapes. Full, plain sentences in both: no shorthand or dropped words, and no jargon without a one-line explanation.
- Distinctive: line 61
Use them whenever their moment comes.
- Distinctive: line 65
write-handoff: after every wave and whenever we stop.
- Distinctive: line 66
make-full: when the person wants the full version.
- Distinctive: line 68
go-live: before the app goes online for other people.
- Distinctive: line 69
feedback-review: when the person shares customer messages, reviews or complaints.
- Distinctive: line 78
Check reality before planning: Read the real code and settings, or the service's official page, before planning anything that depends on …
- Common: line 83
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 …
- Distinctive: line 86
One checkpoint per wave, at least: Never bundle two waves into one checkpoint.
- Distinctive: line 92
Never make up facts, numbers, prices or quotes: If you don't know, say so.
- Distinctive: line 105
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 …
- Distinctive: line 109
If a doc is wrong or out of date, fix it right away and tell me.
≈ “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.
Files
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:
- Open http://localhost:8765. You'll see your 4 cakes.
- Order a 2 kg cake for Saturday twice. Both should go through.
- Try a third. You should see "That day is full".
- 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:
docs/1-PRD.md: what we're building and why: requirements (R#), metrics (M#), what we're not doing, what must never happen.docs/2-APP-FLOW.md: screens (S#) and each person's journey.docs/3-DATA-AND-RULES.md: what we store, who can do what, how things move between steps.docs/4-HOW-IT-WORKS.md: how it's built and run.docs/5-BUILD-PLAN.md: which wave we're on.- The newest file in
docs/handoffs/: where we stopped. - 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.shand 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/withpaths:; Cursor:.cursor/rules/*.mdcwithglobs; 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). -->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
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.

