@donotdev/cli 0.0.12 → 0.0.13

package/templates/root-consumer/guides/wai-way/WAI_WAY_CLI.md.example

@@ -15,13 +15,98 @@
 
 ---
 
+## The Intelligence Engine (MCP Server)
+
+Your project is pre-configured with a **Knowledge Engine** (MCP Server) in `.mcp.json`.
+
+1. **Phase Tracking:** `start_phase(N)` returns the blueprint, agent persona, and files to read for each phase.
+2. **Type Intelligence:** `lookup_symbol("ComponentName")` returns actual TypeScript types — never guess props.
+3. **Knowledge Retrieval:** `get_guide("CRUD")`, `get_guideline("styling")`, `search_framework("keyword")`.
+4. **Implementation Tracking:** `init_implementation()` creates a persistent checklist. `update_progress()` ticks items. `get_progress()` reads status. Survives across sessions.
+5. **Captain's Log:** Session history auto-recorded on `approve_phase()`. `get_project_history()` for metrics and post-mortem.
+6. **Lessons:** `record_lesson("gotcha", { tags: ["stripe", "billing"] })` saves tagged gotchas to `.dndev/LESSONS.md`. Filtered by phase + module on next `start_phase`.
+
+The IDE (Cursor, Claude Code, etc.) handles file write approval natively. No MCP-level gating.
+
+---
+
+## Implementation Tracking (Multi-Session Progress)
+
+For projects that span multiple AI sessions, `.dndev/implementation.md` tracks what's done and what's pending.
+
+### Setup (after Phase 0)
+
+```
+# Auto-generate from spec
+init_implementation({ from_spec: true })
+
+# Or manual sections
+init_implementation({ sections: [
+  { title: "Auth Module", items: ["Login page", "Registration", "Password reset"] },
+  { title: "Dashboard", items: ["Stats cards", "Activity feed", "Charts"] }
+] })
+```
+
+### During Work
+
+```
+# Tick items as you complete them
+update_progress({ item: "Login page", done: true })
+update_progress({ item: "Stats cards", done: true, note: "Used Card component with level h3" })
+
+# Check progress
+get_progress()                              # full overview
+get_progress({ section: "Auth Module" })    # filtered to section
+```
+
+### Cross-Session Continuity
+
+When you start a new session:
+1. `start_phase(N)` automatically includes implementation progress
+2. The agent sees what's done and picks up where it left off
+3. No repeated work, no drift
+
+---
+
+## Captain's Log (Project History)
+
+Every `approve_phase()` auto-records a session entry to `.dndev/captain-log.json`. No manual action needed.
+
+### What's Recorded Automatically
+
+- Date + timestamps (started/completed)
+- Phase number and name
+- Module (if scoped)
+- Files touched + symbols used
+- Outcome summary (from `complete_phase({ summary: "..." })`)
+
+### Viewing History
+
+```
+get_project_history()
+```
+
+Returns computed metrics + timeline:
+- Total sessions, phases completed
+- Files and symbols totals
+- Per-session timeline with outcomes
+
+### Post-Mortem
+
+The raw JSON at `.dndev/captain-log.json` enables:
+- Phase velocity analysis (how many sessions per phase)
+- Issue tracking across the project lifecycle
+- Team-level comparison across projects
+
+---
+
 ## The Flow
 
 ```
-BRAINSTORM → SPEC → SCAFFOLD → ENTITIES → COMPOSE → CONFIGURE
+BRAINSTORM (→ spec) → SCAFFOLD → ENTITIES → COMPOSE → CONFIGURE
 ```
 
-**Critical:** The spec is the OUTPUT of brainstorming, not the input. No code until spec is validated.
+**Critical:** The spec is the OUTPUT of Phase 0 (BRAINSTORM), not a separate phase. No code until spec is validated.
 
 ---
 
@@ -267,94 +352,75 @@ Copy from `page_patterns.md`:
 
 ---
 
-## Phase 4: CONFIGURE
+## Phase 4: CONFIGURE + TEST
 
-**Goal:** Finalize configuration and test.
+**Goal:** Generate tests, firestore rules, CI/CD, and finalize config.
 
 **READ:**
+- `guides/wai-way/spec_template.md` - The validated spec (your test plan)
+- `entities/index.ts` - All entity definitions
 - `src/config/app.ts` - App configuration
-- `src/config/legal.ts` - Legal info
-- `.env` - Environment variables
+- `guides/dndev/SETUP_TESTING.md` - Testing patterns
 
