feat: add Agent Teams support with intent-level modes and dynamic hat discovery

Move operating modes from individual hats to the intent level, enabling
consistent permission models across all teammates when using Claude Code's
Agent Teams. Hats now carry descriptions for dynamic discovery during
elaboration. Skills and commands updated to use han CLI instead of MCP tools.

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

Author: jwaldrip

README.md

@@ -45,7 +45,7 @@ curl -fsSL https://han.guru/install.sh | bash
 
 ### Operating Modes
 
-Each hat operates in one of three modes that define the level of human oversight:
+Each intent operates in one of three modes that define the level of human oversight:
 
 | Mode | Name | Description |
 |------|------|-------------|
@@ -74,6 +74,7 @@ Define what you're building with clear completion criteria:
 ---
 status: active
 workflow: default
+mode: OHOTL
 started_at: 2026-01-28T15:30:00Z
 ---
 
@@ -204,6 +205,7 @@ Examples:
 |-------|--------|------|-------------|
 | `status` | Y | Y | `active`, `completed`, `blocked`, `abandoned` |
 | `workflow` | Y | | Workflow name (default, tdd, adversarial, hypothesis) |
+| `mode` | Y | | Operating mode (`HITL`, `OHOTL`, `AHOTL`) |
 | `started_at` | Y | Y | ISO 8601 timestamp |
 | `completed_at` | | Y | ISO 8601 timestamp |
 | `branch` | | Y | Git branch name |
