feat(plugin): discovery scratchpad, design subagents, hybrid change strategy

Three process improvements based on production feedback:

1. Discovery scratchpad (discovery.md): Persist elaboration findings to
   .ai-dlc/{slug}/discovery.md during Phase 2.5 domain discovery. Offloads
   detailed findings from context to disk, keeping the context window lean.
   Injected into subagent context (section headers) and session start
   (section count indicator). Copied into intent worktree in Phase 6.

2. Design analysis via subagents: Delegate Figma/design analysis to
   general-purpose subagents during elaboration to avoid flooding the main
   context window with design data. One subagent per design file, spawned
   in parallel with codebase exploration.

3. Hybrid per-unit change strategy: A foundational unit can use "unit"
   strategy (own PR to main) while remaining units use "intent" strategy
   (merge to intent branch). Adds parse_unit_change_strategy() to dag.sh,
   updates advance/construct merge logic, and adds hybrid-aware integrator
   skip checks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jwaldrip

plugin/hooks/inject-context.sh

@@ -381,6 +381,17 @@ if [ -n "$INTENT_DIR" ] && [ -f "${INTENT_DIR}/completion-criteria.md" ]; then
   echo ""
 fi
 
+# Show discovery.md availability indicator
+if [ -n "$INTENT_DIR" ] && [ -f "${INTENT_DIR}/discovery.md" ]; then
+  DISCOVERY_COUNT=$(grep -cE '^## ' "${INTENT_DIR}/discovery.md" 2>/dev/null || echo "0")
+  if [ "$DISCOVERY_COUNT" -gt 0 ]; then
+    echo "### Discovery Log"
+    echo ""
+    echo "**${DISCOVERY_COUNT} sections** of elaboration findings available in \`.ai-dlc/${INTENT_SLUG}/discovery.md\`"
+    echo ""
+  fi
+fi
+
 # Load and display current plan (from cached values)
 PLAN="${KEEP_VALUES[current-plan.md]}"
 if [ -n "$PLAN" ]; then

plugin/hooks/subagent-context.sh

@@ -116,6 +116,20 @@ if [ -f "${INTENT_DIR}/completion-criteria.md" ]; then
   echo ""
 fi
 
+# Inject discovery.md section headers (keep subagent context lean)
+if [ -f "${INTENT_DIR}/discovery.md" ]; then
+  DISCOVERY_HEADERS=$(grep -E '^## ' "${INTENT_DIR}/discovery.md" 2>/dev/null || true)
+  if [ -n "$DISCOVERY_HEADERS" ]; then
+    echo "### Discovery Log"
+    echo ""
+    echo "Elaboration findings available in \`.ai-dlc/${INTENT_SLUG}/discovery.md\`:"
+    echo ""
+    echo "$DISCOVERY_HEADERS"
+    echo ""
+    echo "*Read the full file for detailed findings.*"
+    echo ""
+  fi
+fi
 
 # Source DAG library if available
 DAG_LIB="${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"

plugin/lib/dag.sh

@@ -109,6 +109,35 @@ parse_unit_branch() {
   _yaml_get_simple "branch" "" < "$unit_file"
 }
 
+# Parse per-unit change strategy from nested git: { change_strategy: ... } frontmatter
+# Usage: parse_unit_change_strategy <unit_file>
+# Returns the strategy value if set, empty string if not
+parse_unit_change_strategy() {
+  local unit_file="$1"
+  [ ! -f "$unit_file" ] && { echo ""; return; }
+  local in_frontmatter=false in_git=false value=""
+  while IFS= read -r line; do
+    [[ "$line" == "---" ]] && { $in_frontmatter && break || in_frontmatter=true; continue; }
+    $in_frontmatter || continue
+    if [[ "$line" =~ ^git:\ *$ ]]; then
+      in_git=true
+      continue
+    fi
+    if $in_git; then
+      if [[ "$line" =~ ^[[:space:]]+change_strategy:\ *(.*)$ ]]; then
+        value="${BASH_REMATCH[1]}"
+        value="${value#\"}"
+        value="${value%\"}"
+        value="${value#\'}"
+        value="${value%\'}"
+        break
+      fi
+      [[ ! "$line" =~ ^[[:space:]] ]] && in_git=false
+    fi
+  done < "$unit_file"
+  echo "$value"
+}
+
 # Check if all dependencies of a unit are completed
 # Returns 0 (true) if all deps completed, 1 (false) otherwise
 # Usage: are_deps_completed <intent_dir> <unit_file>

plugin/skills/advance/SKILL.md

