Using Intent-First Development on a Greenfield Project

You read the cornerstone piece on Intent-First Development. The argument landed.

You also looked at the recommended tooling — a set of Claude Code plugins that automate the design-session machinery — and noticed something. Maybe your AI tool isn't Claude Code. Maybe it is, but you'd rather understand the methodology before committing to a specific plugin ecosystem. Maybe you want to know what the plugins are automating before you let them run. Maybe you're evaluating IFD on behalf of a team and need to be able to defend the practices on their own merits, not as features of a tool.

Whatever the reason, you'd like to know whether IFD is something you can adopt without installing anything specific to it.

The answer is yes. The plugins are conveniences over a methodology that does not require them. This piece walks the greenfield adoption sequence using only your AI tool's native capabilities and a willingness to drive the discipline yourself. It is more work than the plugin path. It is also clarifying — by the end, you will know exactly what the plugins do, why they do it, and whether you want them after all.

The misconception

"Documentation precedes code" is a methodology principle. It is not a sequencing requirement. It does not mean "write the full design doc, then start coding." That reading produces the response the methodology is most often dismissed for: "I don't have enough clarity yet to write that — I need to build something first."

We agree. You don't have that clarity yet. Nobody starting a new project does. The architecture you'd write on day one is a guess, and committing to it on day one is the most expensive mistake you can make on a new project. Premature architecture is the exact failure mode IFD is built to prevent.

Greenfield IFD does not start with an architecture document. Whether you use plugins or not, it starts somewhere higher.

What actually starts the work

Greenfield IFD adoption — with or without tooling — rests on two ideas that change the cost equation entirely.

First: the design session is the first documentation. You do not write a design doc and then have a design session. You have a design session, and the artifact it produces is the design doc. There is no double work. The session itself runs from a vision-altitude opening — what problem are we solving, for whom, and what changes when we ship — and the explanation document captures that as it surfaces. If the session lasts thirty minutes, the doc is short. If it lasts two hours, the doc is longer. There is no "documentation step" separate from the thinking step.

Second: altitudes match the clarity you actually have. IFD's design protocol uses five altitudes — Vision (50,000 ft), Capabilities (30K), Architecture (10K), Component Design (5K), Implementation (1K). On day one of a greenfield project, you have vision-level clarity. That is enough to start. You document at 50K. You do not descend to 30K until 50K is settled, and you do not descend to 10K until 30K is settled. Each altitude only commits to what is genuinely known at that altitude. Premature commitment to an altitude you can't yet defend is the failure the protocol prevents.

The plugin path enforces the altitudes through explicit gate-checks built into the design-session machinery. Without it, you are the gate-keeper. You watch for the moment when a session is drifting downward — when the conversation has moved from "what problem does this solve" to "what database should we use" — and you pull the conversation back. The discipline is the same. The mechanism shifts from automated to manual.

These two ideas together are why IFD adoption on a greenfield project is not a documentation pre-investment. The first session produces the first doc. The first doc is short, because day-one clarity is short. Lower altitudes get documented when they earn the right to be documented — when the higher altitudes have stabilized.

What going in without it costs

The argument for IFD on greenfield code is not "documentation is good." Day-one design docs have been "good practice" for forty years and most teams skip them, because most day-one design docs are wrong before the second sprint. The argument is sharper than that.

On a greenfield codebase being built with AI assistants, every session generates code from inferred intent. If the intent has not been articulated, the AI infers it from whatever's in the prompt — typically a paragraph of feature description. The output is a plausible design at implementation altitude, generated in the absence of any commitment at vision, capability, or architecture altitude.

What you get, predictably:

• An architecture that emerges by accident from whichever AI session happened to land first, optimized for the first feature rather than the system
• Capabilities that aren't named, scoped, or prioritized — they accumulate until somebody manually traces what the system does today and how
• Decisions that were never made — defaults the AI selected because nobody specified otherwise, now load-bearing
• Three months in: a working prototype that nobody can defend the shape of, because the shape was generated, not chosen

This cost is paid whether or not you use IFD plugins. The plugins do not create the value of capturing intent — they speed up one part of capturing it. The methodology is what catches the drift before it accumulates.

What you actually do

Five passes. Most are conversational rather than batch — greenfield work is design conversation, not extraction. Each is something you do deliberately with your AI assistant, in sequence. The first run takes an afternoon. Everything after is the next altitude descent or the next feature.

Pass 1 — Open the empty repo

Create an empty repository, open it in your AI tool, and write a one-paragraph starter file at the project root. Most AI tools read a file at the project root for orientation — Claude Code reads CLAUDE.md, Cursor reads .cursor/rules/*.mdc, Codex reads AGENTS.md. Whichever your tool uses, the starter content is small:

"This is a new project. It is going to follow Intent-First Development methodology — design happens through documentation, decisions are formal artifacts, code is the executable expression of the design corpus. The project's scope is [one-sentence description]. Before any implementation work, we will run a 50,000-foot vision design session and capture the result as docs/explanation/[system-name]-vision.md."

This file is what gives the AI a methodology-grounded starting picture before any design work is done. It is the equivalent of the orientation that brownfield projects get from reading the existing codebase — except here, you are providing the orientation directly because there is nothing yet to read.

Pass 2 — Scaffold the IFD structure

Create the Diataxis folder tree and the register subfolders. You can do this manually with mkdir, or have your AI do it:

"Create the following folder structure under docs/: explanation/, how-to/, reference/, tutorials/. Under reference/, create subfolders for decisions/, assumptions/, open-questions/, risks/, features/, stakeholders/. Add a README.md to each register subfolder briefly describing what artifacts that register holds. Add a top-level INTENT-FIRST.md that names this project as following IFD methodology."

IFD defines standard templates for each artifact type — Design Decision Document, Assumption, Open Question, Risk, Feature, Stakeholder, Project Context Card, Roadmap. These are provided as part of an IFD engagement with XTIVIA; if you're working independently, a minimal stub structure is enough to start and your AI can scaffold one on first use. The methodology does not require templates to be present from day one, but consistent structure makes it faster to scaffold new artifacts during sessions.

This step takes a few minutes. There is no day-one design cost; the structure is stamped, not authored.

Pass 3 — Fill in the Project Context Card

The Project Context Card is a one-page artifact that sits between vision and capabilities. It answers questions that constrain every design decision the project will face: time-to-market pressure, team skill level, performance sensitivity, rewrite horizon, and the hard problems the system has to solve. Every Design Decision Document in the project will cite it rather than re-deriving project terrain from scratch.

You can fill this in by hand or by walking through it with your AI:

"I'm starting a new IFD project. Walk me through the Project Context Card questions one at a time. After each answer, ask me a follow-up that probes the answer for honesty rather than aspiration. The questions are: 1) When is the best time to market? 2) What is the team's skill level? 3) How performance-sensitive is the system? 4) What is the rewrite horizon? 5) What hard problems must this system solve that adjacent systems will not? Don't accept vague answers — push back when the answer is missing a constant that future decisions will need to cite."

Open the resulting card. Read it back honestly, not aspirationally. "Senior team familiar with the stack" and "Mid-level team, first time with this technology" license entirely different architectures. The Card is the difference between decisions that hold up and decisions that get rewritten in three months.

This step takes 30 minutes. It is the highest-leverage 30 minutes you will spend on the project.

Pass 4 — The first 50K design session

Now the structure exists, and the project terrain is named. From here, the first piece of work — the system itself, at the highest altitude — gets a design session.

The opening prompt for a greenfield 50K session:

"I'm starting a new project. I want to run a 50,000-foot vision design session — this means we commit to vision-level intent and nothing else. We do not descend to 30K (capabilities), 10K (architecture), or below in this session. If you find yourself starting to discuss specific components, technologies, or architecture, pull the conversation back to vision.

The problem is [problem statement]. The audience is [primary stakeholder, with their pain point named]. The success measure is [what changes when this ships]. I want to articulate the vision before descending to anything more concrete.

Help me produce a vision document that captures: what problem the system solves, who feels the pain today, what changes when it ships, what the system explicitly is not, what stakeholders have a stake in it, and what risks or open questions are visible at this altitude. The document goes to docs/explanation/[system-name]-vision.md."

The session that follows commits to vision-level intent and nothing else. The output is an explanation document — short, defensible, and stable. Read it. Where the AI overcommitted to lower-altitude detail, edit it back up. Where the AI missed something, fill it in. The document is the design at this altitude; it is the artifact, not a placeholder for one.

During the session, choices will surface. When they do, capture them. Without the plugin's auto-triggering capture skills, this is a deliberate act:

"Pause. We just made a choice — [restate the choice and the alternatives]. Scaffold a Design Decision Document at docs/reference/decisions/DDD-001-[descriptive-name].md capturing: the scenario, the options considered, the recommendation that emerged from analysis, and the decision we just made. Keep recommendation and decision as separate fields. If they differ, name what drove the deviation."

Repeat the same pattern for assumptions, open questions, and risks as they surface. The discipline is the same as the plugin path; the trigger is your attention rather than the plugin's pattern matching.

Pass 5 — Altitude descent as the project matures

You do not descend to 30K (capabilities) in the same session as 50K unless 50K stabilized cleanly. You do not descend to 10K (architecture) until 30K is settled. Each descent earns its altitude by demonstrating the altitude above is genuinely understood.

The gate condition for descending from 50K to 30K is this: can a stakeholder read the vision document and recognize their problem in it? If yes, the vision is stable and capabilities can be discussed. If no, the vision needs another pass. A common failure mode is descending too early because the conversation has momentum — the AI will follow the practitioner downward unless held back. Without the altitude plugin to enforce gates, the practitioner is the holder.

When you do descend, the prompt for a 30K capabilities session looks like:

"We are descending from 50K (vision) to 30K (capabilities). The vision document at docs/explanation/[system-name]-vision.md is settled — read it before answering. We are now naming what the system does, in business terms, organized by business function. We are not yet discussing components, technologies, or architecture — that is 10K work. Help me enumerate the capabilities the system needs to provide to deliver the vision. For each, capture: what it does, who uses it, what triggers it, what it produces, and what success looks like. Group them by business function. The output goes to docs/explanation/[system-name]-capabilities.md."

The same pattern repeats for 10K (architecture), 5K (component design), and 1K (implementation). Each altitude has gate conditions for descending; each session produces an explanation document that lives at that altitude in the corpus. Decisions, assumptions, risks, and open questions are captured throughout, into the registers scaffolded in pass 2.

That's the whole adoption sequence. The first run produces the vision. Everything after is the next altitude or the next feature, and the next.

What the plugins would have done differently

Each of these passes is what an IFD plugin automates. The intent-first plugin scaffolds passes 1 and 2 in a single command (/ifd-init) and provides seven capture skills that auto-trigger when load-bearing observations surface in conversation — /capture-decision when a choice is named, /capture-assumption when a constraint is treated as fixed, /capture-question when a deferral is named, and so on. The altitude plugin enforces the altitude-gated design protocol with explicit gate checks at each descent — it watches for the conversation drifting downward and pulls it back, so the practitioner is not the only safeguard.

If you find yourself running these passes regularly — across multiple projects, on a recurring engagement basis, or under client pressure where altitude-discipline lapses are costly — the plugins pay for themselves quickly through gate enforcement, capture-skill auto-trigger, and prompt consistency. If you're running this once on a single greenfield project, the methodology-only path described above is faster than installing and configuring plugins.

The methodology is what matters. The plugins are an automation of it. Either path produces the same shape of corpus.

What you don't have to do

This list is the part most teams need to hear explicitly.

• You don't have to write the whole architecture before you start. Day-one architecture is a guess. The protocol commits to vision first, capabilities second, architecture third — and only when each earns it.
• You don't have to enumerate all features. The Roadmap and the feature register start empty and fill in as features become real, not when they're hypothesized.
• You don't have to commit to a tech stack on day one. The Project Context Card constrains technology choice, but the choice itself is a Design Decision Document made when the architecture altitude calls for it — not before.
• You don't have to do all five altitudes the first day. Most greenfield projects spend their first week at 50K and 30K. Architecture (10K) earns its turn when capabilities are stable. Component design (5K) earns its turn when the architecture is. Implementation (1K) is the last altitude, not the first.
• You don't have to commit to specific tooling. The methodology runs on top of any AI assistant capable of running design conversations and producing structured documentation. If you adopt plugins later, the corpus you've already built carries forward unchanged.
• You don't have to convince everyone before starting. A single team member can run the first 50K session and produce the first explanation doc. The first design decision document is a contagion event, not a mandate.

The real tradeoffs

The methodology-only path is more work than the plugin path. That is the reality on the ground. Likewise, you only get out of it what you put into it.

You are the gate-keeper. The altitude plugin enforces gates by watching for premature descent — when a 50K session starts discussing 10K concerns, the plugin pulls the conversation back. Without it, you hold that line yourself. This is harder than it sounds. AI assistants are eager to be helpful; they will follow you downward into specifics whenever the conversation gives them an opening. The first few sessions are particularly hard because the practitioner does not yet have a feel for which questions belong at which altitude. Expect to catch yourself partway down and pull back manually.

You are the capture-trigger. The intent-first plugin's capture skills auto-trigger on phrasing patterns — they recognize "let's go with X over Y because Z" and offer to scaffold a Design Decision Document before the conversation moves on. Without them, you have to notice these moments yourself. A choice that is not captured at the moment it surfaces is much harder to capture later — the alternatives that were considered, the constraints that ruled some of them out, the reason the decision tipped one way rather than the other, all begin to fade within hours. The first few weeks are particularly costly here; you will lose decisions you wish you had captured. This improves as the discipline becomes habit, but the cost is real.

Documentation written before code may need significant revision as reality is encountered. That's the cost of designing before building, regardless of tooling. The methodology does not pretend otherwise — it pretends the cost is worth paying because the alternative is shipping a system whose shape was determined by accident.

Specifically, what greenfield IFD does not give you:

• Certainty. A vision document is a commitment to a problem framing, not a guarantee that the framing is right. The framing may need to be revised as you learn. The protocol expects this — that's why each altitude is documented before descent, so revisions higher up trigger reconsideration lower down rather than silent drift.
• Speed past the design phase. A team that wants to ship a working prototype by Friday is going to find a 50K session inconvenient. The session is the design phase; if the team skips it, the design happens by accident during implementation.
• Protection from external pressure. A client demanding a demo by next Tuesday will not be moved by the methodology. The methodology helps you decide what the demo is; it does not slow the demo down. Sometimes the answer is a 30-minute 50K session, a 30-minute 30K session, and a sprint to ship — and the documentation is short because the clarity is shallow at this stage. That is correct usage of the protocol, not a violation of it.

The honest framing: the methodology-only path gives you the structure on day one, the altitude discipline through the project's life, and the capture habit for every decision that gets made — the same outcomes as the plugin path. It costs you more attention and more orchestration. It rewards you with full understanding of what each altitude is doing and why, and full portability across whatever AI tooling you use now or later.

Frequently Asked Questions

How long before I'm actually writing code? Give me a realistic timeline.

For a typical greenfield project, the first session (50K vision) takes 30–60 minutes and produces a one-page document. A second session at 30K (capabilities) takes another 60–90 minutes. Architecture (10K) is 2–4 hours across one or two sessions. Component design (5K) runs in parallel with implementation once architecture is stable. You can realistically be writing production code within one to two days of starting — not weeks — because the methodology does not require full corpus completion before any implementation. Implementation begins when the relevant altitude is settled. The cost is paid upfront on design; it is not a multi-week documentation sprint.

The post says "you are the gate-keeper" without plugin enforcement. What's the actual failure rate?

High, at first. The first few sessions without plugin enforcement will slip past altitude boundaries you didn't notice. A 50K vision session will drift into discussing the database, and you'll catch it ten minutes in — or not at all. The drift does not invalidate the session; it means the session produced some 10K output mixed into a 50K document. Read the output, move the lower-altitude content to deferred details, and continue. This improves quickly. After three or four sessions, you start to recognize the moment the conversation is dropping altitude, and pulling it back becomes instinct. The plugin path reduces this failure rate significantly; the methodology-only path teaches you the discipline by requiring it.

What specifically does the Project Context Card prevent? Why not skip it?

The Card captures the constants that every design decision will cite: team skill level, time-to-market pressure, performance sensitivity, rewrite horizon, hard problems the system must solve. Without it, each design session re-derives these from context — or worse, assumes them and never surfaces the assumption. Twenty decisions collectively assuming a "mature, experienced team" context without writing it down means those assumptions are invisible to the next person running a session. The Card writes them down once. For a solo project, skipping it is fine. For anything with more than one decision-maker, skipping it costs you more in alignment than writing it cost in time.

If the 50K vision turns out to be wrong — the problem framing is wrong — does the whole corpus have to be rebuilt?

Usually not. You ascend explicitly and revise. The protocol is bidirectional: when a lower-altitude artifact reveals that a higher-altitude artifact is wrong, you ascend to the altitude where the issue lives, revise the artifact, validate the gate condition again, and re-descend through affected intermediate altitudes. A vision change propagates downward — the capability map may need revision, which may require architectural reconsideration. Documents that survive the vision change unchanged are left alone; only those that depended on the original framing need revision. "Wrong vision" is less catastrophic than it sounds precisely because the altitude structure makes propagation explicit.

How is this different from just writing a good README and some comments before you start?

A README describes what the system is. A comment explains what a line does. An IFD vision document answers why the system exists, for whom, what success looks like, and what the system explicitly is not — in a document that lives in the same repository, in the same review process, and is read by the AI assistant as conversation context for every implementation session. The distinction is not the format; it's that the corpus is load-bearing, maintained, and directive. It shapes what the AI produces next Friday, not just what a new hire reads on their first day.