@thierrynakoa/fire-flow 10.0.0 → 12.2.1

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

@@ -0,0 +1,143 @@
+---
+name: self-testing-feedback-loop
+category: methodology
+version: 1.0.0
+contributed: 2026-03-06
+contributor: dominion-flow
+last_updated: 2026-03-06
+contributors:
+  - dominion-flow
+tags: [circuit-breaker, testing, error-recovery, ai-agent, feedback-loop]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Self-Testing Feedback Loop for Circuit Breakers
+
+## Problem
+
+When AI agents hit errors during code generation, they typically rotate to a different approach — but never verify whether the rotation actually fixed anything before continuing. This creates "blind rotation" where the agent tries approach after approach without feedback, wasting context and iterations. The circuit breaker detects spinning (same error repeated), but the rotation itself has no verification step.
+
+Symptoms:
+- Agent rotates approaches but keeps hitting the same underlying error
+- Circuit breaker trips after 5 identical errors despite "different" approaches
+- Agent reports "trying a new approach" but the test output is identical
+- Iterations are wasted on approaches that look different but fail identically
+
+## Solution Pattern
+
+After every approach rotation triggered by the circuit breaker, enforce a **test-classify-feedback** cycle before continuing:
+
+1. **TEST** — Run the most specific available test (failing test > module test > full suite)
+2. **CLASSIFY** — Compare test result against the previous error hash
+3. **FEEDBACK** — Inject the classification back into the agent's context for the next iteration
+
+The classification has four outcomes:
+- **PASS** → Rotation worked. Clear warning state. Continue.
+- **NEW ERROR** → Different failure. That's progress. Feed new error into context.
+- **SAME ERROR** → Rotation didn't help. Double-increment spin counter (accelerate circuit break).
+- **NO TESTS** → Can't verify. Log warning, rely on file-change metrics only.
+
+The key insight: **double-incrementing the spin counter** when a rotation produces the same error. This accelerates the circuit break for approaches that look different but are functionally identical — preventing the agent from exhausting 5 rotation attempts on variations of the same broken strategy.
+
+## Code Example
+
+```
+// Before (problematic) — blind rotation
+ON circuit_breaker_warning:
+  rotation = suggest_new_approach(approaches_tried)
+  inject_into_context(rotation)
+  continue_execution()  // Hope for the best
+
+// After (solution) — verified rotation with feedback
+ON circuit_breaker_warning:
+  rotation = suggest_new_approach(approaches_tried)
+  inject_into_context(rotation)
+
+  // Execute one iteration with new approach
+  result = execute_iteration()
+
+  // TEST: Run most specific available test
+  test_result = run_tests(priority=[
+    specific_failing_test,    // Best: exact test that's failing
+    module_test_file,         // Good: tests for the modified module
+    full_suite_if_quick,      // OK: full suite if < 30 seconds
+  ])
+
+  // CLASSIFY: Compare against previous error
+  IF test_result.passed:
+    health = PROGRESS
+    spin_counter = 0          // Clear — rotation worked
+    record("Rotation successful: {approach}")
+
+  ELIF test_result.error_hash != previous_error_hash:
+    health = PROGRESS           // Different error = forward movement
+    spin_counter = 0
+    feed_new_error(test_result) // New error feeds into next iteration
+    record("New error after rotation: {new_hash}")
+
+  ELIF test_result.error_hash == previous_error_hash:
+    health = SPINNING
+    spin_counter += 2           // DOUBLE increment — rotation failed
+    record("Rotation ineffective: same error {hash}")
+
+  ELIF no_tests_available:
+    health = UNKNOWN
+    record("No tests — manual verification needed")
+
+  // FEEDBACK: Inject result into next iteration
+  inject_into_context(
+    "SELF-TEST after rotation: {test_result.status}
+     Diagnosis: {health}
+     Action: {recommended_next_step}"
+  )
+```
+
+## Implementation Steps
+
+1. Hook into the circuit breaker's approach rotation trigger
+2. After rotation, execute exactly ONE iteration before testing
+3. Run the most specific available test (don't waste time on full suite if a specific test exists)
+4. Hash-compare the new error against the previous error
+5. Classify as PASS / NEW_ERROR / SAME_ERROR / NO_TESTS
+6. If SAME_ERROR: double-increment the spin counter to accelerate circuit break
+7. Inject the test result and classification into the agent's context
+8. Record the classification in the loop tracking file
+
+## When to Use
+
+- Any AI agent system with a circuit breaker or loop detection
+- Code generation agents that run tests after changes
+- Autonomous debugging loops (test-diagnose-fix patterns)
+- Any system where "trying a different approach" needs verification
+- Long-running execution pipelines with error recovery
+
+## When NOT to Use
+
+- Projects with no test suite (the loop relies on test output)
+- Documentation-only changes (no testable code)
+- When the circuit breaker is already TRIPPED (we're stopping, not testing)
+- Interactive/manual debugging where the human provides feedback
+- Single-shot code generation (no iteration loop)
+
+## Common Mistakes
+
+- Running the full test suite when a specific failing test exists — wastes 10x the time
+- Not double-incrementing on SAME_ERROR — allows 5 useless rotations before breaking
+- Testing before the rotation is applied — tests the old approach, not the new one
+- Classifying "different line number, same error type" as progress — normalize error hashes first
+- Skipping the feedback injection — agent doesn't know its rotation failed
+
+## Related Skills
+
+- [TIERED_CONTEXT_ARCHITECTURE](../methodology/TIERED_CONTEXT_ARCHITECTURE.md) - Context management that preserves error state
+- [AGENT_SELF_IMPROVEMENT_LOOP](../methodology/AGENT_SELF_IMPROVEMENT_LOOP.md) - Broader agent improvement patterns
+- [DIFFICULTY_AWARE_AGENT_ROUTING](../methodology/DIFFICULTY_AWARE_AGENT_ROUTING.md) - Route by difficulty level
+
+## References
+
+- SWE-Agent + Reflexion "Test-Diagnose-Fix" loop (NeurIPS 2024) — 37% higher fix rates
+- Manus AI error preservation pattern (Feb 2026) — errors are most valuable context
+- frankbria's Ralph loop fork — quantitative convergence detection
+- Contributed from: dominion-flow v10.1 research session

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

@@ -0,0 +1,178 @@
+---
+name: STACK_COMPATIBILITY_MATRIX
+category: methodology
+description: Reference data for proven stack combinations, known incompatibilities, and project-type mapping
+version: 1.0.0
+tags: [architecture, stack, compatibility, vision]
+---
+
+# Stack Compatibility Matrix
+
+Reference data for the `fire-vision-architect` agent. Contains proven combinations, known conflicts, and project-type recommendations.
+
+---
+
+## Proven Stack Combinations
+
+### MERN (MongoDB + Express + React + Node.js)
+- **Best for:** Rapid prototyping, real-time apps, flexible-schema projects
+- **Industry:** Netflix, Uber (parts), Instagram (early)
+- **Auth pairing:** Passport.js, JWT custom, Auth0
+- **Hosting:** Heroku, Railway, DigitalOcean, AWS EC2
+- **DB extensions:** Redis (caching), Mongoose ODM
+- **Strengths:** Single language (JS) everywhere, huge npm ecosystem, fast iteration
+- **Weaknesses:** No ACID by default, schema discipline required, callback complexity
+
+### PERN (PostgreSQL + Express + React + Node.js)
+- **Best for:** Data-integrity-critical apps, financial, CRM, LMS
+- **Industry:** Many YC startups, internal tools
+- **Auth pairing:** Passport.js, JWT custom, better-auth
+- **Hosting:** Heroku, Railway, Render, AWS RDS + EC2
+- **DB extensions:** Prisma ORM, Drizzle ORM, pg-promise
+- **Strengths:** ACID compliance, complex queries, relational integrity, mature tooling
+- **Weaknesses:** Schema migrations needed, slightly slower prototyping than MongoDB
+
+### Next.js + Supabase
+- **Best for:** Solo devs, MVPs, startups wanting speed-to-market
+- **Industry:** cal.com, Resend, many indie SaaS
+- **Auth pairing:** Supabase Auth (built-in), NextAuth
+- **Hosting:** Vercel (native), Netlify, Cloudflare Pages
+- **DB extensions:** Supabase Realtime, Edge Functions, Row Level Security
+- **Strengths:** Fastest time-to-market, built-in auth/storage/realtime, generous free tier
+- **Weaknesses:** Vendor lock-in risk, limited custom backend logic, Supabase scaling costs
+
+### Next.js + PostgreSQL + Prisma
+- **Best for:** Full-stack teams wanting type safety and control
+- **Industry:** Vercel apps, many B2B SaaS
+- **Auth pairing:** NextAuth/Auth.js, better-auth, Clerk
+- **Hosting:** Vercel + Neon/Supabase DB, Railway
+- **DB extensions:** Prisma Studio, connection pooling (PgBouncer)
+- **Strengths:** Type-safe DB access, excellent DX, SSR/SSG flexibility, full control
+- **Weaknesses:** More setup than Supabase all-in-one, Prisma cold start in serverless
+
+### NestJS + PostgreSQL + Redis
+- **Best for:** Enterprise, microservices, teams > 5 developers
+- **Industry:** Enterprise Node.js projects, fintech
+- **Auth pairing:** Passport.js (NestJS module), custom JWT, Keycloak
+- **Hosting:** AWS ECS/EKS, GCP Cloud Run, DigitalOcean Kubernetes
+- **DB extensions:** TypeORM, MikroORM, Bull (job queues via Redis)
+- **Strengths:** Angular-like structure, dependency injection, microservice-ready, testable
+- **Weaknesses:** Steeper learning curve, more boilerplate, overkill for small projects
+
+### Django + PostgreSQL + React/Vue
+- **Best for:** Content-heavy apps, admin-intensive, rapid CRUD
+- **Industry:** Instagram (early), Pinterest, Eventbrite
+- **Auth pairing:** Django Auth (built-in), django-allauth
+- **Hosting:** Heroku, Railway, AWS Elastic Beanstalk, DigitalOcean
+- **DB extensions:** Django ORM, django-rest-framework, Celery (async tasks)
+- **Strengths:** Batteries-included, admin panel free, excellent ORM, security defaults
+- **Weaknesses:** Python + JS split, frontend integration friction, monolith tendency
+
+### Rails + PostgreSQL + Hotwire/React
+- **Best for:** Rapid development, startups, content platforms
+- **Industry:** GitHub, Shopify, Basecamp, Airbnb (early)
+- **Auth pairing:** Devise, OmniAuth
+- **Hosting:** Heroku, Render, Fly.io, Hatchbox
+- **DB extensions:** ActiveRecord, Sidekiq (background jobs), ActionCable (WebSockets)
+- **Strengths:** Convention over configuration, fastest scaffolding, mature ecosystem
+- **Weaknesses:** Ruby learning curve, performance ceiling, fewer JS devs know it
+
+### Remix + PostgreSQL + Prisma
+- **Best for:** Form-heavy apps, progressive enhancement, accessibility-first
+- **Industry:** Shopify (Hydrogen), newer startups
+- **Auth pairing:** Remix Auth, custom session-based
+- **Hosting:** Fly.io, Vercel, Cloudflare Workers
+- **Strengths:** Web standards first, nested routing, excellent forms, progressive enhancement
+- **Weaknesses:** Smaller ecosystem than Next.js, fewer tutorials, less community support
+
+### Astro + Headless CMS
+- **Best for:** Content sites, blogs, documentation, marketing
+- **Industry:** Content-focused startups, developer docs
+- **Auth pairing:** Usually not needed; if needed, Auth.js
+- **Hosting:** Vercel, Netlify, Cloudflare Pages
+- **CMS options:** Sanity, Contentful, Strapi, WordPress headless
+- **Strengths:** Zero JS by default, island architecture, fastest page loads
+- **Weaknesses:** Not for app-like interactivity, limited client-side state
+
+---
+
+## Known Incompatibilities
+
+### Database Conflicts
+| Combination | Problem | Resolution |
+|-------------|---------|------------|
+| MongoDB + PostgreSQL (both as primary) | Redundant primary DBs, split data model, double migration burden | Pick one based on data shape: relational → PostgreSQL, flexible → MongoDB |
+| Firebase Firestore + PostgreSQL | Two databases with different paradigms, sync nightmares | Use Firebase only for real-time features alongside PostgreSQL, or go all-in on one |
+| SQLite + production multi-user | SQLite has write-locking, not suitable for concurrent production use | SQLite for dev/embedded only; PostgreSQL or MySQL for production |
+
+### Frontend Conflicts
+| Combination | Problem | Resolution |
+|-------------|---------|------------|
+| React + Vue (same project) | Two virtual DOMs, double bundle size, conflicting state management | Pick one. React has larger ecosystem; Vue has simpler API |
+| React + jQuery | jQuery DOM manipulation conflicts with React's virtual DOM | Remove jQuery; use React refs for DOM access |
+| Next.js + Create React App | CRA is client-only; Next.js handles routing and SSR differently | Use Next.js alone (it supersedes CRA) |
+
+### Auth Conflicts
+| Combination | Problem | Resolution |
+|-------------|---------|------------|
+| Firebase Auth + Auth0 + custom JWT | Three auth systems = three user tables, token confusion | Pick one: Firebase Auth (free tier), Auth0 (enterprise), or custom (full control) |
+| Supabase Auth + NextAuth | Both manage sessions; double middleware, token conflicts | Use one: Supabase Auth if using Supabase DB, NextAuth if using custom DB |
+
+### Hosting Conflicts
+| Combination | Problem | Resolution |
+|-------------|---------|------------|
+| Serverless (Vercel/Netlify) + long-running processes | Serverless has execution time limits (10-60s), can't run background jobs | Use a separate worker service (Railway, Render background) or switch to container hosting |
+| Static hosting + server-side rendering | Static hosts (GitHub Pages, S3) can't run SSR | Use Vercel/Netlify/Cloudflare which support both, or go pure static |
+
+---
+
+## Project-Type → Stack Mapping
+
+### Simple Projects (≤3 features, 1 user role)
+| Type | Recommended Stack | Why |
+|------|------------------|-----|
+| Portfolio/Landing | Astro + Tailwind + Vercel | Zero JS, fast loads, cheap hosting |
+| Blog | Astro + Headless CMS + Vercel | Content-first, markdown support |
+| Todo/Notes | Next.js + Supabase | Quick CRUD with auth, free tier |
+
+### Standard Projects (4-10 features, multiple roles)
+| Type | Recommended Stack | Why |
+|------|------------------|-----|
+| SaaS | Next.js + PostgreSQL + Prisma + Vercel | Type safety, SSR, scalable |
+| E-commerce | Next.js + Supabase + Stripe | Built-in auth, real-time inventory |
+| LMS | PERN or Next.js + PostgreSQL | Relational data (courses→lessons→users) |
+| CRM | PERN + Redis | Complex queries, caching for dashboards |
+
+### Enterprise/Complex (10+ features, compliance, scale)
+| Type | Recommended Stack | Why |
+|------|------------------|-----|
+| Multi-tenant SaaS | NestJS + PostgreSQL + Redis + AWS | Row-level security, job queues, horizontal scale |
+| Real-time Collab | Next.js + Supabase Realtime or Socket.io | Built-in WebSocket support |
+| ML Pipeline | Django + PostgreSQL + Celery + Redis | Python ML ecosystem, async task processing |
+| Marketplace | NestJS + PostgreSQL + Stripe Connect + S3 | Complex payment splits, file storage |
+
+---
+
+## 2026 Industry Trends
+
+### Rising
+- **Supabase** — Replacing Firebase for new projects (open source, PostgreSQL-based)
+- **Drizzle ORM** — Lighter alternative to Prisma, better serverless performance
+- **better-auth** — Rising auth library for Node.js (simpler than NextAuth)
+- **Bun** — Faster Node.js alternative, gaining production adoption
+- **Cloudflare Workers** — Edge-first deployment for global latency
+- **Turso/LibSQL** — SQLite for production (embedded replicas, edge-ready)
+
+### Stable
+- **Next.js** — Dominant full-stack React framework
+- **PostgreSQL** — Default database for new projects
+- **Tailwind CSS** — Default styling approach
+- **Vercel/Railway** — Default hosting for Node.js apps
+- **Stripe** — Default payment processing
+
+### Declining
+- **Create React App** — Deprecated, replaced by Vite or Next.js
+- **Firebase (for new projects)** — Supabase taking market share
+- **Heroku (free tier)** — Gone; Railway/Render filling the gap
+- **Webpack (manual config)** — Vite/Turbopack replacing
+- **MongoDB (as default)** — PostgreSQL preferred unless schema flexibility is critical

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

@@ -0,0 +1,118 @@
+---
+name: tiered-context-architecture
+category: methodology
+version: 1.0.0
+contributed: 2026-03-06
+contributor: dominion-flow
+last_updated: 2026-03-06
+contributors:
+  - dominion-flow
+tags: [context-management, ai-agent, llm, token-optimization, memory-tiers]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Tiered Context Architecture (Hot/Warm/Cold)
+
+## Problem
+
+AI agents working on long-running tasks fill their context window with a mix of critical and stale information. Without explicit categorization, all context is treated equally — leading to premature context exhaustion, irrelevant information competing with critical state, and poor compaction decisions that drop important details while preserving noise.
+
+Symptoms:
+- Agent "forgets" current task details while retaining old file contents
+- Context compaction drops error messages but keeps completed task descriptions
+- Agent hits context limits mid-task with no clear eviction strategy
+- Output quality degrades because reasoning competes with stale data
+
+## Solution Pattern
+
+Categorize every context segment into three tiers based on access recency and task relevance, then apply tier-specific retention policies:
+
+**HOT** (never compress, ~15% budget): Current task, active errors, recitation block, circuit breaker state, failed approaches list. This is the "working memory" — losing any of it causes immediate task failure.
+
+**WARM** (compressible, ~45% budget): Plan context, loaded skills, recently-read files, recent decisions, episodic recall. Useful for current phase but can be compressed to key points when space is needed.
+
+**COLD** (evictable, 0% budget in window): Files read 5+ iterations ago, completed task details, resolved errors, unused skills. Saved to disk, retrievable on demand, but not occupying context window.
+
+The key insight: tier assignment is **dynamic** — segments promote (COLD→WARM when re-referenced) and demote (HOT→WARM when task changes) based on actual usage patterns, not static rules.
+
+## Code Example
+
+```
+// Before (problematic) — flat context, no tiers
+context = [
+  system_prompt,          // critical
+  file_read_10_turns_ago, // stale — wastes space
+  current_task,           // critical
+  old_error_resolved,     // stale — wastes space
+  active_error,           // critical
+  completed_task_1,       // stale
+  completed_task_2,       // stale
+  skill_never_used,       // stale
+]
+// Result: 60% of context is stale. Compaction randomly drops items.
+
+// After (solution) — tiered context with explicit budgets
+HOT = [current_task, active_error, recitation, circuit_breaker, failed_approaches]
+WARM = [plan_context, loaded_skills, recent_files, decisions]
+COLD = [] // evicted to disk: old_files, completed_tasks, resolved_errors
+
+// Budget enforcement:
+IF hot_tokens > 30K: ERROR — hot tier should never exceed budget
+IF warm_tokens > 90K: compress WARM to 50% (keep key points)
+IF total > 70%: evict all COLD, compress WARM to 30%
+IF total > 85%: keep only HOT, trigger handoff
+
+// Dynamic tier transitions:
+IF segment.last_accessed > 5 iterations: demote to COLD
+IF cold_segment.referenced_by_current_task: promote to WARM
+IF warm_segment.is_active_error: promote to HOT
+IF hot_segment.error_resolved: demote to WARM → COLD
+```
+
+## Implementation Steps
+
+1. Define tier assignment function based on segment type and recency
+2. Set token budgets per tier (15% HOT, 45% WARM, 0% COLD)
+3. Tag each context segment with its tier on creation/injection
+4. Run tier reassignment every 3 iterations (not every iteration — overhead)
+5. When context exceeds 70%, compress WARM tier first, then evict COLD
+6. Preserve HOT tier unconditionally — never compress or evict
+7. Log tier transitions for debugging context management issues
+
+## When to Use
+
+- Any AI agent system with long-running tasks (10+ iterations)
+- Multi-phase execution pipelines where old phase context becomes stale
+- Agents that read many files but only work on a few at a time
+- Systems where context compaction causes "amnesia" of critical state
+- When you need to extend useful context life before forced handoff
+
+## When NOT to Use
+
+- Short conversations (< 5 turns) — overhead isn't worth it
+- Single-file edits with no accumulated context
+- Systems with unlimited context windows (if such a thing existed)
+- When all context segments are equally critical (rare but possible)
+
+## Common Mistakes
+
+- Setting HOT budget too large — defeats the purpose of tiering. HOT should be < 20% of window
+- Never demoting segments — HOT tier grows unbounded if old errors aren't demoted after resolution
+- Compressing HOT tier during context pressure — this causes immediate task failure
+- Evicting COLD without saving to disk — you lose the ability to retrieve if needed later
+- Running tier reassignment every iteration — the overhead reduces net context benefit
+
+## Related Skills
+
+- [RESEARCH_BACKED_WORKFLOW_UPGRADE](../methodology/RESEARCH_BACKED_WORKFLOW_UPGRADE.md) - Research methodology that discovered this pattern
+- [AGENT_SELF_IMPROVEMENT_LOOP](../methodology/AGENT_SELF_IMPROVEMENT_LOOP.md) - Agent improvement patterns
+
+## References
+
+- Spotify "Honk" Architecture (2024) — tiered context management reduces failures by 40%
+- ACON "Active Context Compression" (2025-2026) — 26-54% token reduction via selective compression
+- PAACE "Plan-Aware Agent Context Engineering" (2025) — plan-aware preservation during compression
+- Focus (ACL 2025) — active forgetting for proactive context management
+- Contributed from: dominion-flow v10.1 research session