@thierrynakoa/fire-flow 10.0.0

package/references/execution-mode-intelligence.md

@@ -0,0 +1,242 @@
+# Dominion Flow Execution Mode Intelligence
+
+## Overview
+
+Dominion Flow automatically determines whether to use **Swarm Mode** (multi-agent parallel teams), **Subagent Mode** (Task tool parallelism), or **Sequential Mode** based on plan/task characteristics. The Team Lead never needs to manually choose — the system analyzes the work and selects the optimal execution strategy.
+
+---
+
+## Execution Modes
+
+| Mode | How It Works | Best For |
+|------|-------------|----------|
+| **Swarm** | Team Lead spawns specialist teammates via Agent Teams | Multi-file features, full-stack plans, parallel debugging |
+| **Subagent** | Task tool spawns focused executor agents per plan | Breath-based phase execution, isolated plan work |
+| **Sequential** | Single agent executes tasks one at a time | Decision-dependent work, small plans, high-risk changes |
+
+---
+
+## Decision Algorithm
+
+### Phase-Level Decision (in `/fire-3-execute`)
+
+When executing a phase with multiple plans grouped into breaths:
+
+```
+FOR each breath in phase:
+  independent_plans = plans in this breath (all can run in parallel)
+
+  IF independent_plans.count == 1:
+    MODE = SEQUENTIAL (single plan, no parallelism needed)
+
+  ELIF independent_plans.count >= 3 AND no_file_overlap(plans):
+    MODE = SWARM (many independent plans, dedicated agents per specialty)
+    REASON: "3+ independent plans with no file overlap — swarm is optimal"
+
+  ELIF independent_plans.count >= 2 AND no_file_overlap(plans):
+    MODE = SUBAGENT (Task tool spawns executor per plan)
+    REASON: "2 parallel plans — subagent execution is sufficient"
+
+  ELIF independent_plans.count >= 2 AND has_file_overlap(plans):
+    MODE = SEQUENTIAL (file conflicts require serialization)
+    REASON: "File overlap detected — sequential prevents merge conflicts"
+
+  ELSE:
+    MODE = SEQUENTIAL (default safe mode)
+```
+
+### Plan-Level Decision (in `/fire-execute-plan`)
+
+When executing a single plan with multiple tasks:
+
+```
+FOR plan:
+  tasks = all tasks in plan
+  auto_tasks = tasks where type == "auto"
+  checkpoint_tasks = tasks where type starts with "checkpoint:"
+
+  IF checkpoint_tasks has type "checkpoint:decision":
+    MODE = SEQUENTIAL (decisions require user interaction in main context)
+    REASON: "Decision checkpoint requires main context"
+
+  ELIF auto_tasks.count >= 3 AND tasks_are_independent(auto_tasks):
+    AND plan.risk_level != "high":
+    MODE = SWARM (multiple independent auto tasks, spawn specialist team)
+    REASON: "3+ independent tasks — Team Lead delegates to specialists"
+    TEAM:
+      - Backend specialist (API/DB tasks)
+      - Frontend specialist (UI/component tasks)
+      - Test specialist (test writing tasks)
+
+  ELIF auto_tasks.count >= 2 AND tasks_are_independent(auto_tasks):
+    MODE = SUBAGENT (2 parallel segments possible)
+    REASON: "2 independent segments — subagent per segment"
+
+  ELIF plan.risk_level == "high":
+    MODE = SEQUENTIAL (high-risk needs careful, serial attention)
+    REASON: "High-risk plan — sequential for careful execution"
+
+  ELSE:
+    MODE = SEQUENTIAL (default)
+```
+
+---
+
+## Independence Checks
+
+### File Overlap Detection
+
+```
+no_file_overlap(plans) =
+  FOR each pair of plans (A, B):
+    files_A = A.frontmatter.files_modified
+    files_B = B.frontmatter.files_modified
+    IF intersection(files_A, files_B) is not empty:
+      RETURN false
+  RETURN true
+```
+
+### Task Independence Detection
+
+```
+tasks_are_independent(tasks) =
+  FOR each pair of tasks (A, B):
+    IF A.files overlaps B.files:
+      RETURN false
+    IF B references output of A:
+      RETURN false
+  RETURN true
+```
+
+### Specialty Detection (for Swarm team composition)
+
+```
+detect_specialties(tasks) =
+  specialties = {}
+  FOR each task:
+    IF task.files match "src/api/*" OR "src/models/*" OR "prisma/*":
+      specialties.add("backend")
+    IF task.files match "src/components/*" OR "src/app/*" OR "*.css":
+      specialties.add("frontend")
+    IF task.files match "*test*" OR "*spec*":
+      specialties.add("testing")
+    IF task.files match "*.sql" OR "prisma/migrations/*":
+      specialties.add("database")
+  RETURN specialties
+```
+
+---
+
+## Mode Display
+
+When execution mode is selected, display to user:
+
+```
++---------------------------------------------------------------+
+|  EXECUTION MODE: SWARM                                         |
++---------------------------------------------------------------+
+|                                                                 |
+|  Breath 1: 3 independent plans                                  |
+|  File overlap: None detected                                   |
+|  Risk level: Low                                               |
+|                                                                 |
+|  Team Lead will delegate to:                                   |
+|    Backend Agent:  Plan 03-01 (API endpoints)                  |
+|    Frontend Agent: Plan 03-02 (Dashboard UI)                   |
+|    Test Agent:     Plan 03-03 (Integration tests)              |
+|                                                                 |
+|  Rationale: 3+ independent plans with no file overlap          |
+|             and complementary specialties                       |
++-----------------------------------------------------------------+
+```
+
+```
++---------------------------------------------------------------+
+|  EXECUTION MODE: SEQUENTIAL                                    |
++---------------------------------------------------------------+
+|                                                                 |
+|  Plan 04-02: Checkout flow                                     |
+|  Decision checkpoint at Task 2 (payment provider)              |
+|  Risk level: High (payment processing)                         |
+|                                                                 |
+|  Rationale: Decision checkpoint requires user interaction       |
+|             + high-risk plan benefits from careful execution    |
++-----------------------------------------------------------------+
+```
+
+---
+
+## Swarm Team Composition
+
+When SWARM mode is selected, compose the team based on detected specialties:
+
+| Detected Specialty | Agent Role | Assignment |
+|-------------------|------------|------------|
+| backend | Backend Specialist | API routes, middleware, database queries |
+| frontend | Frontend Specialist | React components, pages, styles |
+| testing | Test Specialist | Unit tests, integration tests, E2E |
+| database | Database Specialist | Migrations, schema changes, seeds |
+| mixed (single plan) | Full-Stack Agent | Entire plan execution |
+
+### Swarm Prompt Template
+
+```
+"Execute Phase {N}, Breath {W} as a team.
+
+Team composition:
+- Backend Agent: Execute Plan {N}-01 (API endpoints for {feature})
+  Context: @.planning/phases/{N}-name/{N}-01-BLUEPRINT.md
+
+- Frontend Agent: Execute Plan {N}-02 (UI components for {feature})
+  Context: @.planning/phases/{N}-name/{N}-02-BLUEPRINT.md
+
+- Test Agent: Execute Plan {N}-03 (Tests for {feature})
+  Context: @.planning/phases/{N}-name/{N}-03-BLUEPRINT.md
+
+Rules:
+- Each agent commits atomically per task
+- Each agent creates their own RECORD.md
+- Coordinate on shared types/interfaces
+- Flag any dependency discoveries immediately
+"
+```
+
+---
+
+## Override Flags
+
+Users can override the automatic decision:
+
+```yaml
+optional_flags:
+  --swarm: "Force swarm mode regardless of analysis"
+  --sequential: "Force sequential mode regardless of analysis"
+  --subagent: "Force subagent mode (Task tool parallelism)"
+```
+
+---
+
+## Fallback Rules
+
+| Situation | Fallback |
+|-----------|----------|
+| Swarm mode not available (env var not set) | Fall back to Subagent mode |
+| Subagent hits permission error | Fall back to Sequential mode |
+| File overlap detected mid-execution | Pause, serialize remaining tasks |
+| Swarm agent fails | Retry as Subagent, then Sequential |
+
+---
+
+## Metrics Tracking
+
+Each execution records the mode used in RECORD.md:
+
+```yaml
+metrics:
+  execution_mode: swarm|subagent|sequential
+  mode_reason: "3+ independent plans with no file overlap"
+  agents_spawned: 3
+  parallel_efficiency: "42% faster than sequential estimate"
+```
+
+This data feeds into trend analysis for optimizing future mode decisions.

