devflow-kit 1.0.0 → 1.2.0

package/plugins/devflow-ambient/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "devflow-ambient",
+  "description": "Ambient mode — auto-loads relevant skills for every prompt",
+  "version": "1.2.0",
+  "agents": [],
+  "skills": ["ambient-router"]
+}

package/plugins/devflow-ambient/README.md

@@ -0,0 +1,49 @@
+# devflow-ambient
+
+Ambient mode — auto-loads relevant skills based on each prompt, no explicit commands needed.
+
+## Command
+
+### `/ambient`
+
+Classify user intent and apply proportional skill enforcement to any prompt.
+
+```bash
+/ambient add a login form          # BUILD/STANDARD — loads TDD + implementation-patterns
+/ambient fix the auth error        # DEBUG/STANDARD — loads test-patterns + core-patterns
+/ambient where is the config?      # EXPLORE/QUICK — responds normally, zero overhead
+/ambient refactor the auth system  # BUILD/ESCALATE — suggests /implement
+```
+
+## Always-On Mode
+
+Enable ambient classification on every prompt without typing `/ambient`:
+
+```bash
+devflow ambient --enable    # Register UserPromptSubmit hook
+devflow ambient --disable   # Remove hook
+devflow ambient --status    # Check if enabled
+```
+
+When enabled, a `UserPromptSubmit` hook injects a classification preamble before every prompt. Slash commands (`/implement`, `/code-review`, etc.) and short confirmations ("yes", "ok") are skipped automatically.
+
+## How It Works
+
+1. **Classify intent** — BUILD, DEBUG, REVIEW, PLAN, EXPLORE, or CHAT
+2. **Classify depth** — QUICK (zero overhead), STANDARD (2-3 skills), or ESCALATE (workflow nudge)
+3. **Apply proportionally**:
+   - QUICK: respond normally
+   - STANDARD: load relevant skills, enforce TDD for BUILD
+   - ESCALATE: respond + recommend full workflow command
+
+## Depth Tiers
+
+| Depth | When | Overhead |
+|-------|------|----------|
+| QUICK | Chat, simple exploration, git/devops ops, single-word confirmations | ~0 tokens |
+| STANDARD | BUILD/DEBUG/REVIEW/PLAN, 1-5 file scope | ~500-1000 tokens (skill reads) |
+| ESCALATE | Multi-file, architectural, system-wide scope | ~0 extra tokens (nudge only) |
+
+## Skills
+
+- `ambient-router` — Intent + depth classification, skill selection matrix

package/plugins/devflow-ambient/commands/ambient.md