@@ -108,9 +108,16 @@ INTENT_DIR=".ai-dlc/${INTENT_SLUG}"
 CONFIG=$(get_ai_dlc_config "$INTENT_DIR")
 AUTO_MERGE=$(echo "$CONFIG" | jq -r '.auto_merge // "true"')
 AUTO_SQUASH=$(echo "$CONFIG" | jq -r '.auto_squash // "false"')
-CHANGE_STRATEGY=$(echo "$CONFIG" | jq -r '.change_strategy // "unit"')
 DEFAULT_BRANCH=$(echo "$CONFIG" | jq -r '.default_branch')
 
+# Resolve effective change strategy: per-unit override takes priority over intent-level
+source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
+UNIT_CHANGE_STRATEGY=""
+if [ -n "$CURRENT_UNIT" ] && [ -f "$INTENT_DIR/${CURRENT_UNIT}.md" ]; then
+  UNIT_CHANGE_STRATEGY=$(parse_unit_change_strategy "$INTENT_DIR/${CURRENT_UNIT}.md")
+fi
+CHANGE_STRATEGY="${UNIT_CHANGE_STRATEGY:-$(echo "$CONFIG" | jq -r '.change_strategy // "unit"')}"
+
 UNIT_SLUG="${CURRENT_UNIT#unit-}"
 UNIT_BRANCH="ai-dlc/${INTENT_SLUG}/${UNIT_SLUG}"
 
