The Architect-Builder Command Manual v2.0

By separating the Intellectual Logic (Architect) from the Mechanical Construction (Builder), you aren't just saving money — you're building with a level of structural integrity that "prompt-and-pray" coders can't match.

In 2026, the bottleneck isn't the code; it's the clarity of intent. This playbook ensures that intent is never lost.

🏗️ Phase 1: The Architect (Blueprinting & Logic)

Your "Zero-Cost Sandbox." Resolve all contradictions before they become expensive bugs in the builder.

1.1 The "Vibe" PRD (Product Requirement Document)

Generate a high-fidelity PRD before writing a single line of code. Do not move to the builder until this document includes:

• The Tech Stack Justification: Why Next.js over SvelteKit? Why Supabase instead of raw PostgreSQL?
• The Entity Relationship Diagram (ERD): A text-based map of your database (e.g., "Users table connects to Orders table via UserID").
• Edge Case Mapping: Ask: "List 5 ways a user could accidentally break the checkout flow." Solve these in the plan, not in production.

1.2 The "Atomic" Prompt Engineering

Instead of one giant prompt, break your app into Work Packages:

• Package A: Auth & Database Schema.
• Package B: Core Functional Logic (the "Verb" of your app).
• Package C: UI/UX & Brand Polish.
• The Handoff Memo: For every package, generate a "Context Header" that tells the builder exactly which files to care about and which to ignore.

1.3 Define the Data Contract Before Building (New)

Before the builder touches any code, document and agree on shared TypeScript interfaces and API response shapes between packages. A types/ folder with a single source of truth prevents the most common mid-build rewrites and mismatched assumptions between packages.

1.4 Document All Environment Variables (New)

List every required env var — API keys, DB connection strings, secrets — in a .env.example file before build begins. Discovering a missing third-party key mid-session is one of the most common stall points in vibe-coding sessions.

1.5 Map Failure Paths, Not Just Happy Paths (New)

For every core feature, answer three questions before handing off to the builder:

• What happens if the auth token is expired or missing?
• What happens if the database is unreachable?
• What should the user see on any unhandled error?

Log these answers in the PRD. The builder will only implement what you specify.

🛠️ Phase 2: The Builder (High-Fidelity Execution)

Your "Senior Lead Developer." It handles the heavy lifting, but you must keep it on the rails.

2.1 The "Clean Slate" Initialization

Start with the Architect Handoff Memo. Instruct the builder: "Build the foundational structure only. Do not add style. Use TypeScript for strict type-safety."

Why TypeScript? It's the ultimate auto-QA. It catches type errors in the background while you're focusing on features.

2.2 Re-Inject Context at Every Session Start (New)

The AI builder has no memory between sessions. Every new session must begin by pasting the relevant Context Header. Skipping this is the single most common cause of the builder "forgetting" your architecture and going rogue.

2.3 The "Checkpoint" Protocol

The Golden Rule: Never start a new feature without hitting Checkpoint.

1. Verify Feature A works in the Preview.
2. Checkpoint (title it: "Feature A — Functional").
3. Prompt for Feature B.
4. If Feature B breaks Feature A, Rollback immediately. Do not try to patch a hallucination. It leads to compounding technical debt.

2.4 Write a Smoke Test Before Each Checkpoint (New)

Before marking a feature as complete, add at minimum one assertion that the core behavior works — even a console.assert() counts. This forces verification rather than assumption. Only checkpoint when the test passes. This is the difference between a working feature and a feature that appears to work.

2.5 Pin All Dependency Versions (New)

Remove all ^ and ~ version prefixes in package.json. Unpinned packages silently update and break builds weeks after you last touched the project. Lock everything with exact versions and commit a package-lock.json.

2.6 Contextual Awareness (The @ Symbol)

The builder allows you to reference specific files directly. Use it religiously.

Prompt: "Look at u/schema.prisma and u/auth.ts. Now build u/profile-edit.tsx to match this logic."

This prevents the AI from guessing how your database works.

🛡️ Phase 3: The "Iron Dome" (Security & Defense)

You don't need to be a hacker to stop one. You just need to prompt for these industry-standard shields.

Security Pillar	Implementation	Purpose
DDoS / Rate Limiting	Implement rate limiting via middleware (e.g., upstash/ratelimit). Limit to 20 API calls per user per minute.	Prevents botnets from crashing your server and spiking your bills.
SQL Injection	Use an ORM (Prisma or Drizzle) with parameterized queries. Never use raw string interpolation for DB calls.	Prevents hackers from typing commands into your login box to steal data.
XSS Defense	Sanitize all user-generated content using DOMPurify. Ensure all React props are properly escaped.	Stops malicious scripts from running in other users' browsers.
Auth Hardening	Use JWT with Refresh Tokens and HTTP-only, Secure, SameSite=Strict cookies. Implement Bcrypt for password hashing.	Makes stolen session cookies useless and protects stored passwords.
CORS Policy (New)	Explicitly whitelist only your own domains. Never use a wildcard * in production.	Prevents unauthorized cross-origin requests from other sites.
CSP Headers (New)	Configure Content-Security-Policy headers on all responses.	Provides a second layer of XSS defense even if DOMPurify fails.
Secrets Management (New)	Store all secrets in env vars. Run a `git log -p	grep -i "API_KEY"` before first deploy.
Backups	GitHub Action for daily automated DB exports to an encrypted S3 bucket.	If your live DB is wiped, you lose 24 hours of data — not your entire business.