@@ -235,38 +237,38 @@ All hats follow the [Agent SOP format](https://github.com/strands-agents/agent-s
 
 ### Default Workflow
 
-| Hat | Mode | Focus |
-|-----|------|-------|
-| Elaborator | HITL | Define intent and criteria with user |
-| Planner | HITL | Plan what to tackle this iteration |
-| Builder | OHOTL | Implement according to plan and criteria |
-| Reviewer | HITL | Verify implementation meets criteria |
+| Hat | Focus |
+|-----|-------|
+| Elaborator | Define intent and criteria with user |
+| Planner | Plan what to tackle this iteration |
+| Builder | Implement according to plan and criteria |
+| Reviewer | Verify implementation meets criteria |
 
 ### TDD Workflow
 
-| Hat | Mode | Focus |
-|-----|------|-------|
-| Test Writer | OHOTL | Write failing tests first |
-| Implementer | OHOTL | Make tests pass with minimal code |
-| Refactorer | OHOTL | Improve code while keeping tests green |
+| Hat | Focus |
+|-----|-------|
+| Test Writer | Write failing tests first |
+| Implementer | Make tests pass with minimal code |
+| Refactorer | Improve code while keeping tests green |
 
 ### Adversarial Workflow
 
-| Hat | Mode | Focus |
-|-----|------|-------|
-| Builder | OHOTL | Implement to spec |
-| Red Team | OHOTL | Attack - find vulnerabilities |
-| Blue Team | OHOTL | Defend - fix vulnerabilities |
-| Reviewer | HITL | Final security review |
+| Hat | Focus |
+|-----|-------|
+| Builder | Implement to spec |
+| Red Team | Attack - find vulnerabilities |
+| Blue Team | Defend - fix vulnerabilities |
+| Reviewer | Final security review |
 
 ### Hypothesis Workflow
 
-| Hat | Mode | Focus |
-|-----|------|-------|
-| Observer | OHOTL | Gather data about the bug |
-| Hypothesizer | HITL | Form theories about the cause |
-| Experimenter | OHOTL | Test hypotheses systematically |
-| Analyst | HITL | Evaluate results and implement fix |
+| Hat | Focus |
+|-----|-------|
+| Observer | Gather data about the bug |
+| Hypothesizer | Form theories about the cause |
+| Experimenter | Test hypotheses systematically |
+| Analyst | Evaluate results and implement fix |
 
 ## State Management
 
@@ -289,7 +291,7 @@ Session-scoped, cleared on `/reset`:
 | `scratchpad.md` | Learnings and progress notes |
 | `blockers.md` | Documented blockers |
 
-> **Note:** Commands use `han_keep_save()` and `han_keep_load()` syntax which are **MCP tool calls**, not CLI commands. Claude executes these as MCP tool invocations. The hooks use `han keep` CLI commands directly.
+> **Note:** Both commands and hooks use `han keep` CLI commands (`han keep save`, `han keep load`, `han keep delete`, `han keep list`) for state management.
 
 ## Customization
 
@@ -310,7 +312,7 @@ Create `.ai-dlc/hats/` in your project to override or add hats:
 <!-- .ai-dlc/hats/researcher.md -->
 ---
 name: "Researcher"
-mode: HITL
+description: "Investigate before implementing. Research existing solutions and make recommendations."
 ---
 
 # Researcher

commands/advance.md

@@ -31,9 +31,9 @@ Advances to the next hat in the workflow sequence. For example, in the default w
 
 ### Step 1: Load Current State
 
-```javascript
-// Intent-level state is stored on current branch (intent branch)
-const state = JSON.parse(han_keep_load({ scope: "branch", key: "iteration.json" }));
+```bash
+# Intent-level state is stored on current branch (intent branch)
+state=$(han keep load iteration.json --quiet)
 ```
 
 ### Step 2: Determine Next Hat (or Handle Completion)
@@ -75,45 +75,37 @@ ALL_COMPLETE=$(echo "$DAG_SUMMARY" | han parse json allComplete -r)
 READY_COUNT=$(echo "$DAG_SUMMARY" | han parse json readyCount -r)
 ```
 
-```javascript
-if (dagSummary.allComplete) {
-  // ALL UNITS COMPLETE - Mark intent as done
-  state.status = "complete";
-  han_keep_save({ scope: "branch", key: "iteration.json", content: JSON.stringify(state) });
-
-  // Output completion summary (see Step 5)
-  return completionSummary;
-}
-
-if (dagSummary.readyCount > 0) {
-  // MORE UNITS READY - Loop back to builder
-  state.hat = workflow[2] || "builder";  // Reset to builder (index 2 in default workflow)
-  state.currentUnit = null;  // Will be set by /construct when it picks next unit
-  han_keep_save({ scope: "branch", key: "iteration.json", content: JSON.stringify(state) });
+```bash
+if [ "$ALL_COMPLETE" = "true" ]; then
+  # ALL UNITS COMPLETE - Mark intent as done
+  updated_state=$(echo "$state" | jq '.status = "complete"')
+  han keep save iteration.json "$updated_state"
 
-  return `Unit completed. ${dagSummary.readyCount} more unit(s) ready. Continuing construction...`;
-}
+  # Output completion summary (see Step 5)
+  # return completionSummary
+fi
 
-// BLOCKED - No ready units, human must intervene
-return `All remaining units are blocked. Human intervention required.
+if [ "$READY_COUNT" -gt 0 ]; then
+  # MORE UNITS READY - Loop back to builder
+  # Reset to builder (index 2 in default workflow), clear currentUnit
+  updated_state=$(echo "$state" | jq '.hat = "builder" | .currentUnit = null')
+  han keep save iteration.json "$updated_state"
 
-Blocked units:
-${dagSummary.blockedUnits.join('\n')}
+  echo "Unit completed. ${READY_COUNT} more unit(s) ready. Continuing construction..."
+fi
 
-Review blockers and unblock units to continue.`;
+# BLOCKED - No ready units, human must intervene
+echo "All remaining units are blocked. Human intervention required."
+echo "Review blockers and unblock units to continue."
 ```
 
 ### Step 3: Update State
 
-```javascript
-state.hat = nextHat;
-state.needsAdvance = true;  // Signal SessionStart to increment iteration
-// Intent-level state saved to current branch (intent branch)
-han_keep_save({
-  scope: "branch",
-  key: "iteration.json",
-  content: JSON.stringify(state)
-});
+```bash
+# Update hat and signal SessionStart to increment iteration
+# Intent-level state saved to current branch (intent branch)
+updated_state=$(echo "$state" | jq --arg hat "$nextHat" '.hat = $hat | .needsAdvance = true')
+han keep save iteration.json "$updated_state"
 ```
 
 ### Step 4: Confirm (Normal Advancement)

