devflow-kit 1.0.0 → 1.1.0

package/dist/commands/uninstall.js

@@ -9,6 +9,8 @@ import { getInstallationPaths, getClaudeDirectory, getManagedSettingsPath } from
 import { getGitRoot } from '../utils/git.js';
 import { isClaudeCliAvailable } from '../utils/cli.js';
 import { DEVFLOW_PLUGINS, getAllSkillNames, LEGACY_SKILL_NAMES } from '../plugins.js';
+import { removeAmbientHook } from './ambient.js';
+import { removeMemoryHooks } from './memory.js';
 import { detectShell, getProfilePath } from '../utils/safe-delete.js';
 import { isAlreadyInstalled, removeFromProfile } from '../utils/safe-delete-install.js';
 import { removeManagedSettings } from '../utils/post-install.js';
@@ -176,6 +178,21 @@ export const uninstallCommand = new Command('uninstall')
         if (!usedCli) {
             if (isSelectiveUninstall) {
                 await removeSelectedPlugins(claudeDir, selectedPlugins, verbose);
+                // Clean up ambient hook if ambient plugin is being removed
+                if (selectedPlugins.some(sp => sp.name === 'devflow-ambient')) {
+                    const settingsPath = path.join(claudeDir, 'settings.json');
+                    try {
+                        const settings = await fs.readFile(settingsPath, 'utf-8');
+                        const updated = removeAmbientHook(settings);
+                        if (updated !== settings) {
+                            await fs.writeFile(settingsPath, updated, 'utf-8');
+                            if (verbose) {
+                                p.log.success('Ambient mode hook removed from settings.json');
+                            }
+                        }
+                    }
+                    catch { /* settings.json may not exist */ }
+                }
             }
             else {
                 await removeAllDevFlow(claudeDir, devflowScriptsDir, verbose);
@@ -221,7 +238,39 @@ export const uninstallCommand = new Command('uninstall')
                 p.log.info('.docs/ preserved');
             }
         }
-        // 2. .claudeignore
+        // 2. .memory/ directory
+        const memoryDir = path.join(process.cwd(), '.memory');
+        let memoryExist = false;
+        try {
+            await fs.access(memoryDir);
+            memoryExist = true;
+        }
+        catch { /* .memory doesn't exist */ }
+        if (memoryExist) {
+            let shouldRemoveMemory = false;
+            if (options.keepDocs) {
+                shouldRemoveMemory = false;
+            }
+            else if (process.stdin.isTTY) {
+                const removeMemory = await p.confirm({
+                    message: '.memory/ directory found. Remove working memory files?',
+                    initialValue: false,
+                });
+                if (p.isCancel(removeMemory)) {
+                    p.cancel('Uninstall cancelled.');
+                    process.exit(0);
+                }
+                shouldRemoveMemory = removeMemory;
+            }
+            if (shouldRemoveMemory) {
+                await fs.rm(memoryDir, { recursive: true, force: true });
+                p.log.success('.memory/ removed');
+            }
+            else {
+                p.log.info('.memory/ preserved');
+            }
+        }
+        // 4. .claudeignore
         const claudeignorePath = gitRoot
             ? path.join(gitRoot, '.claudeignore')
             : path.join(process.cwd(), '.claudeignore');
@@ -249,12 +298,30 @@ export const uninstallCommand = new Command('uninstall')
                 p.log.info('.claudeignore preserved (non-interactive mode)');
             }
         }
