Skip to content

From an idea in a chat window to a repo the robot can build

Most "I built X with AI" posts skip the part that actually matters. They show you the finished thing, or they show you a single clever prompt, and the implied story is: open a chat, describe the app, get code. That is not how a real project gets built, and if you try it that way you get a pile of plausible-looking code with no memory, no audit trail, and no way to tell the AI what to do next without re-explaining the whole project every time.

This is the first of three posts about how I actually do it, grounded in how this project -- a multi-device board game platform -- went from a blank chat window to AI writing code I can test. This post is the on-ramp: how a person with a brand new idea plans it entirely in a chat, moves it into a git repository, and drops in a workflow orchestrator so AI builds it from tickets instead of from vibes. The two companion posts go deeper: The UI-spec prompt playbook covers how I write the prompts that turn a screen description into a frozen, buildable spec, and The orchestrated build-and-feedback loop covers what happens once tickets are flowing and the AI is shipping code on its own. This one is about getting to that starting line.

There are three beats, and then an honest accounting of what this on-ramp does not give you for free.

Beat one: plan in chat, but capture it as docs, not as scrollback

The first instinct everyone has is right: start by talking to the AI. A chat window is genuinely the best place to think out loud about a new idea. You describe the thing, the AI pushes back, you discover what you actually mean, you throw away the first three versions of the architecture. That part works.

The mistake is leaving it there.

A chat transcript is the worst possible home for the decisions you just made. It is unsearchable in practice, it scrolls away, and -- the killer -- the next AI session has no access to it. Every new conversation starts from zero. You will find yourself re-explaining "no, the server is authoritative, the clients are untrusted" for the fortieth time, because the only place that decision lived was a chat you closed last week.

So the rule is: ideation happens in chat, but it lands as durable, versioned files. For this project the conversation distilled into a small set of documents that each own one kind of decision:

  • the overview docs -- the architectural north star. What the thing is, the load-bearing rules (server-authoritative, role-filtered views, pure-Python engine), the data model, the trust boundaries. This is the file the AI reads first on any new task.
  • the overview docs -- the phase-by-phase build plan. What ships in what order, and why the order is what it is. Build order is strict; the roadmap is where that strictness is written down.
  • the overview docs -- the parking lot. Every "ooh, what if" that is real but not now. Crucially it also has an explicit Rejected section, so killed ideas stay killed instead of getting re-raised every third conversation.
  • the overview docs -- the business and positioning thinking, kept separate from the architecture so the brief stays a brief.

The split matters more than the exact filenames. The point is that when a future AI session asks "what are we building and why," the answer is a file it can read, not a memory it does not have. The chat is where you think; the docs are where you remember. If a decision only exists in scrollback, it does not exist.

A good way to do this beat: have the AI draft these docs from the conversation, then you edit them down. The AI is good at turning a rambling design discussion into a structured brief. You are the one who knows which parts are load-bearing.

Beat two: the repo is the contract

The moment your idea becomes buildable is the moment it becomes a git repository.

This sounds obvious -- of course code goes in a repo -- but the reason is more specific than "version control is good." A repo is the first place where the AI can do all three of the things a builder needs to do: read context, write code, and leave a trail of what it changed. A chat can read and write, but it cannot leave a durable, inspectable trail. git init is the step that gives the AI an audit log it cannot wriggle out of.

Two layout decisions earn their keep early.

Docs-first, partitioned by area. The docs/ tree is split so that different kinds of work touch different files: the overview docs for cross-cutting narrative (the brief, the roadmap), the server docs for backend guides, the client docs for frontend guides. This is not tidiness for its own sake. When two AI tasks run against the same repo, the orchestrator can tell whether they collide by looking at which paths they touch. Partitioned docs let independent work stay independent. A flat docs/ folder forces everything to serialize.

Two clone roots, on purpose. This one is non-obvious and it bit me before I named it. There is a chat/authoring clone -- where I hand-edit docs and plan in a chat session -- and there are ticket clones -- the throwaway working copies the orchestrator spawns to do one task and then discards. They are deliberately separate roots. Mixing them means a ticket run reaches into the clone where you are hand-editing files, and the resulting confusion is exactly the kind of bug that is miserable to track down. If you take one structural idea from this post, take this: the place where a human plans and the place where the robot works should not be the same directory.

The repo is also where you write down the rules the AI must follow. Which brings us to the third beat, because a repo full of good docs still does not make the AI a builder. It makes it a very well-informed advisor.

Beat three: the orchestrator is what turns an advisor into a builder

Here is the gap nobody warns you about. You can have a beautiful brief, a clean repo, and an AI that gives genuinely excellent advice -- and still be doing all the actual building yourself, copy-pasting code out of a chat and pasting errors back in. The AI is advising. It is not building.

