devflow-kit 1.5.0 → 1.6.1

package/scripts/hooks/session-start-memory

@@ -2,7 +2,7 @@
 
 # SessionStart Hook
 # Injects working memory AND ambient skill content as additionalContext.
-# Memory: restores .memory/WORKING-MEMORY.md + patterns + git state + compact recovery.
+# Memory: restores .memory/WORKING-MEMORY.md + git state + compact recovery.
 # Ambient: injects ambient-router SKILL.md so Claude has it in context (no Read call needed).
 # Either section can fire independently — ambient works even without memory files.
 
@@ -27,13 +27,6 @@ MEMORY_FILE="$CWD/.memory/WORKING-MEMORY.md"
 if [ -f "$MEMORY_FILE" ]; then
   MEMORY_CONTENT=$(cat "$MEMORY_FILE")
 
-  # Read accumulated patterns if they exist
-  PATTERNS_FILE="$CWD/.memory/PROJECT-PATTERNS.md"
-  PATTERNS_CONTENT=""
-  if [ -f "$PATTERNS_FILE" ]; then
-    PATTERNS_CONTENT=$(cat "$PATTERNS_FILE")
-  fi
-
   # Compute staleness warning
   if stat --version &>/dev/null 2>&1; then
     FILE_MTIME=$(stat -c %Y "$MEMORY_FILE")
@@ -91,15 +84,6 @@ $BACKUP_MEMORY
 
 ${MEMORY_CONTENT}"
 
-  # Insert accumulated patterns between working memory and git state
-  if [ -n "$PATTERNS_CONTENT" ]; then
-    CONTEXT="${CONTEXT}
-
---- PROJECT PATTERNS (accumulated) ---
-
-${PATTERNS_CONTENT}"
-  fi
-
   CONTEXT="${CONTEXT}
 
 --- CURRENT GIT STATE ---
@@ -119,6 +103,31 @@ ${COMPACT_NOTE}"
   fi
 fi
 
+# --- Section 1.5: Project Knowledge TL;DR ---
+KNOWLEDGE_DIR="$CWD/.memory/knowledge"
+if [ -d "$KNOWLEDGE_DIR" ]; then
+  KNOWLEDGE_TLDR=""
+  for kf in "$KNOWLEDGE_DIR"/decisions.md "$KNOWLEDGE_DIR"/pitfalls.md; do
+    if [ -f "$kf" ]; then
+      TLDR_LINE=$(sed -n '1s/<!-- TL;DR: \(.*\) -->/\1/p' "$kf")
+      if [ -n "$TLDR_LINE" ]; then
+        KNOWLEDGE_TLDR="${KNOWLEDGE_TLDR}${TLDR_LINE}\n"
+      fi
+    fi
+  done
+  if [ -n "$KNOWLEDGE_TLDR" ]; then
+    KNOWLEDGE_SECTION="--- PROJECT KNOWLEDGE (TL;DR) ---
+$(printf '%b' "$KNOWLEDGE_TLDR")"
+    if [ -n "$CONTEXT" ]; then
+      CONTEXT="${CONTEXT}
+
+${KNOWLEDGE_SECTION}"
+    else
+      CONTEXT="$KNOWLEDGE_SECTION"
+    fi
+  fi
+fi
+
 # --- Section 2: Ambient Skill Injection ---
 
 # Inject ambient-router SKILL.md directly into context so Claude doesn't need a Read call.
@@ -129,10 +138,15 @@ AMBIENT_SKILL_PATH="$HOME/.claude/skills/ambient-router/SKILL.md"
 SETTINGS_FILE="$HOME/.claude/settings.json"
 if [ -f "$AMBIENT_SKILL_PATH" ] && [ -f "$SETTINGS_FILE" ] && grep -q "ambient-prompt" "$SETTINGS_FILE" 2>/dev/null; then
   AMBIENT_SKILL_CONTENT=$(cat "$AMBIENT_SKILL_PATH")
