@sandrinio/vbounce 1.0.0 → 1.3.0

package/scripts/verify_framework.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * verify_framework.mjs
+ * 
+ * Tests the backward-compatibility of the AI agent prompts against
+ * the strict YAML parsing schemas in validate_report.mjs.
+ * 
+ * Triggered manually by humans or automatically by CI when updating brains/.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const AGENTS_DIR = path.join(process.cwd(), 'brains', 'claude-agents');
+
+// The exact substring signatures that MUST exist in the agent instructions
+// to ensure the LLM knows to output the correct YAML schema.
+const EXPECTED_PROMPT_SIGNATURES = {
+    'developer.md': [
+        'status:',
+        'correction_tax:',
+        'files_modified:',
+        'lessons_flagged:'
+    ],
+    'qa.md': [
+        'status: "PASS"',
+        'bugs_found: 0',
+        'status: "FAIL"',
+        'failed_scenarios:'
+    ],
+    'architect.md': [
+        'status: "PASS"',
+        'safe_zone_score:',
+        'regression_risk:',
+        'status: "FAIL"',
+        'critical_failures:'
+    ],
+    'devops.md': [
+        'type: "story-merge"',
+        'conflicts_detected:',
+        'type: "sprint-release"',
+        'version:'
+    ]
+};
+
+function main() {
+    console.log("===========================================");
+    console.log(" V-Bounce OS: Framework Integrity Check");
+    console.log("===========================================\n");
+
+    let hasErrors = false;
+
+    if (!fs.existsSync(AGENTS_DIR)) {
+        console.error(`ERROR: ${AGENTS_DIR} not found.`);
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+        const filePath = path.join(AGENTS_DIR, file);
+        const content = fs.readFileSync(filePath, 'utf-8');
+
+        const requiredSignatures = EXPECTED_PROMPT_SIGNATURES[file];
+        if (!requiredSignatures) {
+            console.log(`[PASS] ${file} (No strict YAML signatures required)`);
+            continue;
+        }
+
+        let filePassed = true;
+        for (const sig of requiredSignatures) {
+            if (!content.includes(sig)) {
+                console.error(`[FAIL] ${file} is missing required YAML instruction key: '${sig}'`);
+                filePassed = false;
+                hasErrors = true;
+            }
+        }
+
+        // Check for general Rule 12 presence
+        if (!content.includes('YAML frontmatter') && !content.includes('YAML Frontmatter')) {
+            console.error(`[FAIL] ${file} appears to be missing the Rule 12 YAML Frontmatter instruction.`);
+            filePassed = false;
+            hasErrors = true;
+        }
+
+        if (filePassed) {
+            console.log(`[PASS] ${file} contains all required YAML extraction signatures.`);
+        }
+    }
+
+    console.log("\n-------------------------------------------");
+    if (hasErrors) {
+        console.error("❌ INTEGRITY CHECK FAILED.");
+        console.error("Agent prompts have drifted from the validate_report.mjs schema.");
+        console.error("Please fix the agent templates in brains/claude-agents/ to restore pipeline integrity.");
+        process.exit(1);
+    } else {
+        console.log("✅ INTEGRITY CHECK PASSED.");
+        console.log("All agent prompts strictly map to the required pipeline metadata schemas.");
+        process.exit(0);
+    }
+}
+
+main();

package/scripts/verify_framework.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# verify_framework.sh
+# 
+# Wrapper script to execute the Framework Integrity Check.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$ROOT_DIR" || exit 1
+
+node ./scripts/verify_framework.mjs
+exit $?

package/skills/agent-team/SKILL.md

@@ -201,7 +201,13 @@ Examples:
    e. DevOps runs `hotfix_manager.sh sync` to update any active story worktrees.
    f. Update Delivery Plan Status to "Done".
 
