@thierrynakoa/fire-flow 10.0.0

package/references/metrics-and-trends.md

@@ -0,0 +1,234 @@
+# Bottleneck Detection & Trend Analysis
+
+## Overview
+
+Tracks execution performance across phases and plans to identify bottlenecks, predict durations, and surface improvement opportunities.
+
+## Metrics Collection Points
+
+### Per-Plan Metrics (collected in RECORD.md frontmatter)
+
+```yaml
+---
+metrics:
+  duration_minutes: 12
+  tasks_completed: 4
+  tasks_blocked: 0
+  files_created: 3
+  files_modified: 5
+  lines_added: 245
+  lines_removed: 30
+  tests_added: 6
+  test_coverage_delta: "+3%"
+  skills_applied: 2
+  honesty_checkpoints: 1
+  commits: 4
+  blocker_count: 0
+---
+```
+
+### Per-Phase Metrics (aggregated in CONSCIENCE.md)
+
+```yaml
+## Phase Metrics
+| Phase | Plans | Duration | Avg/Plan | Trend | Bottleneck |
+|-------|-------|----------|----------|-------|------------|
+| 3     | 4     | 45m      | 11m      | -     | None       |
+| 3.1   | 3     | 35m      | 12m      | +8%   | Breath 3     |
+| 3.2   | 3     | 28m      | 9m       | -25%  | None       |
+| 3.4   | 6     | 72m      | 12m      | +33%  | Plan 05    |
+```
+
+### Per-Milestone Metrics (in MILESTONES.md)
+
+```yaml
+## Milestone: v1.0 LMS Core
+- Total phases: 12
+- Total plans: 49
+- Total duration: ~430m (~7.2 hours)
+- Average phase: 36m
+- Average plan: 8.8m
+- Longest phase: Phase 3.4 (72m, 6 plans)
+- Shortest phase: Phase 3.2 (28m, 3 plans)
+- Blocker rate: 2/49 plans (4%)
+- Skill reuse rate: 35% (skills applied from library vs new)
+```
+
+### Per-Iteration Turn Rewards (v6.0 — AgentPRM)
+
+> **Research basis:** AgentPRM (Feb 2025) — Process reward models score each turn,
+> enabling fine-grained learning signals beyond binary success/fail.
+
+```yaml
+## Turn-Level Metrics (collected in dominion-flow.local.md per loop session)
+iteration_rewards:
+  - iteration: 1
+    reward: 4.2
+    task: "fix auth bug in login controller"
+    completion: 5       # task fully completed first try
+    quality: 4          # 1 retry needed
+    efficiency: 4       # ~25k tokens used
+
+  - iteration: 2
+    reward: 2.1
+    task: "add input validation to API"
+    completion: 3       # partial completion
+    quality: 2          # 3 retries needed
+    efficiency: 2       # ~60k tokens used
+
+session_summary:
+  total_iterations: 5
+  average_reward: 3.4
+  lowest_reward: {iteration: 2, reward: 2.1, task: "add input validation"}
+  highest_reward: {iteration: 4, reward: 4.8, task: "update test fixtures"}
+  reward_trend: "stable"  # improving | stable | declining
+```
+
+**Reward Formula:**
+```
+turn_reward = (0.5 * task_completion) + (0.3 * approach_quality) + (0.2 * context_efficiency)
+
+task_completion:   0-5  (5=complete, 0=no progress)
+approach_quality:  0-5  (5=first try success, 1=4+ retries)
+context_efficiency: 0-5 (5=<20k tokens, 1=>80k tokens)
+```
+
+**Downstream Uses:**
+1. **Handoff:** Session average reward stored in WARRIOR handoff for cross-session trending
+2. **Skill pre-loading:** Low-reward task types trigger proactive skill search on next occurrence
+3. **Approach rotation:** Declining reward trend triggers earlier rotation in Step 9 classification
+4. **Episodic recall boost:** When similar task type found in memory, inject reward context:
+   "Previous sessions scored {avg_reward} on {task_type}. Common issue: {lowest_reward_task}"
+
+---
+
+## Bottleneck Detection Algorithm
+
+### What Constitutes a Bottleneck
+
+A plan or phase is flagged as a bottleneck when:
+
+1. **Duration Outlier:** Plan takes >2x the average duration for its phase
+2. **Blocker Rate:** >20% of tasks in a plan are blocked
+3. **Rework Rate:** Plan requires >1 verification cycle (failed then re-executed)
+4. **Dependency Chain:** Plan blocks 2+ downstream plans
+5. **Complexity Spike:** Lines changed >3x average for similar plans
+
+### Detection Rules
+
+```
+RULE 1: Slow Plan
+  IF plan.duration > (phase.avg_plan_duration * 2)
+  THEN flag as BOTTLENECK:SLOW
+  SUGGEST: Break into smaller plans, check for missing skills
+
+RULE 2: Blocked Plan
+  IF plan.tasks_blocked > (plan.tasks_total * 0.2)
+  THEN flag as BOTTLENECK:BLOCKED
+  SUGGEST: Review dependencies, check BLOCKERS.md, missing prerequisites
+
+RULE 3: Failed Verification
+  IF plan.verification_attempts > 1
+  THEN flag as BOTTLENECK:QUALITY
+  SUGGEST: Add more specific must-haves, improve assumption validation
+
+RULE 4: Fan-Out Blocker
+  IF plan.blocks_count >= 2
+  THEN flag as BOTTLENECK:CRITICAL_PATH
+  SUGGEST: Prioritize this plan, consider breaking dependencies
+
+RULE 5: Complexity Spike
+  IF plan.lines_changed > (phase.avg_lines * 3)
+  THEN flag as BOTTLENECK:COMPLEXITY
+  SUGGEST: Split into sub-plans, review scope creep
+```
+
+### Output Format
+
+After each phase completion, `/fire-transition` outputs:
+
+```markdown
+## Bottleneck Report
+
+### Flagged Plans
+| Plan | Flag | Duration | Detail | Suggestion |
+|------|------|----------|--------|------------|
+| 03.4-05 | SLOW | 18m (avg: 12m) | Frontend + testing | Break integration tests into separate plan |
+| 03.4-04 | COMPLEXITY | 380 lines (avg: 120) | Multiple components | Consider splitting UI into sub-plans |
+
+### Phase Health Score
+- Speed: 7/10 (2 plans exceeded 1.5x average)
+- Quality: 9/10 (all verifications passed first attempt)
+- Efficiency: 8/10 (35% skill reuse, 2 new skills discovered)
+- Overall: 8/10
+```
+
+## Trend Analysis
+
+### What Trends Are Tracked
+
+1. **Duration Trend:** Are plans getting faster or slower over time?
+2. **Quality Trend:** Are verification pass rates improving?
+3. **Skill Reuse Trend:** Is the skills library being used more effectively?
+4. **Blocker Trend:** Are blockers decreasing over time?
+5. **Complexity Trend:** Is plan complexity stable or growing?
+
+### Trend Calculation
+
+```
+For each metric across last 5 phases:
+  values = [phase_N-4, phase_N-3, phase_N-2, phase_N-1, phase_N]
+  trend = linear_regression_slope(values)
+
+  IF trend > +10%: "Increasing" (bad for duration/blockers, good for skill reuse)
+  IF trend < -10%: "Decreasing" (good for duration/blockers, bad for quality)
+  ELSE: "Stable"
+```
+
+### Trend Dashboard (in CONSCIENCE.md)
+
+```markdown
+## Trends (Last 5 Phases)
+
+| Metric | P3 | P3.1 | P3.2 | P3.3 | P3.4 | Trend |
+|--------|-----|------|------|------|------|-------|
+| Avg Plan Duration | 11m | 12m | 9m | 10m | 12m | Stable |
+| Verification Pass Rate | 100% | 100% | 100% | 100% | 100% | Stable |
+| Skill Reuse | 20% | 25% | 30% | 35% | 35% | Improving |
+| Blocker Rate | 10% | 5% | 0% | 0% | 0% | Improving |
+| Lines/Plan | 150 | 120 | 100 | 180 | 145 | Stable |
+
+Overall Trajectory: POSITIVE (efficiency improving, blockers decreasing)
+```
+
+## Integration Points
+
+### Where Metrics Are Collected
+
+1. **RECORD.md frontmatter** — Plan-level metrics (written by executor agent)
+2. **CONSCIENCE.md** — Phase-level aggregations (written by transition command)
+3. **MILESTONES.md** — Milestone-level summaries (written by complete-milestone)
+4. **BLOCKERS.md** — Blocker frequency tracking
+
+### Where Metrics Are Displayed
+
+1. **`/fire-dashboard`** — Visual project health dashboard
+2. **`/fire-transition`** — Post-phase bottleneck report
+3. **`/fire-analytics`** — Historical trend analysis
+4. **CONSCIENCE.md** — Always-visible trend table
+
+### Automated Actions
+
+```
+IF blocker_trend == "Increasing" for 3+ phases:
+  SUGGEST: "Blocker rate rising. Consider: assumption validation before planning,
+            dependency review, breaking phases into smaller chunks."
+
+IF duration_trend == "Increasing" for 3+ phases:
+  SUGGEST: "Plans taking longer. Consider: scope reduction, better skill reuse,
+            splitting complex plans, more parallel breaths."
+
+IF skill_reuse < 20% for 3+ phases:
+  SUGGEST: "Low skill reuse. Consider: /fire-search before implementation,
+            adding auto-skill extraction markers, reviewing skills index."
+```