@@ -0,0 +1,110 @@
+---
+description: Ambient mode — classify intent and auto-load relevant skills for any prompt
+---
+
+# Ambient Command
+
+Classify user intent and auto-load relevant skills. No agents spawned — enhances the main session only.
+
+## Usage
+
+```
+/ambient <prompt>           Classify and respond with skill enforcement
+/ambient                    Show usage
+```
+
+## Phases
+
+### Phase 1: Load Router
+
+Read the `ambient-router` skill:
+- `~/.claude/skills/ambient-router/SKILL.md`
+
+### Phase 2: Classify
+
+Apply the ambient-router classification to `$ARGUMENTS`:
+
+1. **Intent:** BUILD | DEBUG | REVIEW | PLAN | EXPLORE | CHAT
+2. **Depth:** QUICK | STANDARD | ESCALATE
+
+If no arguments provided, output:
+
+```
+## Ambient Mode
+
+Classify intent and auto-load relevant skills.
+
+Usage: /ambient <your prompt>
+
+Examples:
+  /ambient add a login form          → BUILD/STANDARD (loads TDD + implementation-patterns)
+  /ambient fix the auth error        → DEBUG/STANDARD (loads test-patterns + core-patterns)
+  /ambient where is the config?      → EXPLORE/QUICK (responds normally)
+  /ambient refactor the auth system  → BUILD/ESCALATE (suggests /implement)
+
+Always-on: devflow ambient --enable
+```
+
+Then stop.
+
+### Phase 3: State Classification
+
+- **QUICK:** Skip this phase entirely. Respond directly in Phase 4.
+- **STANDARD:** Output one line: `Ambient: {INTENT}/{DEPTH}. Loading: {skill1}, {skill2}.`
+- **ESCALATE:** Skip — recommendation happens in Phase 4.
+
+### Phase 4: Apply
+
+**QUICK:**
+Respond to the user's prompt normally. Zero skill loading. Zero overhead.
+
+**STANDARD:**
+Read the selected skills based on the ambient-router's skill selection matrix:
+
+| Intent | Primary Skills | Secondary (conditional) |
+|--------|---------------|------------------------|
+| BUILD | test-driven-development, implementation-patterns | typescript (.ts), react (.tsx), frontend-design (CSS/UI), input-validation (forms/API), security-patterns (auth/crypto) |
+| DEBUG | test-patterns, core-patterns | git-safety (if git ops) |
+| REVIEW | self-review, core-patterns | test-patterns |
+| PLAN | implementation-patterns | core-patterns |
+
+Read up to 3 skills from `~/.claude/skills/{name}/SKILL.md`. Apply their patterns and constraints when responding to the user's prompt.
+
+For BUILD intent: enforce RED-GREEN-REFACTOR from test-driven-development. Write failing tests before production code.
+
+**ESCALATE:**
+Respond to the user's prompt with your best effort, then append:
+
+> This task spans multiple files/systems. Consider `/implement` for full lifecycle management (exploration → planning → implementation → review).
+
+## Architecture
+
+```
+/ambient <prompt> (main session, no agents)
+│
+├─ Phase 1: Load ambient-router skill
+├─ Phase 2: Classify intent + depth
+├─ Phase 3: State classification (STANDARD only)
+└─ Phase 4: Apply
+   ├─ QUICK → respond directly
+   ├─ STANDARD → load 2-3 skills, apply patterns, respond
+   └─ ESCALATE → respond + workflow nudge
+```
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No arguments | Show usage and stop |
+| Single word ("help") | Classify — likely CHAT/QUICK |
+| Prompt references `/implement` etc. | Classify as normal — user chose /ambient intentionally |
+| Mixed intent ("fix and add test") | Use higher-overhead intent (BUILD > DEBUG) |
+| User says "no enforcement" | Respect immediately — treat as QUICK |
+
+## Principles
+
+1. **No agents** — Ambient enhances the main session, never spawns subagents
+2. **Proportional** — QUICK gets zero overhead, STANDARD gets 2-3 skills, ESCALATE gets a nudge
+3. **Transparent** — State classification for STANDARD/ESCALATE, silent for QUICK
+4. **Respectful** — Never over-classify; when in doubt, go one tier lower
+5. **TDD for BUILD** — STANDARD depth BUILD tasks enforce test-first workflow