-        // 3. settings.json (DevFlow hooks)
+        // 5. settings.json (DevFlow hooks)
         for (const scope of scopesToUninstall) {
             try {
                 const paths = await getInstallationPaths(scope);
                 const settingsPath = path.join(paths.claudeDir, 'settings.json');
-                const settingsContent = await fs.readFile(settingsPath, 'utf-8');
+                let settingsContent = await fs.readFile(settingsPath, 'utf-8');
+                // Always remove ambient hook on full uninstall (idempotent)
+                const withoutAmbient = removeAmbientHook(settingsContent);
+                if (withoutAmbient !== settingsContent) {
+                    await fs.writeFile(settingsPath, withoutAmbient, 'utf-8');
+                    settingsContent = withoutAmbient;
+                    if (verbose) {
+                        p.log.success(`Ambient mode hook removed from settings.json (${scope})`);
+                    }
+                }
+                // Always remove memory hooks on full uninstall (idempotent)
+                const withoutMemory = removeMemoryHooks(settingsContent);
+                if (withoutMemory !== settingsContent) {
+                    await fs.writeFile(settingsPath, withoutMemory, 'utf-8');
+                    settingsContent = withoutMemory;
+                    if (verbose) {
+                        p.log.success(`Memory hooks removed from settings.json (${scope})`);
+                    }
+                }
                 const settings = JSON.parse(settingsContent);
                 if (settings.hooks) {
                     if (process.stdin.isTTY) {
@@ -280,7 +347,7 @@ export const uninstallCommand = new Command('uninstall')
                 // settings.json doesn't exist or can't be parsed — skip
             }
         }
-        // 4. Managed settings (security deny list)
+        // 6. Managed settings (security deny list)
         let managedSettingsExist = false;
         try {
             const managedPath = getManagedSettingsPath();
@@ -309,7 +376,7 @@ export const uninstallCommand = new Command('uninstall')
                 p.log.info('Managed settings preserved (non-interactive mode)');
             }
         }
-        // 5. Safe-delete shell function
+        // 7. Safe-delete shell function
         const shell = detectShell();
         const profilePath = getProfilePath(shell);
         if (profilePath && await isAlreadyInstalled(profilePath)) {

package/dist/plugins.js

@@ -10,7 +10,7 @@ export const DEVFLOW_PLUGINS = [
         description: 'Auto-activating quality enforcement (foundation layer)',
         commands: [],
         agents: [],
-        skills: ['accessibility', 'core-patterns', 'docs-framework', 'frontend-design', 'git-safety', 'git-workflow', 'github-patterns', 'input-validation', 'react', 'test-patterns', 'typescript'],
+        skills: ['accessibility', 'core-patterns', 'docs-framework', 'frontend-design', 'git-safety', 'git-workflow', 'github-patterns', 'input-validation', 'react', 'test-driven-development', 'test-patterns', 'typescript'],
     },
     {
         name: 'devflow-specify',
@@ -54,6 +54,13 @@ export const DEVFLOW_PLUGINS = [
         agents: ['simplifier', 'scrutinizer', 'validator'],
         skills: ['self-review', 'core-patterns'],
     },
+    {
+        name: 'devflow-ambient',
+        description: 'Ambient mode — auto-loads relevant skills based on each prompt',
+        commands: ['/ambient'],
+        agents: [],
+        skills: ['ambient-router'],
+    },
     {
         name: 'devflow-audit-claude',
         description: 'Audit CLAUDE.md files against Anthropic best practices',

package/dist/utils/post-install.d.ts

@@ -65,4 +65,16 @@ export declare function updateGitignore(gitRoot: string, verbose: boolean): Prom
  * Create .docs/ directory structure for DevFlow artifacts.
  */
 export declare function createDocsStructure(verbose: boolean): Promise<void>;
+/**
+ * Create .memory/ directory for working memory files.
+ * Separate from .docs/ which is for reviews/releases.
+ */
+export declare function createMemoryDir(verbose: boolean, cwd?: string): Promise<void>;
+/**
+ * Migrate memory files from .docs/ to .memory/.
+ * One-time migration for existing users. Skips if destination exists (no clobber).
+ * Also cleans up ephemeral files from .docs/.
+ * Returns count of migrated files.
+ */
+export declare function migrateMemoryFiles(verbose: boolean, cwd?: string): Promise<number>;
 //# sourceMappingURL=post-install.d.ts.map

package/dist/utils/post-install.js

@@ -386,7 +386,7 @@ export async function installClaudeignore(gitRoot, rootDir, verbose) {
 export async function updateGitignore(gitRoot, verbose) {
     try {
         const gitignorePath = path.join(gitRoot, '.gitignore');
-        const entriesToAdd = ['.claude/', '.devflow/'];
+        const entriesToAdd = ['.claude/', '.devflow/', '.memory/', '.docs/'];
         let gitignoreContent = '';
         try {
             gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
@@ -424,4 +424,85 @@ export async function createDocsStructure(verbose) {
     }
     catch { /* may already exist */ }
 }
+/**
+ * Create .memory/ directory for working memory files.
+ * Separate from .docs/ which is for reviews/releases.
+ */
+export async function createMemoryDir(verbose, cwd) {
+    const memoryDir = path.join(cwd ?? process.cwd(), '.memory');
+    try {
+        await fs.mkdir(memoryDir, { recursive: true });
+        if (verbose) {
+            p.log.success('.memory/ directory ready');
+        }
+    }
+    catch { /* may already exist */ }
+}
+/**
+ * Migrate memory files from .docs/ to .memory/.
+ * One-time migration for existing users. Skips if destination exists (no clobber).
+ * Also cleans up ephemeral files from .docs/.
+ * Returns count of migrated files.
+ */
+export async function migrateMemoryFiles(verbose, cwd) {
+    const root = cwd ?? process.cwd();
+    const docsDir = path.join(root, '.docs');
+    const memoryDir = path.join(root, '.memory');
+    const migrations = [
+        { src: path.join(docsDir, 'WORKING-MEMORY.md'), dest: path.join(memoryDir, 'WORKING-MEMORY.md') },
+        { src: path.join(docsDir, 'patterns.md'), dest: path.join(memoryDir, 'PROJECT-PATTERNS.md') },
+        { src: path.join(docsDir, 'working-memory-backup.json'), dest: path.join(memoryDir, 'backup.json') },
+    ];
+    let migrated = 0;
+    for (const { src, dest } of migrations) {
+        try {
+            await fs.access(src);
+        }
+        catch {
+            continue; // Source doesn't exist
+        }
+        try {
+            await fs.access(dest);
+            continue; // Destination already exists — no clobber
+        }
+        catch {
+            // Destination doesn't exist — proceed with migration
+        }
+        try {
+            await fs.rename(src, dest);
+            migrated++;
+        }
+        catch {
+            // Cross-device or permission error — try copy+delete
+            try {
+                await fs.copyFile(src, dest);
+                await fs.rm(src, { force: true });
+                migrated++;
+            }
+            catch {
+                // Migration failed for this file — skip silently
+            }
+        }
+    }
+    // Clean up ephemeral files from .docs/
+    const ephemeralFiles = [
+        path.join(docsDir, '.working-memory-update.log'),
+        path.join(docsDir, '.working-memory-last-trigger'),
+    ];
+    for (const file of ephemeralFiles) {
+        try {
+            await fs.rm(file, { force: true });
+        }
+        catch { /* doesn't exist or can't remove */ }
+    }
+    // Clean up lock directory
+    try {
+        await fs.rmdir(path.join(docsDir, '.working-memory.lock'));
+    }
+    catch { /* doesn't exist or not empty */ }
+    if (migrated > 0 && verbose) {
+        p.log.success(`Migrated ${migrated} memory file(s) from .docs/ to .memory/`);
+    }
+    return migrated;
+}
 //# sourceMappingURL=post-install.js.map

package/dist/utils/safe-delete-install.d.ts

@@ -1,4 +1,6 @@
 import type { Shell } from './safe-delete.js';
+/** Bump this when the safe-delete block changes. */
+export declare const SAFE_DELETE_BLOCK_VERSION = 2;
 /**
  * Generate the safe-delete shell function block with markers.
  * Returns null for unsupported shells.
@@ -13,6 +15,11 @@ export declare function isAlreadyInstalled(profilePath: string): Promise<boolean
  * Creates parent directories and the file if they don't exist.
  */
 export declare function installToProfile(profilePath: string, block: string): Promise<void>;
+/**
+ * Extract the installed safe-delete block version from a profile file.
+ * Returns 0 (not installed), 1 (legacy block without version stamp), or N (versioned block).
+ */
+export declare function getInstalledVersion(profilePath: string): Promise<number>;
 /**
  * Remove the safe-delete block from a profile file.
  * Returns true if the block was found and removed, false otherwise.

package/dist/utils/safe-delete-install.js

@@ -2,6 +2,8 @@ import { promises as fs } from 'fs';
 import * as path from 'path';
 const START_MARKER = '# >>> DevFlow safe-delete >>>';
 const END_MARKER = '# <<< DevFlow safe-delete <<<';
+/** Bump this when the safe-delete block changes. */
+export const SAFE_DELETE_BLOCK_VERSION = 2;
 /**
  * Generate the safe-delete shell function block with markers.
  * Returns null for unsupported shells.
@@ -13,13 +15,18 @@ export function generateSafeDeleteBlock(shell, platform, trashCommand) {
         const cmd = trashCommand ?? 'trash';
         return [
             START_MARKER,
+            `# v${SAFE_DELETE_BLOCK_VERSION}`,
             `rm() {`,
             `  local files=()`,
             `  for arg in "$@"; do`,
             `    [[ "$arg" =~ ^- ]] || files+=("$arg")`,
             `  done`,
-            `  if (( \${#files[@]} > 0 )); then`,
-            `    ${cmd} "\${files[@]}"`,
+            `  local existing=()`,
+            `  for f in "\${files[@]}"; do`,
+            `    [ -e "$f" ] || [ -L "$f" ] && existing+=("$f")`,
+            `  done`,
+            `  if (( \${#existing[@]} > 0 )); then`,
+            `    ${cmd} "\${existing[@]}"`,
             `  fi`,
             `}`,
             `command() {`,
@@ -36,6 +43,7 @@ export function generateSafeDeleteBlock(shell, platform, trashCommand) {
         const cmd = trashCommand ?? 'trash';
         return [
             START_MARKER,
+            `# v${SAFE_DELETE_BLOCK_VERSION}`,
             `function rm --description "Safe delete via trash"`,
             `  set -l files`,
             `  for arg in $argv`,
@@ -43,8 +51,14 @@ export function generateSafeDeleteBlock(shell, platform, trashCommand) {
             `      set files $files $arg`,
             `    end`,
             `  end`,
-            `  if test (count $files) -gt 0`,
-            `    ${cmd} $files`,
+            `  set -l existing`,
+            `  for f in $files`,
+            `    if test -e $f; or test -L $f`,
+            `      set existing $existing $f`,
+            `    end`,
+            `  end`,
+            `  if test (count $existing) -gt 0`,
+            `    ${cmd} $existing`,
             `  end`,
             `end`,
             END_MARKER,
@@ -54,6 +68,7 @@ export function generateSafeDeleteBlock(shell, platform, trashCommand) {
         if (platform === 'win32') {
             return [
                 START_MARKER,
+                `# v${SAFE_DELETE_BLOCK_VERSION}`,
                 `if (Get-Alias rm -ErrorAction SilentlyContinue) {`,
                 `  Remove-Alias rm -Force -Scope Global`,
                 `}`,
@@ -82,12 +97,14 @@ export function generateSafeDeleteBlock(shell, platform, trashCommand) {
         const cmd = trashCommand ?? 'trash';
         return [
             START_MARKER,
+            `# v${SAFE_DELETE_BLOCK_VERSION}`,
             `if (Get-Alias rm -ErrorAction SilentlyContinue) {`,
             `  Remove-Alias rm -Force -Scope Global`,
             `}`,
             `function rm {`,
             `  $files = $args | Where-Object { $_ -notlike '-*' }`,
-            `  if ($files) { & ${cmd} @files }`,
+            `  $existing = $files | Where-Object { Test-Path $_ }`,
+            `  if ($existing) { & ${cmd} @existing }`,
             `}`,
             END_MARKER,
         ].join('\n');
@@ -123,6 +140,24 @@ export async function installToProfile(profilePath, block) {
     const content = existing.length > 0 ? existing + separator + block + '\n' : block + '\n';
     await fs.writeFile(profilePath, content, 'utf-8');
 }
+/**
+ * Extract the installed safe-delete block version from a profile file.
+ * Returns 0 (not installed), 1 (legacy block without version stamp), or N (versioned block).
+ */
+export async function getInstalledVersion(profilePath) {
+    try {
+        const content = await fs.readFile(profilePath, 'utf-8');
+        const startIdx = content.indexOf(START_MARKER);
+        if (startIdx === -1)
+            return 0;
+        const afterMarker = content.slice(startIdx + START_MARKER.length);
+        const match = afterMarker.match(/^\n# v(\d+)/);
+        return match ? parseInt(match[1], 10) : 1;
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * Remove the safe-delete block from a profile file.
  * Returns true if the block was found and removed, false otherwise.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Agentic Development Toolkit for Claude Code - Enhance AI-assisted development with intelligent commands and workflows",
   "type": "module",
   "bin": {

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.1.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), 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 |