-6. Update DELIVERY_PLAN.md: Sprint Status → "Active"
+6. **Parallel Readiness Check** (before bouncing multiple stories simultaneously):
+   - Verify test runner config excludes `.worktrees/` (vitest, jest, pytest, etc.)
+   - Verify no shared mutable state between worktrees (e.g., shared temp files, singletons writing to same path)
+   - Verify `.gitignore` includes `.worktrees/`
+   If any check fails, fix before spawning parallel stories. Intermittent test failures from worktree cross-contamination erode trust in the test suite fast.
+
+7. Update DELIVERY_PLAN.md: Sprint Status → "Active"
 ```
 
 ### Step 1: Story Initialization
@@ -215,6 +221,7 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
 - Read LESSONS.md
 - Check RISK_REGISTRY.md for risks tagged to this story or its Epic
 - If `product_documentation/_manifest.json` exists, identify docs relevant to this story's scope (match against manifest descriptions/tags). Include relevant doc references in the task file so the Developer has product context.
+- **Adjacent implementation check:** For stories that modify or extend modules touched by earlier stories in this sprint, identify existing implementations the Developer should reuse. Add to the task file: `"Reuse these existing modules: {list with file paths and brief description of what each provides}"`. This prevents agents from independently re-implementing logic that already exists — a common source of duplication when stories run in parallel.
 - Create task file in `.worktrees/STORY-{ID}/.bounce/tasks/`
 - Update DELIVERY_PLAN.md: V-Bounce State → "Bouncing"
 
@@ -224,6 +231,7 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
    - Story §1 The Spec + §3 Implementation Guide
    - LESSONS.md
    - Relevant react-best-practices rules
+   - Adjacent module references (if any — "reuse src/core/X.ts for Y")
 2. Developer writes code and Implementation Report to .bounce/reports/
 3. Lead reads report, verifies completeness
 ```
@@ -295,7 +303,12 @@ After ALL stories are merged into `sprint/S-01`:
 2. Generate Sprint Report to .bounce/sprint-report.md
 3. V-Bounce State → "Sprint Review" for all stories
 4. Present Sprint Report to human
-5. After approval → Spawn devops subagent for Sprint Release:
+5. **BLOCKING STEP — Lesson Approval:**
+   Review and approve/reject ALL flagged lessons from §4 of the Sprint Report.
+   Do NOT proceed to Sprint Release until every lesson has a status of "Yes" or "No".
+   Stale lessons lose context — approve them while the sprint is fresh.
+   Present each lesson to the human and record approved ones to LESSONS.md immediately.
+6. After approval → Spawn devops subagent for Sprint Release:
    - Merge sprint/S-01 → main (--no-ff)
    - Tag release: v{VERSION}
    - Run full test suite + build + lint on main

package/skills/doc-manager/SKILL.md

@@ -234,8 +234,7 @@ Any → Parking Lot: Deferred by decision
 
 ***HOTFIX TRANSITIONS***
 Draft → Bouncing: Hotfix template created + Triage confirmed L1
