devflow-kit 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to DevFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.1] - 2026-03-20
+
+### Added
+- **`--dry-run` flag** for `devflow uninstall` — preview removal plan without deleting anything
+
+### Fixed
+- **Ambient skill loading** — removed `allowed-tools` restriction from ambient-router so skills actually load via the Skill tool
+- **Ambient hook preamble** — explicit Skill tool instruction ensures models invoke skills rather than responding directly
+- **Init wizard** — hide `devflow-ambient` from plugin multiselect (auto-included via ambient prompt)
+- **Working memory** — replaced broken `--resume` with transcript-based background updater
+
+---
+
+## [1.6.0] - 2026-03-19
+
+### Added
+- **Ambient agent orchestration**: ORCHESTRATED tier spawns agent pipelines for IMPLEMENT, DEBUG, PLAN intents
+- **Orchestration skills**: `implementation-orchestration`, `debug-orchestration`, `plan-orchestration` for ambient agent pipelines
+- **`knowledge-persistence` skill** (#145) — extraction procedure, lock protocol, loading instructions for project knowledge
+- **Knowledge loading phase** (#145) — `/debug`, `/specify`, `/self-review` now load project knowledge at startup
+- **Pitfall recording phase** (#145) — `/code-review`, `/resolve` record pitfalls to `.memory/knowledge/pitfalls.md`
+- **Knowledge directory** (#145) — `.memory/knowledge/` with `decisions.md` (ADR-NNN, append-only) and `pitfalls.md` (area-specific gotchas)
+
+### Changed
+- **Ambient mode**: Three depth tiers (QUICK/GUIDED/ORCHESTRATED) replacing old QUICK/GUIDED/ELEVATE
+- **Ambient mode**: GUIDED tier for small-scope IMPLEMENT (≤2 files), simple DEBUG, focused PLAN, and REVIEW — main session with skills + Simplifier
+- **Ambient mode**: BUILD intent renamed to IMPLEMENT for clarity
+- **Coder agent**: Added `test-driven-development` and `search-first` to permanent skills
+- **Command phase numbering** (#145) — renumbered fractional phases to sequential integers across 12 command files
+
+### Fixed
+- **Agent metadata** (#146) — fixed `subagent_type` in debug, added missing YAML frontmatter
+- **Plugin count** (#146) — corrected to "8 core + 9 optional"
+- **Skills catalog** (#146) — cataloged 3 missing skills in reference
+- **Debug command** (#147) — removed non-standard `name=` parameter
+- **Plugin descriptions** (#147, #148) — synced across plugin.json, plugins.ts, marketplace.json
+- **Simplifier agent** (#148) — added Output/Boundaries sections
+- **Plugin metadata** (#148) — added homepage/repository/license/keywords to 3 plugins
+
+### Removed
+- **`/ambient` command**: Ambient mode is now hook-only. Use `devflow ambient --enable` to activate.
+
+### Behavioral Changes
+- EXPLORE intent now always classifies as QUICK (was split QUICK/GUIDED)
+- Simple text edits ("Update the README") classify as QUICK (was BUILD/GUIDED)
+- Debug agent budget cap removed — agents scale to investigation needs
+
+---
+
 ## [1.5.0] - 2026-03-13
 
 ### Added
@@ -866,6 +915,8 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v1.4.0...HEAD
+[1.6.1]: https://github.com/dean0x/devflow/compare/v1.6.0...v1.6.1
+[1.6.0]: https://github.com/dean0x/devflow/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/dean0x/devflow/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/dean0x/devflow/compare/v1.3.3...v1.4.0
 [1.3.3]: https://github.com/dean0x/devflow/compare/v1.3.2...v1.3.3

package/README.md

@@ -24,7 +24,7 @@ DevFlow adds structured commands that handle the full lifecycle: specify feature
 - **Full-lifecycle implementation** — spec, explore, plan, code, validate, refine in one command
 - **Automatic session memory** — survives restarts, `/clear`, and context compaction
 - **Parallel debugging** — competing hypotheses investigated simultaneously
-- **31 quality skills** — 9 auto-activating core, 8 optional language/ecosystem, plus specialized review and agent skills
+- **35 quality skills** — 9 auto-activating core, 8 optional language/ecosystem, plus specialized review, agent, and orchestration skills
 
 ## Quick Start
 
@@ -48,7 +48,7 @@ Then in Claude Code:
 | `devflow-resolve` | `/resolve` | Process review issues — fix or defer to tech debt |
 | `devflow-debug` | `/debug` | Parallel hypothesis debugging |
 | `devflow-self-review` | `/self-review` | Self-review workflow (Simplifier + Scrutinizer) |
-| `devflow-ambient` | `/ambient` | Ambient mode — auto-loads relevant skills based on each prompt |
+| `devflow-ambient` | (hook) | Ambient mode — intent classification with agent orchestration |
 | `devflow-core-skills` | (auto) | Auto-activating quality enforcement skills |
 
 ## Command Details
@@ -197,8 +197,10 @@ DevFlow creates project documentation in `.docs/` and working memory in `.memory
 
 .memory/
 ├── WORKING-MEMORY.md         # Auto-maintained by Stop hook
-├── PROJECT-PATTERNS.md       # Accumulated patterns across sessions
-└── backup.json               # Pre-compact git state snapshot
+├── backup.json               # Pre-compact git state snapshot
+└── knowledge/
+    ├── decisions.md           # Architectural decisions (ADR-NNN, append-only)
+    └── pitfalls.md            # Known pitfalls (area-specific gotchas)
 ```
 
 ## Workflow Examples
@@ -252,7 +254,10 @@ Session context is saved and restored automatically via Working Memory hooks —
 | Option | Description |
 |--------|-------------|
 | `--scope <user\|local>` | Uninstall scope (default: user) |
+| `--plugin <names>` | Comma-separated plugin names to uninstall selectively |
 | `--keep-docs` | Preserve .docs/ directory |
+| `--dry-run` | Show what would be removed without deleting anything |
+| `--verbose` | Show detailed uninstall output |
 
 ## Building from Source
 

package/dist/commands/ambient.js

@@ -122,7 +122,7 @@ export const ambientCommand = new Command('ambient')
         }
         await fs.writeFile(settingsPath, updated, 'utf-8');
         p.log.success('Ambient mode enabled — UserPromptSubmit hook registered');
-        p.log.info(color.dim('Relevant skills will now auto-load based on each prompt'));
+        p.log.info(color.dim('Skills auto-load and agents orchestrate based on each prompt'));
     }
     if (options.disable) {
         const updated = removeAmbientHook(settingsContent);

package/dist/commands/init.js

@@ -62,7 +62,7 @@ export const initCommand = new Command('init')
     .option('--plugin <names>', 'Install specific plugin(s), comma-separated (e.g., implement,code-review)')
     .option('--teams', 'Enable Agent Teams (peer debate, adversarial review)')
     .option('--no-teams', 'Disable Agent Teams (use parallel subagents instead)')
-    .option('--ambient', 'Enable ambient mode (auto-loads relevant skills for every prompt)')
+    .option('--ambient', 'Enable ambient mode (classifies intent, loads skills, orchestrates agents)')
     .option('--no-ambient', 'Disable ambient mode')
     .option('--memory', 'Enable working memory (session context preservation)')
     .option('--no-memory', 'Disable working memory hooks')
@@ -121,14 +121,14 @@ export const initCommand = new Command('init')
     }
     else if (process.stdin.isTTY) {
         const choices = DEVFLOW_PLUGINS
-            .filter(pl => pl.name !== 'devflow-core-skills')
+            .filter(pl => pl.name !== 'devflow-core-skills' && pl.name !== 'devflow-ambient')
             .map(pl => ({
             value: pl.name,
             label: pl.name.replace('devflow-', ''),
             hint: pl.description + (pl.optional ? ' (optional)' : ''),
         }));
         const preSelected = DEVFLOW_PLUGINS
-            .filter(pl => !pl.optional && pl.name !== 'devflow-core-skills')
+            .filter(pl => !pl.optional && pl.name !== 'devflow-core-skills' && pl.name !== 'devflow-ambient')
             .map(pl => pl.name);
         const pluginSelection = await p.multiselect({
             message: 'Select plugins to install',
@@ -176,7 +176,7 @@ export const initCommand = new Command('init')
         const ambientChoice = await p.select({
             message: 'Enable ambient mode?',
             options: [
-                { value: true, label: 'Yes (Recommended)', hint: 'Auto-loads relevant skills for each prompt' },
+                { value: true, label: 'Yes (Recommended)', hint: 'Classifies intent, loads skills, orchestrates agents' },
                 { value: false, label: 'No', hint: 'Full control — load skills manually' },
             ],
         });
@@ -284,6 +284,10 @@ export const initCommand = new Command('init')
     if (pluginsToInstall.length > 0 && coreSkillsPlugin && !pluginsToInstall.includes(coreSkillsPlugin)) {
         pluginsToInstall = [coreSkillsPlugin, ...pluginsToInstall];
     }
+    const ambientPlugin = DEVFLOW_PLUGINS.find(p => p.name === 'devflow-ambient');
+    if (ambientEnabled && ambientPlugin && !pluginsToInstall.includes(ambientPlugin)) {
+        pluginsToInstall.push(ambientPlugin);
+    }
     const { skillsMap, agentsMap } = buildAssetMaps(pluginsToInstall);
     // Install: try native CLI first, fall back to file copy
     const cliAvailable = isClaudeCliAvailable();

package/dist/commands/uninstall.d.ts

@@ -9,5 +9,14 @@ export declare function computeAssetsToRemove(selectedPlugins: PluginDefinition[
     agents: string[];
     commands: string[];
 };
+/**
+ * Format a dry-run plan showing what would be removed.
+ * Pure function — no I/O, fully testable.
+ */
+export declare function formatDryRunPlan(assets: {
+    skills: string[];
+    agents: string[];
+    commands: string[];
+}, extras?: string[]): string;
 export declare const uninstallCommand: Command;
 //# sourceMappingURL=uninstall.d.ts.map

package/dist/commands/uninstall.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getInstallationPaths, getClaudeDirectory, getDevFlowDirectory, getManagedSettingsPath } from '../utils/paths.js';
@@ -46,13 +46,37 @@ export function computeAssetsToRemove(selectedPlugins, allPlugins) {
     }
     return { skills, agents, commands };
 }
+/**
+ * Format a dry-run plan showing what would be removed.
+ * Pure function — no I/O, fully testable.
+ */
+export function formatDryRunPlan(assets, extras) {
+    const skills = [...new Set(assets.skills)];
+    const agents = [...new Set(assets.agents)];
+    const commands = [...new Set(assets.commands)];
+    const hasAssets = skills.length > 0 || agents.length > 0 || commands.length > 0;
+    const hasExtras = extras && extras.length > 0;
+    if (!hasAssets && !hasExtras) {
+        return 'Nothing to remove.';
+    }
+    const lines = [];
+    if (skills.length > 0)
+        lines.push(`Skills (${skills.length}): ${skills.join(', ')}`);
+    if (agents.length > 0)
+        lines.push(`Agents (${agents.length}): ${agents.join(', ')}`);
+    if (commands.length > 0)
+        lines.push(`Commands (${commands.length}): ${commands.join(', ')}`);
+    if (hasExtras)
+        lines.push(`Extras: ${extras.join(', ')}`);
+    return lines.join('\n');
+}
 /**
  * Uninstall plugin using Claude CLI
  */
 function uninstallPluginViaCli(scope) {
     try {
         const cliScope = scope === 'local' ? 'project' : 'user';
-        execSync(`claude plugin uninstall devflow --scope ${cliScope}`, { stdio: 'inherit' });
+        execFileSync('claude', ['plugin', 'uninstall', 'devflow', '--scope', cliScope], { stdio: 'inherit' });
         return true;
     }
     catch {
@@ -77,8 +101,10 @@ export const uninstallCommand = new Command('uninstall')
     .option('--scope <type>', 'Uninstall from specific scope only (default: auto-detect all)', /^(user|local)$/i)
     .option('--plugin <names>', 'Uninstall specific plugin(s), comma-separated (e.g., implement,review)')
     .option('--verbose', 'Show detailed uninstall output')
+    .option('--dry-run', 'Show what would be removed without actually removing anything')
     .action(async (options) => {
-    p.intro(color.bgRed(color.white(' Uninstalling DevFlow ')));
+    const dryRun = options.dryRun ?? false;
+    p.intro(color.bgRed(color.white(dryRun ? ' DevFlow Uninstall (dry run) ' : ' Uninstalling DevFlow ')));
     const verbose = options.verbose ?? false;
     // Parse plugin selection
     let selectedPluginNames = [];
@@ -121,7 +147,7 @@ export const uninstallCommand = new Command('uninstall')
             p.log.info('Checked user scope (~/.claude/) and local scope (git-root/.claude/)');
             process.exit(1);
         }
-        if (scopesToUninstall.length > 1) {
+        if (scopesToUninstall.length > 1 && !dryRun) {
             if (process.stdin.isTTY) {
                 const scopeChoice = await p.select({
                     message: 'Found DevFlow in multiple scopes. Uninstall from:',
@@ -144,6 +170,36 @@ export const uninstallCommand = new Command('uninstall')
             }
         }
     }
+    // === DRY RUN: show plan and exit ===
+    if (dryRun) {
+        p.log.info(`Scope(s): ${scopesToUninstall.join(', ')} (dry-run shows all detected scopes)`);
+        const assets = isSelectiveUninstall
+            ? computeAssetsToRemove(selectedPlugins, DEVFLOW_PLUGINS)
+            : computeAssetsToRemove(DEVFLOW_PLUGINS, DEVFLOW_PLUGINS);
+        // Detect extras that would be cleaned up (full uninstall only)
+        const extras = [];
+        if (!isSelectiveUninstall) {
+            const docsDir = path.join(process.cwd(), '.docs');
+            const memoryDir = path.join(process.cwd(), '.memory');
+            try {
+                await fs.access(docsDir);
+                extras.push('.docs/');
+            }
+            catch { /* noop */ }
+            try {
+                await fs.access(memoryDir);
+                extras.push('.memory/');
+            }
+            catch { /* noop */ }
+            extras.push('hooks in settings.json', 'scripts in ~/.devflow/');
+        }
+        const plan = formatDryRunPlan(assets, extras.length > 0 ? extras : undefined);
+        for (const line of plan.split('\n')) {
+            p.log.info(line);
+        }
+        p.outro(color.dim('No changes made (dry run)'));
+        return;
+    }
     const cliAvailable = isClaudeCliAvailable();
     // Uninstall from each scope
     for (const scope of scopesToUninstall) {

package/dist/plugins.js

@@ -7,59 +7,59 @@
 export const DEVFLOW_PLUGINS = [
     {
         name: 'devflow-core-skills',
-        description: 'Auto-activating quality enforcement (foundation layer)',
+        description: 'Auto-activating quality enforcement skills - foundation layer for all DevFlow plugins',
         commands: [],
         agents: [],
         skills: ['core-patterns', 'docs-framework', 'git-safety', 'git-workflow', 'github-patterns', 'input-validation', 'search-first', 'test-driven-development', 'test-patterns'],
     },
     {
         name: 'devflow-specify',
-        description: 'Interactive feature specification',
+        description: 'Interactive feature specification - creates well-defined GitHub issues',
         commands: ['/specify'],
         agents: ['skimmer', 'synthesizer'],
         skills: ['agent-teams'],
     },
     {
         name: 'devflow-implement',
-        description: 'Complete task implementation workflow',
+        description: 'Complete task implementation workflow with exploration, planning, and coding',
         commands: ['/implement'],
         agents: ['git', 'skimmer', 'synthesizer', 'coder', 'simplifier', 'scrutinizer', 'shepherd', 'validator'],
-        skills: ['agent-teams', 'implementation-patterns', 'self-review'],
+        skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'self-review'],
     },
     {
         name: 'devflow-code-review',
-        description: 'Comprehensive code review',
+        description: 'Comprehensive code review with parallel specialized agents',
         commands: ['/code-review'],
         agents: ['git', 'reviewer', 'synthesizer'],
-        skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'],
+        skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'knowledge-persistence', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'],
     },
     {
         name: 'devflow-resolve',
-        description: 'Process and fix review issues',
+        description: 'Process and fix code review issues with risk assessment',
         commands: ['/resolve'],
         agents: ['git', 'resolver', 'simplifier'],
-        skills: ['agent-teams', 'implementation-patterns', 'security-patterns'],
+        skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'security-patterns'],
     },
     {
         name: 'devflow-debug',
-        description: 'Debugging with competing hypotheses',
+        description: 'Debugging workflows with competing hypothesis investigation using agent teams',
         commands: ['/debug'],
-        agents: ['git'],
-        skills: ['agent-teams', 'git-safety'],
+        agents: ['git', 'synthesizer'],
+        skills: ['agent-teams', 'git-safety', 'knowledge-persistence'],
     },
     {
         name: 'devflow-self-review',
-        description: 'Self-review workflow (Simplifier + Scrutinizer)',
+        description: 'Self-review workflow: Simplifier + Scrutinizer for code quality',
         commands: ['/self-review'],
         agents: ['simplifier', 'scrutinizer', 'validator'],
         skills: ['self-review', 'core-patterns'],
     },
     {
         name: 'devflow-ambient',
-        description: 'Ambient mode — auto-loads relevant skills based on each prompt',
+        description: 'Ambient mode — intent classification with proportional agent orchestration',
         commands: ['/ambient'],
-        agents: [],
-        skills: ['ambient-router'],
+        agents: ['coder', 'validator', 'simplifier', 'scrutinizer', 'shepherd', 'skimmer', 'reviewer'],
+        skills: ['ambient-router', 'implementation-orchestration', 'debug-orchestration', 'plan-orchestration'],
     },
     {
         name: 'devflow-audit-claude',
@@ -71,7 +71,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-typescript',
-        description: 'TypeScript language patterns (type safety, generics, utility types)',
+        description: 'TypeScript language patterns - type safety, generics, utility types, type guards',
         commands: [],
         agents: [],
         skills: ['typescript'],
@@ -79,7 +79,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-react',
-        description: 'React framework patterns (hooks, state, composition, performance)',
+        description: 'React framework patterns - hooks, state management, composition, performance',
         commands: [],
         agents: [],
         skills: ['react'],
@@ -87,7 +87,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-accessibility',
-        description: 'Web accessibility patterns (WCAG, ARIA, keyboard navigation)',
+        description: 'Web accessibility patterns - WCAG compliance, ARIA roles, keyboard navigation, focus management',
         commands: [],
         agents: [],
         skills: ['accessibility'],
@@ -95,7 +95,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-frontend-design',
-        description: 'Frontend design patterns (typography, color, spacing, motion)',
+        description: 'Frontend design patterns - typography, color systems, spacing, motion, responsive design',
         commands: [],
         agents: [],
         skills: ['frontend-design'],
@@ -103,7 +103,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-go',
-        description: 'Go language patterns (error handling, interfaces, concurrency)',
+        description: 'Go language patterns - error handling, interfaces, concurrency, package design',
         commands: [],
         agents: [],
         skills: ['go'],
@@ -111,7 +111,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-java',
-        description: 'Java language patterns (records, sealed classes, composition)',
+        description: 'Java language patterns - records, sealed classes, composition, modern Java features',
         commands: [],
         agents: [],
         skills: ['java'],
@@ -119,7 +119,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-python',
-        description: 'Python language patterns (type hints, protocols, data modeling)',
+        description: 'Python language patterns - type hints, protocols, dataclasses, async programming',
         commands: [],
         agents: [],
         skills: ['python'],
@@ -127,7 +127,7 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-rust',
-        description: 'Rust language patterns (ownership, error handling, type system)',
+        description: 'Rust language patterns - ownership, borrowing, error handling, type-driven design',
         commands: [],
         agents: [],
         skills: ['rust'],

package/dist/utils/post-install.js

@@ -425,11 +425,16 @@ export async function createMemoryDir(verbose, cwd) {
     const memoryDir = path.join(cwd ?? process.cwd(), '.memory');
     try {
         await fs.mkdir(memoryDir, { recursive: true });
+        await fs.mkdir(path.join(memoryDir, 'knowledge'), { recursive: true });
         if (verbose) {
             p.log.success('.memory/ directory ready');
         }
     }
-    catch { /* may already exist */ }
+    catch (e) {
+        if (verbose) {
+            p.log.warn(`Failed to create .memory/ directory: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
 }
 /**
  * Migrate memory files from .docs/ to .memory/.
@@ -443,7 +448,6 @@ export async function migrateMemoryFiles(verbose, cwd) {
     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;

package/package.json

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

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.5.0",
+  "version": "1.6.1",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

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

@@ -1,12 +1,33 @@
 {
   "name": "devflow-ambient",
-  "description": "Ambient mode — auto-loads relevant skills for every prompt",
+  "description": "Ambient mode — intent classification with proportional agent orchestration",
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.5.0",
-  "agents": [],
+  "version": "1.6.1",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": [
+    "ambient",
+    "intent",
+    "classification",
+    "orchestration",
+    "agents"
+  ],
+  "agents": [
+    "coder",
+    "validator",
+    "simplifier",
+    "scrutinizer",
+    "shepherd",
+    "skimmer",
+    "reviewer"
+  ],
   "skills": [
-    "ambient-router"
+    "ambient-router",
+    "implementation-orchestration",
+    "debug-orchestration",
+    "plan-orchestration"
   ]
 }

package/plugins/devflow-ambient/README.md

@@ -1,23 +1,8 @@
 # devflow-ambient
 
-Ambient mode — auto-loads relevant skills based on each prompt, no explicit commands needed.
+Ambient mode — classifies intent and applies proportional effort via a `UserPromptSubmit` hook. No slash command — ambient mode activates automatically on every prompt when enabled.
 
-## Command
-
-### `/ambient`
-
-Classify user intent and apply proportional skill enforcement to any prompt.
-
-```bash
-/ambient add a login form          # BUILD/GUIDED — loads TDD + implementation-patterns
-/ambient fix the auth error        # DEBUG/GUIDED — loads test-patterns + core-patterns
-/ambient where is the config?      # EXPLORE/QUICK — responds normally, zero overhead
-/ambient refactor the auth system  # BUILD/ELEVATE — suggests /implement
-```
-
-## Always-On Mode
-
-Enable ambient classification on every prompt without typing `/ambient`:
+## Activation
 
 ```bash
 devflow ambient --enable    # Register UserPromptSubmit hook
@@ -25,25 +10,59 @@ 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.
+When enabled, the hook injects a classification preamble before every prompt. Slash commands (`/implement`, `/code-review`, etc.) and short confirmations ("yes", "ok") are skipped automatically. Git operations (`commit`, `push`, `merge`, etc.) are fast-pathed to zero overhead.
 
 ## How It Works
 
-1. **Classify intent** — BUILD, DEBUG, REVIEW, PLAN, EXPLORE, or CHAT
-2. **Classify depth** — QUICK (zero overhead), GUIDED (2-3 skills), or ELEVATE (workflow nudge)
+1. **Classify intent** — IMPLEMENT, DEBUG, REVIEW, PLAN, EXPLORE, or CHAT
+2. **Classify depth** — QUICK, GUIDED, or ORCHESTRATED (scope-based)
 3. **Apply proportionally**:
-   - QUICK: respond normally
-   - GUIDED: load relevant skills, enforce TDD for BUILD
-   - ELEVATE: respond + recommend full workflow command
+   - QUICK: respond normally (zero overhead)
+   - GUIDED: load skills, implement in main session, spawn Simplifier after code changes
+   - ORCHESTRATED: load skills, orchestrate full agent pipeline
+
+## Three-Tier Classification
+
+| Depth | When | What Happens |
+|-------|------|-------------|
+| QUICK | Chat, exploration, git ops, config, trivial edits | Zero overhead — respond normally |
+| GUIDED | Small-scope IMPLEMENT (≤2 files), clear DEBUG, focused PLAN, REVIEW | Load skills → main session works → Simplifier cleanup |
+| ORCHESTRATED | Large-scope IMPLEMENT (>2 files), vague DEBUG, system-level PLAN | Load skills → spawn agent pipeline |
+
+### Intent × Depth Matrix
+
+| Intent | GUIDED | ORCHESTRATED |
+|--------|--------|-------------|
+| IMPLEMENT | ≤2 files, single module | >2 files, multi-module |
+| DEBUG | Clear error with stack trace/location | Vague/cross-cutting bug |
+| PLAN | Focused design question | System-level architecture |
+| REVIEW | Always GUIDED | — |
+
+## GUIDED Behavior
+
+Skills are loaded via the Skill tool and work happens in the main session:
+
+| Intent | Skills | Main Session Work | Post-Work |
+|--------|--------|-------------------|-----------|
+| IMPLEMENT | test-driven-development, implementation-patterns, search-first | Implement with TDD | `Task(subagent_type="Simplifier")` |
+| DEBUG | core-patterns, test-patterns | Investigate, diagnose, fix | `Task(subagent_type="Simplifier")` |
+| PLAN | implementation-patterns, core-patterns | Explore and design | — |
+| REVIEW | self-review, core-patterns | Review directly | — |
+
+## ORCHESTRATED Pipelines
 
-## Depth Tiers
+| Intent | Pipeline |
+|--------|----------|
+| IMPLEMENT | Pre-flight → Coder → Validator → Simplifier → Scrutinizer → Shepherd |
+| DEBUG | Hypotheses → parallel Explores → convergence → report → offer fix |
+| PLAN | Skimmer → Explores → Plan agent → gap validation |
 
-| Depth | When | Overhead |
-|-------|------|----------|
-| QUICK | Chat, simple exploration, git/devops ops, single-word confirmations | ~0 tokens |
-| GUIDED | BUILD/DEBUG/REVIEW/PLAN, 1-5 file scope | ~500-1000 tokens (skill reads) |
-| ELEVATE | Multi-file, architectural, system-wide scope | ~0 extra tokens (nudge only) |
+These are lightweight variants of `/implement`, `/debug`, and the Plan phase of `/implement` — focused on the immediate task without full lifecycle features (PR creation, knowledge persistence, retry loops).
 
 ## Skills
 
 - `ambient-router` — Intent + depth classification, skill selection matrix
+- `test-driven-development` — TDD enforcement for IMPLEMENT (GUIDED + ORCHESTRATED)
+- `implementation-orchestration` — Agent pipeline for IMPLEMENT/ORCHESTRATED
+- `debug-orchestration` — Agent pipeline for DEBUG/ORCHESTRATED
+- `plan-orchestration` — Agent pipeline for PLAN/ORCHESTRATED