Fix outdated docs and add tasks/worktrees game tracking

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
                   "name": "guide",
                   "source": "./",
                   "description": "Claude Code guide — interactive onboarding walkthrough and Q&A on setup, best practices, automation, and effective workflows",
-                  "version": "2.15.0",
+                  "version": "2.16.0",
                   "license": "CC-BY-4.0",
                   "keywords": ["onboarding", "guide", "tutorial", "best-practices", "automation", "workflows", "migration"]
           }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "guide",
   "description": "A Claude Code guide — skills for interactive onboarding and Q&A on setup, best practices, automation, and effective workflows",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "author": {
     "name": "Ori Nachum"
   },

hooks/scripts/migrate-data.sh

@@ -37,7 +37,7 @@ fi
 command -v jq >/dev/null 2>&1 || exit 0
 
 # Define expected feature categories
-EXPECTED='["shell","editing","reading","search","agents","skills","plugins","web","planning","mcp","notebooks","loop","btw"]'
+EXPECTED='["shell","editing","reading","search","agents","skills","plugins","web","planning","mcp","notebooks","loop","btw","tasks","worktrees"]'
 
 # Add missing fields and categories, preserve all existing data
 # Intentionally does not touch pluginVersion or migrations — those are

hooks/scripts/track-stop.sh

@@ -74,7 +74,7 @@ is_fibonacci "$SESSION" || exit 0
 eval "$(jq -r '
   def multiplier:
     if . == "shell" or . == "editing" or . == "reading" or . == "search" or . == "btw" then 1
-    elif . == "agents" then 100
+    elif . == "agents" or . == "worktrees" then 100
     else 10
     end;
 
@@ -109,15 +109,16 @@ dep_met() {
   local feature="$1"
   case "$feature" in
     agents)       jq -e '.features.skills.count > 0 and .features.planning.count > 0' "$DATA_FILE" >/dev/null 2>&1 ;;
+    worktrees)    jq -e '.features.agents.count > 0' "$DATA_FILE" >/dev/null 2>&1 ;;
     *)            return 0 ;;
   esac
 }
 
 # Level gating: levels 1-2 see intermediate only; 3+ see intermediate + expert
 if [ "$LEVEL" -ge 3 ]; then
-  CANDIDATES="btw skills plugins web planning notebooks mcp loop agents"
+  CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks agents worktrees"
 else
-  CANDIDATES="btw skills plugins web planning notebooks mcp loop"
+  CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks"
 fi
 
 # Filter: unused, not yet suggested, deps met
@@ -140,7 +141,7 @@ if [ -n "$ELIGIBLE" ]; then
   WEIGHTED=""
   for feat in $ELIGIBLE; do
     case "$feat" in
-      agents) WEIGHTED="$WEIGHTED $feat $feat $feat" ;;
+      agents|worktrees) WEIGHTED="$WEIGHTED $feat $feat $feat" ;;
       *)      WEIGHTED="$WEIGHTED $feat" ;;
     esac
   done
@@ -160,6 +161,8 @@ if [ -n "$ELIGIBLE" ]; then
     loop)      TIP="Loop Scheduling — use /loop to monitor deploys or triage tickets on a timer" ;;
     btw)       TIP="Quick Aside — use /btw to ask a one-off question without cluttering context" ;;
     agents)    TIP="Sub Agents — delegate complex tasks to run in parallel" ;;
+    tasks)     TIP="Task Management — use TaskCreate to break work into tracked steps" ;;
+    worktrees) TIP="Worktrees — use isolation: 'worktree' in agents for parallel git work" ;;
     *)         TIP="$PICK" ;;
   esac
 
@@ -170,5 +173,5 @@ if [ -n "$ELIGIBLE" ]; then
 
   echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | Try: ${TIP} (/guide:level-up for more)"
 else
-  echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | ${UNIQUE}/13 features (/guide:level-up)"
+  echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | ${UNIQUE}/15 features (/guide:level-up)"
 fi

hooks/scripts/track-usage.sh

@@ -53,6 +53,11 @@ case "$TOOL_NAME" in
   WebFetch|WebSearch)            CATEGORY="web" ;;
   EnterPlanMode|ExitPlanMode)    CATEGORY="planning" ;;
   NotebookEdit)                  CATEGORY="notebooks" ;;
