When I start a new project now, I do not open with a prompt. I open with a blank concept folder.

This is a pragmatic experiment in building greenfield projects from a concept rather than from a chain of prompts. The code comes later: first you get the intent right, in plain markdown, where the agent can read it.

The Problem

A chain of prompts feels productive. You ask an agent to "build a web app", it generates boilerplate, and you are moving within seconds.

Then the problems begin. Halfway through you realize the database was the wrong call. You switch libraries. You rewrite core logic. You spend more time correcting the agent's assumptions than building the product, all because the requirements were never broken down before the code started. Each prompt is a local decision with no shared plan behind it, so the project drifts.

The Shift

This protocol flips the workflow. It is built on a simple thesis: if you do the rigorous thinking upfront in a concept document, you can largely hand off the execution to an AI agent.

You start with a blank concept folder. You write the problem statement and the constraints. You use the AI purely as a sounding board. You run theoretical pen tests and look for holes in your logic before a single line of code is written.

Because the protocol handles the mechanics of how work gets executed (slicing tasks, self-healing, and restarting exhausted sessions), the actual coding phase becomes mechanical. The repository-owned contract also makes the workflow portable across coding harnesses that load project instructions, including Cursor, Claude Code, and Antigravity.

A concept layer, not a loop

"Loop" has become the shorthand for the agentic execution cycle: the model acts, observes the result, and goes again until the work is done (Anthropic's agentic loop; tools like Claude Code even expose a /loop). ai-protocol is not that, and it is not an interval runner either. It is the layer the loop runs against.

It shares the loop's instincts (durable, verifiable iteration with recovery), but it puts the thinking before the cycle rather than inside it. The concept docs fix intent up front, AGENTS.md fixes the contract, and BUILD_STATE.md holds the state. A compatible agent loop can then become mechanical and resumable: it reads the contract and the state, runs the next verified slice, and checkpoints. The loop is the engine; ai-protocol is the track it runs on.

Setup

The starter is deliberately small: AGENTS.md, and five reviewable, repository-owned skills under .agents/skills/. Everything else appears only when the project reaches the stage that needs it.

To try it, download the latest starter ZIP, extract it, rename the folder, and open it in your preferred AI coding environment. The archive is not executable. Each GitHub Release also publishes ai-protocol-starter.zip.sha256 so you can verify the download.

If you prefer, copy the root AGENTS.md and .agents/skills/ directory manually. The optional kickstart.sh helper downloads that same release, verifies its checksum, and extracts it into a new project folder.

curl -fsSL https://raw.githubusercontent.com/dnlbox/ai-protocol/main/kickstart.sh | bash -s -- my-project

The Lifecycle

Stage 1: Concept Intake

Invoke /concept-intake and talk through the idea. The agent works in short, focused rounds, challenges gaps without scattering the conversation, and keeps a temporary docs/intake/concept-intake.md. It stops when the product core is covered and further rounds would only refine existing material.

Stage 2: Concept Shaping

Run /shape-concept when the intake is accepted. The agent proposes a small document structure, waits for approval, and turns the intake into canonical docs/concept/. You can keep exploring, researching, and resolving product tensions here without drifting into implementation planning.

Stage 3: Lock-in

When the concept is solid, run /plan-implementation. The agent resolves the technical strategy and compiles the mechanical execution contract: Project Specifics in AGENTS.md, a mandatory BUILD_STATE.md, and DESIGN.md or ROADMAP.md only when the project actually needs them. The ROADMAP.md example shows how a multi-phase plan stays separate from current execution state. Planning stops before writing product code.

Start implementation in a fresh session with Continue from BUILD_STATE.md.

Stage 4: Building (The Mechanics)

This is where the protocol shines. The project now carries its intent, operating contract, validation gates, and exact next step. You let the agent execute one small verified slice at a time instead of repeatedly answering decisions that should have been settled before the build.

Five key mechanics, baked into AGENTS.md, make that safe:

• Self-healing: when a validation gate fails, the agent gets back to green before it moves on. It never leaves a broken tree behind.
• Persistent state: BUILD_STATE.md records where we are, what is next, and how it was verified. The project always knows its own state.
• Roadmaps when needed: complex projects can carry a generated ROADMAP.md for multi-slice plans and gate criteria, while BUILD_STATE.md stays focused on the current handoff.
• Crash continuity: token exhaustion or a dead window is survivable. The next session reads the state file and the git log, then resumes where the last one stopped.
• Tiered delegation: each slice routes to the right model, a fast cheap one for mechanical bulk, the deep one reserved for architecture and integration.

During execution, /sync-protocol reconciles the existing operational contract when implementation changes project behaviour. /consolidate-state keeps BUILD_STATE.md lean when history starts to accumulate. There is no separate prompt file: AGENTS.md owns startup behaviour and BUILD_STATE.md owns current execution truth.

The protocol does not discover or install third-party skills. External examples can inspire a locally authored project skill, but every instruction that enters the workflow remains reviewable in the repository.

Stage 5: Ejecting

Eventually, the project matures and the concept documents may stop representing its accepted intent. Ejection must be deliberate: update or replace the source-of-truth rules in AGENTS.md, archive or remove stale concept documents, and retain only the instructions and skills that still describe reality. Standard tests and CI/CD pipelines can then carry more of the execution contract without leaving agents bound to obsolete product intent.

Nesting and workspaces

A project does not have to be one repo. An umbrella project (a workspace) can hold child projects, each its own ai-protocol scope, each often its own repo, nested as deep as you need: a monorepo of services, a set of sibling repos coordinated from above, or a personal workshop of independent tools.

The layers compose rather than collide:

• The nearest AGENTS.md above you is your contract. The universal baseline is the same at every level, so a child inherits the guardrails and only its Project Specifics differ; a workspace adds a Components dashboard and coordination rules.
• Each level owns its own BUILD_STATE.md. The workspace tracks cross-cutting work and points at each child; a child tracks only itself.
• Skills compose and load lazily: generic capabilities live at the workspace, project-specific ones at the child, and a child sees both (its own winning on a clash). At the workspace you load the shared set and pull a child's in only when work turns to it.

Open a harness at the workspace to coordinate across children, or inside a child to build it. Either way the agent finds the nearest contract and the right state.

Target Audience

This is explicitly for greenfield projects. Do not try to backfill this rigor into legacy monoliths. Retroactively writing concept documentation to satisfy an agentic workflow rarely pays off.

This workflow cut down the friction in my own daily operations, but it is an ongoing experiment. Try it out, pull it apart, and see where it breaks for you.