@thierrynakoa/fire-flow 10.0.0

package/skills-library/common-tasks/file-upload-basics.md

@@ -0,0 +1,166 @@
+# Skill: File Upload Basics
+
+**Category:** Common Tasks
+**Difficulty:** Beginner–Intermediate
+**Applies to:** Node.js/Express
+
+---
+
+## The Problem
+
+File uploads are one of the easiest ways to get hacked if handled carelessly. Users can upload scripts, oversized files, or files with misleading extensions. Done right, uploads are simple and safe.
+
+---
+
+## Setup
+
+```bash
+npm install multer
+```
+
+---
+
+## Pattern 1: Upload to Local Disk (Development)
+
+```js
+const multer = require('multer');
+const path = require('path');
+
+// Configure storage
+const storage = multer.diskStorage({
+  destination: (req, file, cb) => {
+    cb(null, 'uploads/'); // folder must exist
+  },
+  filename: (req, file, cb) => {
+    // Use timestamp + random to avoid name collisions
+    const unique = Date.now() + '-' + Math.round(Math.random() * 1e9);
+    cb(null, unique + path.extname(file.originalname));
+  }
+});
+
+// Configure filters
+const fileFilter = (req, file, cb) => {
+  const allowed = ['image/jpeg', 'image/png', 'image/webp'];
+  if (allowed.includes(file.mimetype)) {
+    cb(null, true);  // accept
+  } else {
+    cb(new Error('Only JPG, PNG, and WebP images allowed'), false); // reject
+  }
+};
+
+const upload = multer({
+  storage,
+  fileFilter,
+  limits: { fileSize: 5 * 1024 * 1024 } // 5MB max
+});
+```
+
+---
+
+## Pattern 2: Single File Upload Route
+
+```js
+// Single file upload — field name must match the form field
+router.post('/upload/avatar', upload.single('avatar'), (req, res) => {
+  if (!req.file) {
+    return res.status(400).json({ error: 'No file uploaded' });
+  }
+
+  const fileUrl = `/uploads/${req.file.filename}`;
+  res.json({ url: fileUrl, filename: req.file.filename });
+});
+
+// Handle multer errors
+router.use((err, req, res, next) => {
+  if (err instanceof multer.MulterError) {
+    if (err.code === 'LIMIT_FILE_SIZE')
+      return res.status(400).json({ error: 'File too large. Maximum 5MB.' });
+    return res.status(400).json({ error: err.message });
+  }
+  if (err) return res.status(400).json({ error: err.message });
+  next();
+});
+```
+
+---
+
+## Pattern 3: Frontend — Sending a File
+
+```html
+<form id="upload-form" enctype="multipart/form-data">
+  <input type="file" id="avatar" name="avatar" accept="image/*" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+```js
+document.getElementById('upload-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+
+  const fileInput = document.getElementById('avatar');
+  if (!fileInput.files[0]) return alert('Please select a file');
+
+  // Client-side size check (convenience only — server also checks)
+  if (fileInput.files[0].size > 5 * 1024 * 1024) {
+    return alert('File must be under 5MB');
+  }
+
+  const formData = new FormData();
+  formData.append('avatar', fileInput.files[0]);
+
+  const res = await fetch('/api/upload/avatar', {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${localStorage.getItem('token')}` },
+    body: formData // Do NOT set Content-Type manually — browser sets it with boundary
+  });
+
+  const data = await res.json();
+  if (res.ok) {
+    document.getElementById('preview').src = data.url;
+  } else {
+    alert(data.error);
+  }
+});
+```
+
+---
+
+## Serve Uploaded Files
+
+```js
+// In app.js — make uploads folder publicly accessible
+app.use('/uploads', express.static('uploads'));
+```
+
+---
+
+## For Production: Use Cloud Storage
+
+Local disk doesn't work when you have multiple servers or restart loses files. Use cloud storage instead:
+
+| Service | Free Tier | Best For |
+|---------|-----------|---------|
+| Cloudinary | 25GB | Images with auto-resizing |
+| AWS S3 | 5GB/month | Any file type |
+| Supabase Storage | 1GB | Projects already on Supabase |
+
+With Cloudinary (simplest for images):
+```bash
+npm install cloudinary multer-storage-cloudinary
+```
+
+---
+
+## Security Checklist
+
+| Check | Why |
+|-------|-----|
+| Validate MIME type server-side | Extensions can be faked |
+| Set file size limit | Prevents server overload |
+| Store outside web root (or in cloud) | Prevents direct script execution |
+| Rename uploaded files | Prevents overwriting existing files |
+| Require authentication for uploads | Prevents anonymous abuse |
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/common-tasks/form-validation.md

@@ -0,0 +1,159 @@
+# Skill: Form Validation
+
+**Category:** Common Tasks
+**Difficulty:** Beginner
+**Applies to:** Any full-stack project
+
+---
+
+## The Rule
+
+**Always validate on the server. Frontend validation is convenience, not security.**
+
+A user can bypass any frontend check by using curl or editing the browser. The server is your last line of defense.
+
+---
+
+## Layer 1: Frontend Validation (User Experience)
+
+Give instant feedback without a round-trip to the server:
+
+```html
+<form id="signup-form">
+  <input type="text" id="name" required minlength="2" maxlength="100" />
+  <input type="email" id="email" required />
+  <input type="password" id="password" required minlength="8" />
+  <button type="submit">Sign Up</button>
+  <p id="error-msg" style="color:red; display:none;"></p>
+</form>
+```
+
+```js
+document.getElementById('signup-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const error = document.getElementById('error-msg');
+  error.style.display = 'none';
+
+  const name = document.getElementById('name').value.trim();
+  const email = document.getElementById('email').value.trim();
+  const password = document.getElementById('password').value;
+
+  // Client-side checks
+  if (name.length < 2) {
+    error.textContent = 'Name must be at least 2 characters';
+    error.style.display = 'block';
+    return;
+  }
+  if (password.length < 8) {
+    error.textContent = 'Password must be at least 8 characters';
+    error.style.display = 'block';
+    return;
+  }
+
+  // Send to server
+  const res = await fetch('/api/auth/register', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name, email, password })
+  });
+
+  const data = await res.json();
+  if (!res.ok) {
+    error.textContent = data.error;
+    error.style.display = 'block';
+  }
+});
+```
+
+---
+
+## Layer 2: Server Validation (Security)
+
+```js
+// Simple manual validation
+router.post('/register', async (req, res) => {
+  const { name, email, password } = req.body;
+  const errors = [];
+
+  if (!name || name.trim().length < 2)
+    errors.push('Name must be at least 2 characters');
+
+  if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+    errors.push('Valid email required');
+
+  if (!password || password.length < 8)
+    errors.push('Password must be at least 8 characters');
+
+  if (errors.length > 0)
+    return res.status(400).json({ error: errors[0] }); // or send all: errors
+
+  // Proceed with registration...
+});
+```
+
+---
+
+## Layer 2 (Alternative): Using a Validation Library
+
+For larger projects, use [Zod](https://zod.dev) (Node.js):
+
+```bash
+npm install zod
+```
+
+```js
+const { z } = require('zod');
+
+const registerSchema = z.object({
+  name: z.string().min(2).max(100),
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+router.post('/register', async (req, res) => {
+  const result = registerSchema.safeParse(req.body);
+
+  if (!result.success) {
+    const message = result.error.errors[0].message;
+    return res.status(400).json({ error: message });
+  }
+
+  const { name, email, password } = result.data;
+  // Proceed...
+});
+```
+
+---
+
+## Common Fields and Their Rules
+
+| Field | Rules |
+|-------|-------|
+| Name | Min 2 chars, max 100, no HTML tags |
+| Email | Valid format, lowercase, max 255 chars |
+| Password | Min 8 chars, at least 1 number or symbol |
+| Phone | Digits only after stripping spaces/dashes |
+| URL | Must start with `http://` or `https://` |
+| Price | Number, min 0, max 2 decimal places |
+| Date | Valid date, not in the past (for future events) |
+
+---
+
+## What NOT to Validate On
+
+- **Never trust `Content-Type` headers alone** — read and validate the actual body
+- **Never trust `req.params.id`** — always parse as integer: `parseInt(req.params.id, 10)`
+- **Never trust file extensions** — check MIME type server-side for uploads
+
+---
+
+## Sanitization vs Validation
+
+- **Validation** — reject bad input ("this email is invalid")
+- **Sanitization** — clean input before using it (`name.trim()`, strip HTML tags)
+
+Do both. Validate first, then sanitize before storing.
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/debugging/FAILURE_TAXONOMY_CLASSIFICATION.md

@@ -0,0 +1,117 @@
+---
+name: failure-taxonomy-classification
+category: parallel-debug
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [debugging, taxonomy, classification, failure-patterns, agentdebug]
+difficulty: medium
+---
+
+# Failure Taxonomy Classification
+
+## Problem
+
+Debugging without classification leads to random investigation. Knowing the TYPE of failure immediately narrows the search space. A MEMORY failure needs different tools than a SYSTEM failure.
+
+## Solution Pattern
+
+Classify every failure into one of 5 categories from the AgentDebug taxonomy (2025). Each category has specific investigation steps and common root causes.
+
+## The 5 Categories
+
+### MEMORY — Agent forgets context
+**Symptoms:**
+- Repeats work already done
+- Ignores previous findings
+- Contradicts earlier decisions
+- Loses track of file changes
+
+**Investigation:**
+- Check if context was compacted
+- Look for conversation length > 100 turns
+- Verify key files are in context window
+- Check if WARRIOR handoff was read
+
+**Common fixes:** Re-read handoff, use `/compact Focus on {topic}`, pin critical context
+
+### REFLECTION — Agent doesn't learn from failures
+**Symptoms:**
+- Same error 3+ times in a row
+- Applies same fix that already failed
+- Doesn't adjust approach after failure
+- Ignores test output
+
+**Investigation:**
+- Search debug history for this error pattern
+- Check if behavioral directives exist for this pattern
+- Verify error output is being read
+
+**Common fixes:** Add behavioral directive (IF/THEN/BECAUSE), record failure pattern to Qdrant
+
+### PLANNING — Wrong approach chosen
+**Symptoms:**
+- Editing wrong file
+- Using wrong API/library
+- Building wrong feature
+- Missing requirements
+
+**Investigation:**
+- Re-read REQUIREMENTS.md or BLUEPRINT.md
+- Check CONSCIENCE.md for project rules
+- Verify understanding of the task
+
+**Common fixes:** Re-plan with `/fire-2-plan`, check skills library for correct patterns
+
+### ACTION — Correct plan, bad execution
+**Symptoms:**
+- Typos in code
+- Wrong parameters
+- Incomplete implementation
+- Tests fail on edge cases
+
+**Investigation:**
+- Diff the actual code against the plan
+- Check for copy-paste errors
+- Verify API signatures match documentation
+
+**Common fixes:** Fix the specific error, add test for the edge case
+
+### SYSTEM — External failure
+**Symptoms:**
+- Database connection refused
+- API rate limit hit
+- Build tool crash
+- Disk full, port in use
+
+**Investigation:**
+- Check if service is running
+- Verify environment variables
+- Check system resources (disk, memory, ports)
+
+**Common fixes:** Restart service, rotate credentials, clear disk space, kill port-holding process
+
+## Classification Flow
+
+```
+Error occurs
+  → Can you reproduce it?
+    No → SYSTEM (intermittent external issue)
+    Yes → Has this exact error happened before?
+      Yes → REFLECTION (not learning from past)
+      No → Is the approach correct?
+        No → PLANNING (wrong approach)
+        Yes → Is the code correct?
+          No → ACTION (execution error)
+          Yes → Is context missing?
+            Yes → MEMORY (lost context)
+            No → SYSTEM (environment issue)
+```
+
+## When to Use
+- First step of ANY debug session
+- Before spawning parallel debug agents
+- When recording failures to Qdrant
+
+## When NOT to Use
+- Not applicable — always classify before debugging

package/skills-library/debugging/THREE_AGENT_HYPOTHESIS_DEBUGGING.md

@@ -0,0 +1,86 @@
+---
+name: three-agent-hypothesis-debugging
+category: parallel-debug
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [debugging, parallel, hypothesis, agents, competing]
+difficulty: hard
+---
+
+# Three-Agent Competing Hypothesis Debugging
+
+## Problem
+
+Single-agent debugging follows one hypothesis at a time. If the first hypothesis is wrong, the agent wastes time before trying alternatives. Complex bugs with multiple possible root causes need parallel investigation.
+
+## Solution Pattern
+
+Spawn 3 agents, each investigating a DIFFERENT hypothesis simultaneously. The first agent to find a confirmed root cause wins. Others are terminated. This is 2-3x faster than sequential debugging for complex issues.
+
+## Workflow
+
+### Step 1: Generate 3 Hypotheses
+
+From symptoms, generate 3 distinct hypotheses:
+
+```
+Bug: "API returns 500 on course enrollment"
+
+H1: Database constraint violation — enrollment table FK or unique constraint
+H2: Middleware auth issue — token parsing fails silently, null user reaches handler
+H3: Race condition — concurrent enrollments for same user/course
+```
+
+### Step 2: Spawn 3 Parallel Agents
+
+```
+Agent 1 (H1): "Investigate database constraints. Check enrollment table schema,
+  run the INSERT manually, check for FK violations, check for duplicate keys."
+
+Agent 2 (H2): "Investigate auth middleware. Add logging to token parsing,
+  check if user object is null when reaching enrollment handler."
+
+Agent 3 (H3): "Investigate race conditions. Check if enrollment INSERT has
+  ON CONFLICT handling, test with 2 concurrent requests."
+```
+
+### Step 3: Collect Results
+
+Each agent returns:
+```
+{
+  hypothesis: "H1: Database constraint violation",
+  verdict: "CONFIRMED" | "ELIMINATED" | "INCONCLUSIVE",
+  evidence: ["FK on course_id references non-existent course 999"],
+  fix: "Validate course exists before INSERT" | null
+}
+```
+
+### Step 4: Choose Winner
+
+| Scenario | Action |
+|----------|--------|
+| 1 CONFIRMED | Apply that agent's fix |
+| 0 CONFIRMED, 3 ELIMINATED | Generate 3 new hypotheses from new evidence |
+| 1+ INCONCLUSIVE | Give inconclusive agent more time/context |
+| 2+ CONFIRMED | Compound bug — apply both fixes |
+
+## Key Rules
+
+1. **Hypotheses must be independent** — Each agent investigates a different root cause
+2. **No shared state** — Agents don't read each other's investigation
+3. **Time-boxed** — If no agent confirms within 10 minutes, stop and reassess
+4. **Evidence required** — CONFIRMED needs reproducible proof, not speculation
+5. **Don't fix what isn't broken** — Only CONFIRMED hypotheses get fixes
+
+## When to Use
+- Bugs with 3+ plausible root causes
+- Production incidents where speed matters
+- Flaky tests with non-deterministic behavior
+- Bugs that have resisted sequential debugging
+
+## When NOT to Use
+- Obvious bugs (typos, missing imports)
+- Bugs with a single clear hypothesis
+- Issues where file access would conflict between agents