fix: session retrospective — branch ordering, team mode hats, workflow transitions, merge strategy

Six fixes from GigSmart Requester MCP retrospective sessions (c19eaafb, 67904c3a):

- Reorder elaboration Phase 6 to create intent branch before writing artifacts
- Add Phase 5.8 git strategy question (change_strategy, auto_merge) during elaboration
- Embed per-unit hat instructions in teammate prompts instead of relying on hook injection
- Skip hat section in subagent-context.sh during team mode to avoid wrong-hat injection
- Replace hardcoded planner/builder/reviewer handlers with generic workflow-array-driven
  hat transitions so custom workflows (red-team, blue-team, etc.) are honored
- Add merge step on unit completion using auto_merge/auto_squash config
- Update mode descriptions with concrete UX language (file editing, approval, autonomy)

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

Author: jwaldrip

hooks/subagent-context.sh

@@ -182,35 +182,39 @@ if [ -d "$INTENT_DIR" ] && ls "$INTENT_DIR"/unit-*.md 1>/dev/null 2>&1; then
   fi
 fi
 
-# Load role/hat instructions (builder/reviewer are orchestration roles)
-HAT_FILE=""
-if [ -f ".ai-dlc/hats/${HAT}.md" ]; then
-  HAT_FILE=".ai-dlc/hats/${HAT}.md"
-elif [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/hats/${HAT}.md" ]; then
-  HAT_FILE="${CLAUDE_PLUGIN_ROOT}/hats/${HAT}.md"
-fi
+# In team mode, hat instructions are embedded in teammate prompts by /construct
+# Skip here to avoid injecting the orchestrator's hat instead of the per-unit hat
+if [ -z "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}" ]; then
+  # Load role/hat instructions (builder/reviewer are orchestration roles)
+  HAT_FILE=""
+  if [ -f ".ai-dlc/hats/${HAT}.md" ]; then
+    HAT_FILE=".ai-dlc/hats/${HAT}.md"
+  elif [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/hats/${HAT}.md" ]; then
+    HAT_FILE="${CLAUDE_PLUGIN_ROOT}/hats/${HAT}.md"
+  fi
 
-echo "### Current Role: $HAT"
-echo ""
+  echo "### Current Role: $HAT"
+  echo ""
 
-if [ -n "$HAT_FILE" ] && [ -f "$HAT_FILE" ]; then
-  # Parse frontmatter
-  NAME=$(han parse yaml name -r --default "" < "$HAT_FILE" 2>/dev/null || echo "")
-  MODE=$(han parse yaml mode -r --default "" < "$HAT_FILE" 2>/dev/null || echo "")
+  if [ -n "$HAT_FILE" ] && [ -f "$HAT_FILE" ]; then
+    # Parse frontmatter
+    NAME=$(han parse yaml name -r --default "" < "$HAT_FILE" 2>/dev/null || echo "")
+    MODE=$(han parse yaml mode -r --default "" < "$HAT_FILE" 2>/dev/null || echo "")
 
-  # Get content after frontmatter
-  INSTRUCTIONS=$(cat "$HAT_FILE" | sed '1,/^---$/d' | sed '1,/^---$/d')
+    # Get content after frontmatter
+    INSTRUCTIONS=$(cat "$HAT_FILE" | sed '1,/^---$/d' | sed '1,/^---$/d')
 
-  echo "**${NAME:-$HAT}** (Mode: ${MODE:-HITL})"
-  echo ""
-  if [ -n "$INSTRUCTIONS" ]; then
-    echo "$INSTRUCTIONS"
+    echo "**${NAME:-$HAT}** (Mode: ${MODE:-HITL})"
+    echo ""
+    if [ -n "$INSTRUCTIONS" ]; then
+      echo "$INSTRUCTIONS"
+      echo ""
+    fi
+  else
+    # No hat file - role is an orchestrator that spawns discipline-specific agents
+    echo "**$HAT** orchestrates work by spawning discipline-specific agents based on unit requirements."
     echo ""
   fi
-else
-  # No hat file - role is an orchestrator that spawns discipline-specific agents
-  echo "**$HAT** orchestrates work by spawning discipline-specific agents based on unit requirements."
-  echo ""
 fi
 
 # AI-DLC Workflow Rules (mandatory for all subagents)

skills/advance/SKILL.md

@@ -45,7 +45,7 @@ const nextIndex = currentIndex + 1;
 
 if (nextIndex >= workflow.length) {
   // At last hat - check DAG status to determine next action
-  // See Step 2b below
+  // See Steps 2b-2d below
 }
 
 const nextHat = workflow[nextIndex];
@@ -68,7 +68,42 @@ CURRENT_UNIT=$(echo "$ITERATION_JSON" | han parse json currentUnit -r --default
 if [ -n "$CURRENT_UNIT" ] && [ -f "$INTENT_DIR/${CURRENT_UNIT}.md" ]; then
   update_unit_status "$INTENT_DIR/${CURRENT_UNIT}.md" "completed"
 fi
+```
+
+### Step 2c: Merge Unit Branch on Completion
+
+After marking a unit as completed, merge the unit branch into the intent branch:
+
+```bash
+# Load config for merge settings
+source "${CLAUDE_PLUGIN_ROOT}/lib/config.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"')
+
+if [ "$AUTO_MERGE" = "true" ]; then
+  UNIT_SLUG="${CURRENT_UNIT#unit-}"
+  UNIT_BRANCH="ai-dlc/${INTENT_SLUG}/${UNIT_SLUG}"
+
+  # Ensure we're on the intent branch
+  git checkout "ai-dlc/${INTENT_SLUG}"
+
+  # Merge unit branch
+  if [ "$AUTO_SQUASH" = "true" ]; then
+    git merge --squash "$UNIT_BRANCH"
+    git commit -m "unit: ${CURRENT_UNIT} completed"
+  else
+    git merge --no-ff "$UNIT_BRANCH" -m "Merge ${CURRENT_UNIT} into intent branch"
+  fi
+
+  # Clean up unit worktree
+  WORKTREE_PATH="/tmp/ai-dlc-${INTENT_SLUG}-${UNIT_SLUG}"
+  [ -d "$WORKTREE_PATH" ] && git worktree remove "$WORKTREE_PATH"
+fi
+```
 
+```bash
 # Get DAG summary
 DAG_SUMMARY=$(get_dag_summary "$INTENT_DIR")
 ALL_COMPLETE=$(echo "$DAG_SUMMARY" | han parse json allComplete -r)
@@ -101,7 +136,7 @@ ${dagSummary.blockedUnits.join('\n')}
 Review blockers and unblock units to continue.`;
 ```
 
-### Step 2c: Spawn Newly Unblocked Units (Agent Teams)
+### Step 2d: Spawn Newly Unblocked Units (Agent Teams)
 
 When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is enabled and completing a unit unblocks new units:
 
@@ -158,10 +193,28 @@ When `/advance` completes the intent (all units done), output:
 ### Criteria Satisfied
 {List of completion criteria}
 
+### Merge to Default Branch
+
+The intent branch is ready to merge:
+
+```bash
+# Load merge config
+source "${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+INTENT_DIR=".ai-dlc/${INTENT_SLUG}"
+CONFIG=$(get_ai_dlc_config "$INTENT_DIR")
+DEFAULT_BRANCH=$(echo "$CONFIG" | jq -r '.default_branch')
+```
+
+```
+Intent branch ready: ai-dlc/{intent-slug} → ${DEFAULT_BRANCH}
+
+Create PR: gh pr create --base ${DEFAULT_BRANCH} --head ai-dlc/{intent-slug}
+```
+
 ### Next Steps
 
 1. **Review changes** - Check the work on branch `ai-dlc/{intent-slug}`
-2. **Create PR** - `gh pr create --base main --head ai-dlc/{intent-slug}`
+2. **Create PR** - `gh pr create --base ${DEFAULT_BRANCH} --head ai-dlc/{intent-slug}`
 3. **Clean up worktrees** - `git worktree remove /tmp/ai-dlc-{intent-slug}`
 4. **Start new task** - Run `/reset` to clear state, then `/elaborate`
 ```

skills/construct/SKILL.md

@@ -158,6 +158,10 @@ Loop over ALL ready units from the DAG (not just one):
 ```bash
 source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
 READY_UNITS=$(find_ready_units "$INTENT_DIR")
+
+# Determine first construction hat (skip "elaborator" if present)
+WORKFLOW_HATS=$(echo "$STATE" | han parse json workflow)
+FIRST_HAT=$(echo "$WORKFLOW_HATS" | jq -r '[.[] | select(. != "elaborator")][0]')
 ```
 
 For EACH ready unit:
@@ -184,31 +188,59 @@ update_unit_status "$UNIT_FILE" "in_progress"
 3. **Initialize unit state in `unitStates`**:
 
 ```bash
-STATE=$(echo "$STATE" | han parse json --set "unitStates.${UNIT_NAME}.hat=planner" --set "unitStates.${UNIT_NAME}.retries=0")
+STATE=$(echo "$STATE" | han parse json --set "unitStates.${UNIT_NAME}.hat=${FIRST_HAT}" --set "unitStates.${UNIT_NAME}.retries=0")
 han keep save iteration.json "$STATE"
 ```
 
-4. **Create shared task via TaskCreate**:
+4. **Load hat instructions for the first hat**:
+
+```bash
+# Load hat instructions for the teammate's role
+HAT_NAME="${FIRST_HAT}"
+HAT_FILE=""
+if [ -f ".ai-dlc/hats/${HAT_NAME}.md" ]; then
+  HAT_FILE=".ai-dlc/hats/${HAT_NAME}.md"
+elif [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/hats/${HAT_NAME}.md" ]; then
+  HAT_FILE="${CLAUDE_PLUGIN_ROOT}/hats/${HAT_NAME}.md"
+fi
+
+# Extract instructions (content after second --- in frontmatter)
+HAT_INSTRUCTIONS=""
+if [ -n "$HAT_FILE" ]; then
+  HAT_INSTRUCTIONS=$(sed '1,/^---$/d' "$HAT_FILE" | sed '1,/^---$/d')
+fi
+```
+
+5. **Select agent type based on hat**:
+
+- `planner` -> `Plan` agent
+- `builder` -> discipline-specific agent (see builder agent selection table below)
+- All other hats (`reviewer`, `red-team`, `blue-team`, etc.) -> `general-purpose` agent
+
+6. **Create shared task via TaskCreate**:
 
 ```javascript
 TaskCreate({
-  subject: `Plan: ${unitName}`,
-  description: `Execute planner role for unit ${unitName}. Worktree: ${WORKTREE_PATH}`,
-  activeForm: `Planning ${unitName}`
+  subject: `${FIRST_HAT}: ${unitName}`,
+  description: `Execute ${FIRST_HAT} role for unit ${unitName}. Worktree: ${WORKTREE_PATH}`,
+  activeForm: `${FIRST_HAT}: ${unitName}`
 })
 ```
 
-5. **Spawn teammate**:
+7. **Spawn teammate with hat instructions in prompt**:
 
 ```javascript
 Task({
-  subagent_type: "Plan",  // planner hat starts as Plan agent
-  description: `planner: ${unitName}`,
-  name: `planner-${unitSlug}`,
+  subagent_type: getAgentTypeForHat(FIRST_HAT, unit.discipline),
+  description: `${FIRST_HAT}: ${unitName}`,
+  name: `${FIRST_HAT}-${unitSlug}`,
   team_name: `ai-dlc-${intentSlug}`,
   mode: modeToAgentTeamsMode(intentMode),
   prompt: `
-    Execute the planner role for this AI-DLC unit.
+    Execute the ${FIRST_HAT} role for unit ${unitName}.
+
+    ## Your Role: ${FIRST_HAT}
+    ${HAT_INSTRUCTIONS}
 
     ## CRITICAL: Work in Worktree
     **Worktree path:** ${WORKTREE_PATH}
@@ -241,53 +273,125 @@ Mode mapping:
 
 The lead processes auto-delivered teammate messages. Handle each event type:
 
-#### Planner Completes
+#### Teammate Completes (Any Hat)
 
-1. Save the plan: `han keep save current-plan.md "<plan content>"`
-2. Update `unitStates.{unit}.hat = "builder"`
-3. Spawn builder teammate:
+When a teammate reports successful completion:
 
-```javascript
-Task({
-  subagent_type: getAgentForDiscipline(unit.discipline),
-  description: `builder: ${unitName}`,
-  name: `builder-${unitSlug}`,
-  team_name: `ai-dlc-${intentSlug}`,
-  mode: modeToAgentTeamsMode(intentMode),
-  prompt: `Execute the builder role for unit ${unitName}...`
-})
+1. Read current hat for this unit from `unitStates.{unit}.hat`
+2. Find current hat's index in the `workflow` array
+3. Determine next hat: `workflow[currentIndex + 1]`
+
+**If next hat exists** (not at end of workflow):
+
+a. Update `unitStates.{unit}.hat = nextHat`
+b. Save state: `han keep save iteration.json "$STATE"`
+c. Load hat file for nextHat:
+
+```bash
+HAT_NAME="${nextHat}"
+HAT_FILE=""
+if [ -f ".ai-dlc/hats/${HAT_NAME}.md" ]; then
+  HAT_FILE=".ai-dlc/hats/${HAT_NAME}.md"
+elif [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/hats/${HAT_NAME}.md" ]; then
+  HAT_FILE="${CLAUDE_PLUGIN_ROOT}/hats/${HAT_NAME}.md"
+fi
+HAT_INSTRUCTIONS=""
+if [ -n "$HAT_FILE" ]; then
+  HAT_INSTRUCTIONS=$(sed '1,/^---$/d' "$HAT_FILE" | sed '1,/^---$/d')
+fi
 ```
 
-#### Builder Completes
+d. Select agent type based on hat:
+   - `planner` -> `Plan` agent
+   - `builder` -> discipline-specific agent (see builder agent selection table below)
+   - All other hats (`reviewer`, `red-team`, `blue-team`, etc.) -> `general-purpose` agent
 
-1. Update `unitStates.{unit}.hat = "reviewer"`
-2. Spawn reviewer teammate:
+e. Spawn teammate with hat instructions in prompt:
 
 ```javascript
 Task({
-  subagent_type: "general-purpose",
-  description: `reviewer: ${unitName}`,
-  name: `reviewer-${unitSlug}`,
+  subagent_type: getAgentTypeForHat(nextHat, unit.discipline),
+  description: `${nextHat}: ${unitName}`,
+  name: `${nextHat}-${unitSlug}`,
   team_name: `ai-dlc-${intentSlug}`,
   mode: modeToAgentTeamsMode(intentMode),
-  prompt: `Execute the reviewer role for unit ${unitName}...`
+  prompt: `
+    Execute the ${nextHat} role for unit ${unitName}.
+
+    ## Your Role: ${nextHat}
+    ${HAT_INSTRUCTIONS}
+
+    ## CRITICAL: Work in Worktree
+    **Worktree path:** ${WORKTREE_PATH}
+    **Branch:** ${UNIT_BRANCH}
+
+    You MUST:
+    1. cd ${WORKTREE_PATH}
+    2. Verify you're on branch ${UNIT_BRANCH}
+    3. Do ALL work in that directory
+    4. Commit changes to that branch
+
+    ## Unit: ${unitName}
+    ## Completion Criteria
+    ${unit.criteria}
+
+    Work according to your role. Report completion via SendMessage to the team lead when done.
+  `
 })
 ```
 
-#### Reviewer APPROVES
+**If no next hat** (last hat in workflow -- unit complete):
+
+a. Mark unit as completed: `update_unit_status "$UNIT_FILE" "completed"`
+b. Remove unit from `unitStates`
+c. Merge unit branch into intent branch:
+
+```bash
+# Merge unit branch into intent branch
+source "${CLAUDE_PLUGIN_ROOT}/lib/config.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"')
+
+if [ "$AUTO_MERGE" = "true" ]; then
+  UNIT_BRANCH="ai-dlc/${INTENT_SLUG}/${UNIT_SLUG}"
+  git checkout "ai-dlc/${INTENT_SLUG}"
+
+  if [ "$AUTO_SQUASH" = "true" ]; then
+    git merge --squash "$UNIT_BRANCH"
+    git commit -m "unit: ${UNIT_NAME} completed"
+  else
+    git merge --no-ff "$UNIT_BRANCH" -m "Merge ${UNIT_NAME} into intent branch"
+  fi
+
+  WORKTREE_PATH="/tmp/ai-dlc-${INTENT_SLUG}-${UNIT_SLUG}"
+  [ -d "$WORKTREE_PATH" ] && git worktree remove "$WORKTREE_PATH"
+fi
+```
+
+d. Check DAG for newly unblocked units
+e. For each newly ready unit, spawn at `workflow[0]` (first hat, skipping "elaborator" if present -- use the first non-elaborator hat):
+
+```bash
+FIRST_HAT=$(echo "$WORKFLOW_HATS" | jq -r '[.[] | select(. != "elaborator")][0]')
+```
+
+Then follow the same spawn logic from Step 3 (load hat instructions, select agent type, spawn teammate with hat instructions in prompt).
+
+#### Teammate Reports Issues (Any Hat)
 
-1. Mark unit completed: `update_unit_status "$UNIT_FILE" "completed"`
-2. Remove unit from `unitStates`
-3. Check DAG for newly unblocked units
-4. For each newly ready unit, go back to Step 3 logic (spawn at planner hat)
+When a teammate reports issues or rejects the work:
 
-#### Reviewer REJECTS
+1. Read current hat index from `workflow` array
+2. Determine previous hat: `workflow[currentIndex - 1]`
+3. Increment `unitStates.{unit}.retries`
+4. If `retries >= 3`: Mark unit as blocked, document in `han keep save blockers.md`
+5. Otherwise: Set `unitStates.{unit}.hat = previousHat`
+6. Load hat file for previousHat
+7. Spawn teammate at previous hat with the feedback/issues in the prompt
 
-1. Increment `unitStates.{unit}.retries`
-2. Check retry limit (max 3):
-   - If `retries >= 3`: Mark unit as blocked, document in `han keep save blockers.md`
-   - If `retries < 3`: Update `unitStates.{unit}.hat = "builder"`, spawn new builder teammate with reviewer feedback in prompt
-3. Continue monitoring
+This means ANY hat can reject -- not just the reviewer. A red-team finding issues sends work back to the previous hat.
 
 #### Blocked