@abdullah-alnahas/claude-sdd 0.7.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "claude-sdd",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Spec-Driven Development discipline system — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops"
 }

package/README.md

@@ -51,7 +51,10 @@ Profile-first discipline for performance work. Defends against convenience bias
 | `/sdd-guardrails` | Show/toggle guardrail status |
 | `/sdd-yolo` | Disable all guardrails (auto-clears next session) |
 | `/sdd-phase` | Show/set development phase |
-| `/sdd-review` | On-demand review with critic + simplifier agents |
+| `/sdd-mode` | Switch context mode (dev/review/research) |
+| `/sdd-review` | Two-stage review — spec compliance then code quality |
+| `/sdd-verify` | Automated checks — build, types, lint, tests, security scans |
+| `/sdd-orchestrate` | Agent pipelines — feature, bugfix, refactor, security, or custom |
 | `/sdd-adopt` | Adopt an existing project into SDD |
 | `/sdd-execute` | Start iterative execution loop against a spec |
 | `/sdd-autopilot` | Full autonomous lifecycle: specify → design → implement → verify → review |
@@ -65,6 +68,23 @@ Profile-first discipline for performance work. Defends against convenience bias
 | **spec-compliance** | Spec adherence checker — verifies traceability (spec → test → code) |
 | **security-reviewer** | Security analysis — OWASP Top 10, input validation, auth review |
 | **performance-reviewer** | Performance optimization reviewer — validates patches for bottleneck targeting, convenience bias, measured improvement |
+| **planner** | Implementation planner — reads specs/architecture and produces ordered steps |
+
+## Context Modes
+
+SDD supports three context modes that adjust which guardrails are active:
+
+| Mode | Focus | Pre-Implementation | Completion Review | Scope Guard |
+|------|-------|-------------------|-------------------|-------------|
+| **dev** (default) | Build correctly | Active | Active | Strict |
+| **review** | Verify and critique | Skipped | Active | Normal |
+| **research** | Explore freely | Skipped | Skipped | Relaxed |
+
+Set mode with `/sdd-mode <mode>` or set a default in `.sdd.yaml`:
+
+```yaml
+mode: dev  # dev | review | research
+```
 
 ## Configuration
 
