@thierrynakoa/fire-flow 10.0.0

package/references/research-improvements.md

@@ -0,0 +1,110 @@
+# Research-Backed Improvements Reference
+
+> Dominion Flow v3.2 — Research sources, gap analysis findings, and implementation mapping
+>
+> Every v3.2 enhancement cites a tag from this document (e.g., `GAP-1`, `RECITATION-1`).
+> Use this file to trace any inline comment back to its research basis.
+
+---
+
+## Research Sources (2024–2026)
+
+### Academic Papers
+
+| ID | Paper | Key Finding | Applied In |
+|----|-------|-------------|------------|
+| PLAN-DEBUG-1 | MapCoder (ACL 2024) — "Multi-Agent Code Generation through Planning" | Achieved 93.9% pass@1 by feeding the Debugging Agent the original plan alongside buggy code. Plan-derived debugging significantly outperforms debugging without plan context because the agent can compare "what was intended" vs "what happened." | `/fire-debug` Step 4: `<plan_context>` block |
+| RECITATION-1 | Manus AI — Context Engineering (2025) | Without task recitation, agents drift off-topic after ~50 tool calls. Rewriting a compressed todo at the end of context keeps the current plan in the model's recent attention span, preventing the "lost-in-the-middle" problem (transformer attention bias toward recent tokens). | `/fire-loop` Step 7 rule 6, iteration context injection |
+| OBSERVE-1 | Mastra — Observational Memory (2025) | Two-agent (Observer/Reflector) compression achieves 5-40x compression with 10x cost reduction over RAG. Observer extracts key facts; Reflector synthesizes patterns. | Future: Tier 2 enhancement |
+| JUDGE-1 | Mason (2026) — "Judge Agent Separation" | Dedicated Judge agent that only evaluates (never generates) prevents self-evaluation bias. Separating generation from evaluation improves quality scoring accuracy. | Future: Tier 3 enhancement |
+| SWE-1 | SWE-Bench Pro (2025) | Single agent + retries outperforms multi-agent swarms for most routine tasks. Multi-agent overhead only justified for genuinely parallel work. | Informs execution mode intelligence (SWARM threshold) |
+| METR-1 | METR Study (2025) — "AI Impact on Developer Productivity" | AI can slow experienced devs 19% on familiar code. AI excels at exploration and unfamiliar codebases, not well-known code. | Informs when to apply AI vs manual work |
+| RLCR-1 | MIT RLCR (2025) — "Confidence-Based Escalation" | Route low-confidence items to human review instead of auto-deciding. Confidence thresholds improve decision quality across automated workflows. | Future: Tier 2 enhancement |
+
+### Community Patterns
+
+| ID | Source | Pattern | Applied In |
+|----|--------|---------|------------|
+| CNCF-1 | CNCF Four Pillars (2025) | Golden Paths, Guardrails, Safety Nets, Manual Review — taxonomy for organizing validation checklists by enforcement level. | Future: restructure 70-point checklist |
+| BOLT-1 | Bolt.new — .powerignore (2025) | File-level exclusion patterns prevent context pollution from generated files, node_modules, etc. | v3.0: `.powerignore` in context engineering |
+| RALPH-1 | Ralph Wiggum Loops — Circuit Breaker Fork | Stall/spin/degradation detection with automatic recovery. Prevents infinite loops and wasted iterations. | v3.0: Circuit Breaker system |
+| REPLIT-1 | Replit Agent — Decision-Time Guidance (2025) | Micro-inject relevant skills at the moment of decision rather than front-loading all knowledge. Reduces context bloat while maintaining quality. | v3.0: DTG system |
+
+---
+
+## Gap Analysis Findings
+
+> Internal analysis of Dominion Flow v3.1 identified these gaps.
+> Each gap has a severity, the v3.2 fix applied, and the file modified.
+
+### GAP Series (Structural Gaps)
+
+| ID | Gap Description | Severity | v3.2 Fix | File Modified |
+|----|----------------|----------|----------|---------------|
+| GAP-1 | No explicit decision log — architectural decisions scattered across handoffs and CONSCIENCE.md with no central tracking | HIGH | Created `DECISION_LOG.md` template with DEC-XXX format, cross-phase impact tracking, and integration points | `templates/DECISION_LOG.md` (new) |
+| GAP-2 | Assumptions accumulate across phases without systematic tracking — Phase 6 can contradict Phase 1 assumptions | HIGH | Enhanced `ASSUMPTIONS.md` with cross-phase contradiction detection, phase-gate validation protocol | `templates/ASSUMPTIONS.md` |
+| GAP-3 | No cross-phase contradiction detection for decisions | MEDIUM | Decision Log includes "Affected Phases" and cross-phase validation protocol | `templates/DECISION_LOG.md` |
+| GAP-4 | Deferred items multiply without compound impact tracking | MEDIUM | Added deferred-item impact analysis template (DEFERRED-XXX format) to Assumptions | `templates/ASSUMPTIONS.md` |
+| GAP-5 | Handoff completeness not validated — broken context chains if any session skips proper handoff | HIGH | Added 17-point automated validation checklist as Step 5 in handoff command | `commands/fire-5-handoff.md` |
+| GAP-6 | Task recitation missing — agents drift after many iterations in fire-loop | HIGH | Added recitation pattern to iteration context injection with compressed todo rewrite | `commands/fire-loop.md` |
+| GAP-7 | Debug loops lack plan context — debugger can't compare intended vs actual behavior | MEDIUM | Added `<plan_context>` block to debugger spawn and continuation prompts | `commands/fire-debug.md` |
+| GAP-8 | CONSCIENCE.md doesn't reference Decision Log | LOW | Added Decision Log reference and Assumptions Health section to state template | `templates/state.md` |
+| GAP-9 | Handoff success criteria don't include Decision Log or Assumptions sync | LOW | Added 3 new items to handoff success criteria | `commands/fire-5-handoff.md` |
+| GAP-10 | No executable handoff validation — relies on manual review | HIGH | 17-point checklist with structural, content, and cross-reference checks | `commands/fire-5-handoff.md` |
+
+### BLIND-SPOT Series (Discovered During Analysis)
+
+| ID | Blind Spot | Impact | v3.2 Fix |
+|----|-----------|--------|----------|
+| BLIND-SPOT-A | Decisions made in one phase can silently conflict with decisions from earlier phases | Cross-phase bugs, wasted work | Decision Log cross-phase validation protocol |
+| BLIND-SPOT-B | Unvalidated assumptions from early phases relied upon in later phases without re-check | Architecture built on unverified foundations | Phase-gate validation: mandatory assumption audit at phase start |
+| BLIND-SPOT-C | Context drift in long fire-loop runs leads to repeated mistakes and circular attempts | Wasted iterations, degraded solutions | Task recitation pattern forces model to re-read compressed state |
+| BLIND-SPOT-D | Handoff chain breaks permanently if one session skips proper handoff | Complete context loss, restart required | Automated completeness validation prevents saving incomplete handoffs |
+
+---
+
+## Implementation Mapping
+
+### Tier 1 — Implemented in v3.2.0
+
+| Enhancement | Research Basis | Files Changed |
+|-------------|---------------|---------------|
+| Decision Log template | GAP-1, GAP-3, BLIND-SPOT-A | `templates/DECISION_LOG.md` (new) |
+| Assumptions Registry enhancement | GAP-2, GAP-4, BLIND-SPOT-B | `templates/ASSUMPTIONS.md` |
+| CONSCIENCE.md Decision/Assumptions references | GAP-8 | `templates/state.md` |
+| Handoff Completeness Validator | GAP-5, GAP-9, GAP-10, BLIND-SPOT-D | `commands/fire-5-handoff.md` |
+| Task Recitation Pattern | RECITATION-1, GAP-6, BLIND-SPOT-C | `commands/fire-loop.md` |
+| Plan-Aware Debugging | PLAN-DEBUG-1, GAP-7 | `commands/fire-debug.md` |
+| Plugin version bump + this doc | — | `plugin.json`, `references/research-improvements.md` |
+
+### Tier 2 — Planned for v3.3.0
+
+| Enhancement | Research Basis | Target |
+|-------------|---------------|--------|
+| Observational Memory (Observer/Reflector agents) | OBSERVE-1 | Handoff compression, cross-session learning |
+| Confidence-Based Escalation | RLCR-1 | Route uncertain decisions to user during execution |
+| CNCF Four Pillars restructure | CNCF-1 | Reorganize 70-point checklist by enforcement level |
+| METR-aware task routing | METR-1 | Route AI to exploration tasks, manual for familiar code |
+
+### Tier 3 — Planned for v3.4.0
+
+| Enhancement | Research Basis | Target |
+|-------------|---------------|--------|
+| Judge Agent separation | JUDGE-1 | Dedicated evaluation agent for verification |
+| SWE-Bench calibrated execution modes | SWE-1 | Better SWARM vs SEQUENTIAL thresholds |
+| Skills Library auto-pruning | Community patterns | Remove unused skills, version popular ones |
+
+---
+
+## Version History
+
+| Version | Date | Key Additions |
+|---------|------|---------------|
+| v3.0.0 | 2026-02-09 | Dominion Flow consolidation, Circuit Breaker, Error Classification, Context Engineering, DTG |
+| v3.1.0 | 2026-02-10 | Playwright E2E testing (Step 8), 70-point validation, visual regression |
+| v3.2.0 | 2026-02-10 | Research-backed: Task Recitation, Plan-Aware Debug, Decision Log, Assumptions enhancement, Handoff Validator, Code Comments Standard |
+
+---
+
+*Created: 2026-02-10*
+*Source: 4-agent parallel research sweep (15 papers + 15 community patterns + 10 testing findings + 10 internal gaps)*