@@ -176,10 +183,26 @@ if (dagSummary.allComplete) {
   // ALL UNITS COMPLETE - Check if integrator should run
   // Skip integrator for:
   //   - Single-unit intents (reviewer already validated it)
-  //   - change_strategy "unit" (each unit reviewed individually via per-unit MR)
-  const unitCount = dagSummary.totalCount;
-  const changeStrategy = config.change_strategy || "unit";
-  const skipIntegrator = unitCount <= 1 || changeStrategy === "unit";
+  //   - ALL units effectively use "unit" strategy (each reviewed individually via per-unit MR)
+  // Hybrid check: iterate all units to see if any use non-unit strategy
+```
+
+```bash
+source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
+ALL_UNIT_STRATEGY=true
+for unit_file in "$INTENT_DIR"/unit-*.md; do
+  [ -f "$unit_file" ] || continue
+  UNIT_CS=$(parse_unit_change_strategy "$unit_file")
+  EFFECTIVE_CS="${UNIT_CS:-$(echo "$CONFIG" | jq -r '.change_strategy // "unit"')}"
+  [ "$EFFECTIVE_CS" != "unit" ] && { ALL_UNIT_STRATEGY=false; break; }
+done
+UNIT_COUNT=$(ls -1 "$INTENT_DIR"/unit-*.md 2>/dev/null | wc -l)
+SKIP_INTEGRATOR=false
+[ "$UNIT_COUNT" -le 1 ] && SKIP_INTEGRATOR=true
+[ "$ALL_UNIT_STRATEGY" = "true" ] && SKIP_INTEGRATOR=true
+```
+
+```javascript
   if (!skipIntegrator && !state.integratorComplete) {
     // Spawn integrator on the intent branch
     // See Step 2e below

plugin/skills/construct/SKILL.md

@@ -351,7 +351,10 @@ han keep save iteration.json "$STATE"
 AGENT_TEAMS_ENABLED="${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}"
 CHANGE_STRATEGY=$(han parse yaml "git.change_strategy" -r --default "unit" < "$INTENT_DIR/intent.md")
 
-# Unit strategy always uses Sequential path (subagent delegation, no team orchestration)
+# Pure unit strategy always uses Sequential path (subagent delegation, no team orchestration).
+# Hybrid strategy (intent-level "intent" + some units overriding to "unit") keeps Teams enabled —
+# the intent-level strategy drives orchestration. Per-unit overrides are resolved at merge time
+# by /advance, not at spawn time.
 if [ "$CHANGE_STRATEGY" = "unit" ]; then
   AGENT_TEAMS_ENABLED=""
 fi
@@ -625,18 +628,50 @@ Task({
 
 a. Mark unit as completed: `update_unit_status "$UNIT_FILE" "completed"`
 b. Remove unit from `unitStates`
-c. Merge unit branch into intent branch:
+c. Merge or PR based on effective change strategy:
 
 ```bash
-# Merge unit branch into intent branch
+# Determine merge behavior based on per-unit or intent-level change strategy
 source "${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
 INTENT_DIR=".ai-dlc/${INTENT_SLUG}"
 CONFIG=$(get_ai_dlc_config "$INTENT_DIR")
 AUTO_MERGE=$(echo "$CONFIG" | jq -r '.auto_merge // "true"')
 AUTO_SQUASH=$(echo "$CONFIG" | jq -r '.auto_squash // "false"')
+DEFAULT_BRANCH=$(echo "$CONFIG" | jq -r '.default_branch')
+
+# Check per-unit change strategy override
+UNIT_FILE="$INTENT_DIR/${UNIT_NAME}.md"
+UNIT_CS=$(parse_unit_change_strategy "$UNIT_FILE")
+EFFECTIVE_CS="${UNIT_CS:-$(echo "$CONFIG" | jq -r '.change_strategy // "unit"')}"
+UNIT_BRANCH="ai-dlc/${INTENT_SLUG}/${UNIT_SLUG}"
+
+if [ "$EFFECTIVE_CS" = "unit" ]; then
+  # Per-unit strategy: create PR to default branch (same as advance/SKILL.md unit path)
+  git push -u origin "$UNIT_BRANCH" 2>/dev/null || true
+
+  UNIT_TICKET=$(han parse yaml ticket -r --default "" < "$UNIT_FILE" 2>/dev/null || echo "")
+  TICKET_LINE=""
+  [ -n "$UNIT_TICKET" ] && TICKET_LINE="Closes ${UNIT_TICKET}"
+
+  gh pr create \
+    --base "$DEFAULT_BRANCH" \
+    --head "$UNIT_BRANCH" \
+    --title "unit: ${UNIT_NAME}" \
+    --body "## Unit: ${UNIT_NAME}
+
+Part of intent: ${INTENT_SLUG}
+
+${TICKET_LINE}
+
+---
+*Built with [AI-DLC](https://ai-dlc.dev)*" 2>/dev/null || echo "PR may already exist for $UNIT_BRANCH"
 
-if [ "$AUTO_MERGE" = "true" ]; then
-  UNIT_BRANCH="ai-dlc/${INTENT_SLUG}/${UNIT_SLUG}"
+  WORKTREE_PATH="${PROJECT_ROOT}/.ai-dlc/worktrees/${INTENT_SLUG}-${UNIT_SLUG}"
+  [ -d "$WORKTREE_PATH" ] && git worktree remove "$WORKTREE_PATH"
+
+elif [ "$AUTO_MERGE" = "true" ]; then
+  # Intent strategy: merge unit branch into intent branch (existing behavior)
   git checkout "ai-dlc/${INTENT_SLUG}/main"
 
   if [ "$AUTO_SQUASH" = "true" ]; then
@@ -698,15 +733,27 @@ UNIT_COUNT=$(ls -1 "$INTENT_DIR"/unit-*.md 2>/dev/null | wc -l)
 
 Skip the integrator if:
 - Only one unit (the reviewer already validated it)
-- `change_strategy` is `unit` (each unit reviewed individually via per-unit MR)
+- ALL units effectively use `unit` strategy (each unit reviewed individually via per-unit MR)
+
+Note: In hybrid mode (intent-level `intent` + some units overriding to `unit`), the integrator still runs because non-unit units merge into the intent branch and need integration verification.
 
 ```bash
 source "${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
 CONFIG=$(get_ai_dlc_config "$INTENT_DIR")
-CHANGE_STRATEGY=$(echo "$CONFIG" | jq -r '.change_strategy // "unit"')
+
+# Hybrid-aware check: iterate all units to determine if ALL effectively use "unit" strategy
+ALL_UNIT_STRATEGY=true
+for unit_file in "$INTENT_DIR"/unit-*.md; do
+  [ -f "$unit_file" ] || continue
+  UNIT_CS=$(parse_unit_change_strategy "$unit_file")
+  EFFECTIVE_CS="${UNIT_CS:-$(echo "$CONFIG" | jq -r '.change_strategy // "unit"')}"
+  [ "$EFFECTIVE_CS" != "unit" ] && { ALL_UNIT_STRATEGY=false; break; }
+done
+
 SKIP_INTEGRATOR=false
 [ "$UNIT_COUNT" -le 1 ] && SKIP_INTEGRATOR=true
-[ "$CHANGE_STRATEGY" = "unit" ] && SKIP_INTEGRATOR=true
+[ "$ALL_UNIT_STRATEGY" = "true" ] && SKIP_INTEGRATOR=true
 ```
 
 If `SKIP_INTEGRATOR` is false and `integratorComplete` is not `true`: