A field guide for your first build
You have two custom skills and one playbook. This explains, in plain terms, what each one is for, why it exists, and how they fit together when you actually sit down to build something.
The whole idea in one line
You do the thinking. The tools catch the thinking on paper so that a tired you tomorrow, or a fresh AI session next week, can pick up exactly where you left off without you re-explaining anything.
Start here
When you build a project across many days and many chat sessions, the same thing keeps breaking: memory leaks out.
You decide something important on Monday. By Thursday you have forgotten why. You open a new chat and the AI knows nothing about your project, so you spend twenty minutes re-explaining before any real work happens. You tell the AI "we agreed not to do X," and it does X anyway because that agreement lived only in a chat that scrolled away.
The fix is simple to say and hard to do by hand: write the important things down in fixed places, and keep them current. That is all these tools are. They are not magic. They are disciplined note-keeping, automated so you actually do it.
The cast
Each has one job. Keeping their jobs separate is what keeps the system from getting tangled.
You give it a rough idea. It first tells you honestly whether the idea is worth building, then turns the good ones into a full plan: what to build, in what order, and how you will know each piece works.
When you use it: once, at the very beginning, before any code exists. It hands you a set of starter files and then steps out of the way.
This is the rulebook for how you build, not what. It defines the back-and-forth loop between the planning chat and the coding tool, and the discipline that keeps a project on the rails: build one small piece at a time, prove it works before moving on, never let the AI wander off.
When you use it: constantly, in the background, all through the build. It is the working style, not a step.
It writes and refreshes one file, STATE.md, that answers "where is this project right now?" Current status, decisions made and why, the exact next step. A cold session reads it and is instantly caught up.
When you use it: whenever you are about to close a chat or start a new one. It is the save point.
Why two chats, not one
The single most important idea to understand: you work with two AI surfaces at once, and you keep their roles apart.
The web app chat is the architect. It thinks, plans, and writes precise instructions. It does not write your project's code.
The coding tool (Claude Code) is the builder. It takes one instruction at a time, writes the actual files, runs the tests, and reports back what really happened.
You sit between them, carrying small packets back and forth. Why split it? Because a planner that also codes drifts. It gets excited, writes too much, and loses the plan. Keeping the roles separate is what keeps you in charge instead of watching an AI build something you didn't ask for.
The sequence
From blank idea to shipped project, here is the real order of events.
In the web app, run /forge with your idea. It vets it, scopes it, breaks it into small modules, and emits a starter file set. It asks one key question up front: is this a timed hackathon or a normal project? That choice quietly tunes everything downstream.
You + the plannerYou make a new folder, drop the forge files in, and commit them by hand. The very first build task, "Module 0," creates the folder structure, the virtual environment, and installs dependencies. Setup is treated as a real step with its own success check, not an afterthought.
You + the builderThe architect writes a small instruction packet for one module. You paste it into the builder. The builder does exactly that, runs the test, and hands back a report with the real output. The architect checks the report against the plan. One piece done. Repeat.
Architect ⇄ builderBefore closing a session, run /state. It refreshes STATE.md so tomorrow's session, or a brand-new chat, reads one file and knows the status, the decisions, and the next move. No re-explaining.
You + the memoryWhen the modules are done and the tests pass, you finish the README, fill in the real numbers, and make the repo public. The plan you wrote in step one already framed it to look good to a recruiter.
YouWhat forge leaves behind
Every file has exactly one job. That is the whole trick: one fact, one home, so nothing contradicts anything else.
Why the guardrail file matters
A written rule like "never commit for me" gets followed most of the time, but not always. A guardrail in settings.json is enforced by the tool itself, every single time. The lesson: for the rules that must never break, don't ask, block.
What a packet looks like
The whole loop runs on two small formats. You don't memorize them; the tools produce them. This is just so they aren't a mystery.
The architect hands you this to give the builder:
The builder hands this back for you to paste to the architect:
The rule that ties it together: a piece is only "done" when the report shows real output and a real commit. The AI saying "it works" is never enough. You look at the proof.
One more thing
The same system runs two speeds, and forge sets the speed when you answer that first question.
In a timed hackathon, the clock is the enemy. Forge skips the "is this idea good" check, because organizers already chose the problem. It drops the polished tests in favor of fast working checks. The playbook adds time boxes, a hard "stop improving and ship" rule near the deadline, and a reminder to sleep.
In a normal project, quality is the point. Every check becomes a real saved test. Cleaning up your code is allowed and encouraged. There is no clock, only "is this piece actually done."
You never manage this by hand. You answer one question at the start, and the right mode is baked into every file forge writes.