-  CONTEXT="${CONTEXT}
-
---- AMBIENT ROUTER (auto-loaded) ---
+  AMBIENT_SECTION="--- AMBIENT ROUTER (auto-loaded) ---
 ${AMBIENT_SKILL_CONTENT}"
+  if [ -n "$CONTEXT" ]; then
+    CONTEXT="${CONTEXT}
+
+${AMBIENT_SECTION}"
+  else
+    CONTEXT="$AMBIENT_SECTION"
+  fi
 fi
 
 # --- Output ---

package/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
@@ -35,6 +35,8 @@ You receive from orchestrator:
    - Cross-reference changed files against EXECUTION_PLAN to identify what's relevant to your task
    - Read those relevant files to understand interfaces, types, naming conventions, error handling, and testing patterns established by prior work
    - If PRIOR_PHASE_SUMMARY is provided, use it to validate your understanding — actual code is authoritative, summaries are supplementary
+   - If `.memory/knowledge/decisions.md` exists, read it. Apply prior architectural decisions relevant to this task. Avoid contradicting accepted decisions without documenting a new ADR.
+   - If `.memory/knowledge/pitfalls.md` exists, scan for pitfalls in files you're about to modify.
 
 2. **Load domain skills**: Based on DOMAIN hint and files in scope, dynamically load relevant language/ecosystem skills by reading their SKILL.md. Only load skills that are installed:
    - `backend` (TypeScript): Read `~/.claude/skills/typescript/SKILL.md`, `~/.claude/skills/input-validation/SKILL.md`
@@ -89,6 +91,9 @@ Return structured completion status:
 ### PR (if created)
 - URL: {pr_url}
 
+### Key Decisions (if any)
+- {Decision}: {rationale}
+
 ### Blockers (if any)
 {Description of blocker or failure with recommendation}
 ```

package/shared/agents/reviewer.md

@@ -42,15 +42,16 @@ The orchestrator provides:
 ## Responsibilities
 
 1. **Load focus skill** - Read the pattern skill file for your focus area from the table above. This gives you detection rules and patterns specific to your review type.
-2. **Identify changed lines** - Get diff against base branch (main/master/develop)
-3. **Apply 3-category classification** - Sort issues by where they occur
-4. **Apply focus-specific analysis** - Use pattern skill detection rules from the loaded skill file
-5. **Assign severity** - CRITICAL, HIGH, MEDIUM, LOW based on impact
-6. **Assess confidence** - Assign 0-100% confidence to each finding (see Confidence Scale below)
-7. **Filter by confidence** - Only report findings ≥80% in main sections; lower-confidence items go to Suggestions
-8. **Consolidate similar issues** - Group related findings to reduce noise (see Consolidation Rules)
-9. **Generate report** - File:line references with suggested fixes
-10. **Determine merge recommendation** - Based on blocking issues
+2. **Check known pitfalls** - If `.memory/knowledge/pitfalls.md` exists, read it. Check if any pitfall Areas overlap with files in the current diff. Verify the Resolution was applied. Flag if a known pitfall pattern is being reintroduced.
+3. **Identify changed lines** - Get diff against base branch (main/master/develop)
+4. **Apply 3-category classification** - Sort issues by where they occur
+5. **Apply focus-specific analysis** - Use pattern skill detection rules from the loaded skill file
+6. **Assign severity** - CRITICAL, HIGH, MEDIUM, LOW based on impact
+7. **Assess confidence** - Assign 0-100% confidence to each finding (see Confidence Scale below)
+8. **Filter by confidence** - Only report findings ≥80% in main sections; lower-confidence items go to Suggestions
+9. **Consolidate similar issues** - Group related findings to reduce noise (see Consolidation Rules)
+10. **Generate report** - File:line references with suggested fixes
+11. **Determine merge recommendation** - Based on blocking issues
 
 ## Confidence Scale
 

package/shared/agents/simplifier.md

@@ -1,6 +1,7 @@
 ---
 name: Simplifier
 description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
+skills: core-patterns
 model: inherit
 ---
 
@@ -59,4 +60,34 @@ Your refinement process:
 5. Verify the refined code is simpler and more maintainable
 6. Document only significant changes that affect understanding
 
-You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.
+You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.
+
+## Output
+
+Return structured completion status:
+
+```markdown
+## Simplification Report
+
+### Changes Applied
+- {file}: {description of simplification}
+
+### Changes Skipped
+- {reason not simplified — would change behavior / already clean}
+
+### Files Modified
+- {file} ({change description})
+```
+
+## Boundaries
+
+**Escalate to orchestrator:**
+- Changes that would alter observable behavior or break tests
+- Simplifications requiring new dependencies or architectural changes
+- Files outside the recently modified scope (unless instructed)
+
+**Handle autonomously:**
+- Naming improvements, dead code removal, nesting reduction
+- Import sorting and organization
+- Redundant abstraction elimination
+- Comment cleanup (remove obvious, keep non-obvious)

package/shared/agents/skimmer.md

@@ -1,6 +1,7 @@
 ---
 name: Skimmer
 description: Codebase orientation using skim to identify relevant files, functions, and patterns for a feature or task
+skills: knowledge-persistence
 model: inherit
 ---
 
@@ -20,6 +21,7 @@ You receive from orchestrator:
 3. **Search for task-relevant code** - Find files matching task keywords
 4. **Identify integration points** - Exports, entry points, import patterns
 5. **Generate orientation summary** - Structured output for implementation planning
+6. **Check project knowledge** - If `.memory/knowledge/decisions.md` exists, read its `<!-- TL;DR: ... -->` first-line comment and include active decision count in orientation under "### Active Decisions". Only the TL;DR is read here (not full entries) — this is intentional for token efficiency; agents that need full entries read the file themselves.
 
 ## Tool Invocation
 
@@ -64,6 +66,9 @@ Always invoke skim via `npx rskim`. This works whether or not skim is globally i
 ### Patterns Observed
 {Existing patterns to follow}
 
+### Active Decisions
+{Count and key decisions from `.memory/knowledge/decisions.md` TL;DR, or "None found" if file missing}
+
 ### Suggested Approach
 {Brief recommendation based on codebase structure}
 ```

