# WAI-WAY: The "With AI Way" Protocol

> **CREDIT:** WAI-WAY is adapted from the **BMAD Method**, optimized for DoNotDev.

---

## The Golden Rule

> **THE SCAFFOLDED FILES ARE YOUR DOCUMENTATION.**
>
> Every scaffolded file contains working examples and inline comments.
> **READ the file. FOLLOW the pattern. EXTEND.**
>
> Do NOT guess. Do NOT invent. Copy patterns from scaffolded files.

---

## The Flow

```
BRAINSTORM → SPEC → SCAFFOLD → ENTITIES → COMPOSE → CONFIGURE
```

**Critical:** The spec is the OUTPUT of brainstorming, not the input. No code until spec is validated.

---

## Phase 0: BRAINSTORM → SPEC

**Goal:** Through conversation, gather requirements and produce a complete spec.

**The flow:**
```
User provides idea → Agent asks questions → Agent fills spec → User validates
```

### Step 1: User Provides Initial Idea

User describes the app informally:
- "I want a car dealership management app"
- "We need a SaaS for team project management"
- "Build me a portfolio website"

### Step 2: Agent Asks Clarifying Questions

**Identity:** What's it called? Who's it for? Value proposition?

**Scope:** What can users DO? What data exists? Main flows?

**Auth:** Login required? Roles? Providers?

**Access:** Who can create/read/update/delete each entity?

**Features:** Billing? i18n? PWA? OAuth?

### Step 3: Agent Fills Spec Template

Using answers, agent fills `guides/wai-way/spec_template.md`:

**READ these to make decisions:**
- `guides/wai-way/presets_guide.md` - Choose preset
- `guides/wai-way/entity_patterns.md` - Common entity schemas
- `guides/wai-way/page_patterns.md` - Common page structures

### Step 4: User Validates Spec

Present completed spec summary:
- App identity + preset
- Entities with access rules
- Pages with auth requirements
- Features

**User confirms → Move to Phase 1.**

**User has changes → Iterate until validated.**

---

## Phase 1: SCAFFOLD

**Goal:** Running app skeleton with all routes.

**READ:**
- `guides/wai-way/page_patterns.md` - Page structure patterns

```bash
# Create new app
dndev create-app my-app --preset [from spec]

# Install dependencies
cd my-app && bun install

# Start emulators
dndev emu start

# Verify it runs
bun dev
```

### Step 1.1: Create Page Files

For each page from spec, create `src/pages/[Name]Page.tsx`:

```bash
touch src/pages/AboutPage.tsx
touch src/pages/DashboardPage.tsx
touch src/pages/ProductsListPage.tsx
touch src/pages/ProductPage.tsx
# etc.
```

### Step 1.2: Add PageMeta

**READ:** `src/pages/HomePage.tsx` - Copy the PageMeta pattern.

```tsx
import type { PageMeta } from '@donotdev/core';
import { PageContainer } from '@donotdev/ui';
import { Info } from 'lucide-react';

export const NAMESPACE = 'about';

export const meta: PageMeta = {
  namespace: NAMESPACE,
  icon: <Info />,
  // auth: true,           // Protected page
  // auth: { required: true, role: 'admin' },  // Admin page
  // hideFromMenu: true,   // Don't show in nav
  // route: '/custom-path', // Override auto route
};

export default function AboutPage() {
  return <PageContainer>About Page</PageContainer>;
}
```

**Output:** All routes exist as stub pages with correct PageMeta.

---

## Phase 2: ENTITIES

**Goal:** Define all data models from spec.

**READ:**
- `entities/ExampleEntity.ts` - Entity definition pattern
- `guides/wai-way/entity_patterns.md` - Common entity schemas

### Step 2.1: Create Entity Files

For each entity from spec:

1. Copy matching pattern from `entity_patterns.md`
2. Create `entities/[Entity].ts`
3. Customize fields, access rules, visibility

```typescript
// entities/Product.ts
import { defineEntity } from '@donotdev/core';

export const productEntity = defineEntity({
  name: 'Product',
  collection: 'products',
  fields: {
    name: {
      name: 'name',
      label: 'name',
      type: 'text',
      visibility: 'guest',
      validation: { required: true },
    },
    price: {
      name: 'price',
      label: 'price',
      type: 'number',
      visibility: 'guest',
      validation: { required: true, min: 0 },
    },
    // ... more fields from spec
  },
  access: {
    create: 'admin',
    read: 'guest',
    update: 'admin',
    delete: 'admin',
  },
});
```

### Step 2.2: Export Entities

```typescript
// entities/index.ts
export { productEntity } from './Product';
export { customerEntity } from './Customer';
export { orderEntity } from './Order';
```

**Output:** All entities defined and exported.

---

## Phase 3: COMPOSE

**Goal:** Build pages with components. HARDCODE ALL STRINGS.

**READ:**
- `src/pages/ListPageExample.tsx` - CRUD list pattern
- `src/pages/FormPageExample.tsx` - CRUD form pattern
- `guides/wai-way/page_patterns.md` - All page patterns

### Step 3.1: CRUD Pages

