devflow-kit 1.0.0 → 1.2.0

package/scripts/hooks/ambient-prompt.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Ambient Mode: UserPromptSubmit Hook
+# Injects a classification preamble before every user prompt so Claude applies
+# relevant skill loading via the ambient-router skill.
+# Zero file I/O beyond stdin — static injection only.
+
+set -euo pipefail
+
+# jq is required to parse hook input JSON — silently no-op if missing
+if ! command -v jq &>/dev/null; then exit 0; fi
+
+INPUT=$(cat)
+
+CWD=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null)
+if [ -z "$CWD" ]; then
+  exit 0
+fi
+
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null)
+
+# Skip slash commands — they have their own orchestration
+if [[ "$PROMPT" == /* ]]; then
+  exit 0
+fi
+
+# Skip single-word confirmations (< 2 words)
+WORD_COUNT=$(echo "$PROMPT" | wc -w | tr -d ' ')
+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) | STANDARD (load skills) | ESCALATE (suggest /command)
+
+If STANDARD+: Read the ambient-router skill for classification details and skill selection matrix. For BUILD tasks, also load test-driven-development skill and enforce RED-GREEN-REFACTOR.
+
+If QUICK: Respond normally without stating classification.
+Only state classification aloud for STANDARD/ESCALATE."
+
+jq -n --arg ctx "$PREAMBLE" '{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": $ctx
+  }
+}'

package/scripts/hooks/background-memory-update.sh

@@ -2,7 +2,7 @@
 
 # Background Working Memory Updater
 # Called by stop-update-memory.sh as a detached background process.
-# Resumes the parent session headlessly to update .docs/WORKING-MEMORY.md.
+# Resumes the parent session headlessly to update .memory/WORKING-MEMORY.md.
 # On failure: logs error, does nothing (no fallback).
 
 set -euo pipefail
@@ -12,8 +12,8 @@ SESSION_ID="$2"
 MEMORY_FILE="$3"
 CLAUDE_BIN="$4"
 
-LOG_FILE="$CWD/.docs/.working-memory-update.log"
-LOCK_DIR="$CWD/.docs/.working-memory.lock"
+LOG_FILE="$CWD/.memory/.working-memory-update.log"
+LOCK_DIR="$CWD/.memory/.working-memory.lock"
 
 # --- Logging ---
 
@@ -102,20 +102,60 @@ fi
 
 # Build instruction
 if [ -n "$EXISTING_MEMORY" ]; then
-  INSTRUCTION="Update the file $MEMORY_FILE with working memory from this session. The file already has content — possibly from a concurrent session that just wrote it moments ago. Merge this session's context with the existing content to produce a single unified working memory snapshot. Both this session and the existing content represent fresh, concurrent work — integrate both fully. Working memory captures what's active now, not a changelog. Deduplicate overlapping information. Keep under 100 lines total. Use the same structure: ## Now, ## Decisions, ## Modified Files, ## Context, ## Session Log.
+  PATTERNS_INSTRUCTION=""
+PATTERNS_FILE="$CWD/.memory/PROJECT-PATTERNS.md"
+EXISTING_PATTERNS=""
+if [ -f "$PATTERNS_FILE" ]; then
+  EXISTING_PATTERNS=$(cat "$PATTERNS_FILE")
+  PATTERNS_INSTRUCTION="
+
+Also update $PATTERNS_FILE by APPENDING any new recurring patterns discovered during this session. Do NOT overwrite existing entries — only add new ones. Skip if no new patterns were observed. Format each entry as: - **Pattern name**: Brief description (discovered: YYYY-MM-DD). Keep patterns.md under 40 entries. When approaching the limit, consolidate related patterns into broader entries rather than adding duplicates.
+
+Existing patterns:
+$EXISTING_PATTERNS"
+else
+  PATTERNS_INSTRUCTION="
+
+If recurring patterns were observed during this session (coding conventions, architectural decisions, team preferences, tooling quirks), create $PATTERNS_FILE with entries formatted as: - **Pattern name**: Brief description (discovered: YYYY-MM-DD). Only create this file if genuine patterns were observed — do not fabricate entries."
+fi
+
+INSTRUCTION="Update the file $MEMORY_FILE with working memory from this session. The file already has content — possibly from a concurrent session that just wrote it moments ago. Merge this session's context with the existing content to produce a single unified working memory snapshot. Both this session and the existing content represent fresh, concurrent work — integrate both fully. Working memory captures what's active now, not a changelog. Deduplicate overlapping information. Keep under 120 lines total. Use the same structure: ## Now, ## Progress, ## Decisions, ## Modified Files, ## Context, ## Session Log.
+
+## Progress tracks Done (completed items), Remaining (next steps), and Blockers (if any). Keep each sub-list to 1-3 items. This section reflects current work state, not historical logs.
+
+## Decisions entries must include date and status. Format: - **[Decision]** — [rationale] (YYYY-MM-DD) [ACTIVE|SUPERSEDED]. Mark superseded decisions rather than deleting them.${PATTERNS_INSTRUCTION}
 
 Existing content:
 $EXISTING_MEMORY"
 else
-  INSTRUCTION="Create the file $MEMORY_FILE with working memory from this session. Keep under 100 lines. Use this structure:
+  PATTERNS_INSTRUCTION=""
+  PATTERNS_FILE="$CWD/.memory/PROJECT-PATTERNS.md"
+  if [ -f "$PATTERNS_FILE" ]; then
+    EXISTING_PATTERNS=$(cat "$PATTERNS_FILE")
+    PATTERNS_INSTRUCTION="
+
+Also update $PATTERNS_FILE by APPENDING any new recurring patterns discovered during this session. Do NOT overwrite existing entries — only add new ones. Skip if no new patterns were observed. Format each entry as: - **Pattern name**: Brief description (discovered: YYYY-MM-DD). Keep patterns.md under 40 entries. When approaching the limit, consolidate related patterns into broader entries rather than adding duplicates.
+
+Existing patterns:
+$EXISTING_PATTERNS"
+  else
+    PATTERNS_INSTRUCTION="
+
+If recurring patterns were observed during this session (coding conventions, architectural decisions, team preferences, tooling quirks), create $PATTERNS_FILE with entries formatted as: - **Pattern name**: Brief description (discovered: YYYY-MM-DD). Only create this file if genuine patterns were observed — do not fabricate entries."
+  fi
+
+  INSTRUCTION="Create the file $MEMORY_FILE with working memory from this session. Keep under 120 lines. Use this structure:
 
 # Working Memory
 
 ## Now
 <!-- Current focus, status, blockers (1-3 bullets) -->
 
+## Progress
+<!-- Done: completed items (1-3). Remaining: next steps (1-3). Blockers: if any. -->
+
 ## Decisions
-<!-- Key decisions made this session with brief rationale -->
+<!-- Format: - **[Decision]** — [rationale] (YYYY-MM-DD) [ACTIVE|SUPERSEDED] -->
 
 ## Modified Files
 <!-- File paths only, most recent first -->
@@ -129,7 +169,7 @@ else
 <!-- Chronological summary of work done today (2-5 bullets) -->
 
 ### This Week
-<!-- Broader multi-day context if relevant -->"
+<!-- Broader multi-day context if relevant -->${PATTERNS_INSTRUCTION}"
 fi
 
 # Resume session headlessly to perform the update
@@ -138,7 +178,8 @@ TIMEOUT=120  # Normal runtime 30-60s; 2x margin
 DEVFLOW_BG_UPDATER=1 env -u CLAUDECODE "$CLAUDE_BIN" -p \
   --resume "$SESSION_ID" \
   --model haiku \
-  --dangerously-skip-permissions \
+  --tools "Write" \
+  --allowedTools "Write($CWD/.memory/WORKING-MEMORY.md)" "Write($CWD/.memory/PROJECT-PATTERNS.md)" \
   --no-session-persistence \
   --output-format text \
   "$INSTRUCTION" \

package/scripts/hooks/ensure-memory-gitignore.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Ensures .memory/ exists and .gitignore entries are configured.
+# Called from stop and pre-compact hooks. Idempotent, ~1μs after first run.
+# Usage: source ensure-memory-gitignore.sh "$CWD"
+
+_MEMORY_DIR="$1/.memory"
+
+# Create .memory/ if needed
+mkdir -p "$_MEMORY_DIR" 2>/dev/null || return 1
+
+# One-time .gitignore setup (marker prevents repeated checks)
+if [ ! -f "$_MEMORY_DIR/.gitignore-configured" ] && [ -e "$1/.git" ]; then
+  for _entry in ".memory/" ".docs/"; do
+    grep -qxF "$_entry" "$1/.gitignore" 2>/dev/null || echo "$_entry" >> "$1/.gitignore"
+  done
+  touch "$_MEMORY_DIR/.gitignore-configured"
+fi

package/scripts/hooks/pre-compact-memory.sh

@@ -18,12 +18,10 @@ if [ -z "$CWD" ]; then
   exit 0
 fi
 
-# Only activate in DevFlow-initialized projects
-if [ ! -d "$CWD/.docs" ]; then
-  exit 0
-fi
+# Auto-create .memory/ and ensure .gitignore entries (idempotent after first run)
+source "$(cd "$(dirname "$0")" && pwd)/ensure-memory-gitignore.sh" "$CWD" || exit 0
 
-BACKUP_FILE="$CWD/.docs/working-memory-backup.json"
+BACKUP_FILE="$CWD/.memory/backup.json"
 
 # Capture git state
 GIT_BRANCH=""
@@ -39,6 +37,12 @@ if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
   GIT_DIFF_STAT=$(git diff --stat HEAD 2>/dev/null || echo "")
 fi
 
+# Snapshot current WORKING-MEMORY.md (preserves session context through compaction)
+MEMORY_SNAPSHOT=""
+if [ -f "$CWD/.memory/WORKING-MEMORY.md" ]; then
+  MEMORY_SNAPSHOT=$(cat "$CWD/.memory/WORKING-MEMORY.md")
+fi
+
 # Write backup JSON
 jq -n \
   --arg ts "$TIMESTAMP" \
@@ -46,9 +50,11 @@ jq -n \
   --arg status "$GIT_STATUS" \
   --arg log "$GIT_LOG" \
   --arg diff "$GIT_DIFF_STAT" \
+  --arg memory "$MEMORY_SNAPSHOT" \
   '{
     timestamp: $ts,
     trigger: "pre-compact",
+    memory_snapshot: $memory,
     git: {
       branch: $branch,
       status: $status,
@@ -59,7 +65,7 @@ jq -n \
 
 # Bootstrap minimal WORKING-MEMORY.md if none exists yet
 # This ensures SessionStart has context to inject after compaction
-MEMORY_FILE="$CWD/.docs/WORKING-MEMORY.md"
+MEMORY_FILE="$CWD/.memory/WORKING-MEMORY.md"
 if [ ! -f "$MEMORY_FILE" ] && [ -n "$GIT_BRANCH" ]; then
   {
     echo "# Working Memory"

package/scripts/hooks/session-start-memory.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Working Memory: SessionStart Hook
-# Reads .docs/WORKING-MEMORY.md and injects it as additionalContext for the new session.
+# Reads .memory/WORKING-MEMORY.md and injects it as additionalContext for the new session.
 # Also captures fresh git state so Claude knows what's changed since the memory was written.
 # Adds staleness warning if memory is >1 hour old.
 
@@ -17,12 +17,7 @@ if [ -z "$CWD" ]; then
   exit 0
 fi
 
-# Only activate in DevFlow-initialized projects
-if [ ! -d "$CWD/.docs" ]; then
-  exit 0
-fi
-
-MEMORY_FILE="$CWD/.docs/WORKING-MEMORY.md"
+MEMORY_FILE="$CWD/.memory/WORKING-MEMORY.md"
 
 # No memory file = nothing to restore (fresh project or first session)
 if [ ! -f "$MEMORY_FILE" ]; then
@@ -31,6 +26,13 @@ fi
 
 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")
@@ -40,6 +42,30 @@ fi
 NOW=$(date +%s)
 AGE=$(( NOW - FILE_MTIME ))
 
+# Check for pre-compact memory snapshot (compaction recovery)
+BACKUP_FILE="$CWD/.memory/backup.json"
+COMPACT_NOTE=""
+if [ -f "$BACKUP_FILE" ]; then
+  BACKUP_MEMORY=$(jq -r '.memory_snapshot // ""' "$BACKUP_FILE" 2>/dev/null)
+  if [ -n "$BACKUP_MEMORY" ]; then
+    BACKUP_TS=$(jq -r '.timestamp // ""' "$BACKUP_FILE" 2>/dev/null)
+    BACKUP_EPOCH=0
+    if [ -n "$BACKUP_TS" ]; then
+      BACKUP_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$BACKUP_TS" +%s 2>/dev/null \
+        || date -d "$BACKUP_TS" +%s 2>/dev/null \
+        || echo "0")
+    fi
+    if [ "$BACKUP_EPOCH" -gt "$FILE_MTIME" ]; then
+      COMPACT_NOTE="
+--- PRE-COMPACT SNAPSHOT ($BACKUP_TS) ---
+Context was compacted. This snapshot may contain decisions or progress not yet in working memory.
+
+$BACKUP_MEMORY
+"
+    fi
+  fi
+fi
+
 STALE_WARNING=""
 if [ "$AGE" -gt 3600 ]; then
   HOURS=$(( AGE / 3600 ))
@@ -62,7 +88,18 @@ fi
 # Build context string
 CONTEXT="${STALE_WARNING}--- WORKING MEMORY (from previous session) ---
 
-${MEMORY_CONTENT}
+${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 ---
 Branch: ${GIT_BRANCH}
@@ -75,6 +112,11 @@ Uncommitted changes:
 ${GIT_STATUS}"
 fi
 
+if [ -n "$COMPACT_NOTE" ]; then
+  CONTEXT="${CONTEXT}
+${COMPACT_NOTE}"
+fi
+
 # Output as additionalContext JSON envelope (Claude sees it as system context, not user-visible)
 jq -n --arg ctx "$CONTEXT" '{
   "hookSpecificOutput": {

package/scripts/hooks/stop-update-memory.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Working Memory: Stop Hook
-# Spawns a background process to update .docs/WORKING-MEMORY.md asynchronously.
+# Spawns a background process to update .memory/WORKING-MEMORY.md asynchronously.
 # The session ends immediately — no visible edit in the TUI.
 # On failure: does nothing (stale memory is better than fake data).
 
@@ -16,21 +16,25 @@ if ! command -v jq &>/dev/null; then exit 0; fi
 
 INPUT=$(cat)
 
-# Only activate in projects with .docs/ directory (DevFlow-initialized projects)
+# Resolve project directory — bail if missing
 CWD=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null)
-if [ -z "$CWD" ] || [ ! -d "$CWD/.docs" ]; then
+if [ -z "$CWD" ]; then
   exit 0
 fi
 
+# Auto-create .memory/ and ensure .gitignore entries (idempotent after first run)
+SCRIPT_DIR_EARLY="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR_EARLY/ensure-memory-gitignore.sh" "$CWD" || exit 0
+
 # Logging (shared log file with background updater; [stop-hook] prefix distinguishes)
-MEMORY_FILE="$CWD/.docs/WORKING-MEMORY.md"
-LOG_FILE="$CWD/.docs/.working-memory-update.log"
+MEMORY_FILE="$CWD/.memory/WORKING-MEMORY.md"
+LOG_FILE="$CWD/.memory/.working-memory-update.log"
 log() { echo "[$(date -u '+%Y-%m-%dT%H:%M:%SZ')] [stop-hook] $1" >> "$LOG_FILE"; }
 
 # Throttle: skip if stop hook was triggered within the last 2 minutes
 # Uses a marker file touched BEFORE spawning the updater — prevents race condition
 # where multiple hooks see stale WORKING-MEMORY.md mtime and all bypass throttle.
-TRIGGER_MARKER="$CWD/.docs/.working-memory-last-trigger"
+TRIGGER_MARKER="$CWD/.memory/.working-memory-last-trigger"
 if [ -f "$TRIGGER_MARKER" ]; then
   if stat --version &>/dev/null 2>&1; then
     MARKER_MTIME=$(stat -c %Y "$TRIGGER_MARKER")

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, typescript, react, test-patterns, input-validation, accessibility, frontend-design
+skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, input-validation
 ---
 
 # Coder Agent
@@ -33,11 +33,16 @@ You receive from orchestrator:
 
 2. **Reference handoff** (if PRIOR_PHASE_SUMMARY provided): Use summary to validate your understanding of prior work, not as the sole source of truth. The actual code is authoritative.
 
-3. **Load domain skills**: Based on DOMAIN hint, apply relevant patterns:
-   - `backend`: typescript, implementation-patterns, input-validation
-   - `frontend`: react, typescript, accessibility, frontend-design
-   - `tests`: test-patterns, typescript
-   - `fullstack`: all of the above
+3. **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`
+   - `backend` (Go): Read `~/.claude/skills/go/SKILL.md`
+   - `backend` (Java): Read `~/.claude/skills/java/SKILL.md`
+   - `backend` (Python): Read `~/.claude/skills/python/SKILL.md`
+   - `backend` (Rust): Read `~/.claude/skills/rust/SKILL.md`
+   - `frontend`: Read `~/.claude/skills/react/SKILL.md`, `~/.claude/skills/typescript/SKILL.md`, `~/.claude/skills/accessibility/SKILL.md`, `~/.claude/skills/frontend-design/SKILL.md`
+   - `tests`: Read `~/.claude/skills/test-patterns/SKILL.md`, `~/.claude/skills/typescript/SKILL.md`
+   - `fullstack`: Combine backend + frontend skills
+   - If a Read fails (skill not installed), skip it silently and continue.
 
 4. **Implement the plan**: Work through execution steps systematically, creating and modifying files. Follow existing patterns. Type everything. Use Result types if codebase uses them.
 

package/shared/agents/reviewer.md

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

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

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

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

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

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

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