package/shared/skills/ambient-router/SKILL.md

@@ -1,25 +1,23 @@
 ---
 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.
+description: This skill should be used when classifying user intent for ambient mode, auto-loading relevant skills without explicit command invocation. Used by the always-on UserPromptSubmit hook.
 user-invocable: false
-allowed-tools: Read, Grep, Glob
+# No allowed-tools: orchestrator requires unrestricted access (Skill, Agent, Edit, Write, Bash)
 ---
 
 # 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.
+Classify user intent and auto-load relevant skills. Zero overhead for simple requests, skill loading + optional agent orchestration for substantive work.
 
 ## Iron Law
 
-> **PROPORTIONAL RESPONSE**
+> **PROPORTIONAL RESPONSE MATCHED TO SCOPE**
 >
-> 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.
+> QUICK gets zero overhead. GUIDED gets skill loading + main session implementation
+> with Simplifier cleanup. ORCHESTRATED gets full skill loading via the Skill tool plus
+> agent pipeline execution. Misclassification in either direction is a failure —
+> false-positive ORCHESTRATED is expensive (5-6 agent spawns), false-negative
+> GUIDED leaves quality on the table.
 
 ---
 
@@ -29,14 +27,14 @@ 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" |
+| **IMPLEMENT** | "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/GUIDED. Git operations like "commit this" → QUICK.
+**Ambiguous prompts:** Default to the lowest-overhead classification. "Update the README" → QUICK. Git operations like "commit this" → QUICK.
 
 ## Step 2: Classify Depth
 