package/plugins/devflow-ambient/skills/ambient-router/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ambient-router
+description: >-
+  Classify user intent and response depth for ambient mode. Auto-loads relevant
+  skills without explicit command invocation. Used by /ambient command and
+  always-on UserPromptSubmit hook.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Ambient Router
+
+Classify user intent and auto-load relevant skills. Zero overhead for simple requests, skill injection for substantive work, workflow nudges for complex tasks.
+
+## Iron Law
+
+> **PROPORTIONAL RESPONSE**
+>
+> Match effort to intent. Never apply heavyweight processes to lightweight requests.
+> A chat question gets zero overhead. A 3-file feature gets 2-3 skills. A system
+> refactor gets a nudge toward `/implement`. Misclassification in either direction
+> is a failure.
+
+---
+
+## Step 1: Classify Intent
+
+Determine what the user is trying to do from their prompt.
+
+| Intent | Signal Words / Patterns | Examples |
+|--------|------------------------|---------|
+| **BUILD** | "add", "create", "implement", "build", "write", "make" | "add a login form", "create an API endpoint" |
+| **DEBUG** | "fix", "bug", "broken", "failing", "error", "why does" | "fix the auth error", "why is this test failing" |
+| **REVIEW** | "check", "look at", "review", "is this ok", "any issues" | "check this function", "any issues with this?" |
+| **PLAN** | "how should", "design", "architecture", "approach", "strategy" | "how should I structure auth?", "what's the approach for caching?" |
+| **EXPLORE** | "what is", "where is", "find", "show me", "explain", "how does" | "where is the config?", "explain this function" |
+| **CHAT** | greetings, meta-questions, confirmations, short responses | "thanks", "yes", "what can you do?" |
+
+**Ambiguous prompts:** Default to the lowest-overhead classification. "Update the README" → BUILD/STANDARD. Git operations like "commit this" → QUICK.
+
+## Step 2: Classify Depth
+
+Determine how much enforcement the prompt warrants.
+
+| Depth | Criteria | Action |
+|-------|----------|--------|
+| **QUICK** | CHAT intent. EXPLORE with no analytical depth ("where is X?"). Git/devops operations (commit, push, merge, branch, pr, deploy, reinstall). Single-word continuations. | Respond normally. Zero overhead. Do not state classification. |
+| **STANDARD** | BUILD/DEBUG/REVIEW/PLAN intent (any word count). EXPLORE with analytical depth ("analyze our X", "discuss how Y works"). | Read and apply 2-3 relevant skills from the selection matrix below. State classification briefly. |
+| **ESCALATE** | Multi-file architectural change, system-wide scope, > 5 files. Detailed implementation plan (100+ words with plan structure). | Respond at best effort + recommend: "This looks like it would benefit from `/implement` for full lifecycle management." |
+
+## Step 3: Select Skills (STANDARD depth only)
+
+Based on classified intent, read the following skills to inform your response.
+
+| Intent | Primary Skills | Secondary (if file type matches) |
+|--------|---------------|----------------------------------|
+| **BUILD** | test-driven-development, implementation-patterns | typescript (.ts), react (.tsx/.jsx), go (.go), java (.java), python (.py), rust (.rs), frontend-design (CSS/UI), input-validation (forms/API), security-patterns (auth/crypto) |
+| **DEBUG** | test-patterns, core-patterns | git-safety (if git operations involved) |
+| **REVIEW** | self-review, core-patterns | test-patterns |
+| **PLAN** | implementation-patterns | core-patterns |
+
+**Excluded from ambient** (review-command-only): review-methodology, complexity-patterns, consistency-patterns, database-patterns, dependencies-patterns, documentation-patterns, regression-patterns, architecture-patterns, accessibility.
+
+See `references/skill-catalog.md` for the full skill-to-intent mapping with file pattern triggers.
+
+## Step 4: Apply
+
+- **QUICK:** Respond directly. No preamble, no classification statement.
+- **STANDARD:** State classification briefly: `Ambient: BUILD/STANDARD. Loading: test-driven-development, implementation-patterns.` Then read the selected skills and apply their patterns to your response. For BUILD intent, enforce RED-GREEN-REFACTOR from test-driven-development.
+- **ESCALATE:** Respond with your best effort, then append: `> This task spans multiple files/systems. Consider \`/implement\` for full lifecycle (exploration → planning → implementation → review).`
+
+---
+
+## Transparency Rules
+
+1. **QUICK → silent.** No classification output.
+2. **STANDARD → brief statement.** One line: intent, depth, skills loaded.
+3. **ESCALATE → recommendation.** Best-effort response + workflow nudge.
+4. **Never lie about classification.** If uncertain, say so.
+5. **Never over-classify.** When in doubt, go one tier lower.
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Mixed intent ("fix this bug and add a test") | Use the higher-overhead intent (BUILD > DEBUG) |
+| Continuation of previous conversation | Inherit previous classification unless prompt clearly shifts |
+| User explicitly requests no enforcement | Respect immediately — classify as QUICK |
+| Prompt references specific DevFlow command | Skip ambient — the command has its own orchestration |