-Bouncing → Done: Dev implements + Human manually verifies
-Done → Sync: `hotfix_manager.sh sync` run to update other worktrees
+Bouncing → Done: Dev implements + Human manually verifies + DevOps runs `hotfix_manager.sh sync`
 ```
 
 ## Agent Integration

package/skills/file-organization/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: file-organization
+description: "**Codebase Cleanliness Standard**: Enforces clean file organization in any codebase. Before creating ANY file, classify it by intent—deliverables go to the project tree, working artifacts go to `/temporary/`. Before committing, review `git diff` to catch misplaced files. Use this skill whenever creating, moving, or committing files. Works with all languages and frameworks. The `/temporary/` folder is git-ignored so working artifacts never get merged. ALWAYS consult this skill when writing files to the repo—it prevents clutter from debug scripts, scratch analysis, throwaway tests, and other AI working artifacts from polluting the codebase."
+compatibility: "Git required. Works with any language or framework."
+---
+
+## Core Principle
+
+Every file you create has an **intent**. You always know why you're creating it. Use that knowledge.
+
+- **"I'm creating this because the user asked for it / it solves the task"** → Project tree (root, src/, etc.)
+- **"I'm creating this to help me work — debug, analyze, test an idea"** → `/temporary/`
+
+This is not about file types or extensions. A `.test.js` file might be a critical part of the test suite, or it might be a throwaway script you wrote to check a theory. The difference is intent.
+
+## Layer 1: Proactive — Decide at Creation Time
+
+Before writing any file, run this mental check:
+
+```
+WHY am I creating this file?
+│
+├─ DELIVERABLE — The user asked for this, or it directly fulfills the task
+│  Examples:
+│  - "Add input validation" → validation.ts (deliverable)
+│  - "Write unit tests for auth" → auth.test.ts (deliverable)
+│  - "Create a migration for the new table" → 003_add_users.sql (deliverable)
+│  - "Update the README" → README.md (deliverable)
+│  → CREATE IN PROJECT TREE
+│
+└─ WORKING ARTIFACT — I need this to help me understand, debug, or explore
+   Examples:
+   - Script to reproduce a bug → debug-repro.py (working artifact)
+   - Markdown notes analyzing the codebase → analysis.md (working artifact)
+   - Quick test to verify an assumption → check-behavior.js (working artifact)
+   - Output log from a test run → output.txt (working artifact)
+   → CREATE IN /temporary/
+```
+
+The question is never "what type of file is this?" — it's **"does this file exist to serve the project, or to serve my working process?"**
+
+## Layer 2: Reactive — Safety Net Before Commit
+
+Before committing, review what you've changed. This catches anything that slipped through Layer 1.
+
+```bash
+git diff --name-only
+git status
+```
+
+For each file in the diff, ask:
+
+1. **Did the user's task require this file?** If no → move to `/temporary/`
+2. **Does this file exist in the project already?** If yes, you're editing existing code — that's fine, leave it
+3. **Is this a new file I created to help myself work?** If yes → move to `/temporary/`
+
+### Example: "Fix the login bug"
+
+```bash
+$ git status
+  modified:   src/auth/login.ts          # ← The actual fix. Commit this.
+  new file:   debug-login.py             # ← Script I wrote to reproduce the bug. Move to /temporary/
+  new file:   test-output.log            # ← Output from my debugging. Move to /temporary/
+  modified:   src/auth/login.test.ts     # ← Updated existing test. Commit this.
+```
+
+After cleanup:
+```bash
+$ git status
+  modified:   src/auth/login.ts          # ✅ commit
+  modified:   src/auth/login.test.ts     # ✅ commit
+```
+
+The debug script and log are now safely in `/temporary/`, out of the commit.
+
+### Example: "Add user validation with tests"
+
+```bash
+$ git status
+  new file:   src/validation/validate.ts       # ← Deliverable. Commit.
+  new file:   src/validation/validate.test.ts  # ← User asked for tests. Commit.
+  new file:   scratch-regex-test.js            # ← I wrote this to test regex patterns. /temporary/
+```
+
+Notice how `validate.test.ts` stays because the user asked for tests — it's a deliverable. But `scratch-regex-test.js` was a working artifact.
+
+## Language-Agnostic — Why Intent Beats File Types
+
+Static file-type rules break across languages:
+
+- Python's `__pycache__/` is already gitignored — don't touch it
+- Java's `target/` is a build artifact — handled by existing `.gitignore`
+- A Go `vendor/` directory might be intentionally committed
+- Database migrations are generated but absolutely committed
+- Protocol buffer outputs, GraphQL codegen — generated but part of the codebase
+- `dist/` and `build/` directories vary by project
+
+Trying to categorize by extension or directory name is fragile. Instead, the intent check works universally:
+
+**"Did I create this to deliver the task, or to help myself work?"**
+
+This one question works whether you're writing Python, TypeScript, Rust, Go, Java, C#, or anything else.
+
+## Things That Are NEVER Working Artifacts
+
+Don't accidentally move these to `/temporary/`:
+
+- Existing files you modified (they're already tracked in git)
+- Test suites the project already has (`tests/`, `__tests__/`, `spec/`)
+- CI/CD configs (`.github/workflows/`, `Dockerfile`, etc.)
+- Lock files (`package-lock.json`, `Cargo.lock`, `poetry.lock`)
+- Migration files (database schema changes)
+- Generated code that the project commits (codegen output, protobuf, etc.)
+- Config files (`.eslintrc`, `tsconfig.json`, `pyproject.toml`)
+
+If a file already exists in the git tree, it belongs there. Your job is only to route **new files you create** during your working process.
+
+## Git Setup
+
+Add `/temporary/` to `.gitignore` if it's not there already:
+
+```gitignore
+# AI/developer working artifacts (never commit)
+/temporary/
+```
+
+This is a one-time setup. After this, anything in `/temporary/` is invisible to git.
+
+## Quick Reference
+
+```
+BEFORE CREATING A FILE:
+  "Is this a deliverable?"  → YES → project tree
+                             → NO  → /temporary/
+
+BEFORE COMMITTING:
+  Run: git diff --name-only
+  For each NEW file: "Did the task require this?" → NO → mv to /temporary/
+  For MODIFIED files: leave them (they're already tracked)
+```
+
+## Why This Matters
+
+Working artifacts in the root folder create real problems: teammates see debug scripts and think they're production code, CI might pick up stray test files, code review gets cluttered with irrelevant changes, and over time the repo becomes a mess of half-finished experiments mixed with real code.
+
+The `/temporary/` folder gives you a safe space to work freely. Use it for anything and everything you need during your process — it never touches the git history and never confuses anyone.

package/skills/file-organization/TEST-RESULTS.md

@@ -0,0 +1,193 @@
+# File Organization Skill — Eval Results
+
+## Eval 1: Repro Script vs. Handler Fix
+
+**Prompt:** "I need to fix a race condition in the websocket handler. I wrote a quick Python script to simulate concurrent connections and reproduce the bug. I also fixed the actual handler. Where does each file go?"
+
+**Expected Output:** The Python repro script is a working artifact → /temporary/. The websocket handler fix is a deliverable → commit in place.
+
+**Relevant Guidance:**
+- "Script to reproduce a bug → debug-repro.py (working artifact)" (Line 33)
+- "I'm creating this because the user asked for it / it solves the task" → Project tree (Line 11)
+- "I'm creating this to help me work — debug, analyze, test an idea" → /temporary/ (Line 12)
+
+**Analysis:**
+The skill clearly distinguishes between debugging artifacts ("Script to reproduce a bug") and actual fixes. An agent following the core principle would recognize:
+- The Python script's intent: "help me understand/debug" → /temporary/
+- The handler fix's intent: "solves the task" → project tree
+
+The guidance is unambiguous. The agent gets the correct answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 2: User-Requested Tests vs. Scratch File
+
+**Prompt:** "User asked me to add unit tests for the payment module. I also created a scratch file to test some regex patterns I needed for the validation logic. Where does each go?"
+
+**Expected Output:** The unit tests are deliverables (user asked for them) → project tree. The regex scratch file is a working artifact → /temporary/.
+
+**Relevant Guidance:**
+- "Write unit tests for auth" → auth.test.ts (deliverable) (Line 26)
+- "Add user validation with tests" example shows validate.test.ts as deliverable because "User asked for tests" (Line 85)
+- "Quick test to verify an assumption → check-behavior.js (working artifact)" (Line 35)
+
+**Analysis:**
+The skill explicitly handles this distinction in the "Add user validation with tests" example (Lines 76-85), which directly parallels Eval 2:
+- User-requested tests (validate.test.ts) = deliverable
+- Scratch working files (scratch-regex-test.js) = working artifact
+
+The key insight is whether **the user asked for** the tests. The skill states this clearly. An agent would correctly identify:
+- User explicitly asked for unit tests → deliverable
+- Regex pattern scratch file is "to help me work" (testing an assumption) → working artifact
+
+**Potential gap:** The skill doesn't address a borderline case where scratch tests could be mistaken for part of the test suite if the agent isn't careful about the "user asked for" criterion. However, the stated guidance is clear enough.
+
+**Rating: PASS**
+
+---
+
+## Eval 3: Existing Tracked Tests vs. Debug Script
+
+**Prompt:** "I see there's a tests/ directory with existing test files. I also see a file called check-api.sh in the root that I created yesterday to debug an endpoint. What should I do?"
+
+**Expected Output:** Leave the tests/ directory alone — it's an existing tracked test suite. Move check-api.sh to /temporary/ since it's a debug working artifact.
+
+**Relevant Guidance:**
+- "Existing files you modified (they're already tracked in git)" — Never working artifacts (Line 108)
+- "Test suites the project already has (`tests/`, `__tests__/`, `spec/`)" — Never working artifacts (Line 109)
+- "If a file already exists in the git tree, it belongs there. Your job is only to route **new files you create** during your working process." (Line 116)
+
+**Analysis:**
+The skill explicitly states that existing tracked files are "NEVER working artifacts" and gives `tests/` as a direct example. For check-api.sh, the intent is clear: debug artifact, not user-requested deliverable.
+
+An agent would correctly identify:
+1. tests/ is already tracked → don't touch it
+2. check-api.sh intent: "to help me debug" → /temporary/
+
+The guidance is explicit and unambiguous. The agent would get the right answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 4: Generated-but-Committed Migration vs. Analysis Notes
+
+**Prompt:** "I'm working on a database migration task. I generated a migration file using the ORM CLI, and I also wrote an analysis.md exploring different indexing strategies. Where do these go?"
+
+**Expected Output:** The migration file is a deliverable (generated but committed as part of the project) → project tree. The analysis.md is a working artifact → /temporary/.
+
+**Relevant Guidance:**
+- "Database migrations are generated but absolutely committed" (Line 94)
+- "Migration files (database schema changes)" — Never working artifacts (Line 112)
+- "Markdown notes analyzing the codebase → analysis.md (working artifact)" (Line 34)
+
+**Analysis:**
+The skill handles this well. It explicitly recognizes that "generated" doesn't mean "working artifact" — migrations are generated by the ORM but belong in the project because they're **part of the deliverable** (schema changes that must be committed).
+
+For the migration file: The skill states directly "Migration files (database schema changes)" as something that is never a working artifact.
+
+For analysis.md: The skill lists "Markdown notes analyzing the codebase → analysis.md (working artifact)" — this directly matches the evaluation scenario.
+
+An agent would correctly identify:
+1. Migration file: "the project commits this" + "database schema changes" → project tree
+2. analysis.md: "notes analyzing the codebase" + "to help me work" → /temporary/
+
+The guidance is explicit and covers both cases directly.
+
+**Rating: PASS**
+
+---
+
+## Eval 5: Requested Component vs. Debug Render vs. Existing Test Suite
+
+**Prompt:** "I created a new React component as requested, plus a debug-render.jsx to test how it renders in isolation. The project already has a __tests__/ folder. Where does everything go?"
+
+**Expected Output:** The React component is a deliverable → project tree. debug-render.jsx is a working artifact → /temporary/. The __tests__/ folder is existing tracked code — don't touch it.
+
+**Relevant Guidance:**
+- "The user asked for it / it solves the task" → Project tree (Line 11)
+- "I need this to help me understand, debug, or explore" → /temporary/ (Line 31)
+- "Test suites the project already has (`tests/`, `__tests__/`, `spec/`)" — Never working artifacts (Line 109)
+
+**Analysis:**
+This eval tests three things:
+1. **Requested component:** Clear deliverable intent
+2. **Debug render file:** Clearly a working artifact ("test how it renders in isolation" = debugging/exploring)
+3. **Existing __tests__/ folder:** Explicitly listed as something to never move
+
+The skill handles all three. The guidance is clear. An agent would get the right answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 6: Git Status Cleanup (Layer 2)
+
+**Prompt:** "Before committing, I ran git status and see: modified src/api/users.ts, new file src/api/users.test.ts (user asked for tests), new file output.log, new file temp-check.py. How do I clean this up?"
+
+**Expected Output:** Commit users.ts (modified existing) and users.test.ts (deliverable). Move output.log and temp-check.py to /temporary/ (working artifacts).
+
+**Relevant Guidance:**
+- Layer 2 reactive check (Lines 42-55)
+- "Did the user's task require this file? If no → move to /temporary/" (Line 53)
+- "Does this file exist in the project already? If yes, you're editing existing code — that's fine, leave it" (Line 54)
+- "Is this a new file I created to help myself work? If yes → move to /temporary/" (Line 55)
+- Example showing git status cleanup (Lines 57-74) with similar structure
+
+**Analysis:**
+The skill provides the Layer 2 reactive framework directly:
+1. **modified users.ts:** Already tracked → commit
+2. **new users.test.ts:** User asked for tests (stated in prompt) → commit
+3. **new output.log:** Created during working process (debug output) → /temporary/
+4. **new temp-check.py:** Name itself suggests "to help myself work" + temporary → /temporary/
+
+The example (Lines 57-74) shows the exact scenario structure. The three questions in Layer 2 map directly:
+- Q1 (did user ask?): No for output.log and temp-check.py → move
+- Q2 (already exists?): No for new files, but users.ts exists → commit users.ts
+- Q3 (new artifact?): Yes for output.log and temp-check.py → move
+
+An agent would get the right answer following the Layer 2 framework.
+
+**Rating: PASS**
+
+---
+
+## Summary Assessment
+
+| Eval | Result | Confidence | Notes |
+|------|--------|-----------|-------|
+| 1 | PASS | High | Clear distinction between debug script and fix |
+| 2 | PASS | High | Explicit example matches eval scenario |
+| 3 | PASS | High | Existing files explicitly excluded from working artifacts |
+| 4 | PASS | High | Migrations explicitly covered; analysis.md directly exemplified |
+| 5 | PASS | High | All three elements (new component, debug file, existing suite) handled clearly |
+| 6 | PASS | High | Layer 2 framework provides exact decision tree; example mirrors scenario |
+
+## Critical Findings
+
+**All evals achieve PASS.** The skill provides:
+
+1. **Clear intent-based framework** that works across all scenarios
+2. **Explicit examples** that map directly to evals 2, 4, 5, and 6
+3. **Direct lists** of files that are "NEVER working artifacts," covering edge cases in evals 3 and 5
+4. **Layer 2 reactive checks** that handle the git status scenario (eval 6) with a concrete decision tree
+5. **Explicit handling of "generated but committed"** files like migrations (eval 4)
+
+The skill successfully distinguishes user-requested deliverables from working artifacts across all cases. Agents following either Layer 1 (proactive) or Layer 2 (reactive) would arrive at correct answers for all six evals.
+
+### Strengths of the Skill
+
+- **Not file-type dependent:** The "intent" approach works for all scenarios without fragile extension-based rules
+- **Handles edge cases explicitly:** Migrations, codegen, existing tracked files all explicitly addressed
+- **Concrete examples:** Evals 2, 4, 5 are nearly identical to skill examples
+- **Dual-layer approach:** Catches mistakes at creation time or before commit
+
+### No Significant Gaps Identified
+
+All three "focus areas" from the prompt are handled well:
+- **Eval 2 (user-requested vs. scratch tests):** Clear distinction via "user asked for"
+- **Eval 3 (existing tracked files):** Explicit list + general rule about existing files
+- **Eval 4 (generated-but-committed):** Direct mention of migrations + intent-based reasoning
+

package/skills/file-organization/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "file-organization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to fix a race condition in the websocket handler. I wrote a quick Python script to simulate concurrent connections and reproduce the bug. I also fixed the actual handler. Where does each file go?",
+      "expected_output": "The Python repro script is a working artifact → /temporary/. The websocket handler fix is a deliverable → commit in place.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "User asked me to add unit tests for the payment module. I also created a scratch file to test some regex patterns I needed for the validation logic. Where does each go?",
+      "expected_output": "The unit tests are deliverables (user asked for them) → project tree. The regex scratch file is a working artifact → /temporary/.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I see there's a tests/ directory with existing test files. I also see a file called check-api.sh in the root that I created yesterday to debug an endpoint. What should I do?",
+      "expected_output": "Leave the tests/ directory alone — it's an existing tracked test suite. Move check-api.sh to /temporary/ since it's a debug working artifact.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I'm working on a database migration task. I generated a migration file using the ORM CLI, and I also wrote an analysis.md exploring different indexing strategies. Where do these go?",
+      "expected_output": "The migration file is a deliverable (generated but committed as part of the project) → project tree. The analysis.md is a working artifact → /temporary/.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I created a new React component as requested, plus a debug-render.jsx to test how it renders in isolation. The project already has a __tests__/ folder. Where does everything go?",
+      "expected_output": "The React component is a deliverable → project tree. debug-render.jsx is a working artifact → /temporary/. The __tests__/ folder is existing tracked code — don't touch it.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Before committing, I ran git status and see: modified src/api/users.ts, new file src/api/users.test.ts (user asked for tests), new file output.log, new file temp-check.py. How do I clean this up?",
+      "expected_output": "Commit users.ts (modified existing) and users.test.ts (deliverable). Move output.log and temp-check.py to /temporary/ (working artifacts).",
+      "files": []
+    }
+  ]
+}

package/skills/file-organization/references/gitignore-template.md

@@ -0,0 +1,53 @@
+# .gitignore Template for File Organization Standard
+
+Add this to your `./.gitignore` file to ensure `/temporary/` never gets committed:
+
+```gitignore
+# ============================================
+# Local temporary work (NEVER commit)
+# ============================================
+/temporary/
+```
+
+## Why This Matters
+
+The `/temporary/` folder is where agents and developers place all working files that won't be part of the final codebase:
+- Debug scripts
+- Test experiments
+- Analysis documents
+- Exploration code
+- Generated output
+
+By adding `/temporary/` to `.gitignore`, you ensure:
+1. ✅ No clutter in git history
+2. ✅ Team members only see production code in the repository
+3. ✅ Safe space for experimentation without affecting commits
+4. ✅ Reduced cognitive load when browsing the codebase
+
+## Installation
+
+If you don't have a `.gitignore` file yet:
+1. Create a new file called `.gitignore` in the root of your repository
+2. Add the entry above
+3. Commit it: `git add .gitignore && git commit -m "Add temporary folder to gitignore"`
+
+If you already have a `.gitignore`:
+1. Open it
+2. Add the entry above (preferably in a section labeled "Local temporary work")
+3. Commit the change
+
+## Verification
+
+To verify the setup is correct:
+```bash
+# This should NOT list any files from /temporary/
+git status
+
+# This should show that /temporary/ is ignored
+git check-ignore -v /temporary/something.txt
+```
+
+If `/temporary/` files are appearing in `git status`, double-check that:
+- The `.gitignore` entry is spelled correctly (case-sensitive on Linux/Mac)
+- The file is committed (not just created but not staged)
+- You haven't accidentally added `/temporary/` files with `git add -f`

package/skills/file-organization/references/quick-checklist.md

@@ -0,0 +1,48 @@
+# File Organization Quick Checklist
+
+## At File Creation Time
+
+```
+WHY am I creating this file?
+│
+├─ DELIVERABLE (serves the project / user asked for it)
+│  → Create in project tree
+│
+└─ WORKING ARTIFACT (helps me debug / analyze / explore)
+   → Create in /temporary/
+```
+
+## Before Committing
+
+```bash
+git diff --name-only
+git status
+```
+
+For each file:
+
+| Question | Answer | Action |
+|----------|--------|--------|
+| Did the user's task require this file? | Yes | Commit |
+| Is this an existing file I modified? | Yes | Commit |
+| Did I create this to help myself work? | Yes | Move to /temporary/ |
+| Not sure? | — | Move to /temporary/ (safer) |
+
+## Never Move These to /temporary/
+
+- Existing tracked files you edited
+- Project test suites (`tests/`, `__tests__/`, `spec/`)
+- CI/CD configs (`.github/workflows/`, `Dockerfile`)
+- Lock files (`package-lock.json`, `Cargo.lock`)
+- Migration files
+- Generated code the project commits (protobuf, codegen)
+- Config files (`.eslintrc`, `tsconfig.json`, etc.)
+
+## Common Working Artifacts (Always /temporary/)
+
+- Debug/repro scripts you wrote to investigate
+- Analysis or exploration markdown
+- Scratch files testing an idea
+- Console output or logs you captured
+- Experimental code trying different approaches
+- Notes and drafts that aren't official docs