@@ -44,44 +42,90 @@ 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. |
-| **GUIDED** | 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. |
-| **ELEVATE** | 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." |
+| **QUICK** | CHAT intent. EXPLORE intent. Git/devops operations (commit, push, merge, branch, pr, deploy, reinstall). Single-word continuations. Small edits, config changes, trivial single-file tweaks. | Respond normally. Zero overhead. Do not state classification. |
+| **GUIDED** | IMPLEMENT with small scope (≤2 files, single module). DEBUG with clear error location (stack trace, specific file, known function). PLAN for focused design questions (specific area/pattern). REVIEW (always GUIDED). | Load skills via Skill tool. Main session implements directly. Spawn Simplifier after code changes. State classification. |
+| **ORCHESTRATED** | IMPLEMENT with larger scope (>2 files, multi-module, complex). DEBUG with vague/cross-cutting bug (no clear location, multiple possible causes). PLAN for system-level architecture (caching layer, auth system, multi-module design). | Load skills via Skill tool, then orchestrate agents per Step 5. State classification. |
 
-## Step 3: Select Skills (GUIDED depth only)
+**Scope-based decision criteria:**
 
-Based on classified intent, read the following skills to inform your response.
+| Intent | GUIDED (small scope) | ORCHESTRATED (large scope) |
+|--------|---------------------|---------------------------|
+| **IMPLEMENT** | ≤2 files, single module, clear task | >2 files, multi-module, complex |
+| **DEBUG** | Clear error with known location (stack trace, specific file) | Vague/cross-cutting bug, multiple possible causes |
+| **PLAN** | Focused question about specific area/pattern | System-level architecture, multi-module design |
+| **REVIEW** | Always GUIDED | — |
+
+**Classification conservatism:** Default to QUICK. Only classify GUIDED/ORCHESTRATED when the prompt has clear task scope. When choosing between GUIDED and ORCHESTRATED, prefer GUIDED — escalate only when scope clearly exceeds main-session capacity.
+
+## Step 3: Select Skills
+
+Based on classified intent and depth, invoke each selected skill using the Skill tool.
+
+### GUIDED-depth skills
 
 | Intent | Primary Skills | Secondary (if file type matches) |
 |--------|---------------|----------------------------------|
-| **BUILD** | test-driven-development, implementation-patterns, search-first | 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) |
+| **IMPLEMENT** | test-driven-development, implementation-patterns, search-first | 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** | core-patterns, test-patterns | git-safety (if git operations involved) |
+| **PLAN** | implementation-patterns, core-patterns | — |
 | **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.
+### ORCHESTRATED-depth skills
+
+| Intent | Primary Skills | Secondary (if file type matches) |
+|--------|---------------|----------------------------------|
+| **IMPLEMENT** | implementation-orchestration, 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** | debug-orchestration, core-patterns | git-safety (if git operations involved) |
+| **PLAN** | plan-orchestration, 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, performance-patterns.
 
 See `references/skill-catalog.md` for the full skill-to-intent mapping with file pattern triggers.
 
 ## Step 4: Apply
 
 <IMPORTANT>
-When classification is GUIDED or ELEVATE, skill application is NON-NEGOTIABLE.
+When classification is GUIDED or ORCHESTRATED, skill loading is NON-NEGOTIABLE.
 Do not rationalize skipping skills. Do not respond without loading them first.
-If test-driven-development is selected, you MUST write the failing test before ANY production code.
+BLOCKING REQUIREMENT: Invoke each selected skill using the Skill tool before proceeding.
+For IMPLEMENT intent, enforce TDD: write the failing test before ANY production code.
+NOTE: Skills loaded in the main session via ambient mode are reference patterns only —
+their allowed-tools metadata does NOT restrict your tool access. You retain full access
+to all tools (Edit, Write, Bash, Agent, etc.) for implementation work.
 </IMPORTANT>
 
 - **QUICK:** Respond directly. No preamble, no classification statement.