package/references/skills-usage-guide.md

@@ -0,0 +1,429 @@
+# Skills Usage Guide
+
+> How agents discover, use, and contribute to the skills library
+
+---
+
+## Overview
+
+The skills library is a curated collection of implementation patterns, methodologies, and domain knowledge. Agents reference skills during planning and execution to ensure consistent, high-quality implementations.
+
+---
+
+## Searching the Skills Library
+
+### Using /fire-search
+
+The primary way to find relevant skills:
+
+```
+/fire-search authentication JWT tokens
+```
+
+**Search Behavior:**
+1. Searches skill titles and descriptions
+2. Searches skill content for keywords
+3. Returns ranked results by relevance
+4. Shows skill category and file path
+
+**Example Output:**
+```
+━━━ DOMINION FLOW > SKILL SEARCH ━━━
+
+Query: "authentication JWT tokens"
+
+Results (3 matches):
+
+1. [HIGH] authentication/jwt-implementation.md
+   JWT token generation, validation, and refresh patterns
+   Category: security
+
+2. [MED] authentication/session-management.md
+   Session handling with various token strategies
+   Category: security
+
+3. [LOW] api-design/protected-routes.md
+   Securing API routes with middleware
+   Category: api-design
+
+Use: Read skill with /fire-skill authentication/jwt-implementation
+```
+
+### Search Tips
+
+| Goal | Search Query |
+|------|-------------|
+| Find implementation patterns | `"pattern" + domain` (e.g., "pattern repository") |
+| Find security guidance | `"security" + topic` (e.g., "security file upload") |
+| Find database patterns | `"database" + operation` (e.g., "database migration") |
+| Find testing approaches | `"test" + type` (e.g., "test integration API") |
+
+### Browsing by Category
+
+Skills are organized into categories:
+
+```
+skills-library/
+├── methodology/           # Development processes
+├── complexity-metrics/    # Effort estimation
+├── ecommerce/            # E-commerce patterns
+├── integrations/         # Third-party integrations
+├── video-media/          # Media processing
+├── deployment-security/  # DevOps and security
+├── database-solutions/   # Database patterns
+├── form-solutions/       # Form handling
+├── advanced-features/    # Complex implementations
+├── automation/           # CI/CD, scripting
+├── document-processing/  # File handling
+└── patterns-standards/   # General patterns
+```
+
+---
+
+## Referencing Skills in Plans
+
+### BLUEPRINT.md Frontmatter
+
+When creating execution plans, reference relevant skills:
+
+```yaml
+---
+phase: 3
+task: "Implement user authentication"
+skills_referenced:
+  - authentication/jwt-implementation.md
+  - database-solutions/user-schema.md
+  - testing/auth-test-patterns.md
+complexity: medium
+estimated_breaths: 3
+---
+```
+
+### Skill Citation in Plan Body
+
+Reference skills when describing implementation approach:
+
+```markdown
+## Implementation Approach
+
+Following the JWT implementation pattern from `authentication/jwt-implementation.md`:
+
+1. **Token Generation** (per skill section 2.1)
+   - Use RS256 algorithm for production
+   - Include standard claims (iss, sub, exp, iat)
+   - Add custom claims for user roles
+
+2. **Token Validation** (per skill section 2.2)
+   - Validate signature before claims
+   - Check expiration with clock skew tolerance
+   - Verify issuer matches expected value
+```
+
+### Inline References
+
+During implementation details:
+
+```markdown
+### Database Schema
+
+Per `database-solutions/user-schema.md`:
+- Use UUID for primary keys
+- Include audit timestamps
+- Soft delete with deletedAt column
+
+### Password Handling
+
+Per `security/password-hashing.md`:
+- Use bcrypt with cost factor 12
+- Never store plaintext
+- Implement password strength validation
+```
+
+---
+
+## Citing Skills in RECORD.md
+
+### Skills Used Section
+
+Always document which skills informed the implementation:
+
+```markdown
+## Skills Referenced
+
+| Skill | Usage | Sections Used |
+|-------|-------|---------------|
+| `authentication/jwt-implementation.md` | Token generation and validation | 2.1, 2.2, 3.1 |
+| `database-solutions/user-schema.md` | User table design | Full |
+| `testing/auth-test-patterns.md` | Test structure | 1.1, 2.3 |
+
+### Deviations from Skills
+
+1. **JWT Algorithm**: Used HS256 instead of RS256
+   - Reason: Simpler key management for MVP
+   - Trade-off: Less suitable for distributed systems
+   - Future: Migrate to RS256 when scaling
+```
+
+### Knowledge Gaps Identified
+
+Document when skills were missing:
+
+```markdown
+## Skills Gaps Identified
+
+The following patterns would benefit from skills documentation:
+
+1. **Rate Limiting with Redis**
+   - Needed: Distributed rate limiting patterns
+   - Currently: Implemented from scratch
+   - Recommendation: Create `security/rate-limiting-redis.md`
+
+2. **GraphQL Subscriptions**
+   - Needed: WebSocket management patterns
+   - Currently: Following Apollo docs only
+   - Recommendation: Create `api-design/graphql-subscriptions.md`
+```
+
+---
+
+## Contributing New Skills
+
+### Using /fire-contribute
+
+When you've implemented a pattern worth documenting:
+
+```
+/fire-contribute "Redis Rate Limiting Pattern"
+```
+
+**Contribution Flow:**
+1. Describe the pattern you implemented
+2. Answer classification questions
+3. Review generated skill draft
+4. Submit for library addition
+
+### Skill Document Structure
+
+```markdown
+# [Skill Title]
+
+> One-line description of what this skill covers
+
+---
+
+## Overview
+
+Brief explanation of when to use this pattern and why.
+
+## Prerequisites
+
+- Required knowledge
+- Dependencies
+- Environment setup
+
+## Implementation
+
+### Step 1: [First Step]
+
+Detailed instructions with code examples.
+
+```typescript
+// Example code
+```
+
+### Step 2: [Second Step]
+
+Continue with clear, actionable steps.
+
+## Variations
+
+### Variation A: [Name]
+
+When to use this variation and how it differs.
+
+### Variation B: [Name]
+
+Alternative approach for different requirements.
+
+## Testing
+
+How to verify the implementation works.
+
+## Common Pitfalls
+
+1. **Pitfall Name**: What goes wrong and how to avoid it
+2. **Another Pitfall**: Description and prevention
+
+## References
+
+- External documentation links
+- Related skills in the library
+
+---
+
+*Last updated: [Date] | Contributor: [Name/Agent]*
+```
+
+### Contribution Guidelines
+
+1. **Be Specific**: Generic advice isn't helpful
+2. **Include Code**: Show, don't just tell
+3. **Test Your Pattern**: Only document what works
+4. **Note Limitations**: Be honest about trade-offs
+5. **Update Existing**: Improve skills rather than duplicating
+
+---
+
+## Syncing with Global Library
+
+### Check for Updates
+
+```
+/fire-sync check
+```
+
+**Output:**
+```
+━━━ DOMINION FLOW > SKILL SYNC CHECK ━━━
+
+Local Library: v2.3.1
+Global Library: v2.4.0
+
+Updates Available:
+  + NEW: api-design/graphql-subscriptions.md
+  ~ UPD: authentication/jwt-implementation.md (security patch)
+  ~ UPD: database-solutions/migration-patterns.md (new examples)
+
+Run /fire-sync pull to update
+```
+
+### Pull Updates
+
+```
+/fire-sync pull
+```
+
+**Behavior:**
+1. Downloads new/updated skills
+2. Preserves local modifications
+3. Shows changelog for updates
+4. Reports conflicts if any
+
+### Push Contributions
+
+```
+/fire-sync push authentication/custom-sso.md
+```
+
+**Behavior:**
+1. Validates skill format
+2. Runs quality checks
+3. Submits to global library
+4. Tracks contribution credit
+
+---
+
+## Skill Discovery During Execution
+
+### Automatic Suggestions
+
+During planning, Dominion Flow may suggest relevant skills:
+
+```
+━━━ DOMINION FLOW > PLANNING ━━━
+
+Analyzing task: "Add payment processing"
+
+Suggested Skills:
+  ├─ ecommerce/payment-integration.md
+  │   └─ Stripe, PayPal integration patterns
+  ├─ security/pci-compliance.md
+  │   └─ Payment data handling requirements
+  └─ testing/payment-mocking.md
+      └─ How to test without real transactions
+
+Review skills before proceeding? (y/n)
+```
+
+### Skill Quick Reference
+
+During execution, quickly check a skill:
+
+```
+/fire-skill-quick authentication/jwt-implementation 2.1
+```
+
+**Output:**
+```
+━━━ JWT Implementation - Section 2.1 ━━━
+
+Token Generation:
+
+```typescript
+import jwt from 'jsonwebtoken';
+
+const generateToken = (user: User): string => {
+  return jwt.sign(
+    {
+      sub: user.id,
+      email: user.email,
+      roles: user.roles,
+    },
+    process.env.JWT_SECRET,
+    {
+      algorithm: 'RS256',
+      expiresIn: '15m',
+      issuer: 'your-app-name',
+    }
+  );
+};
+```
+
+Key Points:
+- Use short expiration (15m) with refresh tokens
+- Include minimal claims (reduce token size)
+- Always set issuer for validation
+```
+
+---
+
+## Best Practices
+
+### When to Search for Skills
+
+1. **Before starting any new feature** - Check if patterns exist
+2. **When encountering unfamiliar territory** - Learn from documented experience
+3. **Before implementing security features** - Always use vetted patterns
+4. **When estimating complexity** - Skills help gauge effort
+
+### When to Create New Skills
+
+1. **After implementing something novel** - Share the knowledge
+2. **When you spent significant time researching** - Save others the effort
+3. **When you found a better way** - Improve on existing patterns
+4. **When you hit undocumented pitfalls** - Prevent others from same mistakes
+
+### Skill Maintenance
+
+1. **Update when patterns evolve** - Keep skills current
+2. **Add examples from real implementations** - Concrete beats abstract
+3. **Note deprecated approaches** - Warn about outdated patterns
+4. **Cross-reference related skills** - Build a connected knowledge base
+
+---
+
+## Quick Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/fire-search <query>` | Find relevant skills |
+| `/fire-skill <path>` | Read full skill document |
+| `/fire-skill-quick <path> <section>` | Read specific section |
+| `/fire-contribute <title>` | Start new skill contribution |
+| `/fire-sync check` | Check for library updates |
+| `/fire-sync pull` | Download library updates |
+| `/fire-sync push <path>` | Submit skill contribution |
+
+---
+
+*The skills library grows with every implementation. Contribute what you learn.*