What closes that gap is a workflow orchestrator: a small system that turns "AI, write this code" into a governed pipeline. For this project that is the workflow subsystem subsystem, driven by a single dispatcher, the orchestrator dispatcher. The first-run setup is written down in the bootstrap docs, and it is worth understanding what it actually wires up, because the shape generalizes even if you never touch this particular scaffold.

The pieces:

  • Tickets are the unit of work. Instead of asking the AI to "go fix the lobby screen," you write a ticket file under the backlog. A ticket says what to do, what it touches, what "done" means, and how to verify it. It is a contract the AI agrees to before it writes a line.
  • A dispatcher runs the lifecycle. the orchestrator dispatcher is the one entry point for the verbs that matter: spawn a clone for a ticket, run it, run the review preflight, ship it. The human does not run raw git inside a ticket clone; the dispatcher does, because it also has to update the run records and state the orchestrator depends on.
  • Review preflight gates every change. Before anything merges, a battery of checks runs -- lint, tests, project-specific rules. The AI cannot ship code that fails the gate. This is the difference between "the AI wrote something" and "the AI shipped something that passes the bar."
  • Run records leave the trail. Every ticket produces a sibling .run.md file recording what actually happened: the surprises, the dead ends, the judgment calls. Six weeks later, when you wonder why a thing was built the way it was, the answer is on disk.

The single most important rule the orchestrator enforces is cultural, not technical. It is the one in this project's CLAUDE.md that says: always propose a ticket -- never hand-edit main from chat. When you ask for a change, the default response is not to edit the file. It is to draft a ticket. That sounds bureaucratic until you have watched the alternative -- a dozen undocumented chat-driven edits to main that nobody can reconstruct -- and realized the ticket is the thing that makes the AI's work debuggable later. The ticket, the review, the run record: those artifacts are the whole point. Ad-hoc edits skip all of them, and you only notice what you lost when something breaks and there is no trail.

That is the on-ramp. Plan in chat, capture as docs. Move to a repo, where the docs become a contract and the AI gets an audit trail. Add the orchestrator, where tickets and gates and run records turn the AI from an advisor into a builder that ships under rules.

The honest edges

This is the part the genre usually skips, so I will not.

The orchestrator is opinionated, and it has real setup cost. BOOTSTRAP.md is not a thirty-second npm install. You are standing up a config file, review surfaces, agent rules, and a dispatcher, and you have to understand the clone-per-task model before any of it makes sense. For a weekend project that you will throw away, this is too much machinery. The on-ramp pays off when the project is going to live long enough that re-explaining context becomes the dominant cost -- which, for anything real, happens faster than you expect. But it is a real up-front tax, and pretending otherwise would be dishonest.

Planning docs go stale if you do not maintain them. A PROJECT_BRIEF.md that no longer matches the code is worse than no brief, because the AI will believe it. The whole system rests on the docs staying true, and keeping them true is ongoing work that nothing fully automates. This project leans on hard rules that force doc updates to ride along with the code changes that invalidate them -- but that is a guardrail against drift, not a cure for it.

You still have to be able to review what the AI produces. This project's owner is a Python and C++ developer with essentially no web-frontend experience, driving an AI-built React client without pretending to have learned or source-reviewed it -- the boundary named in the companion post Shipping a React client I have not read. The orchestrator does not remove the need to understand the output; it makes the output reviewable, which is not the same thing. If you cannot tell whether the product behavior is right, a pipeline that ships it faster is not obviously a win. The on-ramp makes you a faster builder. It does not make you a builder you were not.

None of these are reasons not to do it. They are the shape of the trade. You are buying durable context, an audit trail, and a governed build loop, and you are paying for it in setup cost, doc maintenance, and the requirement that you stay able to judge the work.

That is the starting line. Once tickets are flowing through the orchestrator, the interesting questions move up a level: how do you write a prompt that turns a vague screen idea into a spec precise enough to build from (the subject of The UI-spec prompt playbook), and what does the day-to-day build-and-feedback loop actually feel like once the AI is shipping on its own (the subject of The orchestrated build-and-feedback loop)? Those two posts are the rest of this builder's-eye series. There is also a separate, more machine-facing pair on the orchestration internals -- the phase-to-ticket-to-retro lifecycle, and the review surfaces and AI-first guardrails -- for readers who want to see how the pipeline is built rather than how to use it; the build-loop post links into that pair. And the whole cluster has a capstone, The cross-game compounding flywheel, on why each new game built this way is cheaper than the last, and how a lesson learned building one game ratchets the quality of all the others.

But none of that matters until the on-ramp is built. Plan it in chat. Land it as docs. Put it in a repo. Add the orchestrator. Then the robot can build.

Or: subscribe for the next two posts in this series.