-- **GUIDED:** State classification briefly: `Ambient: BUILD/GUIDED. Loading: test-driven-development, implementation-patterns.` Then read the selected skills and apply their patterns. No exceptions.
-- **ELEVATE:** Respond with your best effort, then append: `> This task spans multiple files/systems. Consider \`/implement\` for full lifecycle.`
+- **GUIDED:** State classification briefly: `Ambient: IMPLEMENT/GUIDED. Loading: implementation-patterns, search-first.` Then invoke each skill using the Skill tool and work directly in main session. After code changes, spawn Simplifier on changed files.
+- **ORCHESTRATED:** State classification briefly: `Ambient: IMPLEMENT/ORCHESTRATED. Loading: implementation-orchestration, implementation-patterns.` Then invoke each skill using the Skill tool and follow Step 5 for agent orchestration.
+
+### GUIDED Behavior by Intent
+
+| Intent | Main Session Work | Post-Work |
+|--------|------------------|-----------|
+| **IMPLEMENT** | Implement directly with loaded skills. Follow TDD cycle. | Spawn Simplifier on changed files. |
+| **DEBUG** | Investigate directly — reproduce bug, diagnose from stack trace/error, fix. | Spawn Simplifier on changed files. |
+| **PLAN** | Explore relevant code and design directly. The area is focused enough for main session. | No Simplifier (no code changes). |
+| **REVIEW** | Review directly with loaded skills. | No Simplifier. |
+
+## Step 5: Orchestrate Agents (ORCHESTRATED depth only)
+
+After loading skills via Step 3-4, execute the agent pipeline for the classified intent:
+
+| Intent | Pipeline |
+|--------|----------|
+| **IMPLEMENT** | Follow implementation-orchestration skill pipeline: pre-flight → plan synthesis → Coder → quality gates |
+| **DEBUG** | Follow debug-orchestration skill pipeline: hypotheses → parallel Explores → convergence → report → offer fix |
+| **PLAN** | Follow plan-orchestration skill pipeline: Skimmer → Explores → Plan agent → gap validation |
+| **EXPLORE** | No agents — respond in main session |
+| **CHAT** | No agents — respond in main session |
 
 ---
 
 ## Transparency Rules
 
 1. **QUICK → silent.** No classification output.
-2. **GUIDED → brief statement + full skill enforcement.** One line: intent, depth, skills loaded. Then follow every skill requirement without shortcuts.
-3. **ELEVATE → recommendation.** Best-effort response + workflow nudge.
+2. **GUIDED → brief statement + full skill enforcement.** One line: intent, depth, skills loaded. Then implement in main session with skill patterns applied.
+3. **ORCHESTRATED → brief statement + full skill enforcement + agent orchestration.** One line: intent, depth, skills loaded. Then follow every skill requirement and orchestrate agents per Step 5.
 4. **Never lie about classification.** If uncertain, say so.
 5. **Never over-classify.** When in doubt, go one tier lower.
 6. **Never under-apply.** Rationalization is the enemy of quality. If a skill requires a step, do the step.
@@ -90,7 +134,10 @@ If test-driven-development is selected, you MUST write the failing test before A
 
 | Case | Handling |
 |------|----------|
