New Project

🚀 new-project — Purpose-First Project OS & DOX Scaffolder

Aliases: Agent Engine | DOX Engine | agent-engine | dox-engine

Interactive project creator and Project Operating System provisioner. Implements the Purpose-First Hierarchical Decision Engine across 6 Sequential Execution Stages:

[ 🎯 Stage 1: Purpose-First Prompt ] ──► [ ⚡ Stage 2: Hierarchical Decision Tree ]
                                                      │
[ 🎨 Stage 4: Modern OKLCH / BEM ]   ◄── [ 🔌 Stage 3: Official Package Wiring ]
         │
         ▼
[ 📖 Stage 5: Client Intake Brief ] ──► [ ✅ Stage 6: Closeout ]

0. Stage 0: AI-Ready Pre-Flight Gate: Audits if root AGENTS.md and .agents/ container already exist and pass ai-ready audit.
1. Stage 1: Purpose-First Root Prompt & Project Identity: Initiates interactively by querying the foundational domain purpose before prompting for identity, mission, and scope.
2. Stage 2: Hierarchical Decision Tree: Prunes irrelevant questions based on selected purpose across 6 branches (Static, Content, Ecommerce, WebApp, Mobile, Custom).
3. Stage 3: Official Package Installation & Config Auto-Wiring: Automatically wires framework configs (astro.config.mjs, uno.config.ts, postcss.config.mjs, src/lib/medusa.ts, db.ts, auth.ts, capacitor.config.ts, .env.example) and synchronizes official dependencies in package.json with self-verification.
4. Stage 4: Modern Tokens & BEM Architecture Injection: Injects wide-gamut OKLCH tokens, fluid clamp() typography & spacing scales (src/styles/tokens.css), and reusable semantic BEM classes (.c-card, .c-button, .c-product-grid, .c-cart-drawer).
5. Stage 5: Client Intake Brief: Writes Client-Intake/00-Intake-Brief.md (employee checklist pre-filled from scaffold answers + agent instructions). Intake docs and start-here.md are written by the AI agent AFTER scaffolding, from real employee answers.
6. Stage 6: Closeout: Synchronizes .agents/context/ (decisions ADRs, product, current, architecture) and runs the health check.

When to Use

• User invokes or references "Agent Engine", "DOX Engine", "new-project", "scaffold a workspace", or "initialize Project OS".
• Provisioning a new client web application, headless storefront, digital publication, SaaS, or mobile app.
• Equipping an existing repository with the Agent Engine / Progressive Disclosure DOX architecture.
• Scaffolding a full-stack Next.js, Astro, Instatic, WordPress, or Expo project with companion integrations.
• Converting an Astro or Next.js web application to native iOS and Android APK via Ionic Capacitor.

Quick Reference & Presets

⚡ 1-Click Agency Golden Presets

Aria isolation rule: any preset or flag set selecting ariabuilder provisions the official ariabuilder/aria clone only (Astro + UnoCSS with Wind 4 preset + CMS + SQLite included). Every other companion in the preset is skipped with a printed notice and added only on explicit request.

Supported Framework Archetypes (@latest)

Procedure

🎯 6 Sequential Execution Stages

Stage 1: Purpose-First Root Prompt & Project Identity

The provisioner never guesses the project domain from ambient files. It prompts:

🎯 What is the primary purpose of this project?
  [1] Static Website          (Brochure, portfolio, landing page, minimal or zero compute)
  [2] Dynamic Content Website (Blog, publication, documentation, agency editorial)
  [3] Ecommerce Storefront    (Catalog, shopping cart, checkout, payments, inventory)
  [4] Full-Stack Web App      (SaaS, dashboard, auth, multi-tenant DB, background jobs)
  [5] Mobile Application      (Native iOS/Android, Expo React Native, or web-to-APK)
  [6] Custom / Infrastructure (Library, monorepo package, agent workspace, custom stack)

Gathers project name, tagline, author/organization, target audience, core problem, features, industry vertical, and catalog offerings.

Stage 2: Hierarchical Decision Tree & Interactive Tradeoff Engine