+  TaskCreate|TaskGet|TaskList|TaskUpdate|TaskStop|TaskOutput)
+                                 CATEGORY="tasks" ;;
+  EnterWorktree|ExitWorktree)    CATEGORY="worktrees" ;;
+  CronCreate|CronDelete|CronList)
+                                 CATEGORY="loop" ;;
   Agent)
     # Only count user-initiated agents (not built-in or plugin ones)
     SUBAGENT_TYPE="$(echo "$PAYLOAD" | jq -r '.tool_input.subagent_type // empty')"

skills/ask/references/beginner/built-ins.md

@@ -120,18 +120,27 @@ Claude Code provides these lifecycle events that you can hook into. No hooks are
 | `UserPromptSubmit` | User submits a prompt | Yes |
 | `PreToolUse` | Before a tool call executes | Yes |
 | `PermissionRequest` | Permission dialog appears | Yes |
+| `PermissionDenied` | Tool call denied by auto mode classifier | No |
 | `PostToolUse` | After a tool call succeeds | No |
 | `PostToolUseFailure` | After a tool call fails | No |
 | `Notification` | Claude sends a notification | No |
+| `InstructionsLoaded` | CLAUDE.md or memory files loaded into context | No |
 | `SubagentStart` | A subagent is spawned | No |
 | `SubagentStop` | A subagent finishes | Yes |
 | `Stop` | Claude finishes responding | Yes |
+| `StopFailure` | Turn ends due to an API error | No |
 | `TeammateIdle` | Agent team teammate goes idle | Yes |
+| `TaskCreated` | A task is created via TaskCreate | Yes |
 | `TaskCompleted` | Task is marked as completed | Yes |
+| `FileChanged` | A watched file changes on disk | No |
+| `CwdChanged` | Working directory changes (e.g., cd command) | No |
 | `ConfigChange` | Configuration file changes | Yes (except policy) |
 | `WorktreeCreate` | Worktree is being created | Yes |
 | `WorktreeRemove` | Worktree is being removed | No |
 | `PreCompact` | Before context compaction | No |
+| `PostCompact` | After context compaction completes | No |
+| `Elicitation` | MCP server requests user input during a tool call | Yes |
+| `ElicitationResult` | User responds to an MCP elicitation | No |
 | `SessionEnd` | Session terminates | No |
 
 Hook handlers can be shell commands (`type: "command"`), HTTP endpoints (`type: "http"`), LLM prompts (`type: "prompt"`), or agentic verifiers (`type: "agent"`).

skills/ask/references/beginner/choosing-your-model.md

@@ -37,12 +37,16 @@ Opus 4.6 and Sonnet 4.6 support **effort levels** that control how deeply the mo
 | **Low** | Minimal reasoning | Fastest | Straightforward tasks: rename a variable, add a log line, simple questions |
 | **Medium** (Opus default) | Balanced reasoning | Moderate | Most daily work: implement features, fix known bugs, write tests |
 | **High** | Deep reasoning | Slowest | Hard problems: architectural design, subtle bugs, complex multi-file changes |
+| **Max** | Deepest reasoning, no token constraint | Slowest | The hardest problems: complex architecture across many files, novel algorithm design. Opus 4.6 only, does not persist across sessions. |
+
+> **Note:** The `max` effort level is available on Opus 4.6 only and does not persist across sessions except through the `CLAUDE_CODE_EFFORT_LEVEL` environment variable.
 
 ### How to set effort level
 
 - **In /model**: use left/right arrow keys to adjust the effort slider
-- **Environment variable**: `export CLAUDE_CODE_EFFORT_LEVEL=low|medium|high`
+- **Environment variable**: `export CLAUDE_CODE_EFFORT_LEVEL=low|medium|high|max`
 - **Settings file**: set `"effortLevel": "medium"` in your settings
+- **Slash command**: `/effort low`, `/effort medium`, `/effort high`, or `/effort max`
 - **One-off deep thinking**: type "ultrathink" anywhere in your prompt to set effort to high for that single turn
 
 ## When to Use Each Model