package/plugins/devflow-ambient/skills/ambient-router/references/skill-catalog.md

@@ -0,0 +1,68 @@
+# Ambient Router — Skill Catalog
+
+Full mapping of DevFlow skills to ambient intents and file-type triggers. The ambient-router SKILL.md references this for detailed selection logic.
+
+## Skills Available for Ambient Loading
+
+These skills may be loaded during STANDARD-depth ambient routing.
+
+### BUILD Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| test-driven-development | Always for BUILD | `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.py` |
+| implementation-patterns | Always for BUILD | Any code file |
+| typescript | TypeScript files in scope | `*.ts`, `*.tsx` |
+| react | React components in scope | `*.tsx`, `*.jsx` |
+| frontend-design | UI/styling work | `*.css`, `*.scss`, `*.tsx` with styling keywords |
+| input-validation | Forms, APIs, user input | Files with form/input/validation keywords |
+| go | Go files in scope | `*.go` |
+| java | Java files in scope | `*.java` |
+| python | Python files in scope | `*.py` |
+| rust | Rust files in scope | `*.rs` |
+| security-patterns | Auth, crypto, secrets | Files with auth/token/crypto/password keywords |
+
+### DEBUG Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| test-patterns | Always for DEBUG | Any test-related context |
+| core-patterns | Always for DEBUG | Any code file |
+| git-safety | Git operations involved | User mentions git, rebase, merge, etc. |
+
+### REVIEW Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| self-review | Always for REVIEW | Any code file |
+| core-patterns | Always for REVIEW | Any code file |
+| test-patterns | Test files in scope | `*.test.*`, `*.spec.*` |
+
+### PLAN Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| implementation-patterns | Always for PLAN | Any planning context |
+| core-patterns | Architectural planning | System design discussions |
+
+## Skills Excluded from Ambient
+
+These skills are loaded only by explicit DevFlow commands (primarily `/code-review`):
+
+- review-methodology — Full review process (6-step, 3-category classification)
+- complexity-patterns — Cyclomatic complexity, deep nesting analysis
+- consistency-patterns — Naming convention, pattern deviation detection
+- database-patterns — Index analysis, query optimization, migration safety
+- dependencies-patterns — CVE detection, license audit, outdated packages
+- documentation-patterns — Doc drift, stale comments, missing API docs
+- regression-patterns — Lost functionality, broken exports, behavioral changes
+- architecture-patterns — SOLID analysis, coupling detection, layering issues
+- accessibility — WCAG compliance, ARIA roles, keyboard navigation
+- performance-patterns — N+1 queries, memory leaks, caching opportunities
+
+## Selection Limits
+
+- **Maximum 3 skills** per ambient response (primary + up to 2 secondary)
+- **Primary skills** are always loaded for the classified intent
+- **Secondary skills** are loaded only when file patterns match conversation context
+- If more than 3 skills seem relevant, this is an ESCALATE signal

package/plugins/devflow-audit-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "devflow-audit-claude",
   "description": "Audit CLAUDE.md files against Anthropic best practices",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "agents": [],
   "skills": []
 }

package/plugins/devflow-code-review/.claude-plugin/plugin.json

@@ -5,14 +5,13 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
   "keywords": ["review", "code-quality", "security", "architecture", "pr-review"],
   "agents": ["git", "reviewer", "synthesizer"],
   "skills": [
-    "accessibility",
     "agent-teams",
     "architecture-patterns",
     "complexity-patterns",
@@ -20,9 +19,7 @@
     "database-patterns",
     "dependencies-patterns",
     "documentation-patterns",
-    "frontend-design",
     "performance-patterns",
-    "react",
     "regression-patterns",
     "review-methodology",
     "security-patterns",

package/plugins/devflow-code-review/agents/reviewer.md

@@ -34,6 +34,10 @@ The orchestrator provides:
 | `react` | `~/.claude/skills/react/SKILL.md` |
 | `accessibility` | `~/.claude/skills/accessibility/SKILL.md` |
 | `frontend-design` | `~/.claude/skills/frontend-design/SKILL.md` |
+| `go` | `~/.claude/skills/go/SKILL.md` |
+| `java` | `~/.claude/skills/java/SKILL.md` |
+| `python` | `~/.claude/skills/python/SKILL.md` |
+| `rust` | `~/.claude/skills/rust/SKILL.md` |
 
 ## Responsibilities
 
@@ -117,3 +121,7 @@ Report format for `{output_path}`:
 | react | If .tsx/.jsx files changed |
 | accessibility | If .tsx/.jsx files changed |
 | frontend-design | If .tsx/.jsx/.css/.scss files changed |
+| go | If .go files changed |
+| java | If .java files changed |
+| python | If .py files changed |
+| rust | If .rs files changed |

package/plugins/devflow-code-review/commands/code-review-teams.md

@@ -42,10 +42,16 @@ Detect file types in diff to determine conditional reviews:
 | .tsx/.jsx files | react |
 | .tsx/.jsx files | accessibility |
 | .tsx/.jsx/.css/.scss files | frontend-design |
+| .go files | go |
+| .java files | java |
+| .py files | python |
+| .rs files | rust |
 | DB/migration files | database |
 | Dependency files changed | dependencies |
 | Docs or significant code | documentation |
 
+**Skill availability check**: Language/ecosystem reviews (typescript, react, accessibility, frontend-design, go, java, python, rust) require their optional skill plugin to be installed. Before adding a conditional perspective, check if `~/.claude/skills/{focus}/SKILL.md` exists (use Glob). If the skill file doesn't exist, **skip that perspective** — the language plugin isn't installed. Non-language reviews (database, dependencies, documentation) use skills bundled with this plugin and are always available.
+
 ### Phase 2: Spawn Review Team
 
 Create an agent team for adversarial review. Always include 4 core perspectives; conditionally add more based on Phase 1 analysis.
@@ -61,6 +67,10 @@ Create an agent team for adversarial review. Always include 4 core perspectives;
 - **React**: hooks, state, rendering, composition (if .tsx/.jsx changed)
 - **Accessibility**: ARIA, keyboard nav, focus management (if .tsx/.jsx changed)
 - **Frontend Design**: visual consistency, spacing, typography (if .tsx/.jsx/.css changed)
+- **Go**: error handling, interfaces, concurrency (if .go changed)
+- **Java**: records, sealed classes, composition (if .java changed)
+- **Python**: type hints, protocols, data modeling (if .py changed)
+- **Rust**: ownership, error handling, type system (if .rs changed)
 - **Database**: schema, queries, migrations, indexes (if DB files changed)
 - **Dependencies**: CVEs, versions, licenses, supply chain (if package files changed)
 - **Documentation**: doc drift, missing docs, stale comments (if docs or significant code changed)
@@ -238,7 +248,7 @@ Display results:
 │  ├─ Architecture Reviewer (teammate)
 │  ├─ Performance Reviewer (teammate)
 │  ├─ Quality Reviewer (teammate)
-│  └─ [Conditional: TypeScript, React, A11y, Design, DB, Deps, Docs]
+│  └─ [Conditional: TypeScript, React, A11y, Design, Go, Java, Python, Rust, DB, Deps, Docs]
 │
 ├─ Phase 3: Debate round
 │  └─ Reviewers challenge each other (max 2 rounds)

package/plugins/devflow-code-review/commands/code-review.md

@@ -42,13 +42,19 @@ Detect file types in diff to determine conditional reviews:
 | .tsx/.jsx files | react |
 | .tsx/.jsx files | accessibility |
 | .tsx/.jsx/.css/.scss files | frontend-design |
+| .go files | go |
+| .java files | java |
+| .py files | python |
+| .rs files | rust |
 | DB/migration files | database |
 | Dependency files changed | dependencies |
 | Docs or significant code | documentation |
 
+**Skill availability check**: Language/ecosystem reviews (typescript, react, accessibility, frontend-design, go, java, python, rust) require their optional skill plugin to be installed. Before spawning a conditional Reviewer for these focuses, check if `~/.claude/skills/{focus}/SKILL.md` exists (use Glob). If the skill file doesn't exist, **skip that review** — the language plugin isn't installed. Non-language reviews (database, dependencies, documentation) use skills bundled with this plugin and are always available.
+
 ### Phase 2: Run Reviews (Parallel)
 
-Spawn Reviewer agents **in a single message**. Always run 7 core reviews; conditionally add up to 4 more:
+Spawn Reviewer agents **in a single message**. Always run 7 core reviews; conditionally add more based on changed file types:
 
 | Focus | Always | Pattern Skill |
 |-------|--------|---------------|
@@ -63,6 +69,10 @@ Spawn Reviewer agents **in a single message**. Always run 7 core reviews; condit
 | react | conditional | react |
 | accessibility | conditional | accessibility |
 | frontend-design | conditional | frontend-design |
+| go | conditional | go |
+| java | conditional | java |
+| python | conditional | python |
+| rust | conditional | rust |
 | database | conditional | database-patterns |
 | dependencies | conditional | dependencies-patterns |
 | documentation | conditional | documentation-patterns |
@@ -123,7 +133,7 @@ Display results from all agents:
 │  ├─ Reviewer: consistency
 │  ├─ Reviewer: regression
 │  ├─ Reviewer: tests
-│  └─ Reviewer: [conditional: typescript, react, a11y, design, database, deps, docs]
+│  └─ Reviewer: [conditional: typescript, react, a11y, design, go, java, python, rust, database, deps, docs]
 │
 ├─ Phase 3: Synthesis (PARALLEL)
 │  ├─ Git agent (comment-pr)

package/plugins/devflow-core-skills/.claude-plugin/plugin.json

@@ -5,23 +5,20 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
   "keywords": ["skills", "quality", "patterns", "auto-activate", "enforcement", "foundation"],
   "agents": [],
   "skills": [
-    "accessibility",
     "core-patterns",
     "docs-framework",
-    "frontend-design",
     "git-safety",
     "git-workflow",
     "github-patterns",
     "input-validation",
-    "react",
-    "test-patterns",
-    "typescript"
+    "test-driven-development",
+    "test-patterns"
   ]
 }

package/plugins/devflow-core-skills/skills/docs-framework/SKILL.md

@@ -32,10 +32,14 @@ All generated documentation lives under `.docs/` in the project root:
 │   ├── {timestamp}.md
 │   ├── compact/{timestamp}.md
 │   └── INDEX.md
-├── swarm/                              # Swarm operation state
-│   ├── state.json
-│   └── plans/
-└── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
+└── swarm/                              # Swarm operation state
+    ├── state.json
+    └── plans/
+
+.memory/
+├── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
+├── PROJECT-PATTERNS.md                 # Accumulated patterns (merged across sessions)
+└── backup.json                         # Pre-compact git state snapshot
 ```
 
 ---
@@ -92,7 +96,7 @@ source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
 | Agent | Output Location | Behavior |
 |-------|-----------------|----------|
 | Reviewer | `.docs/reviews/{branch-slug}/{type}-report.{timestamp}.md` | Creates new |
-| Working Memory | `.docs/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
+| Working Memory | `.memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
 
 ### Agents That Don't Persist
 
@@ -120,7 +124,7 @@ When creating or modifying persisting agents:
 
 This framework is used by:
 - **Review agents**: Creates review reports
-- **Working Memory hooks**: Auto-maintains `.docs/WORKING-MEMORY.md`
+- **Working Memory hooks**: Auto-maintains `.memory/WORKING-MEMORY.md`
 
 All persisting agents should load this skill to ensure consistent documentation.
 

package/plugins/devflow-core-skills/skills/test-driven-development/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: test-driven-development
+description: >-
+  Enforce RED-GREEN-REFACTOR cycle during implementation. Write failing tests before
+  production code. Distinct from test-patterns (which reviews test quality) — this
+  skill enforces the TDD workflow during code generation.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.py"
+  exclude:
+    - "node_modules/**"
+    - "dist/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Test-Driven Development
+
+Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
+
+## Iron Law
+
+> **TESTS FIRST, ALWAYS**
+>
+> Write the failing test before the production code. No exceptions. If you catch
+> yourself writing production code without a failing test, stop immediately, delete
+> the production code, write the test, watch it fail, then write the minimum code
+> to make it pass. The test IS the specification.
+
+---
+
+## The Cycle
+
+### Step 1: RED — Write a Failing Test
+
+Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
+
+```
+Describe what the code SHOULD do, not how it does it.
+One behavior per test. One assertion per test (ideally).
+Name tests as sentences: "returns error when email is invalid"
+```
+
+**Checkpoint:** The test MUST fail before proceeding. A test that passes immediately proves nothing.
+
+### Step 2: GREEN — Write Minimum Code to Pass
+
+Write the simplest production code that makes the failing test pass. No more, no less.
+
+```
+Hardcode first if that's simplest. Generalize when the next test forces it.
+Don't write code "you'll need later." Write code the test demands NOW.
+Don't optimize. Don't refactor. Don't clean up. Just pass the test.
+```
+
+**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
+
+### Step 3: REFACTOR — Improve Without Changing Behavior
+
+Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
+
+```
+Run tests after every refactoring step.
+If a test breaks during refactor, undo immediately — you changed behavior.
+Apply DRY, extract patterns, improve readability.
+```
+
+**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
+
+---
+
+## Rationalization Prevention
+
+These are the excuses developers use to skip TDD. Recognize and reject them.
+
+| Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
+|--------|-------------------|---------------|----------------|
+| "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
+| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
+| "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
+| "Test is too hard to write" | Setup is complex, mocking is painful | Hard-to-test code = bad design; the test is telling you the interface is wrong | Simplify the interface first |
+| "Need to see the whole picture" | Can't test what I haven't designed yet | TDD IS design; each test reveals the next piece of the interface | Let the test guide the design |
+| "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
+
+See `references/rationalization-prevention.md` for extended examples with code.
+
+---
+
+## Process Enforcement
+
+When implementing any feature under ambient BUILD/STANDARD:
+
+1. **Identify the first behavior** — What is the simplest thing this feature must do?
+2. **Write the test** — Describe that behavior as a failing test
+3. **Run the test** — Confirm it fails (RED)
+4. **Write minimum code** — Just enough to pass (GREEN)
+5. **Refactor** — Clean up while tests stay green (REFACTOR)
+6. **Repeat** — Next behavior, next test, next cycle
+
+### File Organization
+
+- Test file lives next to production file: `user.ts` → `user.test.ts`
+- Follow project's existing test conventions (Jest, Vitest, pytest, etc.)
+- Import the module under test, not internal helpers
+
+### What to Test
+
+| Test | Don't Test |
+|------|-----------|
+| Public API behavior | Private implementation details |
+| Error conditions and edge cases | Framework internals |
+| Integration points (boundaries) | Third-party library correctness |
+| State transitions | Getter/setter plumbing (unless non-trivial) |
+
+---
+
+## When TDD Does Not Apply
+
+- **QUICK depth** — Ambient classified as QUICK (chat, exploration, trivial edits)
+- **Non-code tasks** — Documentation, configuration, CI changes
+- **Exploratory prototyping** — User explicitly says "just spike this" or "prototype"
+- **Existing test suite changes** — Modifying tests themselves (test-patterns skill applies instead)
+
+When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [specific reason from list above]."
+
+---
+
+## Integration with Ambient Mode
+
+- **BUILD/STANDARD** → TDD enforced. Every new function/method gets test-first treatment.
+- **BUILD/QUICK** → TDD skipped (trivial single-file edit).
+- **BUILD/ESCALATE** → TDD mentioned in nudge toward `/implement`.
+- **DEBUG/STANDARD** → TDD applies to the fix: write a test that reproduces the bug first, then fix.