package/references/playwright-e2e-testing.md

@@ -0,0 +1,326 @@
+# Playwright E2E Testing Reference
+
+> Patterns, setup, and integration guide for Playwright E2E testing in Dominion Flow
+
+---
+
+## Quick Reference
+
+```
+Tool: Playwright (https://playwright.dev)
+Config: playwright.config.ts
+Test Dir: tests/e2e/ or e2e/
+Run: npx playwright test
+Report: npx playwright show-report
+Debug: npx playwright test --ui
+```
+
+---
+
+## Setup
+
+### Initial Installation
+
+```bash
+# Install Playwright
+npm init playwright@latest
+
+# Or add to existing project
+npm install -D @playwright/test
+
+# Install browsers
+npx playwright install
+```
+
+### Recommended Config (playwright.config.ts)
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html'],
+    ['list'],
+    ...(process.env.CI ? [['github'] as const] : []),
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120 * 1000,
+  },
+});
+```
+
+### Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:debug": "playwright test --debug",
+    "test:e2e:report": "playwright show-report",
+    "test:e2e:update-snapshots": "playwright test --update-snapshots"
+  }
+}
+```
+
+---
+
+## Test Patterns
+
+### Page Object Model
+
+```typescript
+// tests/e2e/pages/login.page.ts
+import { type Page, type Locator } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByTestId('email');
+    this.passwordInput = page.getByTestId('password');
+    this.submitButton = page.getByRole('button', { name: 'Sign In' });
+    this.errorMessage = page.getByTestId('error-message');
+  }
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+}
+```
+
+### Authentication Setup
+
+```typescript
+// tests/e2e/auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'tests/e2e/.auth/user.json';
+
+setup('authenticate as user', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByTestId('email').fill('test@example.com');
+  await page.getByTestId('password').fill('testpassword');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+  await page.waitForURL('/dashboard');
+  await page.context().storageState({ path: authFile });
+});
+```
+
+### CRUD Flow Pattern
+
+```typescript
+// tests/e2e/crud-feature.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Feature CRUD', () => {
+  test('create item', async ({ page }) => {
+    await page.goto('/items/new');
+    await page.getByLabel('Name').fill('Test Item');
+    await page.getByRole('button', { name: 'Create' }).click();
+    await expect(page.getByText('Item created')).toBeVisible();
+  });
+
+  test('read item', async ({ page }) => {
+    await page.goto('/items');
+    await expect(page.getByText('Test Item')).toBeVisible();
+  });
+
+  test('update item', async ({ page }) => {
+    await page.goto('/items/1/edit');
+    await page.getByLabel('Name').fill('Updated Item');
+    await page.getByRole('button', { name: 'Save' }).click();
+    await expect(page.getByText('Item updated')).toBeVisible();
+  });
+
+  test('delete item', async ({ page }) => {
+    await page.goto('/items');
+    await page.getByRole('button', { name: 'Delete' }).click();
+    await page.getByRole('button', { name: 'Confirm' }).click();
+    await expect(page.getByText('Test Item')).not.toBeVisible();
+  });
+});
+```
+
+### API Response Validation
+
+```typescript
+test('form submission calls correct API', async ({ page }) => {
+  const responsePromise = page.waitForResponse(
+    (resp) => resp.url().includes('/api/items') && resp.request().method() === 'POST'
+  );
+
+  await page.goto('/items/new');
+  await page.getByLabel('Name').fill('Test');
+  await page.getByRole('button', { name: 'Create' }).click();
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(201);
+  const body = await response.json();
+  expect(body.name).toBe('Test');
+});
+```
+
+### Visual Regression
+
+```typescript
+test('dashboard renders correctly', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    maxDiffPixels: 100,
+  });
+});
+```
+
+### Network Mocking
+
+```typescript
+test('handles API error gracefully', async ({ page }) => {
+  await page.route('**/api/items', (route) =>
+    route.fulfill({ status: 500, body: 'Server Error' })
+  );
+  await page.goto('/items');
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+});
+```
+
+---
+
+## Integration with Claude Code Playwright MCP
+
+When running interactive E2E testing during Dominion Flow execution, the Playwright MCP tools provide direct browser control:
+
+### Available MCP Tools
+
+| Tool | Use For |
+|------|---------|
+| `browser_navigate` | Go to pages |
+| `browser_snapshot` | Capture accessibility tree (best for assertions) |
+| `browser_click` | Click elements by ref |
+| `browser_fill_form` | Fill form fields |
+| `browser_type` | Type text into elements |
+| `browser_take_screenshot` | Visual captures |
+| `browser_console_messages` | Check for JS errors |
+| `browser_network_requests` | Validate API calls |
+| `browser_evaluate` | Run JS in browser |
+| `browser_wait_for` | Wait for text/conditions |
+
+### MCP Testing Pattern
+
+```
+1. browser_navigate -> page URL
+2. browser_snapshot -> get element refs
+3. browser_fill_form -> fill inputs
+4. browser_click -> submit
+5. browser_wait_for -> expected text
+6. browser_snapshot -> verify result
+7. browser_console_messages -> check errors
+8. browser_take_screenshot -> visual evidence
+```
+
+---
+
+## Dominion Flow Integration Points
+
+### In /fire-3-execute (Step 8)
+
+After all breath implementation completes:
+1. Detect existing `playwright.config.ts`
+2. Run `npx playwright test`
+3. If no tests exist for new features, write them
+4. Report results before spawning verifier
+
+### In /fire-4-verify (E2E Category)
+
+10-point E2E validation checklist:
+- E2E-1: Playwright installed
+- E2E-2: Browsers installed
+- E2E-3: Critical flows covered
+- E2E-4: All tests pass
+- E2E-5: Cross-browser
+- E2E-6: Mobile viewport
+- E2E-7: API assertions
+- E2E-8: Visual baselines
+- E2E-9: Test isolation
+- E2E-10: No console errors
+
+### In fire-executor Agent (Step 6)
+
+Executor runs Playwright after task implementation:
+1. Check for existing E2E test files
+2. Run full suite
+3. Write new tests if missing for new features
+4. Report results in handoff
+
+### In fire-verifier Agent (Section 3.7)
+
+Verifier validates E2E coverage and results:
+- Run `npx playwright test` with reporter
+- Check test count vs feature count
+- Verify cross-browser results
+- Score 0-10 points
+
+---
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--skip-e2e` | Skip E2E testing step in `/fire-3-execute` |
+| `--e2e-only` | Run only E2E tests without re-executing implementation |
+
+---
+
+## Best Practices
+
+1. **Use data-testid attributes** - Don't rely on CSS classes or text that changes
+2. **Test user flows, not implementation** - E2E tests should mirror real user behavior
+3. **Keep tests independent** - Each test should set up its own state
+4. **Use auth setup** - Share auth state via storage state, not repeated logins
+5. **Retry on CI only** - Local tests should fail fast for fast feedback
+6. **Trace on failure** - Enable trace recording for debugging failed CI tests
+7. **Parallel by default** - Let Playwright parallelize for speed
+8. **Mobile-first** - Include mobile viewport in default projects
+
+---
+
+*Added to Dominion Flow v3.0 - Playwright E2E Testing Integration (2026-02-10)*

package/references/questioning.md

@@ -0,0 +1,125 @@
+# Dominion Flow Questioning Reference
+
+> **Origin:** Ported from Dominion Flow `questioning.md` with SDLC-aware questioning additions.
+
+## Philosophy
+
+**You are a thinking partner, not an interviewer.** The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+---
+
+## The Goal
+
+By the end of questioning, you need enough clarity to write a PROJECT.md:
+
+- **Research:** What domain to research, what unknowns exist
+- **Requirements:** Clear enough vision to scope v1 features
+- **Roadmap:** Clear enough to decompose into phases
+- **Testing:** Which flows are critical and require mandatory testing
+- **Branch strategy:** Project complexity determines Git Flow depth
+- **Blocker risks:** Known technical risks that might become blockers
+
+---
+
+## How to Question
+
+- **Start open.** Let them dump their mental model.
+- **Follow energy.** Whatever they emphasized, dig into that.
+- **Challenge vagueness.** "Good" means what? "Users" means who?
+- **Make abstract concrete.** "Walk me through using this."
+- **Surface critical flows early.** Payment, auth, data mutation.
+- **Know when to stop.** Offer to proceed when you understand enough.
+
+---
+
+## Question Types
+
+### Motivation
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+
+### Concreteness
+- "Walk me through using this"
+- "Give me an example"
+
+### Clarification
+- "When you say Z, do you mean A or B?"
+
+### Success
+- "How will you know this is working?"
+- "What does done look like?"
+
+### Critical Flows (Dominion Flow)
+- "Is there any payment or billing involved?"
+- "How do users log in?"
+- "What data can users create, edit, or delete?"
+- "What happens if [critical action] fails halfway?"
+
+### Technical Risks (Dominion Flow)
+- "Have you tried building this before? What went wrong?"
+- "Any third-party services this depends on?"
+- "Is there existing code or data we need to work with?"
+
+### Deployment Context (Dominion Flow)
+- "Where does this need to be deployed?"
+- "Any existing infrastructure?"
+
+---
+
+## Context Checklist
+
+Check these mentally as you go:
+
+### Core
+- [ ] What they are building (concrete enough to explain)
+- [ ] Why it needs to exist (the problem driving it)
+- [ ] Who it is for
+- [ ] What "done" looks like
+
+### SDLC Awareness (Dominion Flow)
+- [ ] Critical flows identified (payment, auth, data mutation)
+- [ ] Known technical risks surfaced
+- [ ] Third-party dependencies listed
+- [ ] Deployment target understood
+- [ ] Data sensitivity level (PII, financial, public)
+
+---
+
+## Decision Gate
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you are after. Ready to create PROJECT.md?"
+- options: ["Create PROJECT.md", "Keep exploring"]
+
+---
+
+## Dominion Flow PROJECT.md Additions
+
+```markdown
+## Critical Flows (Mandatory Testing)
+- [ ] [Flow 1]: requires [unit/integration/e2e] tests
+- [ ] [Flow 2]: requires [unit/integration/e2e] tests
+
+## Known Risks
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| [Risk 1] | High | [Plan] |
+
+## Third-Party Dependencies
+| Service | Purpose | Fallback |
+|---------|---------|----------|
+| [Service] | [Why] | [If unavailable] |
+```
+
+---
+
+## Anti-Patterns
+
+- Checklist walking (going through domains regardless of context)
+- Corporate speak ("Who are your stakeholders?" for solo project)
+- Interrogation (firing questions without building on answers)
+- Shallow acceptance (taking vague answers without probing)
+- Skipping critical flows (not asking about payment/auth/mutations)
+- Asking about user's technical experience (Claude builds, not the user)