@@ -73,6 +93,8 @@ Create `.sdd.yaml` in your project root:
 ```yaml
 verbosity: standard  # minimal | standard | verbose
 enabled: true
+mode: dev  # dev | review | research
+compaction_threshold: 50  # tool invocations before suggesting /compact
 
 guardrails:
   pre-implementation:

package/agents/planner.md

@@ -0,0 +1,78 @@
+---
+name: planner
+model: sonnet
+color: blue
+description: >
+  Reads specs, architecture docs, and codebase structure to produce ordered implementation steps.
+  Use when starting a feature, breaking down a task, or needing an implementation roadmap.
+
+  <example>
+  Context: User has a spec and wants to know what to implement first.
+  user: "Break down this feature into implementation steps"
+  assistant: "I'll use the planner agent to analyze the spec and produce an ordered implementation plan."
+  </example>
+
+  <example>
+  Context: User is starting a new feature from a behavior spec.
+  user: "Plan the implementation for this spec"
+  assistant: "Let me launch the planner agent to create an implementation roadmap."
+  </example>
+
+  <example>
+  Context: User needs to understand implementation order and dependencies.
+  user: "What should I build first?"
+  assistant: "I'll use the planner agent to analyze dependencies and suggest an implementation order."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Planner Agent
+
+You analyze specs, architecture, and codebase structure to produce ordered implementation steps. You plan — you do not implement.
+
+## Planning Process
+
+1. **Read the spec** — understand what needs to be built (behavior spec, acceptance criteria)
+2. **Read architecture docs** — understand the system structure (if available)
+3. **Scan the codebase** — identify existing patterns, conventions, relevant files
+4. **Identify dependencies** — what must exist before other things can be built
+5. **Produce ordered steps** — a sequence that respects dependencies and enables incremental testing
+
+## Output Format
+
+```
+## Implementation Plan
+
+### Prerequisites
+[What must be true before starting — dependencies, setup, existing code to understand]
+
+### Steps
+
+1. **Step title** — Brief description
+   - Files: `path/to/file.ts` (create | modify)
+   - Depends on: (none | step N)
+   - Test: How to verify this step works
+
+2. **Step title** — Brief description
+   - Files: `path/to/file.ts` (create | modify)
+   - Depends on: Step 1
+   - Test: How to verify this step works
+
+### Risks
+[Potential issues, ambiguities in the spec, architectural concerns]
+
+### Suggested Order
+[If steps can be parallelized, note which can run concurrently]
+```
+
+## Planning Standards
+
+- **Respect existing patterns** — don't suggest new conventions when the codebase has established ones
+- **Small steps** — each step should be independently testable
+- **Dependencies are explicit** — never assume step order is obvious
+- **Tests at every step** — every step includes how to verify it
+- **Be honest about unknowns** — flag ambiguities, don't paper over them

package/commands/sdd-mode.md

@@ -0,0 +1,42 @@
+---
+name: sdd-mode
+description: Switch SDD context mode (dev/review/research). Controls which guardrails are active.
+argument-hint: "[dev|review|research]"
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# /sdd-mode
+
+Switch the active SDD context mode. Each mode adjusts which guardrails, hooks, and checks are active.
+
+## Usage
+
+- `/sdd-mode` — Show current mode
+- `/sdd-mode dev` — Full guardrails (default)
+- `/sdd-mode review` — Review/verification focus
+- `/sdd-mode research` — Exploration focus, relaxed guardrails
+
+## Modes
+
+| Mode | Pre-Implementation Checkpoint | Completion Review | Scope Guard | Focus |
+|------|------------------------------|-------------------|-------------|-------|
+| **dev** | Active | Active | Strict | Build correctly — TDD, spec compliance, full discipline |
+| **review** | Skipped | Active | Normal | Verify and critique — find issues, check quality |
+| **research** | Skipped | Skipped | Relaxed | Explore and understand — read code, trace flows, prototype |
+
+## Behavior
+
+When invoked with an argument:
+1. Write `SDD_MODE=<mode>` to `$CLAUDE_ENV_FILE`
+2. Read the corresponding context file from `contexts/<mode>.md`
+3. Report the mode switch and what changed
+
+When invoked without an argument:
+1. Read `$SDD_MODE` (default: `dev`)
+2. Report current mode and its settings
+
+## Context Files
+
+Each mode has a context file at `contexts/<mode>.md` that is loaded by the session init hook. These define the behavioral adjustments for that mode. See `.sdd.yaml` to set a default mode per project.

package/commands/sdd-orchestrate.md

@@ -0,0 +1,103 @@
+---
+name: sdd-orchestrate
+description: Run named agent pipelines with structured handoffs — feature, bugfix, refactor, security, or custom.
+argument-hint: "<pipeline> [agent1,agent2,...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+---
+
+# /sdd-orchestrate
+
+Run a named pipeline of agents with structured handoffs. Each agent receives the previous agent's findings and builds on them.
+
+## Usage
+
+- `/sdd-orchestrate feature` — Full feature review pipeline
+- `/sdd-orchestrate bugfix` — Bug-focused pipeline
+- `/sdd-orchestrate refactor` — Refactoring review pipeline
+- `/sdd-orchestrate security` — Security-focused pipeline
+- `/sdd-orchestrate custom agent1,agent2,...` — User-specified agent sequence
+
+## Named Pipelines
+
+| Pipeline | Agent Sequence | Focus |
+|----------|---------------|-------|
+| **feature** | spec-compliance → planner → critic → security-reviewer | Complete feature validation |
+| **bugfix** | critic → spec-compliance → simplifier | Find root cause, check spec, simplify fix |
+| **refactor** | simplifier → critic → spec-compliance | Simplify, verify correctness, check spec |
+| **security** | security-reviewer → critic → simplifier | Security first, then correctness, then cleanup |
+
+### custom
+
+Specify agents as a comma-separated list:
+```
+/sdd-orchestrate custom critic,simplifier,performance-reviewer
+```
+
+Available agents: `critic`, `simplifier`, `spec-compliance`, `security-reviewer`, `performance-reviewer`, `planner`
+
+## Handoff Format
+
+Each agent produces a structured handoff:
+
+```
+## Agent: <name>
+
+### Findings
+[Structured findings from this agent]
+
+### Handoff
+[Key information the next agent needs]
+
+### Status: PASS | FAIL | NEEDS-ATTENTION
+```
+
+## Pipeline Behavior
+
+1. Run each agent in sequence
+2. Pass previous agent's findings as context to the next agent
+3. **On FAIL**: Pause the pipeline and ask the user:
+   - Fix issues and re-run from the failed agent
+   - Continue to the next agent anyway
+   - Abort the pipeline
+4. After all agents complete, produce a summary
+
+## Summary Output
+
+```
+SDD Orchestrate — feature pipeline
+────────────────────────────────────
+
+  ✓ spec-compliance ............... PASS
+  ✓ planner ....................... PASS (spec-compliance findings applied)
+  ✗ critic ........................ FAIL (2 critical issues)
+  ⊘ security-reviewer ............ SKIPPED (pipeline paused)
+
+Pipeline: PAUSED at critic — 2 critical issues found
+Action required: Fix issues before continuing
+```
+
+## Agent Prompt Template
+
+When launching each agent, include:
+
+```
+You are running as part of an SDD orchestration pipeline.
+Pipeline: <pipeline-name>
+Your position: Agent <N> of <total>
+Previous findings:
+<handoff from previous agent, or "First agent — no prior findings">
+
+Your task: <agent's standard task>
+Output your findings in the structured handoff format.
+```
+
+## References
+
+See agent definitions in `agents/` for each agent's review standards and output format.

package/commands/sdd-verify.md

@@ -0,0 +1,87 @@
+---
+name: sdd-verify
+description: Run automated verification checks — build, types, lint, tests, security scans. Distinct from /sdd-review (agent-based).
+argument-hint: "[quick|full|pre-commit|pre-pr]"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Task
+---
+
+# /sdd-verify
+
+Run automated verification checks against the codebase. This is the **automated checks** complement to `/sdd-review` (which uses agent-based analysis).
+
+## Usage
+
+- `/sdd-verify` — Run full verification (default)
+- `/sdd-verify quick` — Build + type check only
+- `/sdd-verify full` — Build + types + lint + test suite + coverage
+- `/sdd-verify pre-commit` — Quick + lint + debug statement scan + git status check
+- `/sdd-verify pre-pr` — Full + security-reviewer agent + diff review + TODO/secrets scan
+
+## Modes
+
+### quick
+Fast feedback loop during development.
+1. Build / compile check
+2. Type check (tsc, mypy, etc.)
+
+### full (default)
+Comprehensive automated verification.
+1. Build / compile check
+2. Type check
+3. Lint (eslint, ruff, etc.)
+4. Full test suite
+5. Coverage report (if configured)
+
+### pre-commit
+Everything needed before committing.
+1. All `quick` checks
+2. Lint
+3. Debug statement scan (`console.log`, `debugger`, `print(`, `TODO`, `FIXME`, `HACK`)
+4. Git status — ensure no unintended files staged
+
+### pre-pr
+Everything needed before opening a PR.
+1. All `full` checks
+2. Launch **security-reviewer** agent on changed files
+3. Diff review — scan for TODO, FIXME, secrets patterns, hardcoded values
+4. Generate summary
+
+## Output Format
+
+```
+SDD Verify — [mode]
+───────────────────
+
+  ✓ Build .......................... PASS
+  ✓ Type check .................... PASS
+  ✗ Lint .......................... FAIL (3 errors)
+  ✓ Tests ......................... PASS (42/42)
+  ✓ Coverage ...................... 87%
+  ✗ Debug statements .............. FAIL (2 found)
+  ✓ Secrets scan .................. PASS
+
+──────────────────────────────────
+Summary: 5/7 passed, 2 failed
+Ready for PR: NO
+```
+
+## How to Detect Project Tools
+
+1. Check `package.json` for scripts (build, test, lint, typecheck)
+2. Check for `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`
+3. Check for config files (`.eslintrc`, `tsconfig.json`, `ruff.toml`, `mypy.ini`)
+4. If no tools detected, report what's missing and skip those checks
+
+## Difference from /sdd-review
+
+| | /sdd-verify | /sdd-review |
+|---|---|---|
+| **Type** | Automated checks | Agent-based analysis |
+| **Speed** | Fast (runs tools) | Slower (launches agents) |
+| **Finds** | Build errors, type errors, lint issues, test failures | Logic errors, spec drift, unnecessary complexity |
+| **When** | During development, before commit/PR | After implementation, before merge |

package/contexts/dev.md

@@ -0,0 +1,25 @@
+# SDD Context: Dev Mode
+
+Full guardrails active. This is the default mode for implementation work.
+
+## Active Guardrails
+
+- **Pre-implementation checkpoint**: ON — enumerate assumptions, flag ambiguity, surface alternatives, push back on bad ideas, define scope, check for spec, plan TDD approach
+- **Completion review**: ON — spec adherence, test coverage, complexity audit, dead code check, scope creep check
+- **Scope guard**: STRICT — reject changes outside defined scope without explicit approval
+- **TDD enforcement**: ON — tests before implementation
+- **Post-edit review**: ON — review after each write/edit
+
+## When to Use
+
+- Implementing features from specs
+- Fixing bugs
+- Refactoring code
+- Any task where correctness and discipline matter
+
+## Principles
+
+- Every change starts with understanding the spec
+- Every implementation starts with a test
+- Every completion is verified against criteria
+- Scope is defended — no drive-by improvements

package/contexts/research.md

@@ -0,0 +1,26 @@
+# SDD Context: Research Mode
+
+Exploration focus. Guardrails are relaxed to allow free investigation without implementation ceremony.
+
+## Active Guardrails
+
+- **Pre-implementation checkpoint**: OFF — you're exploring, not committing to implementation
+- **Completion review**: OFF — research doesn't have a "done" in the spec-compliance sense
+- **Scope guard**: RELAXED — follow the investigation wherever it leads
+- **TDD enforcement**: OFF for prototypes — but ON if research produces code intended for production
+- **Post-edit review**: OFF — prototypes and experiments don't need review
+
+## When to Use
+
+- Understanding unfamiliar codebases
+- Investigating bugs (root cause analysis)
+- Prototyping and experimentation
+- Architecture exploration and spike work
+- Reading documentation and tracing flows
+
+## Principles
+
+- Follow curiosity — explore freely
+- Take notes — capture findings for later
+- Don't ship research code — if it becomes production code, switch to dev mode
+- Time-box — set a goal for what you want to learn

package/contexts/review.md

@@ -0,0 +1,25 @@
+# SDD Context: Review Mode
+
+Critic and verification focus. Pre-implementation checkpoint is skipped since you're reviewing, not building.
+
+## Active Guardrails
+
+- **Pre-implementation checkpoint**: OFF — you're reviewing existing code, not starting new work
+- **Completion review**: ON — ensure review findings are complete and actionable
+- **Scope guard**: NORMAL — stay focused on what you're reviewing
+- **TDD enforcement**: ON for any fixes — if review leads to fixes, tests come first
+- **Post-edit review**: ON — verify any fixes made during review
+
+## When to Use
+
+- Code review (PRs, post-implementation)
+- Auditing existing code for quality
+- Security reviews
+- Running `/sdd-review` or agent-based reviews
+
+## Principles
+
+- Find what's wrong, not confirm what's right
+- Be specific and evidence-based
+- Report findings honestly — don't soften
+- If fixing, follow TDD discipline

package/hooks/hooks.json

@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "If this message is a trivial acknowledgment (e.g. 'yes', 'no', 'thanks', 'ok', 'continue'), skip and respond normally. Otherwise, apply the SDD pre-implementation checkpoint from the guardrails skill (enumerate assumptions, flag ambiguity, surface alternatives, push back on bad ideas, define scope, check for spec, plan TDD approach) before proceeding. If GUARDRAILS_DISABLED=true, skip."
+            "prompt": "If this message is a trivial acknowledgment (e.g. 'yes', 'no', 'thanks', 'ok', 'continue'), skip and respond normally. If SDD_MODE=review or SDD_MODE=research, skip. Otherwise, apply the SDD pre-implementation checkpoint from the guardrails skill (enumerate assumptions, flag ambiguity, surface alternatives, push back on bad ideas, define scope, check for spec, plan TDD approach) before proceeding. If GUARDRAILS_DISABLED=true, skip."
           }
         ]
       }
@@ -34,6 +34,16 @@
             "timeout": 15
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/compaction-counter.sh\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "Stop": [
@@ -42,7 +52,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Before finalizing, perform the SDD completion review from the guardrails skill (spec adherence, test coverage, complexity audit, dead code check, scope creep check, conceptual error scan). Report findings concisely. If GUARDRAILS_DISABLED=true, skip."
+            "prompt": "Before finalizing, perform the SDD completion review from the guardrails skill (spec adherence, test coverage, complexity audit, dead code check, scope creep check, conceptual error scan). Report findings concisely. If GUARDRAILS_DISABLED=true or SDD_MODE=research, skip."
           }
         ]
       }

package/hooks/scripts/compaction-counter.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# SDD Strategic Compaction Counter
+# Counts tool invocations per session and suggests compaction at threshold.
+# Runs as PostToolUse hook — must be fast and silent on stdout.
+
+set -euo pipefail
+
+THRESHOLD="${SDD_COMPACTION_THRESHOLD:-50}"
+COUNTER_FILE="/tmp/sdd-compaction-$$"
+
+# Use parent PID to scope counter to the Claude session
+if [ -n "${PPID:-}" ]; then
+  COUNTER_FILE="/tmp/sdd-compaction-$PPID"
+fi
+
+# Increment counter
+COUNT=0
+if [ -f "$COUNTER_FILE" ]; then
+  COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+fi
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Check threshold
+if [ "$COUNT" -ge "$THRESHOLD" ]; then
+  echo "SDD: $COUNT tool invocations since last compaction suggestion. Consider running /compact to free context window space. Key information to preserve: current task, spec criteria, files modified, test status." >&2
+  # Reset counter after suggesting
+  echo "0" > "$COUNTER_FILE"
+fi
+
+exit 0

package/hooks/scripts/post-edit-review.sh

@@ -4,10 +4,13 @@
 
 set -euo pipefail
 
-# Skip if guardrails disabled
+# Skip if guardrails disabled or in research mode
 if [ "${GUARDRAILS_DISABLED:-false}" = "true" ]; then
   exit 0
 fi
+if [ "${SDD_MODE:-dev}" = "research" ]; then
+  exit 0
+fi
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 # Resolve to absolute path (POSIX-compatible fallback when realpath unavailable)

package/hooks/scripts/session-init.sh

@@ -34,12 +34,24 @@ if [ -n "$ENV_FILE" ]; then
   echo "SDD_ACTIVE=true" >> "$ENV_FILE"
 fi
 
-# Check for config file
+# Check for config file and read settings
+SDD_DEFAULT_MODE="dev"
+SDD_COMPACTION_THRESHOLD="50"
 if [ -f "$CONFIG_FILE" ]; then
   echo "SDD: Config file found at $CONFIG_FILE" >&2
   if [ -n "$ENV_FILE" ]; then
     echo "SDD_CONFIG_FOUND=true" >> "$ENV_FILE"
   fi
+  # Read mode from config (grep-based, no yaml parser needed)
+  CONFIG_MODE=$(grep -E '^\s*mode\s*:' "$CONFIG_FILE" 2>/dev/null | head -1 | sed 's/.*:\s*//' | tr -d '[:space:]"'"'" || true)
+  if [ -n "$CONFIG_MODE" ] && echo "$CONFIG_MODE" | grep -qE '^(dev|review|research)$'; then
+    SDD_DEFAULT_MODE="$CONFIG_MODE"
+  fi
+  # Read compaction threshold from config
+  CONFIG_THRESHOLD=$(grep -E '^\s*compaction_threshold\s*:' "$CONFIG_FILE" 2>/dev/null | head -1 | sed 's/.*:\s*//' | tr -d '[:space:]"'"'" || true)
+  if [ -n "$CONFIG_THRESHOLD" ] && echo "$CONFIG_THRESHOLD" | grep -qE '^[0-9]+$'; then
+    SDD_COMPACTION_THRESHOLD="$CONFIG_THRESHOLD"
+  fi
 else
   echo "SDD: No .sdd.yaml found — using defaults" >&2
   if [ -n "$ENV_FILE" ]; then
@@ -47,6 +59,12 @@ else
   fi
 fi
 
+# Set mode and compaction threshold in env
+if [ -n "$ENV_FILE" ]; then
+  echo "SDD_MODE=$SDD_DEFAULT_MODE" >> "$ENV_FILE"
+  echo "SDD_COMPACTION_THRESHOLD=$SDD_COMPACTION_THRESHOLD" >> "$ENV_FILE"
+fi
+
 # Inject using-sdd skill as additionalContext
 USING_SDD_PATH="${CLAUDE_PLUGIN_ROOT:-}/skills/using-sdd/SKILL.md"
 if [ -f "$USING_SDD_PATH" ]; then
@@ -56,5 +74,14 @@ else
   echo "SDD WARNING: using-sdd skill not found at $USING_SDD_PATH" >&2
 fi
 
-echo "SDD: Session initialized — guardrails active" >&2
+# Inject context mode file
+CONTEXT_PATH="${CLAUDE_PLUGIN_ROOT:-}/contexts/${SDD_DEFAULT_MODE}.md"
+if [ -f "$CONTEXT_PATH" ]; then
+  echo ""
+  cat "$CONTEXT_PATH"
+else
+  echo "SDD WARNING: context file not found at $CONTEXT_PATH" >&2
+fi
+
+echo "SDD: Session initialized — mode=$SDD_DEFAULT_MODE, guardrails active" >&2
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abdullah-alnahas/claude-sdd",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Spec-Driven Development discipline system for Claude Code — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops",
   "keywords": [
     "claude-code-plugin",

package/scripts/verify-commands.sh

@@ -23,7 +23,7 @@ check() {
 echo "SDD Command Verification"
 echo "────────────────────────"
 
-COMMANDS=("sdd-guardrails" "sdd-yolo" "sdd-phase" "sdd-review" "sdd-adopt" "sdd-execute" "sdd-autopilot")
+COMMANDS=("sdd-guardrails" "sdd-yolo" "sdd-phase" "sdd-review" "sdd-adopt" "sdd-execute" "sdd-autopilot" "sdd-mode" "sdd-verify" "sdd-orchestrate")
 
 for cmd in "${COMMANDS[@]}"; do
   echo ""
@@ -47,7 +47,7 @@ check "All command names are unique" test "$(echo "$NAMES" | wc -l)" -eq "$(echo
 # Check agents referenced by commands exist
 echo ""
 echo "Agent references:"
-AGENTS=("critic" "simplifier" "spec-compliance" "security-reviewer" "performance-reviewer")
+AGENTS=("critic" "simplifier" "spec-compliance" "security-reviewer" "performance-reviewer" "planner")
 for agent in "${AGENTS[@]}"; do
   check "Agent: $agent.md exists" test -f "$PLUGIN_DIR/agents/$agent.md"
 done

package/scripts/verify-hooks.sh

@@ -73,8 +73,10 @@ echo ""
 echo "Hook scripts:"
 check "session-init.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/session-init.sh"
 check "post-edit-review.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/post-edit-review.sh"
+check "compaction-counter.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/compaction-counter.sh"
 check "session-init.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/session-init.sh"
 check "post-edit-review.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/post-edit-review.sh"
+check "compaction-counter.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/compaction-counter.sh"
 
 # Test session-init.sh runs without error (in isolated temp dir to avoid side effects)
 echo ""

package/skills/iterative-execution/SKILL.md

@@ -90,3 +90,4 @@ For performance optimization tasks, the verification step must additionally incl
 See: `references/loop-patterns.md`
 See: `references/completion-criteria.md`
 See: `references/review-prompts.md`
+See: `references/retrieval-pattern.md`

package/skills/iterative-execution/references/retrieval-pattern.md

@@ -0,0 +1,65 @@
+# Iterative Retrieval Pattern
+
+A disciplined approach for subagents gathering context before acting. Prevents both under-researching (acting on incomplete information) and over-researching (reading everything "just in case").
+
+## The Pattern: DISPATCH → EVALUATE → REFINE → LOOP
+
+```
+1. DISPATCH — Send a focused query (search, read, find_symbol)
+2. EVALUATE — Is this enough to act? Do I know what I need?
+3. REFINE — If not, narrow or broaden the query based on what I learned
+4. LOOP — Repeat until confident or max iterations reached
+```
+
+## When to Use
+
+- Subagents exploring unfamiliar code before making changes
+- Gathering context across multiple files for a review
+- Understanding how a feature works before extending it
+- Investigating a bug's root cause across layers
+
+## When NOT to Use
+
+- You already know the exact file and symbol
+- The task is a single-file edit with clear instructions
+- You're running automated checks (tests, lint) — just run them
+
+## Example: Finding Where Auth Is Handled
+
+```
+DISPATCH: Search for "authenticate" in src/
+EVALUATE: Found 3 files. middleware/auth.ts looks like the entry point.
+DISPATCH: Read auth.ts symbols overview
+EVALUATE: Has validateToken(), refreshSession(), authMiddleware(). Need to understand validateToken.
+DISPATCH: Read validateToken body
+EVALUATE: Now I know the auth flow. Sufficient to proceed.
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| **Shotgun read** — read every file in the directory | Wastes context window, buries signal in noise | Start narrow, broaden only if needed |
+| **Single-shot guess** — read one file and assume that's enough | Misses critical context, produces wrong fixes | Always EVALUATE before acting |
+| **Infinite refinement** — keep searching "just one more thing" | Never starts the actual work | Set max iterations (3-5 for context gathering) |
+| **Keyword tunnel vision** — only search for one term | Misses related code using different names | Try synonyms, check imports/references |
+| **Depth-first rabbit hole** — follow every reference chain to the bottom | Loses sight of the original task | Stay focused on what you need to know for THIS task |
+
+## Integration with Iterative Execution
+
+The retrieval pattern is the **information-gathering phase** that precedes the execution cycle. Use it to:
+1. Understand the current state before defining completion criteria
+2. Find the spec and acceptance criteria
+3. Map the code that needs to change
+4. Identify test files and patterns
+
+Then hand off to the main iterative execution cycle: implement → verify → fix gaps → repeat.
+
+## Bounded Retrieval
+
+Always set bounds:
+- **Max queries**: 5-8 for context gathering before acting
+- **Max depth**: 2-3 levels of reference following
+- **Sufficiency check**: After each query, ask "Can I act now?"
+
+The goal is **sufficient context**, not **complete context**. You will never know everything. Act when you know enough.

package/skills/using-sdd/SKILL.md

@@ -51,6 +51,16 @@ These thoughts mean STOP — you're rationalizing skipping a skill:
 | "The user said to skip guardrails" | Only `/sdd-yolo` disables guardrails. Verbal requests don't count. |
 | "I already know what to do" | Knowing the task ≠ following the discipline. |
 
+## Context Modes
+
+SDD supports three context modes that adjust which guardrails are active. Switch with `/sdd-mode <mode>`.
+
+| Mode | Pre-Implementation | Completion Review | Scope Guard | Use For |
+|------|-------------------|-------------------|-------------|---------|
+| **dev** (default) | Active | Active | Strict | Building, implementing, fixing |
+| **review** | Skipped | Active | Normal | Code review, auditing, verification |
+| **research** | Skipped | Skipped | Relaxed | Exploring, investigating, prototyping |
+
 ## Skill Classification
 
 **Rigid skills** (follow exactly, don't adapt away discipline):