devflow-kit 1.0.0 → 1.1.0

package/plugins/devflow-ambient/skills/ambient-router/references/skill-catalog.md

@@ -0,0 +1,64 @@
+# 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 |
+| 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/plugins/devflow-audit-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "devflow-audit-claude",
   "description": "Audit CLAUDE.md files against Anthropic best practices",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "agents": [],
   "skills": []
 }

package/plugins/devflow-code-review/.claude-plugin/plugin.json

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-core-skills/.claude-plugin/plugin.json

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
@@ -21,6 +21,7 @@
     "github-patterns",
     "input-validation",
     "react",
+    "test-driven-development",
     "test-patterns",
     "typescript"
   ]

package/plugins/devflow-core-skills/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.
 

package/plugins/devflow-core-skills/skills/test-driven-development/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: test-driven-development
+description: >-
+  Enforce RED-GREEN-REFACTOR cycle during implementation. Write failing tests before
+  production code. Distinct from test-patterns (which reviews test quality) — this
+  skill enforces the TDD workflow during code generation.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.py"
+  exclude:
+    - "node_modules/**"
+    - "dist/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Test-Driven Development
+
+Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
+
+## Iron Law
+
+> **TESTS FIRST, ALWAYS**
+>
+> Write the failing test before the production code. No exceptions. If you catch
+> yourself writing production code without a failing test, stop immediately, delete
+> the production code, write the test, watch it fail, then write the minimum code
+> to make it pass. The test IS the specification.
+
+---
+
+## The Cycle
+
+### Step 1: RED — Write a Failing Test
+
+Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
+
+```
+Describe what the code SHOULD do, not how it does it.
+One behavior per test. One assertion per test (ideally).
+Name tests as sentences: "returns error when email is invalid"
+```
+
+**Checkpoint:** The test MUST fail before proceeding. A test that passes immediately proves nothing.
+
+### Step 2: GREEN — Write Minimum Code to Pass
+
+Write the simplest production code that makes the failing test pass. No more, no less.
+
+```
+Hardcode first if that's simplest. Generalize when the next test forces it.
+Don't write code "you'll need later." Write code the test demands NOW.
+Don't optimize. Don't refactor. Don't clean up. Just pass the test.
+```
+
+**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
+
+### Step 3: REFACTOR — Improve Without Changing Behavior
+
+Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
+
+```
+Run tests after every refactoring step.
+If a test breaks during refactor, undo immediately — you changed behavior.
+Apply DRY, extract patterns, improve readability.
+```
+
+**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
+
+---
+
+## Rationalization Prevention
+
+These are the excuses developers use to skip TDD. Recognize and reject them.
+
+| Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
+|--------|-------------------|---------------|----------------|
+| "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
+| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
+| "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
+| "Test is too hard to write" | Setup is complex, mocking is painful | Hard-to-test code = bad design; the test is telling you the interface is wrong | Simplify the interface first |
+| "Need to see the whole picture" | Can't test what I haven't designed yet | TDD IS design; each test reveals the next piece of the interface | Let the test guide the design |
+| "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
+
+See `references/rationalization-prevention.md` for extended examples with code.
+
+---
+
+## Process Enforcement
+
+When implementing any feature under ambient BUILD/STANDARD:
+
+1. **Identify the first behavior** — What is the simplest thing this feature must do?
+2. **Write the test** — Describe that behavior as a failing test
+3. **Run the test** — Confirm it fails (RED)
+4. **Write minimum code** — Just enough to pass (GREEN)
+5. **Refactor** — Clean up while tests stay green (REFACTOR)
+6. **Repeat** — Next behavior, next test, next cycle
+
+### File Organization
+
+- Test file lives next to production file: `user.ts` → `user.test.ts`
+- Follow project's existing test conventions (Jest, Vitest, pytest, etc.)
+- Import the module under test, not internal helpers
+
+### What to Test
+
+| Test | Don't Test |
+|------|-----------|
+| Public API behavior | Private implementation details |
+| Error conditions and edge cases | Framework internals |
+| Integration points (boundaries) | Third-party library correctness |
+| State transitions | Getter/setter plumbing (unless non-trivial) |
+
+---
+
+## When TDD Does Not Apply
+
+- **QUICK depth** — Ambient classified as QUICK (chat, exploration, trivial edits)
+- **Non-code tasks** — Documentation, configuration, CI changes
+- **Exploratory prototyping** — User explicitly says "just spike this" or "prototype"
+- **Existing test suite changes** — Modifying tests themselves (test-patterns skill applies instead)
+
+When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [specific reason from list above]."
+
+---
+
+## Integration with Ambient Mode
+
+- **BUILD/STANDARD** → TDD enforced. Every new function/method gets test-first treatment.
+- **BUILD/QUICK** → TDD skipped (trivial single-file edit).
+- **BUILD/ESCALATE** → TDD mentioned in nudge toward `/implement`.
+- **DEBUG/STANDARD** → TDD applies to the fix: write a test that reproduces the bug first, then fix.