-### Step 4.1: Update Configuration
+### Step 4.1: Generate Tests
 
-**app.ts:**
-- [ ] `APP_NAME` and `APP_SHORT_NAME`
-- [ ] Correct `preset`
-- [ ] Footer legal links
+Call `get_guide("TESTING")` for patterns.
 
-**legal.ts:**
-- [ ] Company name and registration
-- [ ] Contact emails
-- [ ] Hosting provider
-- [ ] Jurisdiction
+**Entity tests** — one per entity in `tests/entities/[Entity].test.ts`:
+- [ ] Required fields defined
+- [ ] Field types match spec
+- [ ] Access rules match spec (create/read/update/delete per role)
 
-**.env:**
-- [ ] `VITE_FIREBASE_*` values
-- [ ] `VITE_DONOTDEV_LICENSE_KEY`
-- [ ] Optional: `VITE_STRIPE_*`, `VITE_SENTRY_DSN`
+**Page tests** — one per page in `tests/pages/[Page].test.tsx`:
+- [ ] Renders without error
+- [ ] PageMeta defined (title, auth, admin)
+- [ ] Route protection matches spec
 
-### Step 4.2: Firebase Setup
+**Access control tests** in `tests/access/access-rules.test.ts`:
+- [ ] Admin entities require admin access
+- [ ] User-owned entities have owner access
+- [ ] No unauthenticated writes
 
-1. Enable auth providers in Firebase Console
-2. Create Firestore database
-3. Deploy rules: `firebase deploy --only firestore:rules`
+### Step 4.2: Generate Firestore Rules
 
-### Step 4.3: Test
+Create `firestore.rules` from entity access definitions:
+- `owner` → `resource.data.userId == request.auth.uid`
+- `admin` → `request.auth.token.admin == true`
+- `authenticated` → `request.auth != null`
 
-```bash
-dndev emu start
-bun dev
-```
+### Step 4.3: Generate CI/CD
 
-**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
+Create `.github/workflows/ci.yml`:
+- Quality job: `bun install` → `bun run type-check` → `bun test`
+- Deploy job: `bun run build` → Firebase deploy (on main push)
 
-### Step 4.4: Mobile Check
+### Step 4.4: Update Configuration
 
-1. Open DevTools (F12)
-2. Toggle device toolbar (Ctrl+Shift+M)
-3. Test at 375px width
+**app.ts:** APP_NAME, APP_SHORT_NAME, preset, footer links
+**legal.ts:** Company, contacts, hosting, jurisdiction
+**.env:** VITE_FIREBASE_*, VITE_DONOTDEV_LICENSE_KEY, optional Stripe/Sentry
 
-**Output:** Working app with auth, CRUD, config complete.
+### Step 4.5: Run Tests
 
----
-
-## Phase 5: i18n (Optional, After Validation)
+```bash
+bun test
+```
 
-**Only after Phase 4 is validated.**
+All tests must pass before completing.
 
-### Step 5.1: Extract Strings
+### Step 4.6: Mobile Check
 
-Create `src/locales/[namespace]_en.json`:
-```json
-{
-  "hero": {
-    "title": "Welcome to My App",
-    "subtitle": "The best app ever built"
-  }
-}
-```
+DevTools → 375px width → navigation, forms, text, buttons (44px), no horizontal scroll.
 
-### Step 5.2: Replace Hardcoded Strings
+**Output:** Test files, firestore.rules, CI/CD pipeline, configured app.
 
-```tsx
-const { t } = useTranslation('home');
+---
 
-<HeroSection
-  title={t('hero.title')}
-  subtitle={t('hero.subtitle')}
-/>
-```
+### Step 4.7: i18n (Optional)
 
-### Step 5.3: Add Translations
+**Only after Steps 4.1-4.6 pass.**
 
-Copy `home_en.json` → `home_fr.json`, translate values.
+Extract hardcoded strings to `src/locales/[namespace]_en.json`, replace with `useTranslation()`.
 
 ---
 
@@ -381,10 +447,10 @@ Activate agent personas from `guides/wai-way/agents/`:
 
 | Agent | Phase | Focus |
 |-------|-------|-------|
-| **Extractor** | 1 | Routes, sitemap, PageMeta |
+| **Extractor** | 0-1 | Requirements gathering, routes, sitemap, PageMeta |
 | **Architect** | 2 | Entities, data models |
 | **Builder** | 3 | Page composition, components |
-| **Polisher** | 4 | Config, testing, polish |
+| **Polisher** | 4 | Config, testing, polish, i18n |
 
 See individual agent files for activation prompts.
 
@@ -397,8 +463,7 @@ Phase 0: BRAINSTORM → User idea → Agent questions → Agent fills spec → U
 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
+Phase 4: CONFIGURE  → Config, Firebase, test, mobile, optional i18n
 ```
 
 **Remember:** Spec is the OUTPUT of brainstorming. Validated spec = mechanical build.

package/templates/root-consumer/guides/wai-way/agents/polisher.md.example

@@ -10,27 +10,58 @@ agent:
   id: polisher
   title: QA & Config Specialist
   icon: 🧪
-  phase: "4_configure_polish"
-  done_when: "Config complete, tests pass, mobile responsive"
+  phase: "4_configure_test"
+  done_when: "Tests pass, config complete, firestore rules generated"
 
 persona:
-  role: Quality Gatekeeper & Configuration Expert
-  style: Detail-oriented, systematic, thorough
-  identity: You ensure the app is configured correctly and production-ready.
-  focus: Configuration, testing, mobile check, optional i18n.
+  role: Quality Gatekeeper & Test Generator
+  style: Systematic, thorough, test-driven
+  identity: You generate tests from the spec, configure the app, and verify everything works.
+  focus: Test generation, configuration, firestore rules, mobile check.
 
 golden_rule: |
-  THE SCAFFOLDED FILES ARE YOUR DOCUMENTATION.
-  READ src/config/app.ts for config options.
-  READ src/config/legal.ts for legal checklist.
-  READ src/themes.css for theme variables.
+  THE SPEC IS YOUR TEST PLAN.
+  READ the spec (Phase 0 output) for entities, permissions, journeys.
+  READ each entity file for access rules and fields.
+  GENERATE tests that verify the spec is implemented correctly.
 
 core_principles:
-  - Configuration first: app.ts, legal.ts, .env
-  - Test with emulators: dndev emu start
+  - Tests first: generate entity tests, page tests, access tests
+  - Firestore rules from entities: access definitions → security rules
+  - Configuration: app.ts, legal.ts, .env
   - Mobile check: 375px width
   - i18n is OPTIONAL and comes LAST
 
+test_generation:
+  entity_tests:
+    per_entity:
+      - Required fields are defined
+      - Field types match spec
+      - Access rules match spec (create/read/update/delete per role)
+      - State transitions valid (if applicable)
+    output: "tests/entities/[EntityName].test.ts"
+  page_tests:
+    per_page:
+      - Renders without error
+      - PageMeta defined (title, auth, admin)
+      - Route protection matches spec
+    output: "tests/pages/[PageName].test.tsx"
+  access_tests:
+    - Admin entities require admin access
+    - User-owned entities have owner access
+    - Public entities allow guest read
+    - No unauthenticated writes
+    output: "tests/access/access-rules.test.ts"
+
+firestore_rules:
+  source: "Entity access definitions"
+  mapping:
+    owner: "resource.data.userId == request.auth.uid"
+    admin: "request.auth.token.admin == true"
+    authenticated: "request.auth != null"
+    guest: "true"
+  output: "firestore.rules"
+
 config_checklist:
   app_ts:
     - APP_NAME and APP_SHORT_NAME set
@@ -45,32 +76,19 @@ config_checklist:
     - VITE_FIREBASE_* values set
     - VITE_DONOTDEV_LICENSE_KEY set
 
-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
-
-mobile_check:
-  - Open DevTools (F12)
-  - Toggle device toolbar (Ctrl+Shift+M)
-  - Test at 375px width
-  - Navigation works
-  - Forms are usable
-  - Text is readable
-
 commands:
   - help: Show available commands
+  - generate-tests: Generate all test files from spec + entities
+  - generate-rules: Generate firestore.rules from entities
   - audit-config: Check configuration files
   - audit-mobile: Check mobile responsiveness
   - add-i18n: Extract strings to locales (optional)
   - exit: Exit persona
 
 output:
+  - Test files generated and passing
+  - Firestore rules generated
   - Configuration complete
-  - All tests pass
   - Mobile responsive
   - (Optional) i18n added
 ```
@@ -81,20 +99,24 @@ output:
 Activate AGENT Polisher.
 
 READ these files first:
+- guides/wai-way/spec_template.md (the validated spec — your test plan)
+- entities/index.ts (all entity definitions)
+- src/pages/ (all page files)
 - src/config/app.ts (app configuration)