package/references/tdd.md

@@ -0,0 +1,131 @@
+# Dominion Flow TDD Reference
+
+> **Origin:** Ported from Dominion Flow `tdd.md` with Dominion Flow Git Flow integration.
+
+## Overview
+
+Test-Driven Development in Dominion Flow. Plans with `type: tdd` in frontmatter follow the Red-Green-Refactor cycle with atomic commits at each stage.
+
+---
+
+## When to Use TDD Plans
+
+- Pure functions, utilities, validators, formatters
+- API endpoints with clear input/output contracts
+- Business logic with defined rules
+- Data transformations
+
+## When NOT to Use TDD Plans
+
+- UI components (test after build with checkpoint:human-verify)
+- Configuration/setup tasks
+- Database migrations (test with integration tests)
+- One-off scripts
+
+---
+
+## TDD Plan Frontmatter
+
+```yaml
+---
+phase: XX-name
+plan: NN
+type: tdd
+feature: "[Single feature being tested]"
+test_framework: jest|vitest|pytest|go-test
+---
+```
+
+**One feature per TDD plan.** If features are trivial enough to batch, skip TDD.
+
+---
+
+## Red-Green-Refactor Cycle
+
+### RED - Write failing test
+
+1. Ensure correct feature branch: `feature/phase-XX-description`
+2. Create test file following project conventions
+3. Write test describing expected behavior
+4. Run test - MUST fail
+5. If test passes: feature already exists or test is wrong
+6. Commit: `test({phase}-{plan}): add failing test for [feature]`
+
+### GREEN - Implement to pass
+
+1. Write minimal code to make test pass
+2. No cleverness, no optimization - just make it work
+3. Run test - MUST pass
+4. If not passing, iterate. Do not move to REFACTOR.
+5. Commit: `feat({phase}-{plan}): implement [feature]`
+
+### REFACTOR (if needed)
+
+1. Clean up if obvious improvements exist
+2. Run tests - MUST still pass
+3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
+
+**Result:** 2-3 atomic commits on the feature branch per TDD plan.
+
+---
+
+## Test Quality Standards
+
+- **Test behavior, not implementation** - tests should survive refactors
+- **One concept per test** - separate tests for valid, empty, malformed input
+- **Descriptive names** - "should reject empty email" not "test1"
+- **No implementation details** - test public API, observable behavior
+- **Meaningful assertions** - NEVER `expect(true).toBe(true)`
+- **Cover happy + error paths** - at minimum one of each
+
+---
+
+## Test Types
+
+| Type | When | Speed | Example |
+|------|------|-------|---------|
+| Unit | Pure functions, utilities | Milliseconds | `validateEmail('bad') === false` |
+| Integration | API routes, DB operations | Seconds | `POST /api/register -> 201` |
+| E2E | Complete user journeys | Seconds-minutes | Playwright checkout flow |
+
+---
+
+## Branch Integration
+
+TDD work follows Git Flow:
+
+1. Ensure feature branch: `git checkout -b feature/phase-XX-desc develop`
+2. RED commit on feature branch
+3. GREEN commit on feature branch
+4. REFACTOR commit on feature branch
+5. Create PR from feature to develop
+6. Merge after review. Never directly to main.
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Test doesn't fail in RED | Feature may exist. Investigate before proceeding. |
+| Test doesn't pass in GREEN | Keep iterating. Don't skip to REFACTOR. |
+| Tests fail in REFACTOR | Undo refactor immediately. Smaller steps. |
+| Unrelated tests break | Stop. Investigate coupling. Create P1 blocker if needed. |
+| Stuck after 3 GREEN attempts | Create P1 blocker in BLOCKERS.md. |
+
+---
+
+## Commit Pattern
+
+```
+test(08-02): add failing test for email validation
+- Tests valid email formats accepted
+- Tests invalid formats rejected
+
+feat(08-02): implement email validation
+- Regex pattern matches RFC 5322
+- Returns boolean for validity
+
+refactor(08-02): extract regex to constant (optional)
+- No behavior changes, tests still pass
+```