@@ -102,6 +106,7 @@ Here's how to think about combining model choice and effort level:
 | Debug a race condition | Opus + medium effort | Needs deeper reasoning to trace concurrent paths |
 | Design a caching strategy | Opus + high effort | Complex tradeoffs, needs thorough analysis |
 | Review code for security issues | Opus + high effort | Subtle issues require careful examination |
+| Novel algorithm design or architecture from scratch | Opus + max effort | Deepest possible reasoning with no token constraint |
 | Generate test boilerplate | Sonnet + low effort | Repetitive, well-defined task |
 | Understand unfamiliar codebase | Sonnet + medium effort (or Haiku sub agent) | Balances thoroughness with speed |
 

skills/ask/references/beginner/starting-to-work.md

@@ -13,14 +13,15 @@ permalink: /starting-to-work/
 
 Before you start typing a prompt, you need to make one key decision: **what permission mode should Claude run in?** This determines how much autonomy Claude has — from read-only exploration to fully autonomous execution.
 
-## The Three Permission Modes
+## Permission Modes
 
 You cycle through modes using **Shift+Tab** during a session, or set them at startup.
 
 | Mode | Indicator | Claude can read files | Claude can edit files | Claude can run commands | You approve each action |
 |---|---|---|---|---|---|
 | **Normal** (default) | (none) | ✅ | ✅ (with approval) | ✅ (with approval) | Yes — for edits and commands |
 | **Accept Edits** | `⏵⏵ accept edits on` | ✅ | ✅ (auto-approved) | ✅ (with approval) | Only for shell commands |
+| **Auto** (research preview) | `🤖 auto mode on` | ✅ | ✅ (auto-approved) | ✅ (auto-approved) | No — background safety checks verify alignment |
 | **Plan Mode** | `⏸ plan mode on` | ✅ | ❌ | ❌ | N/A — Claude only reads and plans |
 
 ## Choosing Your Mode
@@ -41,7 +42,7 @@ You're about to work on something **complex, risky, or unfamiliar** and you want
 In Plan Mode, Claude can read files, search code, and analyze your codebase, but cannot write files or execute commands. It uses `AskUserQuestion` to gather requirements and propose plans.
 
 **The workflow:**
-1. Start in Plan Mode: `claude --permission-mode plan` or press `Shift+Tab` twice
+1. Start in Plan Mode: `claude --permission-mode plan` or press `Shift+Tab` to cycle through modes
 2. Ask Claude to explore and plan: "I need to add OAuth. What files need to change? Create a plan."
 3. Review the plan (press `Ctrl+G` to edit it in your text editor)
 4. Switch to Normal Mode (`Shift+Tab`) and let Claude implement
@@ -106,6 +107,27 @@ File edits (Write, Edit) are auto-approved for the session. Shell commands still
 3. Claude writes files without asking — you only approve shell commands
 4. Review the diff afterward: `/diff` or `git diff`
 
+### 🌳 Start in Auto mode when...
+
+> **Research preview** — this mode is experimental and may change. It requires understanding its safety model before use.
+
+You **fully understand the safety classifier** and are comfortable with autonomous tool execution. Auto mode is an expert-level capability, not a convenience upgrade from Accept Edits.
+
+**Typical scenarios:**
+
+- You understand how the background safety classifier works and have configured `autoMode.environment`
+- You're working on a well-tested codebase with good CI coverage
+- You want maximum speed and are prepared to review denied actions after the fact
+
+**How it works:**
+Auto-approves tool calls with background safety checks that verify actions align with your request. A background classifier evaluates each action — anything that appears misaligned is denied and logged in `/permissions`. You configure trusted infrastructure (repos, domains, buckets) in `autoMode.environment` settings so the classifier knows what's "internal" vs. "external."
+
+**The workflow:**
+1. Configure `autoMode.environment` in your settings with your trusted infrastructure
+2. Start with `claude --permission-mode auto` or press `Shift+Tab` to cycle to Auto mode
+3. Describe your task and let Claude work
+4. Check `/permissions` to review any denied actions and retry false positives
+
 ## Decision Flowchart
 
 ```
@@ -119,6 +141,10 @@ Am I exploring or planning?
     └── Is this a quick, low-risk task?
         ├── Yes → Normal mode (just approve as you go)
         └── No, it's complex → Start in Plan Mode first
+
+Auto mode (🌳 Expert, research preview):
+  Use only if you fully understand the safety model
+  and are comfortable with autonomous tool execution.
 ```
 
 ## The Explore → Plan → Implement Workflow