-- src/config/legal.ts (legal info checklist)
-- src/themes.css (theme customization)
-- .env (environment variables)
-
-Your goal: Finalize configuration and test the app.
-
-Checklist:
-1. Update app.ts (name, preset, footer)
-2. Update legal.ts (company, contacts)
-3. Fill .env (Firebase config)
-4. Test with emulators
-5. Mobile check at 375px
-6. (Optional) Add i18n
-
-Verify each item before marking complete.
+- guides/dndev/SETUP_TESTING.md (testing patterns)
+
+Your goal: Generate tests, firestore rules, and finalize config.
+
+Steps:
+1. Create vitest.config.ts + tests/setup.ts
+2. Generate entity tests (one per entity from entities/)
+3. Generate page tests (one per page from src/pages/)
+4. Generate access control tests (from spec permissions)
+5. Generate firestore.rules (from entity access definitions)
+6. Update app.ts, legal.ts, .env
+7. Run bun test — all must pass
+8. Mobile check at 375px
+9. (Optional) Add i18n
+
+Call get_guide("TESTING") for testing patterns.
 ```

package/templates/root-consumer/guides/wai-way/blueprints/0_brainstorm.md.example

@@ -2,7 +2,16 @@
 
 **Goal:** Deeply understand the app and document ALL requirements before any code.
 
-**Done when:** spec_template.md is COMPLETE with user flows, business rules, and entity relationships - AND user has validated it.
+**MCP:** `start_phase(0)` to begin. `complete_phase()` when done.
+**Done when:** `spec_template.md` is COMPLETE and user has validated it.
+
+---
+
+## First: Call list_features()
+
+**Before probing the user or designing anything**, call `list_features()`.
+
+It returns a one-line summary from each framework package README (core, ui, templates, auth, billing, etc.). Use it to avoid designing custom solutions when the framework already provides them (e.g. blog, CRUD, billing pages). If you skip this, you may propose work that already exists in `@donotdev/templates` or other packages.
 
 ---
 
@@ -26,6 +35,8 @@ Before moving to Phase 1, you MUST have:
 ```
 User provides idea
     ↓
+Agent calls list_features() → matches needs to existing framework capabilities
+    ↓
 Agent asks IDENTITY questions (who, what, why)
     ↓
 Agent asks USER JOURNEY questions (what do users DO step by step?)
@@ -277,5 +288,11 @@ Completed spec_template.md with:
 - All permissions defined
 - User validation
 
+**After spec validation, generate the implementation tracker:**
+```
+init_implementation({ from_spec: true })
+```
+This creates `.dndev/implementation.md` with checklist items for all phases (pages, entities, composition, config). Agents will read and update this file across sessions.
+
 **Spec validated AND complete? Move to Phase 1: SCAFFOLD.**
 **Anything unclear? Keep asking questions.**

package/templates/root-consumer/guides/wai-way/blueprints/1_scaffold.md.example

@@ -2,6 +2,7 @@
 
 **Goal:** Running app with all routes defined.
 
+**MCP:** `start_phase(1)` to begin. `complete_phase()` when done.
 **Done when:** All routes listed, all *Page.tsx files created with correct PageMeta.
 
 **Prerequisite:** Phase 0 (spec) must be complete.

package/templates/root-consumer/guides/wai-way/blueprints/2_entities.md.example

@@ -1,7 +1,8 @@
 # BLUEPRINT: 2_ENTITIES
 
-**Goal:** Define all data models from spec.
+**Goal:** Define all data models from spec (Single Source of Truth).
 
+**MCP:** `start_phase(2)` to begin. Use `lookup_symbol('defineEntity')` for types. `complete_phase()` when done.
 **Done when:** All entities defined with fields, access rules, visibility. Exported from index.ts.
 
 **Prerequisite:** Phase 0 (spec) and Phase 1 (scaffold) complete.

package/templates/root-consumer/guides/wai-way/blueprints/3_compose.md.example

@@ -2,6 +2,7 @@
 
 **Goal:** Build pages with components. HARDCODE ALL STRINGS.
 
+**MCP:** `start_phase(3)` to begin. Use `lookup_symbol(component_name)` for types. `complete_phase()` when done.
 **Done when:** All pages functional with content. CRUD pages use EntityList/EntityFormRenderer. All strings hardcoded.
 
 **Prerequisite:** Phase 0-2 complete. Spec validated, entities defined.
@@ -111,7 +112,7 @@ Copy Landing pattern from `page_patterns.md`:
 />
 ```
 
-Validate UX in one language. Add i18n in Phase 5.
+Validate UX in one language. Add i18n in Phase 4 (CONFIGURE) after validation.
 
 ---