feat(writing-plans): add model directive support for automatic model switching

[cbolden15]

Summary

Adds <!-- model: xxx --> directive support to the writing-plans skill so that generated plans embed explicit model hints at each phase boundary. A companion PostToolUse hook (installed separately in ~/.claude/settings.json) reads these directives and auto-switches the active Claude model as the plan is executed.

How it works

Plans generated by writing-plans now include directives immediately before task checklists:

<!-- model: sonnet -->
- [ ] Write the failing test
- [ ] Implement the minimal code

<!-- model: haiku -->
- [ ] Run: `pytest tests/path/test.py -v`
- [ ] Commit

A hook registered in ~/.claude/settings.json fires on every Read tool call. When it reads a .md file that contains both <!-- model: --> directives and unchecked - [ ] tasks, it finds the directive for the current phase (the one above the first unchecked task) and writes the resolved model ID to ~/.claude/settings.local.json. Claude Code picks this up immediately.

Model assignment rules

Task type	Model	Why
Architecture, design decisions, hard debugging	opus	Deep reasoning required
Writing tests, writing implementation, refactoring	sonnet	Needs codebase understanding
Running commands, committing, installing deps	haiku	No reasoning needed

Hook setup (companion config)

// ~/.claude/settings.json — PostToolUse section
{
  "PostToolUse": [
    {
      "matcher": "Read",
      "hooks": [
        {
          "type": "command",
          "command": "$HOME/.claude/hooks/plan-model-switch.sh"
        }
      ]
    }
  ]
}

#!/usr/bin/env bash
# ~/.claude/hooks/plan-model-switch.sh
trap 'exit 0' ERR
SETTINGS_FILE="$HOME/.claude/settings.local.json"
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
[ "$TOOL_NAME" != "Read" ] && exit 0
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
echo "$FILE_PATH" | grep -qE '\.md$' || exit 0
CONTENT=$(echo "$INPUT" | jq -r '
  if (.tool_response | type) == "string" then .tool_response
  elif (.tool_response.content | type) == "string" then .tool_response.content
  else empty
  end
' 2>/dev/null)
[ -z "$CONTENT" ] && exit 0
echo "$CONTENT" | grep -q '^- \[ \]' || exit 0
MODEL=$(echo "$CONTENT" | awk '
  /<!-- model:/ {
    m = $0; gsub(/.*<!-- model: */, "", m); gsub(/ *-->.*/, "", m)
    gsub(/^[ \t]+|[ \t]+$/, "", m); current = m
  }
  /^- \[ \]/ { if (current != "") { print current }; exit }
')
[ -z "$MODEL" ] && exit 0
case "$(echo "$MODEL" | tr '[:upper:]' '[:lower:]')" in
  opus*|claude-opus*)     FULL_MODEL="claude-opus-4-6" ;;
  sonnet*|claude-sonnet*) FULL_MODEL="claude-sonnet-4-6" ;;
  haiku*|claude-haiku*)   FULL_MODEL="claude-haiku-4-5-20251001" ;;
  *) exit 0 ;;
esac
CURRENT=$(jq -r '.model // empty' "$SETTINGS_FILE" 2>/dev/null)
[ "$CURRENT" = "$FULL_MODEL" ] && exit 0
[ ! -f "$SETTINGS_FILE" ] && echo '{}' > "$SETTINGS_FILE"
jq --arg m "$FULL_MODEL" '.model = $m' "$SETTINGS_FILE" > /tmp/plan-model-tmp.json \
  && mv /tmp/plan-model-tmp.json "$SETTINGS_FILE"

Changes

• skills/writing-plans/SKILL.md: Added Model Directives section with 3-tier model table, updated Task Structure template to include directives at step boundaries, added rule about splitting tasks at model boundaries

Notes

• Directives are opt-in — plans without them behave exactly as before
• The hook fires globally on all .md reads, not just plan files — it only acts when both a directive and unchecked tasks are present
• Works with any skill or plan file, not just writing-plans output
• Closes Feature request: model switching directives in plans #1115

[obra]

Hi. Thanks so much for contributing. It looks like you've ignored the pull request template and this bakes claude-specific assumptions into the planning phase, which isn't really something we can do. Also, claude itself is capable of...just doing this at subagent dispatch. It picks what it thinks is best for a subagent and runs with it. You can also instruct it in prose. You don't need the hooks.

Adding model-use directive hooks at the tool-use level is an interesting idea and merits its own claude code plugin, but probably doesn't belong in superpowers.

[EagleEyeVisionLabz]

Apologies for that! I didn't realize this was happening. Done by mistake. I'm new to GitHub! Still learning, so lesson learned. Question: how would I fix this?

[EagleEyeVisionLabz]

Love your work by the way. Amazing, has helped me so much.

[obra]

Apologies for that! I didn't realize this was happening. Done by mistake. I'm new to GitHub! Still learning, so lesson learned. Question: how would I fix this?

No worries! (And GitHub helpfully flagged you as new-to-github ;)

So, I think that the right thing, if you want model-directives is just to ask claude to annotate each numbered task which which model to use for that step and see if that does enough of what you mean.