package/plugins/devflow-core-skills/skills/test-driven-development/references/rationalization-prevention.md

@@ -0,0 +1,111 @@
+# TDD Rationalization Prevention — Extended Examples
+
+Detailed code examples showing how each rationalization leads to worse outcomes.
+
+## "I'll write tests after"
+
+### What happens:
+
+```typescript
+// Developer writes production code first
+function calculateDiscount(price: number, tier: string): number {
+  if (tier === 'gold') return price * 0.8;
+  if (tier === 'silver') return price * 0.9;
+  return price;
+}
+
+// Then "writes tests after" — but only for the happy path they remember
+test('gold tier gets 20% off', () => {
+  expect(calculateDiscount(100, 'gold')).toBe(80);
+});
+// Missing: negative prices, unknown tiers, zero prices, NaN handling
+```
+
+### What TDD would have caught:
+
+```typescript
+// Test first — forces you to think about the contract
+test('returns error for negative price', () => {
+  expect(calculateDiscount(-100, 'gold')).toEqual({ ok: false, error: 'NEGATIVE_PRICE' });
+});
+// Now the interface includes error handling from the start
+```
+
+## "Too simple to test"
+
+### What happens:
+
+```typescript
+// "It's just a config getter, no test needed"
+function getMaxRetries(): number {
+  return parseInt(process.env.MAX_RETRIES || '3');
+}
+// 6 months later: someone sets MAX_RETRIES="three" and prod crashes with NaN retries
+```
+
+### What TDD would have caught:
+
+```typescript
+test('returns default when env var is not a number', () => {
+  process.env.MAX_RETRIES = 'three';
+  expect(getMaxRetries()).toBe(3); // Forces validation logic
+});
+```
+
+## "Test is too hard to write"
+
+### What happens:
+
+```typescript
+// "I can't test this easily because it needs database + email + filesystem"
+async function processOrder(orderId: string) {
+  const db = new Database();
+  const order = await db.find(orderId);
+  await sendEmail(order.customerEmail, 'Your order is processing');
+  await fs.writeFile(`/invoices/${orderId}.pdf`, generateInvoice(order));
+  await db.update(orderId, { status: 'processing' });
+}
+// Result: untestable monolith, test would need real DB + email + filesystem
+```
+
+### What TDD forces:
+
+```typescript
+// Hard-to-test = bad design. TDD forces dependency injection:
+async function processOrder(
+  orderId: string,
+  deps: { db: OrderRepository; emailer: Emailer; invoices: InvoiceStore }
+): Promise<Result<void, OrderError>> {
+  // Now trivially testable with mocks
+}
+```
+
+## "I'll refactor later"
+
+### What happens:
+
+```typescript
+// Sprint 1: "just get it working"
+function handleRequest(req: any) {
+  if (req.type === 'create') { /* 50 lines */ }
+  else if (req.type === 'update') { /* 50 lines */ }
+  else if (req.type === 'delete') { /* 30 lines */ }
+  // Sprint 2-10: more conditions added, function grows to 500 lines
+  // "Refactor later" never comes because nobody wants to touch it
+}
+```
+
+### What TDD enforces:
+
+Step 3 (REFACTOR) happens every cycle. The function never grows beyond what's clean because you clean it every 5-10 minutes.
+
+## "Tests slow me down"
+
+### The math:
+
+| Approach | Time to write | Time to first bug | Time to fix bug | Total (1 month) |
+|----------|:---:|:---:|:---:|:---:|
+| No TDD | 2h | 4h | 3h (no repro test) | 9h+ |
+| TDD | 3h | Caught in test | 15min (test pinpoints) | 3h 15min |
+
+TDD is slower for the first 30 minutes. It's faster for everything after that.

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

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

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

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

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

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-self-review/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "devflow-self-review",
   "description": "Self-review workflow: Simplifier + Scrutinizer for code quality",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "agents": ["simplifier", "scrutinizer", "validator"],
   "skills": ["self-review", "core-patterns"]
 }

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

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

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"