commands/construct.md

@@ -97,10 +97,10 @@ fi
 
 ### Step 1: Load State
 
-```javascript
-// Intent-level state is stored on the current branch (intent branch)
-const state = JSON.parse(han_keep_load({ scope: "branch", key: "iteration.json" }));
-const intentSlug = han_keep_load({ scope: "branch", key: "intent-slug" }) || null;
+```bash
+# Intent-level state is stored on the current branch (intent branch)
+state=$(han keep load iteration.json --quiet)
+intentSlug=$(han keep load intent-slug --quiet)
 ```
 
 If no state exists:
@@ -153,14 +153,11 @@ update_unit_status "$UNIT_FILE" "in_progress"
 
 **Track current unit in iteration state** so `/advance` knows which unit to mark completed:
 
-```javascript
-state.currentUnit = UNIT_NAME;  // e.g., "unit-01-core-backend"
-// Intent-level state saved to current branch (intent branch)
-han_keep_save({
-  scope: "branch",
-  key: "iteration.json",
-  content: JSON.stringify(state)
-});
+```bash
+# Update currentUnit in state, e.g., "unit-01-core-backend"
+# Intent-level state saved to current branch (intent branch)
+updated_state=$(echo "$state" | jq --arg unit "$UNIT_NAME" '.currentUnit = $unit')
+han keep save iteration.json "$updated_state"
 ```
 
 **Note:** The `update_unit_status` function validates that:
@@ -392,10 +389,10 @@ These are managed by the orchestrator and stored on the intent branch (`ai-dlc/{
 | `current-plan.md` | Planner's output |
 | `intent-slug` | Slug identifier |
 
-```javascript
-// Orchestrator reads/writes to current branch (intent branch)
-han_keep_load({ scope: "branch", key: "iteration.json" })
-han_keep_save({ scope: "branch", key: "iteration.json", content: "..." })
+```bash
+# Orchestrator reads/writes to current branch (intent branch)
+han keep load iteration.json --quiet
+han keep save iteration.json "..."
 ```
 
 ### Unit-Level State (use current branch - omit `branch_name`)
@@ -408,10 +405,10 @@ These are specific to each unit's worktree branch:
 | `next-prompt.md` | Continuation prompt for this unit |
 | `blockers.md` | Blockers specific to this unit |
 
-```javascript
-// Subagent reads/writes to its own branch (current branch)
-han_keep_load({ scope: "branch", key: "scratchpad.md" })
-han_keep_save({ scope: "branch", key: "scratchpad.md", content: "..." })
+```bash
+# Subagent reads/writes to its own branch (current branch)
+han keep load scratchpad.md --quiet
+han keep save scratchpad.md "..."
 ```
 
 **Why this matters:** When a subagent runs in a worktree on branch `ai-dlc/{intent}/{unit}`, it saves its own working notes to its unit branch. The orchestrator runs on the intent branch and manages intent-level state there.

commands/elaborate.md

@@ -372,26 +372,12 @@ This ensures:
 
 Intent-level state is saved to the current branch (which is now the intent branch):
 
-```javascript
-// Intent-level state → current branch (intent branch)
-han_keep_save({
-  scope: "branch",
-  key: "intent-slug",
-  content: "{intent-slug}"
-})
-
-// Intent-level state → current branch (intent branch)
-han_keep_save({
-  scope: "branch",
-  key: "iteration.json",
-  content: JSON.stringify({
-    iteration: 1,
-    hat: "{first-hat-after-elaborator}",
-    workflowName: "{workflow}",
-    workflow: ["{hat1}", "{hat2}", ...],
-    status: "active"
-  })
-})
+```bash
+# Intent-level state → current branch (intent branch)
+han keep save intent-slug "{intent-slug}"
+
+# Intent-level state → current branch (intent branch)
+han keep save iteration.json '{"iteration":1,"hat":"{first-hat-after-elaborator}","workflowName":"{workflow}","workflow":["{hat1}","{hat2}"],"status":"active"}'
 ```
 
 ---

commands/fail.md

@@ -28,9 +28,9 @@ If already at the first hat (elaborator by default), this command is blocked.
 
 ### Step 1: Load Current State
 
-```javascript
-// Intent-level state is stored on current branch (intent branch)
-const state = JSON.parse(han_keep_load({ scope: "branch", key: "iteration.json" }));
+```bash
+# Intent-level state is stored on current branch (intent branch)
+state=$(han keep load iteration.json --quiet)
 ```
 
 ### Step 2: Determine Previous Hat
@@ -52,26 +52,19 @@ const prevHat = workflow[prevIndex];
 
 Before updating state, save the reason for failing:
 
-```javascript
-// Append to blockers (unit-level state - saved to current branch)
-const reason = "Reviewer found issues: [describe issues]";
-han_keep_save({
-  scope: "branch",
-  key: "blockers.md",
-  content: reason
-});
+```bash
+# Append to blockers (unit-level state - saved to current branch)
+reason="Reviewer found issues: [describe issues]"
+han keep save blockers.md "$reason"
 ```
 
 ### Step 4: Update State
 
-```javascript
-state.hat = prevHat;
-// Intent-level state saved to current branch (intent branch)
-han_keep_save({
-  scope: "branch",
-  key: "iteration.json",
-  content: JSON.stringify(state)
-});
+```bash
+# Update hat to previous hat
+# Intent-level state saved to current branch (intent branch)
+updated_state=$(echo "$state" | jq --arg hat "$prevHat" '.hat = $hat')
+han keep save iteration.json "$updated_state"
 ```
 
 ### Step 5: Confirm

commands/reset.md

@@ -34,33 +34,20 @@ The work you did is preserved in git. Only the AI-DLC workflow state is cleared.
 
 If the task is not complete, warn:
 
-```javascript
-// Intent-level state is on current branch (intent branch)
-const state = JSON.parse(han_keep_load({ scope: "branch", key: "iteration.json" }) || "{}");
-
-if (state.status !== "complete") {
-  console.log("Warning: Task is not complete. Current hat:", state.hat);
-  console.log("Are you sure you want to clear all state?");
-}
+```bash
+# Intent-level state is on current branch (intent branch)
+state=$(han keep load iteration.json --quiet)
+
+status=$(echo "$state" | jq -r '.status // empty')
+if [ "$status" != "complete" ]; then
+  hat=$(echo "$state" | jq -r '.hat // empty')
+  echo "Warning: Task is not complete. Current hat: $hat"
+  echo "Are you sure you want to clear all state?"
+fi
 ```
 
 ### Step 2: Delete All AI-DLC Keys
 
-```javascript
-// Clear intent-level state (from current branch / intent branch)
-han_keep_delete({ scope: "branch", key: "iteration.json" });
-han_keep_delete({ scope: "branch", key: "intent.md" });
-han_keep_delete({ scope: "branch", key: "completion-criteria.md" });
-han_keep_delete({ scope: "branch", key: "current-plan.md" });
-han_keep_delete({ scope: "branch", key: "intent-slug" });
-
-// Clear unit-level state (from current branch, if on a unit branch)
-han_keep_delete({ scope: "branch", key: "scratchpad.md" });
-han_keep_delete({ scope: "branch", key: "blockers.md" });
-han_keep_delete({ scope: "branch", key: "next-prompt.md" });
-```
-
-Or use the CLI:
 ```bash
 # Clear intent-level state from current branch (intent branch)
 han keep delete iteration.json