package/references/git-integration.md

@@ -0,0 +1,217 @@
+# Dominion Flow Git Integration Reference
+
+> **Origin:** Ported from Dominion Flow `git-integration.md` with full Git Flow branch strategy.
+
+## Core Principle
+
+**Commit outcomes, not process.** The git log should read like a changelog of what shipped, not a diary of planning activity.
+
+---
+
+## Git Flow Branch Strategy
+
+### Branch Types
+
+| Branch | Purpose | Created From | Merges Into | Lifetime |
+|--------|---------|-------------|-------------|----------|
+| `main` | Production-ready code | --- | --- | Permanent |
+| `develop` | Integration branch | `main` | `main` | Permanent |
+| `feature/phase-N-desc` | Per-phase feature work | `develop` | `develop` | Until phase complete |
+| `hotfix/description` | Emergency production fixes | `main` | `main` AND `develop` | Until fix deployed |
+| `release/vX.Y.Z` | Release preparation | `develop` | `main` AND `develop` | Until release shipped |
+
+### Branch Naming
+
+```
+feature/phase-01-foundation
+feature/phase-02-auth
+feature/phase-03-dashboard
+hotfix/fix-login-crash
+release/v1.0.0
+```
+
+### Branch Lifecycle
+
+**Starting a phase:**
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/phase-03-dashboard
+```
+
+**Completing a phase (after verification passes):**
+```bash
+git push -u origin feature/phase-03-dashboard
+gh pr create --base develop --head feature/phase-03-dashboard \
+  --title "Phase 03: Dashboard" --body "..."
+```
+
+**Hotfix workflow:**
+```bash
+git checkout main && git pull origin main
+git checkout -b hotfix/fix-login-crash
+# Make fix, commit, push
+gh pr create --base main --title "Hotfix: Login crash"
+# After merge to main, also merge to develop
+git checkout develop && git merge main && git push
+```
+
+---
+
+## Commit Points
+
+| Event | Commit? | Why |
+|-------|---------|-----|
+| PROJECT.md + ROADMAP created | YES | Project initialization |
+| BLUEPRINT.md created | NO | Intermediate |
+| RESEARCH.md created | NO | Intermediate |
+| **Task completed** | YES | Atomic unit of work |
+| **Plan completed** | YES | Metadata commit |
+| **Test written (TDD RED)** | YES | Atomic test commit |
+| **Test passing (TDD GREEN)** | YES | Atomic implementation |
+| Handoff created | YES | WIP state preserved |
+| **Blocker created/resolved** | YES | Track blocker state |
+
+---
+
+## Commit Formats
+
+### Project Initialization
+
+```
+docs: initialize [project-name] ([N] phases)
+
+[One-liner from PROJECT.md]
+
+Phases:
+1. [phase-name]: [goal]
+2. [phase-name]: [goal]
+
+Branch strategy: main -> develop -> feature/phase-N-*
+```
+
+### Task Completion (Per-Task Atomic Commits)
+
+```
+{type}({phase}-{plan}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+```
+
+**Types:** `feat`, `fix`, `test`, `refactor`, `perf`, `chore`, `docs`
+
+**Examples:**
+```bash
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08-02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Returns JWT token on success"
+
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07-02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour"
+```
+
+### Plan Completion
+
+```
+docs({phase}-{plan}): complete [plan-name]
+
+Tasks completed: [N]/[N]
+- [Task 1]
+- [Task 2]
+
+SUMMARY: .planning/phases/XX-name/{phase}-{plan}-RECORD.md
+```
+
+### Handoff (WIP)
+
+```
+wip: [phase-name] paused at task [X]/[Y]
+
+Current: [task name]
+Branch: feature/phase-XX-description
+Blockers: [count] open
+```
+
+---
+
+## PR Workflow
+
+### When to Create PRs
+
+| Event | PR Target | Required |
+|-------|-----------|----------|
+| Phase complete + verified | `develop` | Yes |
+| Hotfix ready | `main` | Yes |
+| Release ready | `main` | Yes |
+| Mid-phase handoff | None (push only) | No |
+
+### PR Template
+
+```bash
+gh pr create --base develop --title "Phase XX: Short description" --body "$(cat <<'EOF'
+## Summary
+- [Key deliverable 1]
+- [Key deliverable 2]
+
+## Test Results
+- Unit tests: X/X passing
+- Build: Clean
+
+## Verification
+- [x] Must-haves verified
+- [x] WARRIOR quality gates passed
+- [x] No P0/P1 blockers open
+EOF
+)"
+```
+
+---
+
+## Example Git Log
+
+```
+# Phase 03 - Products (feature/phase-03-products)
+3m4n5o docs(03-02): complete product listing plan
+6p7q8r feat(03-02): add pagination controls
+9s0t1u feat(03-02): implement search and filters
+2v3w4x feat(03-01): create product catalog schema
+
+# Phase 02 - Auth (feature/phase-02-auth)
+5y6z7a docs(02-02): complete token refresh plan
+8b9c0d feat(02-02): implement refresh token rotation
+1e2f3g test(02-02): add failing test for token refresh
+7k8l9m feat(02-01): add JWT generation and validation
+
+# Phase 01 - Foundation (feature/phase-01-foundation)
+6t7u8v feat(01-01): configure Tailwind and globals
+9w0x1y feat(01-01): set up Prisma with database
+2z3a4b feat(01-01): create Next.js 15 project
+
+# Initialization (develop)
+5c6d7e docs: initialize ecommerce-app (5 phases)
+```
+
+---
+
+## Why Per-Task Commits?
+
+- **AI context:** `git log --grep="{phase}-{plan}"` shows all work for a plan
+- **Failure recovery:** Can revert to last successful task
+- **Debugging:** `git bisect` finds exact failing task
+- **PR clarity:** Reviewers step through commits individually
+
+---
+
+## Anti-Patterns
+
+- Committing directly to main or develop (use feature branches)
+- Giant commits with all plan work (commit per task)
+- Committing planning artifacts separately (commit with plan completion)
+- Long-lived feature branches (one phase per branch)
+- Forgetting to merge hotfixes back to develop