Each selection prunes irrelevant downstream choices while explicitly surfacing architectural tradeoffs (Lightweight vs. Full-Stack, Serverless vs. Local Container, Git-based vs. Embedded DB) so the user is in full control without opaque defaults or mystery breaks:

• Branch A (Static Website / Landing Page): Pure HTML/CSS (Zero build step, semantic BEM, OKLCH fluid design tokens) vs Instatic SSG vs Astro v7 vs Next.js SSG ➔ Hybrid UnoCSS Wind 4 vs Semantic BEM ➔ Hardware CSS animations vs Motion.dev. (Aria Builder is not an Astro add-on — selecting it provisions the isolated official scaffold instead of this branch's companions.)
• Branch B (Dynamic Content Website):
  • Astro v7 (Zero-JS baseline, islands):
    • StudioCMS (Astro DB / Turso native persistence) — Recommended for content blogs.
    • Emdash CMS (Cloudflare Workers, D1 database, and R2 storage) — Recommended for edge publications.
    • Aria Builder (ariabuilder.io) — Visual drag-and-drop page builder for marketing sites. Isolated official clone (ships its own Astro + UnoCSS + CMS + SQLite); all other companions are skipped unless explicitly requested.
    • WollyCMS — Self-hosted headless CMS for Astro (pages, blocks, media, revisions, Content/Admin/GraphQL APIs). Official Astro integration @wollycms/astro wired with local endpoint; run the CMS via npx create-wolly@latest per its quick start.
    • Keystatic — Zero DB overhead, Git-committed Markdown/MDX collections.
  • Next.js 16 (React 19 App Router):
    • Payload CMS 3.0 + Puck Visual Builder — Full-stack database collections with interactive visual block editing.
    • Payload CMS 3.0 Standard — Lexical rich text editor and typed collections.
    • Keystatic — Flat-file Git collections.
  • Roots Bedrock: Modern 12-factor WordPress with Composer and Gutenberg blocks.
• Branch C (Ecommerce Storefront): E-Commerce Tradeoff Questionnaire (Aria Builder never pairs here — it provisions as the isolated official scaffold; pair Medusa with plain Astro or Next.js instead):
  • Astro + MedusaJS: High-performance zero-JS storefront with Medusa v2 Sovereign Engine (Recommended for Speed).
  • Next.js + Payload CMS + Puck + Payload E-Commerce: All-in-one unified Next.js App Router application with Puck visual builder and native Product/Order/Customer/Stripe collections (Recommended for Fullstack All-in-One).
  • Next.js + Medusa v2 Sovereign Engine: Next.js App Router frontend with Medusa sovereign backend.
  • Stripe Direct Checkout: Lightweight zero-backend payments with hosted checkout and webhook routes.
  • Fastrr 1-Click / Razorpay: Accelerated mobile checkout for D2C brands.
  • Vendure: Scalable enterprise TypeScript GraphQL backend.
• Branch D (Full-Stack Web App): Next.js 16 App Router vs Astro SSR ➔ Database & Auth Tradeoffs:
  • Database: Neon Serverless Postgres (zero local infrastructure) vs Supabase (managed BaaS) vs Local Docker Postgres 16 (isolated local dev container) vs SQLite/Turso.
  • Authentication: Better Auth (Drizzle ORM adapter, full local control, typed client SDK) vs Supabase Auth (managed BaaS) vs NextAuth/Auth.js.
  • State Management: NanoStores (sub-1KB cross-framework reactive store) vs Zustand (React-only).
• Branch E (Mobile Application): React Native with Expo vs Astro + Ionic Capacitor (web-to-APK) vs Next.js + Capacitor.
• Branch F (Custom / Infrastructure): Custom architecture or governance-only workspace.

Stage 3: Official Package Installation & Full End-to-End Companion Wiring

The provisioner enforces Zero Half-Baked Stubs. Every selected technology is provisioned with its complete working ecosystem—schemas, route handlers, client SDKs, admin UIs, and Docker container services:

• Pure HTML/CSS Framework Option (--type=html / pure-html):
  • Standalone index.html with semantic BEM classes, linking wide-gamut OKLCH design tokens, reset, and hardware-accelerated animations with zero build step.
  • Pinned package.json scripts (bun x serve ., bun test, biome check src).
• Database & Drizzle ORM:
  • src/lib/schema.ts: Fully-typed starter schema defining relational users and posts tables.
  • src/lib/db.ts: Connection pool client exporting both db and re-exporting * from './schema'.
  • drizzle.config.ts: Configured pointing to ./src/lib/schema.ts with output to ./drizzle.
  • docker-compose.yml: For containerized Postgres (--db=postgres), provisions a local PostgreSQL 16 container with healthchecks and persistent volumes.
• Authentication (Better Auth & Supabase):
  • src/lib/auth.ts: Server-side Better Auth initialization configured with the Drizzle ORM adapter and database schema.
  • src/lib/auth-client.ts: Client-side React SDK (createAuthClient) exporting signIn, signUp, signOut, and useSession for immediate UI consumption.
  • Route Handlers: src/app/api/auth/[...all]/route.ts (Next.js App Router) or src/pages/api/auth/[...all].ts (Astro) wrapping auth.handler.
  • src/lib/supabase-server.ts: Server-side Supabase client with cookie storage adapters for SSR.
• Aria Builder (isolated official scaffold): Aria ships its own Astro + UnoCSS + CMS + SQLite, so selecting it clones the official repo untouched and adds nothing else unless explicitly requested:
  • git clone https://github.com/ariabuilder/aria.git into the target, npm install (skipped with --skip-install), npm run dev.
  • Open http://localhost:4321/admin; first visit completes setup at http://localhost:4321/admin/setup to create the first administrator.
  • Engine ensures the UnoCSS Wind 4 preset in ./uno.user.config.ts (upstream ships Wind3) and leaves everything else byte-identical to upstream. No bun create astro, no companion overlays, no token injection, no package.json rewrite.
• Content Management Systems (CMS):
  • Payload CMS 3.0 & E-Commerce Module: payload.config.ts, strongly-typed collections (Users.ts, Media.ts, Pages.ts, Products.ts, Orders.ts, Customers.ts), Next.js App Router admin UI (src/app/(payload)/admin/page.tsx), REST API route handler (src/app/(payload)/api/[...slug]/route.ts), Stripe checkout endpoint (src/app/api/payload-checkout/route.ts), and importMap.js.
  • StudioCMS: studiocms.config.mjs, Astro DB integration, and astro.config.mjs integration wiring (studioCMS()).
  • Emdash CMS: emdash.config.ts, Cloudflare D1/R2 routing, starter markdown article in src/content/blog/welcome.md, and blog listing at src/pages/blog/index.astro.
  • Keystatic: keystatic.config.ts, initial post in src/content/posts/welcome.mdoc, Next.js App Router and Astro admin pages (/keystatic) and API route handlers (/api/keystatic).
  • Puck Visual Builder: Strongly-typed component schema in src/lib/puck.config.tsx and Next.js App Router editor (src/app/puck/[...puckPath]/client.tsx and page.tsx).
• E-Commerce Engines:
  • Medusa 2.0 Sovereign Backend: Fully scaffolded backend/ directory with medusa-config.ts, docker-compose.yml (PostgreSQL 16 + Redis 7), package.json, tsconfig.json, .env.example, and custom route /src/api/store/custom/route.ts, alongside the frontend client SDK in src/lib/medusa.ts.
  • Stripe: Server client in src/lib/stripe.ts, Checkout session creation route handler in src/app/api/checkout/route.ts, and webhook signature verification route in src/app/api/webhooks/stripe/route.ts.
  • Razorpay: Server client and order creation endpoint in src/lib/razorpay.ts.
  • Vendure: Typed GraphQL client for catalog queries and mutations in src/lib/vendure.ts.
• Mobile & Styling Integrations:
  • capacitor.config.ts: Cross-platform mobile configuration for Ionic Capacitor (@capacitor/cli, @capacitor/core).
  • uno.config.ts & postcss.config.mjs: UnoCSS Wind 4 presets, icon collections, and fluid typography tokens.
  • src/stores/app.ts: NanoStores sub-1KB reactive store for cross-framework state.
• Day-1 Proof-of-Life Starter Dashboard UI:
  • src/app/page.tsx & src/app/layout.tsx (Next.js), src/pages/index.astro (Astro), or index.html (Pure HTML): Generates an interactive live dashboard that immediately exercises the selected stack upon startup.
  • src/app/page.tsx & src/app/layout.tsx (Next.js) or src/pages/index.astro (Astro): Generates an interactive live dashboard that immediately exercises the selected stack upon bun run dev (Drizzle DB status, Better Auth client SDK status, Stripe checkout trigger, and quick-launch links to /admin, /keystatic, or /puck).
• Production Deployment Artifacts & CI/CD:
  • .github/workflows/ci.yml: Automated CI pipeline running dependencies installation, TypeScript checking, test runner, and Vibeguard secret audits.
  • Dockerfile & .dockerignore: Multi-stage production container for Node/Bun with unprivileged non-root user (--deploy=docker).
  • wrangler.toml: Cloudflare Workers / Pages configuration with node compatibility and binding placeholders (--deploy=cloudflare).
  • vercel.json: Production headers, function rules, and security policies (--deploy=vercel).
• Automated Quality Gates & Test Suite:
  • tests/health.test.ts: Out-of-the-box health check asserting environment configuration, AI governance container, and design tokens baseline.
  • biome.json: High-speed zero-config linter and formatter.
• Day-1 Secret Defense (Vibeguard Pre-Commit Hook):
  • scripts/pre-commit.sh & .git/hooks/pre-commit: Executable pre-commit hook that automatically blocks commits containing staged .env files or high-entropy credentials.
• Package Scripts & Secrets Injection:
  • Injects setup (one-command bootstrap handling dependencies, Docker container startup, and Drizzle migrations), test (bun test), lint (biome check src), format (biome format --write src), and precommit (bash scripts/pre-commit.sh).
  • Automatically provisions db:generate, db:push, docker:up, docker:down, payload, dev:backend, and backend:migrate into package.json.
  • Automatically populates all required connection strings, database URLs, and API secret keys into .env.example.
  • Synchronizes official dependencies in package.json with self-verification gate.

Stage 4: Modern Tokens & BEM Architecture Injection

• src/styles/tokens.css: Wide-gamut OKLCH colors (choice of 37 official palettes from oklch.fyi: 16 Radix scales + 21 curated designer themes like sunset-vibes, deep-sea, forest, neon-nights, etc.), fluid typography scale via clamp(), fluid spacing scale via clamp(), and 12-step numeric scales (--color-scale-1 through 12).
• .agents/skills/oklch-skill/: Automatically provisions project-scoped oklch-skill (strictly project-only, zero global pollution) with full color conversion, APCA/WCAG contrast guidelines, gamut clamping, and UnoCSS Wind 4 @theme mappings.
• src/styles/semantic.css: Reusable semantic BEM classes (.c-card, .c-button, .c-product-grid, .c-product-card, .c-cart-drawer).
• src/styles/animations.css: Hardware-accelerated GPU animations with prefers-reduced-motion compliance.

Stage 5: Client Intake Brief (Instructions, Not Documents)

The engine writes ONE file: Client-Intake/00-Intake-Brief.md — pre-filled with scaffold-time answers (name, purpose, audience, palette, etc.) plus an employee checklist and agent instructions. It does NOT pre-generate the intake documents; those are produced by the AI agent AFTER scaffolding, grounded in real employee answers:

Post-scaffold onboarding flow (agent-driven):

1. Read ./Client-Intake/00-Intake-Brief.md with the employee and collect answers to the checklist (brand corrections, business context, offerings, technical access, scope boundaries).
2. Write 01-Brand/, 02-Business/, 03-Offerings/, and 04-Technical-Intake/ documents from those answers — real content only, no invented filler.
3. Write ./start-here.md: a short developer orientation derived from the actual scaffolded stack (install/run commands from package.json, token locations, verification steps).
4. Sync answers into .agents/context/product.md and .memory/CURRENT.md.

Durable DOX Closeout (engine-run at scaffold):

• Populates .agents/context/decisions.md with dynamic Architectural Decision Records (ADR-001 through ADR-006).
• Populates .agents/context/product.md with dynamic project vision, target audience, problem statement, and catalog offerings.
• Records initial shipped state in .agents/context/current.md and .agents/context/architecture.md.

CLI Usage & Flags Reference

# Interactive Mode (Prompts for Purpose -> Hierarchical Tree -> Stack)
bun new-project/scripts/new-project.ts

# 1-Click Agency Golden Presets
bun new-project/scripts/new-project.ts <targetPath> --preset=powerhouse
bun new-project/scripts/new-project.ts <targetPath> --preset=astro-mobile

# Granular Non-Interactive Mode
bun new-project/scripts/new-project.ts <targetPath> \
  --intent=ecommerce \
  --type=nextjs \
  --styling=hybrid \
  --animation=motion \
  --state=nanostores \
  --mobile=capacitor \
  --cms=payload \
  --puck \
  --ecommerce=medusa \
  --db=postgres \
  --auth=better-auth \
  --non-interactive

Official Stack Setup References (Post-Scaffold Agent Procedures)

When the intake brief or a stack change requires provisioning a companion manually, follow these official procedures. Always use @latest resolution (bun add <pkg> / npm i <pkg>), never pinned versions.

Payload CMS 3.0

Official docs: Astro → https://docs.astro.build/en/guides/cms/payload/ · All other frameworks → https://payloadcms.com/docs/getting-started/installation

1. Next.js App Router: install payload, @payloadcms/next, @payloadcms/db-sqlite (or @payloadcms/db-postgres), @payloadcms/richtext-lexical, @payloadcms/translations, sharp.
2. Copy the (payload) route group into src/app/(payload)/ from node_modules/@payloadcms/templates (or generate payload.config.ts with collections, Lexical editor, secret: process.env.PAYLOAD_SECRET, and the chosen db adapter).
3. Wire next.config.mjs with withPayload and add "@payload-config": ["./src/payload.config.ts"] to tsconfig.json paths.
4. Add PAYLOAD_SECRET to .env, then npm run dev and open /admin to create the first user.

Payload E-Commerce Module

Follow the official overview: https://payloadcms.com/docs/ecommerce/overview

Aria Builder (isolated official scaffold — Astro + UnoCSS + CMS + SQLite included)

1. git clone https://github.com/ariabuilder/aria.git
2. cd aria && npm install
3. npm run dev
4. Open http://localhost:4321/admin. On first visit, complete setup at http://localhost:4321/admin/setup to create the first administrator.
5. The engine additionally ensures the UnoCSS Wind 4 preset in ./uno.user.config.ts (upstream ships Wind3). Nothing else is added or overlaid — no framework re-scaffold, no companion wiring, no token injection. Request extra features after scaffolding and they will be layered on explicitly.

WollyCMS (self-hosted headless CMS for Astro)

1. New WollyCMS project: npx create-wolly@latest my-site && cd my-site && npm run migrate && npm run seed && npm run dev (requires Node.js 22 LTS; API + admin at http://localhost:4321, default login admin@wollycms.local / admin123). Templates: blog, marketing, wordpress, drupal, college via --template=<name>.
2. In the scaffolded Astro project the engine wires the official integration: npm install @wollycms/astro + wollycms({ endpoint: 'http://localhost:4321' }) in astro.config.mjs.
3. Docker/self-host: ghcr.io/wollycms/wollycms:latest with JWT_SECRET set and /app/data persisted. Full docs at https://docs.wollycms.com/ — always refer to the latest upstream docs before changing this flow.

Emdash CMS (Astro edge CMS)

1. Create a new project: npm create emdash@latest, then follow the prompts to name the project and set your preferences.
2. Move in and start the dev server: cd my-emdash-site && npm install && npm run dev, then open http://localhost:4321.
3. Complete the Setup Wizard: visit http://localhost:4321/_emdash/admin — you are redirected to the wizard. Enter Site Title, Tagline, and Admin Email, then click Create Site to register your passkey (Touch ID, Face ID, Windows Hello, or a security key). Once registered you are logged in and redirected to the admin dashboard.
4. Content lives as _emdash live collections; edit via /admin, consume via getLiveCollection/getLiveEntry.
5. For production on Cloudflare Workers, provision D1/R2 bindings (this is what the engine's preset=edge path generates with wrangler.jsonc and src/worker.ts; the engine also wires adminRoute: '/_emdash/admin' to match the official wizard URL).

Tina CMS

• Interactive TinaCMS starter site locally: npx create-tina-app@latest
• Scaffold the Astro starter directly: npx create-tina-app@latest --template tina-astro-starter

Keystatic CMS

• Starting a new Astro + Keystatic project from scratch: npm create @keystatic@latest (generates a ready-to-run project in seconds). In an existing scaffold, the engine wires keystatic.config.ts plus /keystatic admin pages and /api/keystatic handlers.

Decap CMS (Astro)

Two options for adding Decap to Astro:

1. Install Decap via a package manager: npm install decap-cms-app, then import the package into a <script> tag in your page <body> (e.g. /admin).
2. Or include the CDN bundle directly in the /admin page body: <script src="https://unpkg.com/decap-cms@^3.1.2/dist/decap-cms.js"></script>

Keystone CMS

Follow the official walkthrough: https://keystonejs.com/docs/walkthroughs/lesson-1

Sanity CMS

• Astro: official integration at https://www.sanity.io/plugins/sanity-astro — install with npx astro add @sanity/astro @astrojs/react (note: @astrojs/react is only needed if you plan to embed a Sanity Studio in the project). Manual dependency install: npm install @astrojs/react @sanity/astro @sanity/client sanity @types/react-dom @types/react-is @types/react react-dom react-is react styled-components. Starter template: https://www.sanity.io/templates/astro-sanity-clean
• Next.js: follow the Studio quickstart at https://www.sanity.io/docs/next-js-quickstart/setting-up-your-studio

Strapi CMS

• Astro: https://docs.astro.build/en/guides/cms/strapi/
• Other frameworks: npx create-strapi-app@latest

Custom CMS

Bring your own: wire the CMS strictly per its official documentation, keep credentials in .env (never committed), and record the integration as an ADR in .agents/context/decisions.md.

Puck Visual Editor

1. Install @puckeditor/core (the official package — renamed from @measured/puck): npm i @puckeditor/core --save.
2. Or generate a Puck application using a recipe: npx create-puck-app my-app.
3. Full getting-started detail (rendering the editor): https://puckeditor.com/docs/getting-started#render-the-editor — render pages with <Puck> (edit route) / <Render> (public route).

Medusa JS (Sovereign Commerce Backend)

1. Prerequisites: Node.js v20.19.0+ or v22.12.0+ (LTS versions only; use Node v24 LTS or lower if installing the Next.js Starter Storefront), the Git CLI, and PostgreSQL installed and running.
2. Create the application: npx create-medusa-app@latest my-medusa-store (tip: yarn/pnpm install faster than npm — yarn dlx create-medusa-app@latest my-medusa-store or add --use-yarn). The PostgreSQL database created is named medusa-my-medusa-store; you are asked whether to install the Next.js Starter Storefront.
3. The command installs a monorepo: backend + admin dashboard in apps/backend, and (if chosen) the storefront in apps/storefront.
4. On success the Medusa app runs at http://localhost:9000 and the Admin dashboard at http://localhost:9000/app (the installer opens it to create the first user). The Next.js Starter Storefront runs at http://localhost:8000.
5. Engine path: when provisioned by the engine, ./backend/ ships medusa-config.ts, docker-compose.yml (PostgreSQL 16 + Redis 7), and the frontend SDK in src/lib/medusa.ts — always defer to the official create-medusa-app flow above for a fresh backend.

Vendure

1. npx @vendure/create my-shop (replace my-shop with your project name), then choose the Quick Start option — the fastest path, handling all configuration.
2. With Docker Desktop installed it creates and configures a Postgres database; otherwise it uses SQLite.
3. Official docs: https://docs.vendure.io/current/core/getting-started/installation

Neon Serverless Postgres

• Next.js: https://neon.com/docs/guides/nextjs
• Astro: https://neon.com/docs/guides/astro
• Medusa: https://neon.com/docs/guides/medusajs

Supabase

• Next.js: https://supabase.com/docs/guides/getting-started/quickstarts/nextjs
• Astro: https://supabase.com/docs/guides/getting-started/quickstarts/astrojs
• Expo React Native: https://supabase.com/docs/guides/getting-started/quickstarts/expo-react-native

Instatic (zero-runtime SSG)

1. npx create-instatic@latest (or wire instatic into an existing Astro/HTML project) to generate instatic.json, content collections, and layout templates.
2. Author Markdown/MDX under the configured content directory; the compiler emits fully static pages at build time with zero client runtime.

Pitfalls

• Skipping Agents First: Never run framework generation before AI governance is initialized, or framework defaults may overwrite or conflict with agent boundaries.
• Cross-Project Bleed: Never copy client-specific skills, assets, or memory files from sibling projects. Every project starts with a clean isolated container.
• Committing Secrets: Ensure .env is listed in .gitignore and .env.example exists. Follow the Vibeguard protocol.
• Monolithic Memory Dumps: Keep .memory/CURRENT.md for machine real-time invariants and .agents/context/current.md for durable shipped reality.
• Never Ship Half-Baked Companion Stubs: Never provision an SDK or integration flag without the accompanying route handlers, client SDKs, schemas, admin UIs, or container configs needed to actually run it. Every technology must be immediately runnable from a clean checkout.

Verification

After scaffolding, verify the project:

1. Intake Brief: Check that ./Client-Intake/00-Intake-Brief.md exists with pre-filled scaffold answers.
2. Post-Scaffold Onboarding: Walk the employee through the brief with your agent, then write the intake docs and ./start-here.md it prescribes.
3. Design Tokens: Check wide-gamut OKLCH tokens and fluid clamp scales in ./src/styles/tokens.css and .c-* classes in semantic.css.
4. Governance Container: Check ./.agents/ 9-folder tree and ./AGENTS.md. Working artifacts (research corpora, planning docs, reports) live under ./.agents/artifacts/<topic>/ per its README contract stub — never the repo tree, never ./.memory; durable findings promote to ./.agents/context/.
5. Database & Auth Completeness: If database or auth is provisioned, verify src/lib/schema.ts, src/lib/db.ts, src/lib/auth-client.ts, and API route handlers (/api/auth/[...all]) exist and compile cleanly.
6. CMS & Visual Builder Completeness: If Payload, Keystatic, or Puck is enabled, verify config files (payload.config.ts, keystatic.config.ts), collection schemas, and admin UI pages exist.
7. Aria Builder Isolation: If Aria is enabled, verify the target holds the official upstream clone (package.json named @ariabuilder/aria, astro.config.ts, uno.user.config.ts with the Wind 4 preset) plus engine governance only — no aria.config.mjs, no Aria*.astro components, no backend/, no engine tokens/CI. Run npm run dev and complete first-admin setup at http://localhost:4321/admin/setup.
8. Backend Engine: If Medusa is provisioned, check ./backend/medusa-config.ts, ./backend/docker-compose.yml, and ./backend/package.json. If PostgreSQL container is requested, check ./docker-compose.yml.
9. Day-1 Starter Dashboard: Check that src/app/page.tsx (Next.js) or src/pages/index.astro (Astro) is provisioned with live stack badges and quick links.
10. Deployment & CI/CD: Verify .github/workflows/ci.yml is present, alongside Dockerfile / wrangler.toml / vercel.json matching --deploy.
11. Quality Gates & Test Suite: Run bun test inside the scaffolded workspace to confirm tests/health.test.ts passes cleanly.
12. Day-1 Secret Defense: Verify scripts/pre-commit.sh exists and is executable.
13. Dynamic ADRs & Product DOX: Check that .agents/context/decisions.md contains ADR-001 through ADR-006, and .agents/context/product.md reflects the interview scope.
14. Secret Defense: Verify no secrets or credentials appear in .env or git status. Run bun ~/.config/LIFEOS/runtime/TOOLS/SecretScan.ts . to ensure compliance with the Vibeguard protocol.