**List Page:**
```tsx
import { EntityList } from '@donotdev/crud';
import { useAuth } from '@donotdev/auth';
import { PageContainer } from '@donotdev/ui';
import { productEntity } from 'entities';

export default function ProductsListPage() {
  const user = useAuth('user');
  return (
    <PageContainer>
      <EntityList entity={productEntity} userRole={user?.role} />
    </PageContainer>
  );
}
```

**Form Page:**
```tsx
import { EntityFormRenderer, useCrud } from '@donotdev/crud';
import { productEntity } from 'entities';

export default function ProductPage() {
  const { id } = useParams();
  const { get, add, update } = useCrud(productEntity);
  const isNew = id === 'new';
  // ... see page_patterns.md for full pattern
}
```

### Step 3.2: Landing/Dashboard Pages

Copy from `page_patterns.md`:
- Dashboard pattern for logged-in home
- Landing pattern for marketing pages
- Settings pattern for preferences

**HARDCODE all strings:**
```tsx
// ✅ GOOD - Start with hardcoded strings
<HeroSection
  title="Welcome to My App"
  subtitle="The best app ever built"
/>

// ❌ BAD - Don't start with i18n
<HeroSection
  title={t('hero.title')}
  subtitle={t('hero.subtitle')}
/>
```

**Output:** All pages functional with hardcoded content.

---

## Phase 4: CONFIGURE

**Goal:** Finalize configuration and test.

**READ:**
- `src/config/app.ts` - App configuration
- `src/config/legal.ts` - Legal info
- `.env` - Environment variables

### Step 4.1: Update Configuration

**app.ts:**
- [ ] `APP_NAME` and `APP_SHORT_NAME`
- [ ] Correct `preset`
- [ ] Footer legal links

**legal.ts:**
- [ ] Company name and registration
- [ ] Contact emails
- [ ] Hosting provider
- [ ] Jurisdiction

**.env:**
- [ ] `VITE_FIREBASE_*` values
- [ ] `VITE_DONOTDEV_LICENSE_KEY`
- [ ] Optional: `VITE_STRIPE_*`, `VITE_SENTRY_DSN`

### Step 4.2: Firebase Setup

1. Enable auth providers in Firebase Console
2. Create Firestore database
3. Deploy rules: `firebase deploy --only firestore:rules`

### Step 4.3: Test

```bash
dndev emu start
bun dev
```

**Test checklist:**
- [ ] Can create/login user
- [ ] Public pages work without auth
- [ ] Protected pages redirect to login
- [ ] Admin pages require admin role
- [ ] CRUD operations work
- [ ] Data persists

### Step 4.4: Mobile Check

1. Open DevTools (F12)
2. Toggle device toolbar (Ctrl+Shift+M)
3. Test at 375px width

**Output:** Working app with auth, CRUD, config complete.

---

## Phase 5: i18n (Optional, After Validation)

**Only after Phase 4 is validated.**

### Step 5.1: Extract Strings

Create `src/locales/[namespace]_en.json`:
```json
{
  "hero": {
    "title": "Welcome to My App",
    "subtitle": "The best app ever built"
  }
}
```

### Step 5.2: Replace Hardcoded Strings

```tsx
const { t } = useTranslation('home');

<HeroSection
  title={t('hero.title')}
  subtitle={t('hero.subtitle')}
/>
```

### Step 5.3: Add Translations

Copy `home_en.json` → `home_fr.json`, translate values.

---

## Quick Reference

### Key Files to Read

| File | Purpose | When |
|------|---------|------|
| `guides/wai-way/spec_template.md` | App specification | Phase 0 |
| `guides/wai-way/presets_guide.md` | Preset decision | Phase 0 |
| `guides/wai-way/entity_patterns.md` | Entity schemas | Phase 2 |
| `guides/wai-way/page_patterns.md` | Page structures | Phase 1, 3 |
| `src/pages/HomePage.tsx` | PageMeta pattern | Phase 1 |
| `entities/ExampleEntity.ts` | Entity pattern | Phase 2 |
| `src/pages/ListPageExample.tsx` | CRUD list | Phase 3 |
| `src/pages/FormPageExample.tsx` | CRUD form | Phase 3 |
| `src/config/app.ts` | App config | Phase 4 |
| `src/config/legal.ts` | Legal info | Phase 4 |

### Agents (Optional)

Activate agent personas from `guides/wai-way/agents/`:

| Agent | Phase | Focus |
|-------|-------|-------|
| **Extractor** | 1 | Routes, sitemap, PageMeta |
| **Architect** | 2 | Entities, data models |
| **Builder** | 3 | Page composition, components |
| **Polisher** | 4 | Config, testing, polish |

See individual agent files for activation prompts.

---

## Summary

```
Phase 0: BRAINSTORM → User idea → Agent questions → Agent fills spec → User validates
Phase 1: SCAFFOLD   → Create all *Page.tsx with PageMeta (from spec)
Phase 2: ENTITIES   → Define all entities with fields/access (from spec)
Phase 3: COMPOSE    → Build pages with components (HARDCODE strings)
Phase 4: CONFIGURE  → Config, Firebase, test, mobile
Phase 5: i18n       → (Optional) Extract strings, translate
```

**Remember:** Spec is the OUTPUT of brainstorming. Validated spec = mechanical build.