-| Mixed intent ("fix this bug and add a test") | Use the higher-overhead intent (BUILD > DEBUG) |
+| Mixed intent ("fix this bug and add a test") | Use the higher-overhead intent (IMPLEMENT > 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 |
+| Scope ambiguous between GUIDED and ORCHESTRATED | Default to GUIDED; escalate if complexity emerges during work |
+| REVIEW intent | Always GUIDED — single Reviewer focus, no orchestration pipeline |
+| Multiple triggers per session | Each runs independently; context compaction handles accumulation |

package/shared/skills/ambient-router/references/skill-catalog.md

@@ -4,47 +4,50 @@ Full mapping of DevFlow skills to ambient intents and file-type triggers. The am
 
 ## Skills Available for Ambient Loading
 
-These skills may be loaded during GUIDED-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 |
-| search-first | 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 |
+These skills may be loaded during GUIDED and ORCHESTRATED-depth ambient routing.
+
+### IMPLEMENT Intent
+
+| Skill | When to Load | Depth | File Patterns |
+|-------|-------------|-------|---------------|
+| implementation-orchestration | ORCHESTRATED only | ORCHESTRATED | Any — orchestrates agent pipeline |
+| test-driven-development | Always for IMPLEMENT | GUIDED + ORCHESTRATED | Any code file — enforces RED-GREEN-REFACTOR |
+| implementation-patterns | Always for IMPLEMENT | GUIDED + ORCHESTRATED | Any code file |
+| search-first | Always for IMPLEMENT | GUIDED + ORCHESTRATED | Any — enforces research before building |
+| typescript | TypeScript files in scope | GUIDED + ORCHESTRATED | `*.ts`, `*.tsx` |
+| react | React components in scope | GUIDED + ORCHESTRATED | `*.tsx`, `*.jsx` |
+| frontend-design | UI/styling work | GUIDED + ORCHESTRATED | `*.css`, `*.scss`, `*.tsx` with styling keywords |
+| input-validation | Forms, APIs, user input | GUIDED + ORCHESTRATED | Files with form/input/validation keywords |
+| go | Go files in scope | GUIDED + ORCHESTRATED | `*.go` |
+| java | Java files in scope | GUIDED + ORCHESTRATED | `*.java` |
+| python | Python files in scope | GUIDED + ORCHESTRATED | `*.py` |
+| rust | Rust files in scope | GUIDED + ORCHESTRATED | `*.rs` |
+| security-patterns | Auth, crypto, secrets | GUIDED + ORCHESTRATED | 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. |
+| Skill | When to Load | Depth | File Patterns |
+|-------|-------------|-------|---------------|
+| debug-orchestration | ORCHESTRATED only | ORCHESTRATED | Any — orchestrates investigation pipeline |
+| core-patterns | Always for DEBUG | GUIDED + ORCHESTRATED | Any code file |
+| test-patterns | Always for DEBUG (GUIDED) | GUIDED | Any code file |
+| git-safety | Git operations involved | GUIDED + ORCHESTRATED | 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.*` |
+| Skill | When to Load | Depth | File Patterns |
+|-------|-------------|-------|---------------|
+| self-review | Always for REVIEW | GUIDED | Any code file |
+| core-patterns | Always for REVIEW | GUIDED | Any code file |
+| test-patterns | Test files in scope | GUIDED | `*.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 |
+| Skill | When to Load | Depth | File Patterns |
+|-------|-------------|-------|---------------|
+| plan-orchestration | ORCHESTRATED only | ORCHESTRATED | Any — orchestrates design pipeline |
+| implementation-patterns | Always for PLAN | GUIDED + ORCHESTRATED | Any planning context |
+| core-patterns | Always for PLAN | GUIDED + ORCHESTRATED | System design discussions |
 
 ## Skills Excluded from Ambient
 
@@ -63,7 +66,9 @@ These skills are loaded only by explicit DevFlow commands (primarily `/code-revi
 
 ## Selection Limits
 
-- **Maximum 3 skills** per ambient response (primary + up to 2 secondary)
-- **Primary skills** are always loaded for the classified intent
+- **Maximum 3 knowledge skills** per ambient response (primary + up to 2 secondary)
+- **Orchestration skills** (implementation-orchestration, debug-orchestration, plan-orchestration) are loaded only at ORCHESTRATED depth — they don't count toward the knowledge skill limit
+- **Primary skills** are always loaded for the classified intent at both GUIDED and ORCHESTRATED depth
 - **Secondary skills** are loaded only when file patterns match conversation context
-- If more than 3 skills seem relevant, this is an ELEVATE signal
+- **GUIDED depth** loads knowledge skills only (no orchestration skills) — main session works directly
+- **ORCHESTRATED depth** loads orchestration skill + knowledge skills — agents execute the pipeline

package/shared/skills/debug-orchestration/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: debug-orchestration
+description: Agent orchestration for DEBUG intent — hypothesis investigation, root cause analysis, optional fix
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion
+---
+
+# Debug Orchestration
+
+Agent pipeline for DEBUG intent in ambient ORCHESTRATED mode. Competing hypothesis investigation, parallel evidence gathering, convergence validation, and optional fix.
+
+This is a lightweight variant of `/debug` for ambient ORCHESTRATED mode. Excluded: knowledge persistence loading, GitHub issue fetching, pitfall recording.
+
+## Iron Law
+
+> **COMPETING HYPOTHESES BEFORE CONCLUSIONS**
+>
+> Never investigate a single theory. Generate 3-5 distinct hypotheses, investigate them
+> in parallel, and let evidence determine the root cause. Confirmation bias is the enemy
+> of debugging — multiple hypotheses are the antidote.
+
+---
+
+## Phase 1: Hypothesize
+
+Analyze the bug description, error messages, and conversation context. Generate 3-5 hypotheses that are:
+
+- **Specific**: Points to a concrete mechanism (not "something is wrong with auth")
+- **Testable**: Can be confirmed or disproved by examining specific files/logs
+- **Distinct**: Each hypothesis proposes a different root cause
+
+If fewer than 3 hypotheses are possible, proceed with 2.
+
+## Phase 2: Investigate (Parallel)
+
+Spawn one `Task(subagent_type="Explore")` per hypothesis **in a single message** (parallel execution):
+
+- Each investigator searches for evidence FOR and AGAINST its hypothesis
+- Must provide file:line references for all evidence
+- Returns verdict: **CONFIRMED** | **DISPROVED** | **PARTIAL** (some evidence supports, some contradicts)
+
+## Phase 3: Converge
+
+Evaluate investigation results:
+
+- **One CONFIRMED**: Spawn 1-2 additional `Task(subagent_type="Explore")` agents to validate from different angles (prevent confirmation bias)
+- **Multiple PARTIAL**: Look for a unifying root cause that explains all partial evidence
+- **All DISPROVED**: Report honestly — "No root cause identified from initial hypotheses." Generate 2-3 second-round hypotheses if conversation context suggests avenues not yet explored.
+
+## Phase 4: Report
+
+Present root cause analysis:
+
+- **Confidence level**: HIGH (confirmed + validated) | MEDIUM (partial convergence) | LOW (best guess from incomplete evidence)
+- **Evidence table**: Hypothesis → verdict → key evidence (file:line)
+- **Root cause**: Clear statement of what's wrong and why
+- **Recommended fix**: Specific changes with file references
+
+## Phase 5: Offer Fix
+
+Ask user via AskUserQuestion: "Want me to implement this fix?"
+
+- **YES** → Implement the fix directly in main session using GUIDED approach: load implementation-patterns, search-first, and test-driven-development skills, then code the fix. Spawn `Task(subagent_type="Simplifier")` on changed files after.
+- **NO** → Done. Report stands as documentation.
+
+## Error Handling
+
+- **All hypotheses disproved, no second-round ideas**: Report "No root cause identified" with summary of what was investigated and ruled out
+- **Explore agents return insufficient evidence**: Report LOW confidence with available evidence, suggest manual investigation areas

package/shared/skills/docs-framework/SKILL.md

@@ -38,8 +38,10 @@ All generated documentation lives under `.docs/` in the project root:
 
 .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
+├── backup.json                         # Pre-compact git state snapshot
+└── knowledge/
+    ├── decisions.md                    # Architectural decisions (ADR-NNN format)
+    └── pitfalls.md                     # Known pitfalls (PF-NNN format)
 ```
 
 ---
@@ -97,6 +99,8 @@ source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
 |-------|-----------------|----------|
 | Reviewer | `.docs/reviews/{branch-slug}/{type}-report.{timestamp}.md` | Creates new |
 | Working Memory | `.memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
+| Knowledge (decisions) | `.memory/knowledge/decisions.md` | Append-only (ADR-NNN sequential IDs) |
+| Knowledge (pitfalls) | `.memory/knowledge/pitfalls.md` | Append-only (PF-NNN sequential IDs) |
 
 ### Agents That Don't Persist
 
@@ -125,6 +129,7 @@ When creating or modifying persisting agents:
 This framework is used by:
 - **Review agents**: Creates review reports
 - **Working Memory hooks**: Auto-maintains `.memory/WORKING-MEMORY.md`
+- **Command flows**: `/implement` appends ADRs to `decisions.md`; `/code-review`, `/debug`, `/resolve` append PFs to `pitfalls.md`
 
 All persisting agents should load this skill to ensure consistent documentation.