@@ -161,7 +187,7 @@ Claude implements, and you supervise (Normal) or let it write freely (Accept Edi
 > Commit with a descriptive message and create a PR.
 ```
 
-## 🌿 Beyond the Three Modes: Advanced Options
+## 🌿 Beyond the Permission Modes: Advanced Options
 
 ### `dontAsk` mode
 
@@ -188,6 +214,7 @@ An alternative to permission modes — OS-level isolation that restricts filesys
 | Plan a complex change | Plan Mode |
 | Implement with active supervision | Normal |
 | Implement with file-edit freedom | Accept Edits |
+| Let Claude work fully autonomously | Auto (research preview) |
 | Run in CI/automation | `bypassPermissions` (in a sandbox) |
 | Lock down to specific operations | `dontAsk` + allow rules |
 | Ask a quick question without losing context | `/btw` (one-off, stays out of context) |
@@ -196,7 +223,7 @@ An alternative to permission modes — OS-level isolation that restricts filesys
 
 You don't have to pick one mode and stick with it. Switch freely:
 
-- **Shift+Tab**: cycles Normal → Accept Edits → Plan Mode → Normal
+- **Shift+Tab**: cycles Normal → Accept Edits → Auto → Plan Mode → Normal
 - **`/plan`**: enters Plan Mode from the prompt
 - The mode indicator at the bottom of the terminal tells you which mode you're in
 

skills/ask/references/intermediate/hooks.md

@@ -150,19 +150,27 @@ exit 0
 | `UserPromptSubmit` | User submits a prompt | Yes |
 | `PreToolUse` | Before a tool call executes | Yes |
 | `PermissionRequest` | Permission dialog appears | Yes |
+| `PermissionDenied` | Tool call denied by auto mode classifier | No |
 | `PostToolUse` | After a tool call succeeds | No (tool already ran) |
 | `PostToolUseFailure` | After a tool call fails | No |
 | `Notification` | Claude sends a notification | No |
+| `InstructionsLoaded` | CLAUDE.md/memory files loaded | No |
 | `SubagentStart` | A subagent is spawned | No |
 | `SubagentStop` | A subagent finishes | Yes |
 | `Stop` | Claude finishes responding | Yes |
-| `InstructionsLoaded` | CLAUDE.md/memory files loaded | No |
-| `ConfigChange` | Settings file changes | Yes |
+| `StopFailure` | Turn ends due to an API error | No |
 | `TeammateIdle` | A teammate has no pending tasks | Yes |
+| `TaskCreated` | A task is created via TaskCreate | Yes |
 | `TaskCompleted` | A background task finishes | Yes |
+| `FileChanged` | A watched file changes on disk | No |
+| `CwdChanged` | Working directory changes (e.g., cd command) | No |
+| `ConfigChange` | Settings file changes | Yes |
 | `WorktreeCreate` | A worktree is created | Yes |
 | `WorktreeRemove` | A worktree is removed | No |
 | `PreCompact` | Before context compaction | No |
+| `PostCompact` | After context compaction completes | No |
+| `Elicitation` | MCP server requests user input during a tool call | Yes |
+| `ElicitationResult` | User responds to an MCP elicitation | No |
 | `SessionEnd` | Session terminates | No |
 
 ## Next Steps

skills/ask/references/intermediate/loop.md

@@ -72,7 +72,7 @@ Each iteration runs in the same conversation, so Claude has full context of prev
 | Constraint | Detail |
 |---|---|
 | **Session-scoped** | Tasks die when your terminal closes, the session exits, or the machine restarts. There is no persistence across sessions. |
-| **3-day auto-expiry** | Recurring tasks automatically expire 3 days after creation — the task fires one final time, then self-deletes. |
+| **7-day auto-expiry** | Recurring tasks automatically expire 7 days after creation — the task fires one final time, then self-deletes. |
 | **50 task limit** | Maximum 50 scheduled tasks per session. |
 | **Fires only when idle** | If Claude is busy when the interval elapses, the task waits. There is no catch-up for missed intervals — it fires once when Claude becomes idle. |
 | **Minute granularity** | The scheduler is cron-based; intervals under 1 minute are rounded up to the nearest minute. |
@@ -81,7 +81,7 @@ Each iteration runs in the same conversation, so Claude has full context of prev
 
 **What this means in practice:**
 
-- The `d` unit exists but is impractical — `/loop 1d` fires roughly 3 times before auto-expiry.
+- The `d` unit exists but is impractical — `/loop 1d` fires roughly 7 times before auto-expiry.
 - Anything longer than a few hours is unreliable. Best practice: intervals from minutes to a few hours within a single working session.
 - For unattended automation that runs without an active session, see [GitHub Actions](github-actions.md).
 
@@ -175,7 +175,7 @@ GitHub Actions is for **unattended automation** — CI/CD pipelines, scheduled m
 | Aspect | /loop | GitHub Actions |
 |---|---|---|
 | **Setup time** | Seconds — just type the command | Minutes to hours — write YAML, configure secrets, push |
-| **Persistence** | Dies with session (3-day max) | Runs on GitHub's infrastructure |
+| **Persistence** | Dies with session (7-day max) | Runs on GitHub's infrastructure |
 | **Reliability** | Depends on session staying alive | Production-grade, team-visible |
 | **Cost model** | Claude tokens per iteration | GitHub Actions minutes + Claude tokens |
 | **Best for** | In-session monitoring, deploy checks, on-call triage | Production workflows, team-wide automation, compliance |

skills/game-mode/SKILL.md

@@ -82,7 +82,9 @@ Present the available commands:
     "mcp":       { "count": 0, "lastUsed": null },
     "notebooks": { "count": 0, "lastUsed": null },
     "loop":      { "count": 0, "lastUsed": null },
-    "btw":       { "count": 0, "lastUsed": null }
+    "btw":       { "count": 0, "lastUsed": null },
+    "tasks":     { "count": 0, "lastUsed": null },
+    "worktrees": { "count": 0, "lastUsed": null }
   },
   "tokens": {
     "read": 0,
@@ -96,7 +98,7 @@ Present the available commands:
 ```
 
 1. Tell the user game mode is now active. Mention:
-   - Tool usage is being tracked across 13 feature categories
+   - Tool usage is being tracked across 15 feature categories
    - Use `/guide:game-mode stats` to see their dashboard
    - Use `/guide:game-mode off` to pause tracking
    - Data is stored locally and never transmitted
@@ -122,8 +124,8 @@ Present the available commands:
 | Tier | Multiplier | Features |
 |---|---|---|
 | Beginner | x1 | shell, editing, reading, search, btw |
-| Intermediate | x10 | skills, plugins, web, planning, notebooks, mcp, loop |
-| Expert | x100 | agents |
+| Intermediate | x10 | skills, plugins, web, planning, notebooks, mcp, loop, tasks |
+| Expert | x100 | agents, worktrees |
 
 1. Compute: `raw_points = sum(feature.count * multiplier)` and `score = sqrt(raw_points)` to 2 decimal places
 1. Count unique features (count > 0)
@@ -159,9 +161,11 @@ Present the available commands:
 |  ⚪ Sub Agents       E       8     800   3h ago       |
 |  ⚪ MCP Tools        I       1      10   7d ago       |
 |  ⚪ Loop/Schedule    I       0       0   never        |
+|  ⚪ Task Mgmt        I       0       0   never        |
+|  ⚪ Worktrees        E       0       0   never        |
 +=======================================================+
 |  Raw: 1053 pts | Score: sqrt(1053) = 32.45            |
-|  Features: 10/13 unlocked                             |
+|  Features: 10/15 unlocked                             |
 |  Tokens: ~12.4K read, ~3.1K write                     |
 |  Next level: Master (score 55+, 10+ features)         |
 |  Migrated: unknown → 2.2.0 (2026-03-09)              |