feat(ambient): add agent orchestration to ambient mode

.claude-plugin/marketplace.json

@@ -91,7 +91,7 @@
     {
       "name": "devflow-ambient",
       "source": "./plugins/devflow-ambient",
-      "description": "Ambient mode — auto-loads relevant skills for every prompt",
+      "description": "Ambient mode — classifies intent and applies proportional effort (skills for guided work, agent orchestration for complex tasks)",
       "version": "1.5.0",
       "keywords": [
         "ambient",

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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
+
+### 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
+
+### 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

CLAUDE.md

@@ -22,7 +22,7 @@ Plugin marketplace with 17 plugins (8 core + 9 optional language/ecosystem), eac
 | `devflow-resolve` | Review issue resolution | Optional |
 | `devflow-debug` | Competing hypothesis debugging | Optional |
 | `devflow-self-review` | Self-review (Simplifier + Scrutinizer) | No |
-| `devflow-ambient` | Ambient mode — auto-loads relevant skills based on each prompt | No |
+| `devflow-ambient` | Ambient mode — three-tier intent classification (QUICK/GUIDED/ORCHESTRATED) | No |
 | `devflow-core-skills` | Auto-activating quality enforcement | No |
 | `devflow-audit-claude` | Audit CLAUDE.md files (optional) | No |
 | `devflow-typescript` | TypeScript language patterns (optional) | No |
@@ -44,7 +44,7 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 ```
 devflow/
-├── shared/skills/          # 32 skills (single source of truth)
+├── shared/skills/          # 35 skills (single source of truth)
 ├── shared/agents/          # 10 shared agents (single source of truth)
 ├── plugins/devflow-*/      # 17 plugins (8 core + 9 optional language/ecosystem)
 ├── docs/reference/         # Detailed reference documentation
@@ -113,7 +113,6 @@ Working memory files live in a dedicated `.memory/` directory:
 - `/resolve` — N Resolver agents + Git
 - `/debug` — Agent Teams competing hypotheses
 - `/self-review` — Simplifier then Scrutinizer (sequential)
-- `/ambient` — Intent classification + proportional skill loading (no agents, main session only)
 - `/audit-claude` — CLAUDE.md audit (optional plugin)
 
 **Shared agents** (10): git, synthesizer, skimmer, simplifier, coder, reviewer, resolver, shepherd, scrutinizer, validator

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
-- **32 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

docs/reference/skills-architecture.md

@@ -21,7 +21,7 @@ Shared patterns used by multiple agents.
 | `github-patterns` | GitHub API patterns (rate limiting, PR comments, issues, releases) | Git |
 | `implementation-patterns` | CRUD, API endpoints, events, config, logging | Coder, Resolver |
 | `agent-teams` | Agent Teams patterns for peer-to-peer collaboration, debate, consensus | /code-review, /implement, /debug |
-| `ambient-router` | Intent classification and proportional skill loading for ambient mode | `/ambient` command |
+| `ambient-router` | Intent classification and proportional skill loading for ambient mode | Ambient UserPromptSubmit hook |
 | `knowledge-persistence` | Record/load architectural decisions and pitfalls to `.memory/knowledge/` | /implement, /code-review, /resolve, /debug, /specify, /self-review |
 
 ### Tier 1b: Pattern Skills

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

@@ -1,6 +1,6 @@
 {
   "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"
   },
@@ -12,11 +12,22 @@
     "ambient",
     "intent",
     "classification",
-    "skills",
-    "auto-load"
+    "orchestration",
+    "agents"
+  ],
+  "agents": [
+    "coder",
+    "validator",
+    "simplifier",
+    "scrutinizer",
+    "shepherd",
+    "skimmer",
+    "reviewer"
   ],
-  "agents": [],
   "skills": [
-    "ambient-router"
+    "ambient-router",
+    "implementation-orchestration",
+    "debug-orchestration",
+    "plan-orchestration"
   ]
 }

plugins/devflow-ambient/README.md

@@ -1,49 +1,68 @@
 # 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
 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

scripts/hooks/ambient-prompt

@@ -30,15 +30,16 @@ if [ "$WORD_COUNT" -lt 2 ]; then
   exit 0
 fi
 
-# Inject classification preamble
-PREAMBLE="AMBIENT MODE ACTIVE: Before responding, silently classify this prompt:
-Intent: BUILD | DEBUG | REVIEW | PLAN | EXPLORE | CHAT
-Depth: QUICK (no overhead) | GUIDED (load skills) | ELEVATE (suggest /command)
+# Normalize to lowercase for matching
+PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
 
-If GUIDED+: Use the ambient-router skill already in your session context for classification details and skill selection matrix. Then Read the selected skills from ~/.claude/skills/<name>/SKILL.md and apply their patterns. For BUILD tasks, also load test-driven-development skill and enforce RED-GREEN-REFACTOR.
+# Fast-path: git operations are always QUICK — skip preamble
+if echo "$PROMPT_LOWER" | grep -qE '^(commit|push|pull|merge|rebase|cherry-pick|squash|tag|stash)|create (a )?pr|open (a )?pr'; then
+  exit 0
+fi
 
-If QUICK: Respond normally without stating classification.
-Only state classification aloud for GUIDED/ELEVATE."
+# Inject classification preamble
+PREAMBLE="AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification."
 
 jq -n --arg ctx "$PREAMBLE" '{
   "hookSpecificOutput": {

shared/agents/coder.md

@@ -2,7 +2,7 @@
 name: Coder
 description: Autonomous task implementation on feature branch. Implements, tests, and commits.
 model: inherit
-skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, input-validation
+skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, test-driven-development, search-first, input-validation
 ---
 
 # Coder Agent