@thierrynakoa/fire-flow 12.2.1 → 12.2.2

package/README.md

@@ -33,6 +33,16 @@ AUTOPSY → INTENT → CLARIFY → VISION → REBUILD → COMPARISON
 /fire-phoenix --source ./app --dry-run
 ```
 
+### Got a Messy Project Sitting in a Folder?
+
+We all have them — that side project you built in a weekend, the freelance app that grew out of control, the "it works so don't touch it" codebase. Instead of rewriting from scratch manually or abandoning it, point Phoenix at it:
+
+```bash
+/fire-phoenix --source ./that-old-project
+```
+
+Phoenix will tell you exactly what's wrong, what's worth keeping, and what should be rebuilt. Your original code is never touched — the clean version goes to a new folder. **This is the fastest way to turn technical debt into production-quality code.**
+
 ---
 
 ## What Does It Do?
@@ -148,15 +158,197 @@ npx @thierrynakoa/fire-flow --uninstall
 
 ---
 
-## Optional but Recommended: Power Features
+## Slash Commands Not Appearing?
+
+If you've installed Dominion Flow but the `/fire-` commands don't show up when you type `/` in Claude Code, follow these steps:
+
+### Option A — Ask Claude to Fix It (Easiest)
+
+Open Claude Code and paste this message:
+
+> *"My Dominion Flow plugin is installed but the /fire- slash commands aren't appearing. Please check my ~/.claude/settings.json, register the plugin under enabledPlugins, and refresh my commands."*
+
+Claude will inspect your configuration, add the missing plugin entry, and reload the commands automatically.
+
+### Option B — Fix settings.json Manually
+
+1. Open your global Claude Code settings file:
+
+   **Mac / Linux:**
+   ```bash
+   code ~/.claude/settings.json
+   ```
+
+   **Windows:**
+   ```bash
+   code %USERPROFILE%\.claude\settings.json
+   ```
+
+   *(Replace `code` with `notepad`, `nano`, or any text editor you prefer)*
+
+2. Find the `"enabledPlugins"` section. If it doesn't exist, add it. Then add the Dominion Flow entry:
+
+   ```json
+   {
+     "enabledPlugins": {
+       "dominion-flow@local": true
+     }
+   }
+   ```
+
+   If you already have other plugins listed, just add the `"dominion-flow@local": true` line inside the existing block (don't forget the comma on the line above it).
+
+3. Save the file and **restart Claude Code completely** (close and reopen — not just a new conversation).
+
+4. Type `/fire-0-orient` to confirm the commands are working.
 
-The core workflow works out of the box. These extras unlock **persistent memory**, **codebase search**, and **Docker Hub access** — features that make Claude dramatically more capable on larger projects.
+### Option C — Reinstall the Plugin
+
+If the above steps don't work, reinstall from scratch:
+
+```bash
+npx @thierrynakoa/fire-flow --update
+```
+
+Or if you cloned from GitHub:
+
+```bash
+claude plugin uninstall dominion-flow
+claude install-plugin ./fire-flow
+```
+
+Then restart Claude Code.
+
+### Still Not Working?
+
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for additional diagnostics, or open an issue at [github.com/ThierryN/fire-flow/issues](https://github.com/ThierryN/fire-flow/issues).
+
+---
+
+## Highly Recommended: Install the Playwright Plugin
+
+Dominion Flow includes built-in E2E (end-to-end) browser testing through its `/fire-test` and `/fire-verify-uat` commands. For these to work, Claude needs the **Playwright plugin** — which gives Claude the ability to open a real browser, click buttons, fill forms, take screenshots, and verify that your application actually works the way a real user would experience it.
+
+**This is the single most impactful add-on you can install.** Without it, Dominion Flow can still verify your code quality and logic — but with it, Claude can launch your app in a browser and prove it works visually.
+
+### Install Playwright Plugin (One Command)
+
+```bash
+claude plugin install playwright@claude-plugins-official
+```
+
+That's it. Restart Claude Code and the Playwright tools are available immediately.
+
+### What This Unlocks
+
+| Capability | What Claude Can Do |
+|------------|-------------------|
+| **Visual verification** | Open your app in a browser and confirm UI renders correctly |
+| **Form testing** | Fill out forms, submit them, and verify responses |
+| **Click-through flows** | Test multi-step user journeys (signup → login → dashboard) |
+| **Screenshot comparison** | Capture before/after screenshots during Phoenix Rebuild |
+| **Error detection** | Catch console errors, broken links, and missing elements |
+| **Responsive testing** | Test at different viewport sizes (mobile, tablet, desktop) |
+
+### How Dominion Flow Uses Playwright
+
+Once installed, Playwright is automatically used by:
+
+- **`/fire-verify-uat`** — Runs user acceptance tests against your running application
+- **`/fire-test`** — Includes E2E test generation and execution
+- **`/fire-4-verify`** — The 70-point WARRIOR checklist awards up to 10 points for E2E coverage
+- **`/fire-phoenix`** — Phase 6 (COMPARISON) uses screenshots to visually compare source vs rebuild
+
+### Verify Playwright Is Working
+
+After installing, ask Claude:
+
+> *"Take a screenshot of http://localhost:3000"*
+
+If Claude opens a browser and returns a screenshot, Playwright is working. If your app isn't running yet, you can test with any public URL:
+
+> *"Take a screenshot of https://example.com"*
+
+### Don't Have Playwright Yet? Dominion Flow Still Works
+
+All core commands (`/fire-1a-new` through `/fire-6-resume`, `/fire-autonomous`, `/fire-phoenix`) work without Playwright. E2E testing features will simply be skipped, and the verifier will redistribute those points to other categories. But you'll get significantly more value from Dominion Flow with Playwright installed.
+
+---
+
+## Highly Recommended: Install browser-use (AI Browser Automation)
+
+**browser-use** is an open-source AI browser automation library that lets Claude control a real browser using natural language. Instead of writing test scripts, you describe what to test in plain English and the AI navigates, clicks, fills forms, and verifies results autonomously.
+
+Dominion Flow integrates browser-use into `/fire-verify-uat` — enabling **fully autonomous User Acceptance Testing**. No more manually clicking through every flow. Claude generates the test flows, browser-use executes them in a headless browser, and results come back as structured pass/fail reports.
+
+### Install browser-use (3 Commands)
+
+```bash
+pip install browser-use
+```
+
+```bash
+uvx browser-use install
+```
+
+```bash
+python -c "from browser_use import Agent; print('Setup OK')"
+```
+
+**Note:** You also need your `ANTHROPIC_API_KEY` set as an environment variable (the same key you use for Claude Code).
+
+### What This Unlocks
+
+| Without browser-use | With browser-use |
+|--------------------|-----------------|
+| You manually click through every UAT flow | AI navigates the browser and tests flows automatically |
+| Testing takes 10-30 minutes per phase | Testing takes 1-3 minutes per phase |
+| You might miss edge cases when tired | AI tests exactly what was specified, every time |
+| Can't test at 2 AM when you're asleep | `/fire-autonomous` includes UAT without human intervention |
+
+### How Dominion Flow Uses It
+
+When you run `/fire-verify-uat`, you'll be asked to choose a mode:
+
+- **Autonomous** — browser-use AI runs all flows. Just sit back and watch the results.
+- **Manual** — the current guided testing mode. You click, Claude watches.
+
+Both modes include automatic parallel diagnosis when flows fail — 3 debug agents investigate the root cause simultaneously.
+
+### browser-use vs Playwright — Both Work Together
+
+| Tool | Role in Dominion Flow |
+|------|----------------------|
+| **Playwright** | Deterministic E2E regression tests, CI/CD, cross-browser matrix, visual snapshots |
+| **browser-use** | AI-driven UAT flows, exploratory testing, natural language test specs |
+
+They complement each other. Playwright catches regressions. browser-use explores like a real user would.
+
+---
+
+## Highly Recommended: Persistent Memory with Docker + Qdrant + Ollama
+
+Without persistent memory, Claude starts every session from scratch — it forgets your codebase, past decisions, what worked, and what didn't. **With Qdrant and Ollama installed, Claude remembers everything across sessions.** It can recall past debugging sessions, reuse solutions it discovered weeks ago, and pick up exactly where it left off with full context.
+
+This is the difference between an AI that helps you for 30 minutes and one that becomes a long-term collaborator on your project.
+
+**What you get:**
+
+| Without Memory | With Qdrant + Ollama |
+|----------------|---------------------|
+| Claude forgets everything when you close the session | Claude recalls past sessions, decisions, and patterns |
+| You re-explain your project every time | Claude already knows your codebase and conventions |
+| Same mistakes get repeated across sessions | Lessons learned persist — Claude gets smarter over time |
+| Skills and patterns are discovered but lost | Auto-extracted skills are stored and reused |
+| Handoffs rely on text files only | Handoffs are backed by vector search across all history |
+
+**The setup takes about 10 minutes and runs entirely on your local machine — no cloud services, no data leaving your computer.**
 
 ---
 
 ### Step 1 — Install Docker Desktop
 
-Docker Desktop is required to run Qdrant. Install it before anything else.
+Docker Desktop is required to run Qdrant (the vector database that stores Claude's memory). Install it before anything else.
 
 **Windows (PC):**
 
@@ -193,7 +385,7 @@ Docker Desktop is required to run Qdrant. Install it before anything else.
 
 ### Step 2 — Run Qdrant (Vector Database)
 
-Qdrant stores Claude's persistent memory across sessions — so Claude remembers your codebase, past decisions, and patterns from previous work.
+Qdrant is the brain behind Claude's long-term memory. Every session handoff, debugging insight, skill discovery, and architectural decision gets stored as a searchable vector. When Claude starts a new session, it automatically searches this memory for relevant context — giving it continuity that no other AI coding tool provides.
 
 ```bash
 docker pull qdrant/qdrant
@@ -239,19 +431,24 @@ claude mcp add qdrant -s user -- cmd /c uvx mcp-server-qdrant \
 
 ### Step 4 — Install Ollama (Local Embeddings)
 
-Ollama runs locally and generates the vectors that get stored in Qdrant.
+Ollama is the engine that converts your code, decisions, and session context into vectors that Qdrant can search. It runs entirely on your machine — no API keys, no cloud calls, no cost per query. Once installed, it works silently in the background.
 
 1. Download and install from [ollama.com](https://ollama.com)
 2. Pull the embedding model:
    ```bash
    ollama pull nomic-embed-text
    ```
+3. Ollama starts automatically after install. Verify it's running:
+   ```bash
+   ollama list
+   ```
+   You should see `nomic-embed-text` in the output.
 
 ---
 
-### Step 5 — Run Docker Hub MCP Server (hub-mcp)
+### Step 5 (Optional) — Run Docker Hub MCP Server (hub-mcp)
 
-hub-mcp lets Claude search Docker Hub, browse images and tags, and pull images by just asking.
+hub-mcp lets Claude search Docker Hub, browse images and tags, and pull images by just asking. This is optional — it's useful if you work with Docker images regularly.
 
 ```bash
 docker pull docker/hub-mcp
@@ -326,8 +523,39 @@ Claude will plan, build, and verify every phase without you having to type each
 
 ## How Does It Compare?
 
+There are several open-source orchestration tools for Claude Code. Here's an honest, side-by-side comparison across 14 features:
+
 ![Feature Comparison](./docs/feature-comparison.png)
 
+### Why Dominion Flow Wins
+
+Most orchestration plugins do one or two things well. Dominion Flow is the only one that covers the **entire development lifecycle** — from initial project setup to production verification — in a single, free, open-source package.
+
+**Features no other free orchestration tool offers:**
+
+| Exclusive to Dominion Flow | What It Means for You |
+|---------------------------|----------------------|
+| **Phoenix Rebuild** | Take any messy "vibe coded" project and rebuild it clean. No other tool does this. |
+| **478+ skills library** | The largest collection of reusable patterns for AI-assisted development. Next closest has 60. |
+| **Playwright E2E testing** | Claude can open a real browser and prove your app works. No other orchestration tool integrates this. |
+| **Tiered verification (3-tier + 70-point)** | Fast gate catches obvious issues in 30 seconds. Full checklist catches everything else. Other tools have basic checks at best. |
+| **6-type circuit breaker** | Classifies WHY Claude is stuck (stall, spin, degrade, blocked, thrash, drift) and takes different action for each. Others just retry or stop. |
+| **GoF design patterns for AI** | All 22 Gang of Four patterns mapped to AI agent architecture. Educational and practical. |
+| **Learncoding mode** | Walk through any codebase step-by-step to understand it before changing it. A learning tool built into a production tool. |
+| **46 commands in 8 tiers** | Most tools have 5-10 commands. Dominion Flow covers planning, execution, verification, debugging, security, analytics, milestones, and learning. |
+
+**Where others are strong too** (credit where it's due):
+
+- **claude-mem** — Best-in-class session memory if memory is all you need
+- **GSD** — Solid plan-execute-verify pipeline with goal-backward verification
+- **everything-cc** — Good skills system with built-in security (AgentShield)
+- **Ruflo** — Strong swarm-based parallel execution
+- **Composio** — Powerful multi-agent orchestration with 30+ agents and CI self-healing
+
+**The difference:** Those tools specialize. Dominion Flow integrates. You get structured workflow, memory, verification, security, debugging, skills, E2E testing, autonomous mode, Phoenix Rebuild, and a learning system — all working together in one coherent pipeline. And it's completely free.
+
+---
+
 ## Key Features
 
 | Feature | What It Does |
@@ -408,14 +636,21 @@ This is where students and followers ask questions, share projects, and stay up
 
 ---
 
-## Support This Project
+## Star This Repo and Share It
+
+If Dominion Flow has helped you build faster, catch bugs earlier, or clean up a messy project — **please star this repo.** It takes one click and makes a real difference:
+
+**[github.com/ThierryN/fire-flow](https://github.com/ThierryN/fire-flow)** — Click the star button at the top right.
+
+Stars help other developers discover this project. The more people using Dominion Flow, the better the skills library gets, the more patterns get shared, and the stronger the community becomes.
 
-If you're following along and finding Dominion Flow useful, the best way to help is simple:
+**Know someone who could use this?**
 
-- **Star this repo** — it helps others discover it
-- **Share it** — pass it along to anyone learning Claude Code or building AI-assisted projects
+- A friend struggling with a messy codebase? Send them the Phoenix Rebuild section
+- A colleague learning Claude Code? This gives them structure from day one
+- A developer drowning in technical debt? `/fire-phoenix` was built for exactly that
 
-This is a living project. Your support keeps it growing.
+Share the link: `https://github.com/ThierryN/fire-flow`
 
 ---
 

package/TROUBLESHOOTING.md

@@ -261,4 +261,107 @@ Common failure modes and their fixes.
 
 ---
 
+## 11. Slash commands not appearing after install
+
+**Symptoms:**
+- You installed Dominion Flow but typing `/` doesn't show any `/fire-` commands
+- Claude doesn't recognize `/fire-0-orient` or any other Dominion Flow command
+- The plugin files exist on disk but Claude Code doesn't see them
+
+**Likely Cause:**
+- The plugin is not registered in your global `~/.claude/settings.json` under `enabledPlugins`
+- Claude Code was not restarted after installation
+- The plugin directory path is incorrect or the files were extracted to the wrong location
+- Stale command cache from a previous installation
+
+**Fix Steps:**
+
+**Option A — Ask Claude to fix it:**
+
+Open Claude Code and paste this message:
+
+> "My Dominion Flow plugin is installed but the /fire- slash commands aren't appearing. Please check my ~/.claude/settings.json, register the plugin under enabledPlugins, and refresh my commands."
+
+Claude will inspect your configuration, add the missing entry, and reload everything.
+
+**Option B — Fix manually:**
+
+1. Open your settings file:
+   - **Mac/Linux:** `~/.claude/settings.json`
+   - **Windows:** `%USERPROFILE%\.claude\settings.json`
+
+2. Find or create the `"enabledPlugins"` section and add:
+   ```json
+   {
+     "enabledPlugins": {
+       "dominion-flow@local": true
+     }
+   }
+   ```
+
+3. Verify the plugin files exist at the expected location:
+   ```bash
+   ls ~/.claude/plugins/dominion-flow/plugin.json
+   ```
+   If the file doesn't exist, the plugin wasn't installed correctly — reinstall with `npx @thierrynakoa/fire-flow` or `claude install-plugin ./fire-flow`.
+
+4. **Restart Claude Code completely** — close the terminal and reopen. A new conversation in the same terminal is not enough.
+
+5. Verify: type `/fire-0-orient` — you should see the orientation output.
+
+**Option C — Reinstall:**
+
+```bash
+npx @thierrynakoa/fire-flow --update
+```
+
+Or for git-cloned installs:
+```bash
+claude plugin uninstall dominion-flow
+claude install-plugin ./fire-flow
+```
+
+**Prevention:**
+- Always restart Claude Code after installing or updating any plugin
+- After installation, immediately test with `/fire-0-orient` before starting work
+- If you update Claude Code itself, re-verify your plugins are still registered — major updates can sometimes reset plugin state
+- Keep your `settings.json` backed up so you can restore plugin registrations quickly
+
+---
+
+## 12. Hooks not running or outdated
+
+**Symptoms:**
+- Session hooks (auto-update check, memory injection, compact restoration) don't fire
+- Hook errors appear at session start
+- Hooks reference files that no longer exist after an update
+
+**Likely Cause:**
+- Hooks were registered with absolute paths that changed after a plugin update or reinstall
+- The `hooks.json` file in the plugin references scripts that weren't included in the update
+- Global `settings.json` hooks conflict with plugin hooks
+
+**Fix Steps:**
+
+1. Ask Claude to refresh your hooks:
+
+   > "Please check my Dominion Flow hooks configuration and update any stale paths or missing hook scripts."
+
+2. Or manually check your plugin's hooks file:
+   ```bash
+   cat ~/.claude/plugins/dominion-flow/hooks/hooks.json
+   ```
+   Verify every `"command"` path points to a file that actually exists.
+
+3. If hooks reference missing files, reinstall:
+   ```bash
+   npx @thierrynakoa/fire-flow --update
+   ```
+
+**Prevention:**
+- After every plugin update, restart Claude Code and verify hooks fire correctly
+- Don't manually edit hook paths unless you know the exact file structure
+
+---
+
 *If your issue isn't listed here, check the references directory for detailed protocol documentation, or run `/fire-debug` to systematically investigate.*

package/commands/fire-verify-uat.md

@@ -1,10 +1,10 @@
 ---
-description: Conversational User Acceptance Testing with automatic parallel diagnosis on failures
+description: User Acceptance Testing with autonomous browser-use AI mode or manual guided mode, plus automatic parallel diagnosis on failures
 ---
 
 # /fire-verify-uat
 
-> Conversational UAT testing with automatic parallel diagnosis when flows fail.
+> UAT testing with autonomous AI browser mode or manual guided mode, plus automatic parallel diagnosis when flows fail.
 
 ---
 
@@ -48,7 +48,166 @@ Critical Flows to Test:
 
 Present to user: "Ready to start UAT? I'll guide you through each flow."
 
-### Step 3: Guided Testing
+### Step 2.5: Select Testing Mode
+
+```
++---------------------------------------------------------------+
+|  UAT MODE SELECTION                                            |
++---------------------------------------------------------------+
+|                                                                |
+|  A) AUTONOMOUS — browser-use AI runs all flows automatically   |
+|     - No clicking required, AI navigates the browser           |
+|     - Requires: Python 3.11+, browser-use, ANTHROPIC_API_KEY   |
+|     - Best for: form flows, page navigation, standard UI       |
+|                                                                |
+|  B) MANUAL — you click through each flow (current behavior)    |
+|     - Always works, no extra setup needed                      |
+|     - Best for: OAuth popups, file uploads, visual layout      |
+|                                                                |
++---------------------------------------------------------------+
+```
+
+Use AskUserQuestion with header "UAT Mode" and options:
+- "Autonomous (Recommended)" — browser-use AI runs all flows
+- "Manual" — guided human testing
+
+#### If user selects Autonomous:
+
+Run prerequisite checks via Bash:
+
+```bash
+# Check Python 3.11+
+python --version 2>&1
+
+# Check browser-use installed
+python -c "import browser_use; print('OK')" 2>&1
+
+# Check API key
+python -c "import os; print('KEY_OK' if os.environ.get('ANTHROPIC_API_KEY') else 'KEY_MISSING')" 2>&1
+
+# Check app is running (use the app's URL from PROJECT.md or default localhost:3000)
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>&1
+```
+
+If any check fails:
+```
++---------------------------------------------------------------+
+|  SETUP ISSUE — falling back to Manual mode                     |
++---------------------------------------------------------------+
+|                                                                |
+|  Missing: [what failed]                                        |
+|                                                                |
+|  To fix:                                                       |
+|    pip install browser-use                                     |
+|    uvx browser-use install                                     |
+|    export ANTHROPIC_API_KEY="sk-ant-..."                       |
+|                                                                |
+|  Proceeding with Manual mode instead.                          |
++---------------------------------------------------------------+
+```
+Fall back to Step 3 (Manual).
+
+If all checks pass: proceed to Step 2.6 (Autonomous Execution). Skip Step 3.
+
+#### If user selects Manual:
+
+Proceed to Step 3 (Guided Testing) as normal.
+
+### Step 2.6: Autonomous UAT Execution
+
+**Only runs if mode = Autonomous and all checks passed.**
+
+Load skill: `@skills-library/specialists/quality/browser-use-expert.md`
+
+Locate the UAT runner script:
+```bash
+RUNNER="$HOME/.claude/plugins/fire-flow/tools/uat-runner.py"
+# Fallback: check if running from cloned repo
+if [ ! -f "$RUNNER" ]; then
+  RUNNER="$HOME/.claude/plugins/dominion-flow/tools/uat-runner.py"
+fi
+```
+
+For each test flow generated in Step 2:
+
+```
++---------------------------------------------------------------+
+|  AUTONOMOUS TEST: Flow N of M                                  |
++---------------------------------------------------------------+
+|  Flow: [flow description]                                      |
+|  Mode: browser-use AI agent (headless Chromium)                |
+|  Running... (this may take 30-90 seconds per flow)             |
++---------------------------------------------------------------+
+```
+
+**Generate the task string** from the flow's must-have truth. Include explicit PASS/FAIL criteria:
+
+```
+"Go to http://localhost:{port}/{path}.
+[Specific steps derived from the flow]
+
+PASS CRITERIA (all must be true):
+1. [Expected outcome 1]
+2. [Expected outcome 2]
+
+FAIL if:
+- [Failure condition 1]
+- [Failure condition 2]
+
+Report your verdict as PASS or FAIL with a one-sentence summary."
+```
+
+**If the flow requires credentials**, add the `--credentials` flag:
+```bash
+python "$RUNNER" \
+  --task "[generated task string]" \
+  --output /tmp/uat-flow-N.json \
+  --max-steps 20 \
+  --credentials '{"localhost": {"x_email": "[test email]", "x_password": "[test password]"}}'
+```
+
+**If no credentials needed:**
+```bash
+python "$RUNNER" \
+  --task "[generated task string]" \
+  --output /tmp/uat-flow-N.json \
+  --max-steps 20
+```
+
+**Parse the result:**
+```bash
+cat /tmp/uat-flow-N.json
+```
+
+Read the JSON and record:
+- `status` = PASS, FAIL, or ERROR
+- `summary` = what happened
+- `errors` = any error messages
+
+**After all flows complete, display results:**
+
+```
++---------------------------------------------------------------+
+|  AUTONOMOUS UAT RESULTS                                        |
++---------------------------------------------------------------+
+
+| # | Flow                          | Status | Summary            |
+|---|-------------------------------|--------|--------------------|
+| 1 | User registration             | PASS   | Redirected to /dashboard |
+| 2 | User login                    | FAIL   | Login button not found   |
+| 3 | Dashboard loads               | PASS   | All widgets rendered     |
+
+Passed: 2/3  |  Failed: 1/3  |  Errors: 0/3
+```
+
+**Route results:**
+- PASS flows → record and continue
+- FAIL flows → proceed to Step 4 (Automatic Diagnosis) for each failure
+- ERROR flows → display: "Infrastructure error on flow N. Retest manually?" and offer to run that flow in Manual mode (Step 3)
+
+After all flows processed, proceed to Step 6 (Generate UAT Report).
+
+### Step 3: Guided Testing (Manual Mode Only)
 
 For each flow:
 1. Present exact steps to test
@@ -106,12 +265,16 @@ For each failure with diagnosis:
 ```markdown
 ## UAT Report: Phase XX
 
+### Session Info
+- **Mode:** [autonomous / manual]
+- **Tester:** [browser-use AI / human]
+
 ### Results
-| Flow | Status | Notes |
-|------|--------|-------|
-| Registration | PASS | |
-| Login | PASS | |
-| Dashboard | FAIL -> PASS | Fixed: missing redirect |
+| Flow | Status | Mode | Notes |
+|------|--------|------|-------|
+| Registration | PASS | autonomous | Redirected to /dashboard |
+| Login | PASS | autonomous | |
+| Dashboard | FAIL -> PASS | manual | Fixed: missing redirect |
 
 ### Verdict: [PASS / CONDITIONAL PASS / FAIL]
 - Blocking issues: [N]
@@ -131,10 +294,12 @@ For each failure with diagnosis:
 
 ## Success Criteria
 
+- [ ] Testing mode selected (autonomous or manual)
+- [ ] If autonomous: prerequisites verified (Python, browser-use, API key, app running)
 - [ ] All critical flows tested
 - [ ] Failures diagnosed with parallel agents
 - [ ] Fixes committed and retested
-- [ ] UAT report generated
+- [ ] UAT report generated with mode column
 - [ ] Clear verdict and next action
 
 ---
@@ -144,3 +309,6 @@ For each failure with diagnosis:
 - **Template:** `@templates/UAT.md`
 - **Debugging pattern:** CLAUDE.md parallel debugging section
 - **Verification:** `@references/verification-patterns.md`
+- **Skill:** `@skills-library/specialists/quality/browser-use-expert.md`
+- **Runner:** `@tools/uat-runner.py`
+- **Library:** [browser-use](https://github.com/browser-use/browser-use) — MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thierrynakoa/fire-flow",
-  "version": "12.2.1",
+  "version": "12.2.2",
   "description": "Dominion Flow — the most comprehensive orchestration platform for Claude Code. 46 commands, 15 agents, 478+ skills. Plan → Execute → Verify → Handoff with parallel execution, session memory, circuit breaker safety, Phoenix Rebuild, and learning mode.",
   "keywords": [
     "claude-code",
@@ -36,6 +36,7 @@
     "skills-library/",
     "templates/",
     "references/",
+    "tools/",
     "workflows/",
     "plugin.json",
     ".claude-plugin/",

package/skills-library/specialists/quality/browser-use-expert.md

@@ -0,0 +1,210 @@
+---
+name: browser-use-expert
+description: Use when running autonomous AI-driven UAT flows, exploratory browser testing, or scripting multi-step browser interactions via browser-use Python library. Invoke for AI browser automation, credential-masked testing, structured test output from browser sessions.
+license: MIT
+metadata:
+  author: Dominion Flow
+  version: "1.0.0"
+  domain: quality
+  triggers: browser-use, autonomous UAT, AI browser testing, browser automation, exploratory testing
+  role: specialist
+  scope: testing
+  output-format: json
+  related-skills: playwright-expert, test-master, debugging-wizard
+---
+
+# browser-use Expert
+
+Senior QA automation engineer specializing in AI-driven browser testing using the browser-use Python library. Complements Playwright (deterministic E2E) with AI-driven exploratory testing where the agent decides HOW to test based on natural language instructions.
+
+## Role: Complementary to Playwright
+
+| Tool | Best For |
+|------|----------|
+| **Playwright** | Regression tests, CI/CD, deterministic flows, cross-browser matrix |
+| **browser-use** | UAT exploratory flows, natural language test specs, credential-masked testing, flows too complex to script |
+
+Never replace Playwright E2E with browser-use. Use both.
+
+## Setup Requirements
+
+```bash
+# 1. Python 3.11+ required
+python --version
+
+# 2. Install browser-use
+pip install browser-use
+
+# 3. Install Chromium (one-time)
+uvx browser-use install
+
+# 4. Anthropic API key must be set
+# Windows: System Environment Variables
+# Mac/Linux: export ANTHROPIC_API_KEY="sk-ant-..."
+
+# 5. Verify setup
+python -c "from browser_use import Agent; from browser_use.llm import ChatAnthropic; print('Setup OK')"
+```
+
+## The UAT Runner Script
+
+Dominion Flow ships a thin runner: `~/.claude/plugins/fire-flow/tools/uat-runner.py`
+
+Call it from Bash inside fire-verify-uat:
+
+```bash
+python ~/.claude/plugins/fire-flow/tools/uat-runner.py \
+  --task "Go to http://localhost:3000. Test user registration..." \
+  --output /tmp/uat-result.json \
+  --max-steps 20
+```
+
+### Output Format
+
+```json
+{
+  "status": "PASS",
+  "summary": "User registered successfully, redirected to /dashboard",
+  "steps_taken": 8,
+  "final_url": "http://localhost:3000/dashboard",
+  "errors": [],
+  "screenshots": ["/tmp/.../step_0.png", "/tmp/.../step_1.png"]
+}
+```
+
+Status values: `"PASS"`, `"FAIL"`, `"ERROR"` (infrastructure failure, not test failure)
+
+## Canonical Usage Pattern
+
+```python
+import asyncio
+from browser_use import Agent
+from browser_use.llm import ChatAnthropic
+from browser_use.browser.profile import BrowserProfile
+from pydantic import BaseModel
+
+class UATResult(BaseModel):
+    status: str          # "PASS" or "FAIL"
+    summary: str         # 1-2 sentences of what happened
+    steps_taken: int
+    final_url: str
+    errors: list[str]
+
+async def run_uat_flow(task: str, sensitive_data: dict = None):
+    llm = ChatAnthropic(model='claude-sonnet-4-5', temperature=0.0)
+    profile = BrowserProfile(headless=True)
+
+    agent = Agent(
+        task=task,
+        llm=llm,
+        browser_profile=profile,
+        sensitive_data=sensitive_data,
+        output_model_schema=UATResult,
+    )
+
+    history = await agent.run(max_steps=20)
+    return history.final_result()
+```
+
+## Credential Masking Pattern
+
+NEVER put real passwords in the task string. Use `sensitive_data`:
+
+```python
+# In task string, use placeholder names
+task = "Login with x_email and x_password, then verify dashboard loads"
+
+# In sensitive_data, map placeholders to real values
+sensitive_data = {
+    'localhost': {
+        'x_email': 'testuser@example.com',
+        'x_password': 'RealPassword123!'
+    }
+}
+
+# The LLM sees "x_email" and "x_password" — never the actual values
+```
+
+When calling via CLI:
+```bash
+--credentials '{"localhost": {"x_email": "test@example.com", "x_password": "Pass123!"}}'
+```
+
+## Writing Effective UAT Task Strings
+
+Good task strings are explicit about WHAT to verify:
+
+```
+# GOOD — includes explicit verification criteria
+"Go to http://localhost:3000/register.
+Fill in the email field with: x_email
+Fill in the password field with: x_password
+Click the Register button.
+
+PASS CRITERIA (all must be true):
+1. The browser URL changes to /dashboard
+2. The page displays a welcome message
+
+FAIL if any error message appears or URL does not change."
+
+# BAD — no verification criteria
+"Go to localhost:3000 and register"
+```
+
+## Multi-Flow Pattern
+
+Reuse the same browser session for sequential flows:
+
+```python
+profile = BrowserProfile(keep_alive=True, headless=True)
+agent = Agent(task=task1, llm=llm, browser_profile=profile)
+await agent.run()
+
+agent.add_new_task("Now test the login flow: logout, go to /login, fill credentials")
+await agent.run()
+```
+
+## When to Prefer Manual UAT Instead
+
+- OAuth popup windows from external providers
+- File uploads or downloads (OS file dialogs)
+- Visual design or pixel-level layout verification
+- Testing on specific mobile device form factors
+- Flows requiring CAPTCHA interaction
+
+## Must Do
+
+- Always use `headless=True` in UAT runner
+- Always provide explicit PASS/FAIL criteria in task strings
+- Always use `sensitive_data` for credentials
+- Set `temperature=0.0` for deterministic testing
+- Set `max_steps` to prevent runaway sessions (15-25 typical)
+- Check that the dev server is running before starting tests
+
+## Must Not Do
+
+- Do not use browser-use for regression tests that have Playwright coverage
+- Do not run without `max_steps` set
+- Do not embed real passwords in task strings
+- Do not spawn multiple browser-use agents against the same localhost app
+- Do not use as a replacement for unit or integration tests
+
+## Error Handling
+
+```bash
+# Check exit code: 0 = ran (check JSON), 1 = setup error
+python uat-runner.py --task "..." --output /tmp/result.json
+if [ $? -ne 0 ]; then
+    echo "Setup error — check stderr for details"
+fi
+
+# Parse JSON status
+python -c "import json; r=json.load(open('/tmp/result.json')); print(r['status'])"
+```
+
+## Windows Notes
+
+- Use `python` (not `python3`) unless aliased
+- `ANTHROPIC_API_KEY` must be in system environment or `.env` file
+- Headless mode works without a display server
+- Screenshot paths use forward slashes in Python even on Windows

package/tools/uat-runner.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+Dominion Flow UAT Runner — browser-use integration
+Called by fire-verify-uat autonomous mode via Bash.
+
+Usage:
+  python uat-runner.py --task "..." --output /tmp/result.json [--max-steps 20] [--credentials '{}']
+
+Exit codes:
+  0 = script ran successfully, check JSON for PASS/FAIL/ERROR
+  1 = setup error (missing dependency, missing API key, etc.)
+"""
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def check_setup():
+    """Verify all prerequisites before importing browser_use."""
+    errors = []
+
+    if sys.version_info < (3, 11):
+        errors.append(f"Python 3.11+ required (got {sys.version})")
+
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        env_file = Path(".env")
+        if env_file.exists():
+            for line in env_file.read_text().splitlines():
+                if line.startswith("ANTHROPIC_API_KEY="):
+                    os.environ["ANTHROPIC_API_KEY"] = line.split("=", 1)[1].strip().strip('"')
+                    break
+
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        errors.append("ANTHROPIC_API_KEY not found in environment or .env file")
+
+    try:
+        import browser_use  # noqa: F401
+    except ImportError:
+        errors.append("browser_use not installed. Run: pip install browser-use")
+
+    return errors
+
+
+def get_result_model():
+    from pydantic import BaseModel
+
+    class UATFlowResult(BaseModel):
+        status: str
+        summary: str
+        steps_taken: int
+        final_url: str
+        errors: list[str]
+
+    return UATFlowResult
+
+
+async def run_uat(task, max_steps, sensitive_data):
+    """Run one UAT flow via browser-use agent."""
+    from browser_use import Agent
+    from browser_use.llm import ChatAnthropic
+    from browser_use.browser.profile import BrowserProfile
+
+    UATFlowResult = get_result_model()
+
+    llm = ChatAnthropic(
+        model=os.environ.get("BROWSER_USE_MODEL", "claude-sonnet-4-5"),
+        temperature=0.0,
+    )
+
+    profile = BrowserProfile(headless=True)
+
+    agent = Agent(
+        task=task,
+        llm=llm,
+        browser_profile=profile,
+        sensitive_data=sensitive_data,
+        output_model_schema=UATFlowResult,
+        generate_gif=False,
+    )
+
+    history = await agent.run(max_steps=max_steps)
+
+    raw = history.final_result()
+    if raw:
+        try:
+            parsed = UATFlowResult.model_validate_json(raw)
+            result = parsed.model_dump()
+        except Exception as e:
+            result = {
+                "status": "FAIL",
+                "summary": f"Agent returned unstructured output: {str(raw)[:500]}",
+                "steps_taken": max_steps,
+                "final_url": "",
+                "errors": [f"Schema parse error: {e}"],
+            }
+    else:
+        result = {
+            "status": "FAIL",
+            "summary": "Agent completed but returned no result.",
+            "steps_taken": max_steps,
+            "final_url": "",
+            "errors": ["No final result returned by agent"],
+        }
+
+    # Attach screenshot paths if available
+    try:
+        screenshots = [str(p) for item in history.history if hasattr(item, 'state') and hasattr(item.state, 'screenshot') and item.state.screenshot for p in [item.state.screenshot]]
+        result["screenshots"] = screenshots
+    except Exception:
+        result["screenshots"] = []
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Dominion Flow UAT Runner (browser-use)")
+    parser.add_argument("--task", required=True, help="Plain-English UAT task description")
+    parser.add_argument("--output", required=True, help="Path for JSON output file")
+    parser.add_argument("--max-steps", type=int, default=20, help="Max browser steps (default: 20)")
+    parser.add_argument("--credentials", default=None, help='JSON string: {"domain": {"key": "value"}}')
+    args = parser.parse_args()
+
+    # 1. Setup checks
+    errors = check_setup()
+    if errors:
+        print("SETUP ERRORS:", file=sys.stderr)
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        print("\nFix: pip install browser-use && uvx browser-use install", file=sys.stderr)
+        sys.exit(1)
+
+    # 2. Parse credentials
+    sensitive_data = None
+    if args.credentials:
+        try:
+            sensitive_data = json.loads(args.credentials)
+        except json.JSONDecodeError as e:
+            print(f"Invalid --credentials JSON: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    # 3. Run agent
+    try:
+        result = asyncio.run(run_uat(
+            task=args.task,
+            max_steps=args.max_steps,
+            sensitive_data=sensitive_data,
+        ))
+    except KeyboardInterrupt:
+        print("UAT run interrupted.", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        result = {
+            "status": "ERROR",
+            "summary": f"Infrastructure error: {str(e)}",
+            "steps_taken": 0,
+            "final_url": "",
+            "errors": [str(e)],
+            "screenshots": [],
+        }
+
+    # 4. Write JSON output
+    output_path = Path(args.output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(result, indent=2))
+
+    # 5. Print summary to stdout for Claude to read
+    print(f"STATUS: {result['status']}")
+    print(f"SUMMARY: {result['summary']}")
+    if result.get("errors"):
+        print(f"ERRORS: {'; '.join(result['errors'])}")
+    print(f"OUTPUT: {args.output}")
+
+
+if __name__ == "__main__":
+    main()