@thierrynakoa/fire-flow 12.2.1 → 13.0.1

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()

package/version.json

@@ -1,7 +1,11 @@
 {
-  "version": "12.2.0",
+  "version": "13.0.0",
   "commit": "local",
   "branch": "main",
-  "updatedAt": "2026-03-06T00:00:00Z",
-  "installMethod": "local"
+  "updatedAt": "2026-03-12T22:00:00Z",
+  "installMethod": "local",
+  "changelog": {
+    "13.0.0": "17 research-backed changes across 3 waves: Societies of Thought plan critique, Spec-Driven verification, SE-Agent TDD + Implied Scenarios, FoldAgent cross-turn compression, Variation Injection, CNCF taxonomy, Frequency-Ranked Core Learnings, Background Agent Execution, Multi-Agent Reflexion, Adversarial Judge separation, Magentic-UI confidence escalation",
+    "12.6.0": "Unified /fire-skill CLI, 6 skill templates, import/validate/stats scripts"
+  }
 }

package/workflows/handoff-session.md

@@ -268,7 +268,7 @@ next_action: "{what to do next}"
 ### Important Paths
 - **Project Root:** {absolute path}
 - **Planning Docs:** {path}/.planning/
-- **Skills Library:** ~/.claude/plugins/fire-flow/skills-library/
+- **Skills Library:** ~/.claude/plugins/dominion-flow/skills-library/
 - **Handoffs:** ~/.claude/warrior-handoffs/
 
 ---
@@ -607,7 +607,7 @@ Before finalizing handoff, verify:
 ║                                                                              ║
 ║  No .planning/CONSCIENCE.md found.                                                ║
 ║                                                                              ║
-║  Action: Run `/fire-1-new` to initialize project first.                     ║
+║  Action: Run `/fire-1a-new` to initialize project first.                     ║
 ║                                                                              ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
 ```

package/workflows/new-project.md

@@ -476,7 +476,7 @@ status: ready_to_plan
 
 **Purpose:** Ensure automatic context loading on session start.
 
-The Fire Flow plugin includes SessionStart hooks that:
+The Dominion Flow plugin includes SessionStart hooks that:
 1. Load CONSCIENCE.md context automatically
 2. Remind about WARRIOR handoffs
 3. Display last activity and next action
@@ -484,7 +484,7 @@ The Fire Flow plugin includes SessionStart hooks that:
 **Verify hook configuration:**
 ```bash
 # Check hooks.json exists in plugin
-ls ~/.claude/plugins/fire-flow/hooks/hooks.json
+ls ~/.claude/plugins/dominion-flow/hooks/hooks.json
 ```
 
 ---

package/workflows/plan-phase.md

@@ -36,7 +36,7 @@ Before executing this workflow, load:
 # Check required files exist
 if [ ! -f ".planning/CONSCIENCE.md" ]; then
   echo "ERROR: No .planning/CONSCIENCE.md found"
-  echo "Run /fire-1-new to initialize project first"
+  echo "Run /fire-1a-new to initialize project first"
   exit 1
 fi
 

package/.claude-plugin/plugin.json

@@ -1,64 +0,0 @@
-{
-  "name": "dominion-flow",
-  "version": "12.2.0",
-  "description": "Dominion Flow is a comprehensive orchestration platform that empowers your Claude agent. It gives Claude a complete, structured workflow for taking projects from idea to production — with parallel execution, 478+ reusable skills, session memory across handoffs, 70-point quality verification, autonomous mode, Phoenix Rebuild (messy-to-clean), E2E testing, and a circuit breaker to prevent stuck loops. Includes 46 slash commands organized into 8 tiers covering planning, execution, verification, debugging, skills management, milestone tracking, and learning mode.",
-  "author": {
-    "name": "Thierry",
-    "email": ""
-  },
-  "repository": "https://github.com/ThierryN/fire-flow",
-  "license": "MIT",
-  "keywords": [
-    "workflow",
-    "fire-flow",
-    "warrior",
-    "sdlc",
-    "skills-library",
-    "validation",
-    "handoff",
-    "project-management",
-    "automation",
-    "testing",
-    "git-flow",
-    "blocker-tracking",
-    "metrics",
-    "auto-skill-extraction",
-    "breath-execution",
-    "parallel-agents",
-    "uat-testing",
-    "codebase-mapping",
-    "circuit-breaker",
-    "error-classification",
-    "context-engineering",
-    "phoenix-rebuild",
-    "intent-extraction",
-    "autonomous-rebuild",
-    "playwright-e2e",
-    "e2e-testing",
-    "visual-regression",
-    "plan-aware-debugging",
-    "decision-log",
-    "assumptions-registry",
-    "handoff-validator",
-    "task-recitation",
-    "cross-phase-validation",
-    "confidence-scoring",
-    "worktree-isolation",
-    "model-split",
-    "parallelizability-routing",
-    "context-compression",
-    "error-preservation",
-    "issue-to-pr",
-    "skills-validation",
-    "post-verification-routing"
-  ],
-  "commands": "./commands/",
-  "agents": "./agents/",
-  "hooks": "./hooks/hooks.json",
-  "capabilities": {
-    "commands": true,
-    "skills": true,
-    "hooks": true,
-    "agents": true
-  }
-}

package/skills-library/_general/methodology/LIVE_BREADCRUMB_PROTOCOL.md

@@ -1,242 +0,0 @@
----
-name: LIVE_BREADCRUMB_PROTOCOL
-category: methodology
-description: Automatic breadcrumb trail that makes each Claude instance smarter than the last
-version: 1.0.0
-tags: [reflexion, breadcrumbs, learning, memory, cross-session]
----
-
-# Live Breadcrumb Protocol — Institutional Memory
-
-Each Claude instance drops breadcrumbs as it works. The next instance reads them and starts smarter. Over time, the project accumulates institutional knowledge that no single session could hold.
-
-> **Military analogy:** After-action reports. Every unit debriefs. The lessons go into doctrine. The next unit deploys with that doctrine baked in — they've never been to that battlefield, but they know what works there.
-
----
-
-## Architecture
-
-```
-.planning/
-  breadcrumbs/
-    LESSONS.md           ← Living document: solutions that worked (READ FIRST)
-    FAILURES.md          ← What was tried and failed (READ SECOND)
-    PATTERNS.md          ← Project-specific patterns discovered during execution
-    DEPENDENCIES.md      ← Gotchas with specific libraries/versions
-```
-
-### Why 4 files (not 1)
-
-- **LESSONS.md** — "Do this" (positive knowledge, solutions)
-- **FAILURES.md** — "Don't do this" (negative knowledge, dead ends)
-- **PATTERNS.md** — "This is how things work here" (project conventions)
-- **DEPENDENCIES.md** — "Watch out for this" (library/version gotchas)
-
-Separating them lets agents read only what's relevant. A planner needs LESSONS + FAILURES. An executor needs PATTERNS + DEPENDENCIES. A researcher needs all four.
-
----
-
-## When Breadcrumbs Are Written (Automatic Triggers)
-
-### Trigger 1: After Solving a Non-Trivial Problem (> 2 attempts)
-**Who writes:** fire-executor, fire-debugger → `LESSONS.md`
-```markdown
-### JWT refresh token not persisting
-Root cause: httpOnly cookie not set on response — missing `credentials: 'include'`
-Fix: add `credentials: 'include'` to fetch AND `cors({ credentials: true })` on server
-```
-
-### Trigger 2: After Verification Failure
-**Who writes:** fire-verifier → `FAILURES.md`
-```markdown
-### Phase 2: Custom auth middleware approach FAILED
-Tried: rolling own JWT validation middleware
-Why: race condition on token refresh — 2 concurrent requests both try to refresh
-Don't retry unless: switching to a battle-tested auth library (better-auth, lucia)
-```
-
-### Trigger 3: After Discovering a Project Pattern
-**Who writes:** fire-executor, fire-planner → `PATTERNS.md`
-```markdown
-### API routes use camelCase, not snake_case
-Example: `server/routes/userProgress.js` — `getUserProgress`, not `get_user_progress`
-Breaks: frontend expects camelCase from API responses
-```
-
-### Trigger 4: After Hitting a Dependency Gotcha
-**Who writes:** fire-executor, fire-researcher → `DEPENDENCIES.md`
-```markdown
-### next@15 — cookies() is now async
-Symptom: `cookies()` returns Promise, not CookieStore
-Fix: `const cookieStore = await cookies()` — must await in App Router
-```
-
-**Notice: every example above is 3-4 lines. That's the target.**
-
----
-
-## When Breadcrumbs Are Read (Automatic Injection)
-
-### On Session Start (via hooks)
-When `/fire-6-resume` or a new session starts on an existing project:
-```
-1. Check if .planning/breadcrumbs/ exists
-2. If yes: Read LESSONS.md (always) + FAILURES.md (always)
-3. Inject as context: "Previous instances learned these lessons..."
-4. PATTERNS.md and DEPENDENCIES.md are read on-demand by agents
-```
-
-### Before Planning (fire-planner, Step 1)
-```
-Read .planning/breadcrumbs/LESSONS.md
-  → "Previous instances found these solutions..."
-Read .planning/breadcrumbs/FAILURES.md
-  → "Previous instances tried these and they FAILED..."
-
-This prevents re-planning with approaches already proven to fail.
-```
-
-### Before Execution (fire-executor, start of each plan)
-```
-Read .planning/breadcrumbs/PATTERNS.md
-  → "This project follows these conventions..."
-Read .planning/breadcrumbs/DEPENDENCIES.md
-  → "Watch out for these library gotchas..."
-```
-
-### During Recovery Research (fire-researcher, recovery mode)
-```
-Read ALL 4 breadcrumb files
-  → "Here's everything previous instances learned about this project"
-  → Cross-reference with FAILURES.md to avoid repeating dead ends
-```
-
----
-
-## File Templates (Slim — 2-line headers, 3-4 line entries)
-
-### LESSONS.md
-```markdown
-# Lessons — {Project Name}
-> Solutions that worked. Max 20 entries. Merge or archive when full.
-
-### {title}
-Root cause: {why}
-Fix: {what to do}
-```
-
-### FAILURES.md
-```markdown
-# Dead Ends — {Project Name}
-> What failed. If you're about to try something here, STOP.
-
-### {approach that failed}
-Tried: {what}
-Why it failed: {root cause}
-Don't retry unless: {condition}
-```
-
-### PATTERNS.md
-```markdown
-# Patterns — {Project Name}
-> Follow these conventions. Breaks stuff if you don't.
-
-### {pattern name}
-Example: `{file:line}`
-Breaks: {what goes wrong if ignored}
-```
-
-### DEPENDENCIES.md
-```markdown
-# Gotchas — {Project Name}
-> Library-specific traps. Check before debugging weird errors.
-
-### {package}@{version} — {title}
-Symptom: {what you see}
-Fix: {what to do}
-```
-
----
-
-## Breadcrumb Hygiene
-
-### Size Limits — Breadcrumbs, Not a Loaf
-
-**Hard caps per file:**
-| File | Max entries | Max lines | Entry max |
-|------|-------------|-----------|-----------|
-| LESSONS.md | 20 | 80 lines | 4 lines |
-| FAILURES.md | 15 | 60 lines | 4 lines |
-| PATTERNS.md | 15 | 60 lines | 3 lines |
-| DEPENDENCIES.md | 15 | 60 lines | 4 lines |
-
-**Each breadcrumb is a CRUMB — 3-4 lines max.** If you need more than 4 lines to explain it, you're writing documentation, not a breadcrumb.
-
-**Compact format (use this, not the verbose templates above):**
-```markdown
-### Prisma findMany returns empty on new schema
-Root cause: forgot `npx prisma generate` after schema change
-Fix: always run `prisma generate` after editing schema.prisma
-```
-
-**When a file hits the cap:**
-1. Merge related entries (3 Prisma gotchas → 1 consolidated entry)
-2. Delete entries that are obvious in hindsight (not worth preserving)
-3. Only then archive to `.planning/breadcrumbs/archive/{filename}-{date}.md`
-4. **Never let breadcrumbs exceed the cap** — an agent reading 80+ lines of "lessons" is wasting tokens on context it probably won't use
-
-### Deduplication
-Before writing a breadcrumb, check if a similar one already exists:
-```
-Grep pattern="{key phrase from new breadcrumb}" path=".planning/breadcrumbs/"
-IF match found:
-  → Update existing entry instead of creating duplicate
-  → Add "Confirmed again on {date}" to show it's a recurring pattern
-```
-
-### Quality Check
-Every breadcrumb must have:
-- [ ] A clear **search term** (how would a future instance find this?)
-- [ ] The **root cause** (not just the symptom)
-- [ ] The **solution** or **warning** (actionable, not just descriptive)
-- [ ] A **date** (to know how fresh this knowledge is)
-
-Breadcrumbs without root causes are symptoms — not lessons. Don't write "X broke" without "because Y."
-
----
-
-## Integration Points
-
-| Agent | Reads | Writes |
-|-------|-------|--------|
-| **fire-planner** | LESSONS.md, FAILURES.md | PATTERNS.md (when discovering conventions during planning) |
-| **fire-executor** | PATTERNS.md, DEPENDENCIES.md | LESSONS.md (after solving problems), PATTERNS.md (after discovering conventions), DEPENDENCIES.md (after hitting gotchas) |
-| **fire-verifier** | — | FAILURES.md (after verification failure) |
-| **fire-researcher** | All 4 files | DEPENDENCIES.md (after discovering version issues) |
-| **fire-debugger** | LESSONS.md, FAILURES.md, DEPENDENCIES.md | LESSONS.md (after resolution), FAILURES.md (for dead ends tried) |
-| **fire-6-resume** | LESSONS.md, FAILURES.md | — (read-only injection) |
-
----
-
-## The Compounding Effect
-
-```
-Session 1:  Claude knows nothing about the project
-            → Hits 5 problems, solves them
-            → Writes 5 breadcrumbs
-
-Session 2:  Claude reads 5 breadcrumbs
-            → Avoids 3 of those problems entirely
-            → Hits 2 new problems, solves them
-            → Writes 2 new breadcrumbs (total: 7)
-
-Session 3:  Claude reads 7 breadcrumbs
-            → Avoids 5 problems, solves 1 new one
-            → Total: 8 breadcrumbs
-
-Session 10: Claude reads 15+ breadcrumbs
-            → Knows every gotcha, every pattern, every dead end
-            → Executes like a senior developer on the project
-```
-
-Each instance is disposable. The breadcrumbs are permanent. The knowledge compounds.