working-with-agents · open source · MIT
Stop prompting the agent.
Onboard it like a senior hire.
A capable agent that keeps producing the wrong thing isn’t a prompting problem — it’s an onboarding problem. It doesn’t know your stack, your conventions, your traps, or your definition of done, because none of it is written where it can read it. Fix that once, in the repo. The tool is interchangeable; the operating model is not.
$ ✔ detected Next.js · TypeScript · Tailwind · pnpm✔ 6 questions pre-filled — confirmed in 22s✔ wrote AGENTS.md✔ wrote DESIGN.md✔ wired .claude/ · .cursor/ · AGENTS.md → committed. every session now starts from the same baseline.# get started
$ npx github:alinuredini/working-with-agents init # the problem
Every new chat, the agent re-guesses your stack, re-derives your conventions, and re-invents your design. You re-explain the same context you explained yesterday — the most common waste in agentic work, and entirely avoidable.
// you’re not a bad prompter. you skipped onboarding.
# how it works
- 1 run init zero dependencies, one command in your repo root
- 2 detect + confirm it reads your stack, asks a few pre-filled questions (~20s)
- 3 commit once AGENTS.md + DESIGN.md + tool wiring, and every agent starts there
$ ls onboarding/
- AGENTS.md onboarding doc — stack, conventions, traps, definition of done
- DESIGN.md design chapter, generated from your code, not hand-written
- CHECKLIST verification — the agent proves “done” before handing back
- config/ one doc, mounted into every tool you run
- skills/ optional agent skills, scaffolded and ready to commit
$ cat principles
- › context lives in the repo, not the chat
- › shortest working change wins
- › “done” means verified
- › let it push back
$ working-with-agents --tools
claude-code codex cursor antigravity pi gemini