claude-master-toolkit 0.1.3 → 0.1.5

package/README.md

@@ -1,4 +1,4 @@
-# workctl
+# claude-master-toolkit
 
 **Token-efficient CLI + metrics dashboard for [Claude Code](https://claude.ai/code).**
 
@@ -15,7 +15,7 @@ Opens a local dashboard at `http://localhost:3200` backed by SQLite. Reads your
 
 ## Why
 
-Claude Code stores every session as JSONL under `~/.claude/projects/`. That's the source of truth for real token usage and cost — but there's no good way to see it. `workctl` parses those files into SQLite and gives you:
+Claude Code stores every session as JSONL under `~/.claude/projects/`. That's the source of truth for real token usage and cost — but there's no good way to see it. `claude-master-toolkit` parses those files into SQLite and gives you:
 
 - **Realized cost** per session, per project, per day — using the actual Claude 4.6 / 4.5 pricing table.
 - **Context window telemetry** — know when you're about to hit the 200k wall before the warning.
@@ -27,7 +27,7 @@ Think of it as the missing `/cost` page for Claude Code.
 ## Install
 
 ```bash
-npm install -g workctl
+npm install -g claude-master-toolkit
 ```
 
 Requires Node 18+. The database auto-initializes on first run at `~/.claude/state/claude-master-toolkit/ctk.sqlite`.
@@ -37,9 +37,9 @@ Requires Node 18+. The database auto-initializes on first run at `~/.claude/stat
 ### Dashboard
 
 ```bash
-workctl dashboard              # http://localhost:3200
-workctl dashboard -p 4000      # custom port
-workctl dashboard --no-open    # don't auto-open browser
+ctk dashboard              # http://localhost:3200
+ctk dashboard -p 4000      # custom port
+ctk dashboard --no-open    # don't auto-open browser
 ```
 
 The server watches `~/.claude/projects/` and syncs new session events in real time.
@@ -48,19 +48,19 @@ The server watches `~/.claude/projects/` and syncs new session events in real ti
 
 All commands are designed to return **compact, Claude-friendly output** — ideal for the `Bash` tool in agent loops.
 
-| Command                         | What it does                                                                |
-| ------------------------------- | --------------------------------------------------------------------------- |
-| `workctl cost [--quiet]`        | Realized cost of the current session (reads session JSONL, applies pricing) |
-| `workctl context`               | Current window usage, cumulative totals, cost, threshold advice             |
-| `workctl tokens [file]`         | Rough token count for a file or stdin (`chars / 4`)                         |
-| `workctl estimate <file>`       | Faithful pre-flight count via Anthropic `count_tokens` API                  |
-| `workctl slice <file> <symbol>` | Extract just one function / class / type from a file                        |
-| `workctl find <query> [path]`   | Ranked ripgrep, top 20 results                                              |
-| `workctl git-log [N]`           | One-line log for last N commits                                             |
-| `workctl git-changed`           | Files changed vs main branch with line counts                               |
-| `workctl test-summary [cmd]`    | Run a test command, print only pass/fail summary                            |
-| `workctl model <phase>`         | Model alias recommendation per SDD phase                                    |
-| `workctl dashboard`             | Launch the local metrics dashboard                                          |
+| Command                     | What it does                                                                |
+| --------------------------- | --------------------------------------------------------------------------- |
+| `ctk cost [--quiet]`        | Realized cost of the current session (reads session JSONL, applies pricing) |
+| `ctk context`               | Current window usage, cumulative totals, cost, threshold advice             |
+| `ctk tokens [file]`         | Rough token count for a file or stdin (`chars / 4`)                         |
+| `ctk estimate <file>`       | Faithful pre-flight count via Anthropic `count_tokens` API                  |
+| `ctk slice <file> <symbol>` | Extract just one function / class / type from a file                        |
+| `ctk find <query> [path]`   | Ranked ripgrep, top 20 results                                              |
+| `ctk git-log [N]`           | One-line log for last N commits                                             |
+| `ctk git-changed`           | Files changed vs main branch with line counts                               |
+| `ctk test-summary [cmd]`    | Run a test command, print only pass/fail summary                            |
+| `ctk model <phase>`         | Model alias recommendation per SDD phase                                    |
+| `ctk dashboard`             | Launch the local metrics dashboard                                          |
 
 Every command supports `--json` for machine-readable output.
 
@@ -80,7 +80,7 @@ Pricing table is hard-coded in `src/shared/pricing.ts` for the Claude 4.6 / 4.5
 
 ## Context window vs cumulative cost
 
-These are **different metrics** and `workctl` reports both:
+These are **different metrics** and `ctk` reports both:
 
 - **Context window** = what Claude sees right now. Equals the last turn's `input + cache_read + output`. Not a running sum — summing double-counts cache reads.
 - **Cumulative cost** = every turn's tokens weighted by per-model prices. This is what `/cost` shows.

package/bin/.ctk-legacy

@@ -0,0 +1,398 @@
+#!/usr/bin/env bash
+# ctk — Claude Master Toolkit CLI
+# Token-efficient command helpers for Claude Code.
+
+set -euo pipefail
+
+VERSION="0.1.0"
+
+usage() {
+  cat <<'EOF'
+ctk — Claude Master Toolkit
+
+USAGE
+  ctk <command> [args]
+
+COMMANDS
+  slice <file> <symbol>      Extract a symbol's block from a file (function/class/etc.)
+  git-log [N]                Compact git log: last N commits (default 10), one line each
+  git-changed                List files changed vs main branch with line counts
+  test-summary [cmd]         Run test command, show only pass/fail summary (default: yarn test)
+  find <query> [path]        Ranked search via ripgrep, top 20 results with 1 line context
+  model <phase>              Print model alias for an SDD phase (respects user preference)
+  model-pref [get|set|clear] Get/set/clear model selection preference
+  tokens [file]              Rough token estimate for a file or stdin (chars/4)
+  estimate <file|->          Faithful pre-flight token count via Anthropic API (fallback: rough)
+  cost [--quiet]             Realized cost of current session (reads session JSONL)
+  context                    Show current Claude Code session context usage
+  version                    Print version
+  help                       This help
+
+EXAMPLES
+  ctk slice src/foo.ts handleSubmit
+  ctk git-log 5
+  ctk find "useEffect" src/
+  ctk model sdd-propose              # depends on preference — see below
+  ctk model-pref get                 # show current preference
+  ctk model-pref set auto            # enable smart routing
+  ctk model-pref set pinned:sonnet   # pin everything to sonnet (absolute)
+  ctk model-pref clear               # back to default (inherit)
+EOF
+}
+
+cmd_slice() {
+  local file="${1:?file required}" symbol="${2:?symbol required}"
+  [[ -f "$file" ]] || { echo "ctk slice: file not found: $file" >&2; exit 1; }
+
+  # Heuristic: find the line matching the symbol definition, then extract to matching brace/end.
+  # Works for JS/TS/Go/Python/Rust with common patterns.
+  awk -v sym="$symbol" '
+    BEGIN { depth = 0; inside = 0 }
+    !inside && $0 ~ ("(function|const|let|var|class|func|def|fn|type|interface)[[:space:]]+" sym "[[:space:](<:=]") {
+      inside = 1; start = NR
+    }
+    inside {
+      print NR": "$0
+      # Brace counting for C-like
+      for (i = 1; i <= length($0); i++) {
+        c = substr($0, i, 1)
+        if (c == "{") depth++
+        else if (c == "}") { depth--; if (depth == 0 && NR > start) { exit } }
+      }
+      # Python/indent-based: blank line after non-empty inside def = end
+      if ($0 ~ /^[[:space:]]*$/ && NR > start + 1 && depth == 0) exit
+    }
+  ' "$file"
+}
+
+cmd_git_log() {
+  local n="${1:-10}"
+  git log --oneline --decorate -n "$n" 2>/dev/null || {
+    echo "ctk git-log: not a git repo" >&2; exit 1;
+  }
+}
+
+cmd_git_changed() {
+  local base
+  base="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|origin/||')"
+  base="${base:-main}"
+  git diff --stat "$base...HEAD" 2>/dev/null || {
+    echo "ctk git-changed: not a git repo or no base branch" >&2; exit 1;
+  }
+}
+
+cmd_test_summary() {
+  local cmd="${*:-yarn test}"
+  local out rc
+  out="$($cmd 2>&1)" && rc=0 || rc=$?
+  # Print last 20 lines which usually contain the summary
+  echo "$out" | tail -20
+  echo "---"
+  echo "exit: $rc"
+  return $rc
+}
+
+cmd_find() {
+  local query="${1:?query required}"
+  local path="${2:-.}"
+  if command -v rg >/dev/null 2>&1; then
+    rg --color=never --line-number --max-count 3 --heading "$query" "$path" 2>/dev/null | head -60
+  else
+    grep -rn --max-count=3 "$query" "$path" 2>/dev/null | head -60
+  fi
+}
+
+MODEL_PREF_FILE="$HOME/.claude/state/claude-master-toolkit/model-preference"
+
+# Pricing table — USD per 1M tokens, as of Claude 4.6 / 4.5 family.
+# Source: https://www.anthropic.com/pricing (user-verified values)
+# Format: "INPUT OUTPUT CACHE_READ CACHE_WRITE"
+_pricing() {
+  case "$1" in
+    opus*)   echo "5 25 0.50 6.25" ;;   # Opus 4.6
+    sonnet*) echo "3 15 0.30 3.75" ;;   # Sonnet 4.6
+    haiku*)  echo "1 5 0.10 1.25" ;;    # Haiku 4.5
+    *)       echo "3 15 0.30 3.75" ;;   # fallback: sonnet
+  esac
+}
+
+_latest_session_file() {
+  local cwd encoded proj_dir
+  cwd="${CLAUDE_PROJECT_DIR:-$PWD}"
+  encoded="$(printf '%s' "$cwd" | sed 's|/|-|g')"
+  proj_dir="$HOME/.claude/projects/$encoded"
+  [[ -d "$proj_dir" ]] || return 1
+  find "$proj_dir" -maxdepth 1 -name '*.jsonl' -type f -printf '%T@ %p\n' 2>/dev/null \
+    | sort -rn | head -1 | awk '{print $2}'
+}
+
+# Extract the LAST turn's usage from a session JSONL.
+# Used for "current context window occupied" — the sum below is the actual window,
+# NOT the cumulative across turns (that's what _session_tokens gives, for cost).
+# Prints: "INPUT OUTPUT CACHE_READ CACHE_WRITE"
+_session_latest_usage() {
+  local file="$1"
+  [[ -f "$file" ]] || { echo "0 0 0 0"; return; }
+  local line i o cr cw
+  line="$(tac "$file" 2>/dev/null | grep -m 1 '"input_tokens"' || true)"
+  [[ -z "$line" ]] && { echo "0 0 0 0"; return; }
+  i="$(echo  "$line" | grep -oE '"input_tokens":[0-9]+' | head -1 | cut -d: -f2)"
+  o="$(echo  "$line" | grep -oE '"output_tokens":[0-9]+' | head -1 | cut -d: -f2)"
+  cr="$(echo "$line" | grep -oE '"cache_read_input_tokens":[0-9]+' | head -1 | cut -d: -f2)"
+  cw="$(echo "$line" | grep -oE '"cache_creation_input_tokens":[0-9]+' | head -1 | cut -d: -f2)"
+  echo "${i:-0} ${o:-0} ${cr:-0} ${cw:-0}"
+}
+
+# Extract CUMULATIVE token counts from a session JSONL (for cost).
+# Prints: "INPUT OUTPUT CACHE_READ CACHE_WRITE" (all integers).
+_session_tokens() {
+  local file="$1"
+  [[ -f "$file" ]] || { echo "0 0 0 0"; return; }
+  awk '
+    BEGIN { i=0; o=0; cr=0; cw=0 }
+    {
+      while (match($0, /"input_tokens":[0-9]+/))        { i  += substr($0, RSTART+15, RLENGTH-15); $0 = substr($0, RSTART+RLENGTH) }
+      while (match($0, /"output_tokens":[0-9]+/))       { o  += substr($0, RSTART+16, RLENGTH-16); $0 = substr($0, RSTART+RLENGTH) }
+      while (match($0, /"cache_read_input_tokens":[0-9]+/))     { cr += substr($0, RSTART+26, RLENGTH-26); $0 = substr($0, RSTART+RLENGTH) }
+      while (match($0, /"cache_creation_input_tokens":[0-9]+/)) { cw += substr($0, RSTART+30, RLENGTH-30); $0 = substr($0, RSTART+RLENGTH) }
+    }
+    END { print i, o, cr, cw }
+  ' "$file"
+}
+
+# Compute cost from tokens and a model alias.
+# Usage: _compute_cost <model> <in> <out> <cache_r> <cache_w>
+_compute_cost() {
+  local model="$1" in="$2" out="$3" cr="$4" cw="$5"
+  local prices
+  read -r p_in p_out p_cr p_cw <<<"$(_pricing "$model")"
+  awk -v i="$in" -v o="$out" -v cr="$cr" -v cw="$cw" \
+      -v pi="$p_in" -v po="$p_out" -v pcr="$p_cr" -v pcw="$p_cw" \
+      'BEGIN { printf "%.4f", (i*pi + o*po + cr*pcr + cw*pcw) / 1000000 }'
+}
+
+_read_main_model() {
+  # Best-effort read of the user's currently configured main model.
+  # Falls back to "sonnet" if not discoverable.
+  if [[ -f "$HOME/.claude/settings.json" ]] && command -v jq >/dev/null 2>&1; then
+    jq -r '.model // "sonnet"' "$HOME/.claude/settings.json" 2>/dev/null || echo "sonnet"
+  else
+    echo "sonnet"
+  fi
+}
+
+cmd_model() {
+  local phase="${1:?phase required}"
+  local pref="inherit"
+  [[ -f "$MODEL_PREF_FILE" ]] && pref="$(cat "$MODEL_PREF_FILE")"
+
+  # pinned:<model> — absolute override, no phase logic
+  if [[ "$pref" == pinned:* ]]; then
+    echo "${pref#pinned:}"
+    return
+  fi
+
+  local current
+  current="$(_read_main_model)"
+
+  case "$pref" in
+    inherit)
+      # Full respect — return the current main model regardless of phase
+      echo "$current"
+      ;;
+    auto)
+      # Smart routing — opt-in cost optimization
+      case "$phase" in
+        sdd-propose|sdd-design|orchestrator)
+          # Architectural — prefer opus
+          echo "opus"
+          ;;
+        sdd-archive)
+          # Copy-and-close — cheapest tier
+          echo "haiku"
+          ;;
+        sdd-explore|sdd-spec|sdd-tasks|sdd-apply|sdd-verify|default)
+          # Mechanical / structural — sonnet is sufficient
+          echo "sonnet"
+          ;;
+        *)
+          echo "$current"
+          ;;
+      esac
+      ;;
+    opus|sonnet|haiku)
+      # Explicit model as floor/default, no phase logic
+      echo "$pref"
+      ;;
+    *)
+      # Unknown preference — safe fallback
+      echo "$current"
+      ;;
+  esac
+}
+
+cmd_model_pref() {
+  mkdir -p "$(dirname "$MODEL_PREF_FILE")"
+  local action="${1:-get}"
+  case "$action" in
+    get)
+      if [[ -f "$MODEL_PREF_FILE" ]]; then
+        cat "$MODEL_PREF_FILE"
+      else
+        echo "inherit (default)"
+      fi
+      ;;
+    set)
+      local value="${2:?value required — inherit | auto | opus | sonnet | haiku | pinned:<model>}"
+      case "$value" in
+        inherit|auto|opus|sonnet|haiku|pinned:*)
+          echo "$value" > "$MODEL_PREF_FILE"
+          echo "Model preference set: $value"
+          ;;
+        *)
+          echo "ctk model-pref: invalid value '$value'" >&2
+          echo "valid: inherit | auto | opus | sonnet | haiku | pinned:<model>" >&2
+          exit 1
+          ;;
+      esac
+      ;;
+    clear)
+      rm -f "$MODEL_PREF_FILE"
+      echo "Model preference cleared (→ inherit)"
+      ;;
+    *)
+      echo "ctk model-pref: unknown action '$action'" >&2
+      echo "usage: ctk model-pref [get | set <value> | clear]" >&2
+      exit 1
+      ;;
+  esac
+}
+
+cmd_tokens() {
+  local chars
+  if [[ -n "${1:-}" ]]; then
+    chars=$(wc -c <"$1")
+  else
+    chars=$(wc -c)
+  fi
+  # Rough: ~4 chars per token (English). Conservative estimate.
+  echo $(( chars / 4 ))
+}
+
+cmd_cost() {
+  local quiet=0
+  [[ "${1:-}" == "--quiet" ]] && quiet=1
+  local session_file
+  session_file="$(_latest_session_file)" || {
+    (( quiet )) || echo "ctk cost: no session data"; return 0;
+  }
+  [[ -n "$session_file" ]] || { (( quiet )) || echo "ctk cost: no session files"; return 0; }
+
+  local tokens model in_tok out_tok cr_tok cw_tok cost
+  tokens="$(_session_tokens "$session_file")"
+  read -r in_tok out_tok cr_tok cw_tok <<<"$tokens"
+  model="$(_read_main_model)"
+  cost="$(_compute_cost "$model" "$in_tok" "$out_tok" "$cr_tok" "$cw_tok")"
+
+  if (( quiet )); then
+    echo "$cost"
+  else
+    printf 'Model: %s | In: %s | Out: %s | Cache R/W: %s / %s | Cost: $%s\n' \
+      "$model" "$in_tok" "$out_tok" "$cr_tok" "$cw_tok" "$cost"
+  fi
+}
+
+cmd_estimate() {
+  local src="${1:?file or - for stdin required}"
+  local text
+  if [[ "$src" == "-" ]]; then
+    text="$(cat)"
+  elif [[ -f "$src" ]]; then
+    text="$(cat "$src")"
+  else
+    echo "ctk estimate: not a file: $src (use '-' for stdin)" >&2
+    exit 1
+  fi
+
+  if [[ -n "${ANTHROPIC_API_KEY:-}" ]] && command -v curl >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then
+    # Use official count_tokens endpoint — faithful, model-agnostic for counting purposes
+    local body response tokens
+    body=$(jq -n --arg t "$text" '{
+      model: "claude-sonnet-4-5",
+      messages: [{role: "user", content: $t}]
+    }')
+    response=$(curl -sS -X POST https://api.anthropic.com/v1/messages/count_tokens \
+      -H "x-api-key: $ANTHROPIC_API_KEY" \
+      -H "anthropic-version: 2023-06-01" \
+      -H "content-type: application/json" \
+      -d "$body" 2>/dev/null)
+    tokens=$(echo "$response" | jq -r '.input_tokens // empty' 2>/dev/null)
+    if [[ -n "$tokens" ]]; then
+      # Also show estimated cost at current main model's input rate
+      local model p_in p_out p_cr p_cw cost
+      model="$(_read_main_model)"
+      read -r p_in p_out p_cr p_cw <<<"$(_pricing "$model")"
+      cost=$(awk -v t="$tokens" -v p="$p_in" 'BEGIN { printf "%.4f", t*p/1000000 }')
+      printf '%s tokens (exact, count_tokens API) | est. input cost: $%s (%s)\n' "$tokens" "$cost" "$model"
+      return
+    fi
+    echo "ctk estimate: API error, falling back to rough estimate" >&2
+  fi
+
+  local chars rough
+  chars=${#text}
+  rough=$(( chars / 4 ))
+  echo "$rough tokens (rough — set ANTHROPIC_API_KEY for exact count)"
+}
+
+cmd_context() {
+  local session_file
+  session_file="$(_latest_session_file)" || {
+    echo "ctk context: no Claude Code session data"; return 0;
+  }
+  [[ -n "$session_file" ]] || { echo "ctk context: no session files"; return 0; }
+
+  # Current window = last turn's (input + cache_read + output). NOT cumulative.
+  local li lo lcr lcw window pct
+  read -r li lo lcr lcw <<<"$(_session_latest_usage "$session_file")"
+  window=$(( li + lcr + lo ))
+  pct=$(( window * 100 / 200000 ))
+
+  # Cumulative cost (all turns weighted by price)
+  local ci co ccr ccw model cost
+  read -r ci co ccr ccw <<<"$(_session_tokens "$session_file")"
+  model="$(_read_main_model)"
+  cost="$(_compute_cost "$model" "$ci" "$co" "$ccr" "$ccw")"
+
+  printf 'Session: %s\n' "$(basename "$session_file")"
+  printf 'Window:  %s tokens (~%d%% of 200k) — last turn: in=%s cache_r=%s out=%s\n' \
+    "$window" "$pct" "$li" "$lcr" "$lo"
+  printf 'Session: in=%s out=%s cache_r=%s cache_w=%s (cumulative)\n' "$ci" "$co" "$ccr" "$ccw"
+  printf 'Cost:    $%s (%s)\n' "$cost" "$model"
+  if (( pct >= 70 )); then
+    echo "Advice:  /compact (continuing) or /clear (new task)"
+  fi
+}
+
+main() {
+  local cmd="${1:-help}"
+  shift || true
+  case "$cmd" in
+    slice)        cmd_slice "$@" ;;
+    git-log)      cmd_git_log "$@" ;;
+    git-changed)  cmd_git_changed "$@" ;;
+    test-summary) cmd_test_summary "$@" ;;
+    find)         cmd_find "$@" ;;
+    model)        cmd_model "$@" ;;
+    model-pref)   cmd_model_pref "$@" ;;
+    tokens)       cmd_tokens "$@" ;;
+    estimate)     cmd_estimate "$@" ;;
+    cost)         cmd_cost "$@" ;;
+    context)      cmd_context "$@" ;;
+    version|-v|--version) echo "ctk $VERSION" ;;
+    help|-h|--help|"") usage ;;
+    *) echo "ctk: unknown command: $cmd" >&2; usage; exit 1 ;;
+  esac
+}
+
+main "$@"

package/claude-dist/CLAUDE.md

@@ -0,0 +1,86 @@
+<!-- claude-master-toolkit: managed file -->
+<!-- Edit source at ~/Documentos/Coding/claude-master-toolkit/claude/CLAUDE.md -->
+
+## Rules
+
+- Never add "Co-Authored-By" or AI attribution to commits. Use conventional commits only, add end prefix specify (autommated by AI).
+- Never build after changes.
+- When asking a question, STOP and wait for response. Never continue or assume answers.
+- Never agree with user claims without verification. Say "let me verify" and check code/docs first.
+- If user is wrong, explain WHY with evidence. If you were wrong, acknowledge with proof.
+- Always propose alternatives with tradeoffs when relevant.
+- Verify technical claims before stating them. If unsure, investigate first.
+
+## Personality
+
+Senior Architect, 15+ years experience, GDE & MVP. Passionate teacher who genuinely wants people to learn and grow. Gets frustrated when someone can do better but isn't — not out of anger, but because you CARE about their growth.
+
+## Language
+
+- Always respond in the same language the user writes in.
+- Use a warm, professional, and direct tone. No slang, no regional expressions.
+
+## Tone
+
+Passionate and direct, but from a place of CARING. When someone is wrong: (1) validate the question makes sense, (2) explain WHY it's wrong with technical reasoning, (3) show the correct way with examples. Frustration comes from caring they can do better. Use CAPS for emphasis.
+
+## Philosophy
+
+- CONCEPTS > CODE: call out people who code without understanding fundamentals
+- AI IS A TOOL: we direct, AI executes; the human always leads
+- SOLID FOUNDATIONS: design patterns, architecture, bundlers before frameworks
+- AGAINST IMMEDIACY: no shortcuts; real learning takes effort and time
+
+## Expertise
+
+Clean/Hexagonal/Screaming Architecture, testing, atomic design, container-presentational pattern, LazyVim, Tmux, Zellij.
+
+## Behavior
+
+- Push back when user asks for code without context or understanding
+- Use construction/architecture analogies to explain concepts
+- Correct errors ruthlessly but explain WHY technically
+- For concepts: (1) explain problem, (2) propose solution with examples, (3) mention tools/resources
+
+## Skills (Auto-load based on context)
+
+Load BEFORE writing code. Multiple skills can apply simultaneously.
+
+| Context                                                    | Skill                                             |
+| ---------------------------------------------------------- | ------------------------------------------------- |
+| Go tests, Bubbletea TUI testing                            | go-testing                                        |
+| Creating new AI skills                                     | skill-creator                                     |
+| SDD meta-commands (`/sdd-new`, `/sdd-ff`, `/sdd-continue`) | delegates to `sdd-orchestrator` sub-agent         |
+| Any `/sdd-*` executor phase                                | existing SDD skill (sdd-explore, sdd-apply, etc.) |
+| Delegating work to sub-agents                              | `/delegate` (enforces `ctk model` + context check)|
+
+## Persistent Memory (Engram)
+
+Engram is a plugin — its SessionStart hook injects the full protocol automatically. You do NOT need to memorize rules here. Just remember the principle:
+
+**SAVE PROACTIVELY** after any decision, bug fix, convention, discovery, preference, or non-obvious pattern. Do not wait to be asked. On recall requests ("recordá", "qué hicimos"), search memory before answering.
+
+Full rules and templates live in the `engram-protocol` skill if you ever need to re-read them.
+
+## Model Selection Layer
+
+**MANDATORY:** Before ANY Agent tool call, run `ctk model <phase>` and pass the result as the `model` parameter. Prefer using `/delegate` which enforces this automatically.
+
+- `inherit` (default) — sub-agents use the same model as the main conversation.
+- `auto` — smart routing: Opus for architectural phases, Haiku for archive, inherit otherwise.
+- `pinned:<model>` — absolute override, never deviates.
+
+If `ctk` is unavailable, inherit the main model. Never impose a model the user did not choose.
+
+## Context Guardian
+
+Hooks in `~/.claude/hooks/` warn you when context window usage crosses 70/85/95% thresholds. When a warning fires, recommend:
+
+- **`/compact`** if the work is coherent and you want to keep the thread alive
+- **`/clear`** if the new task is unrelated to the accumulated context
+
+Cache TTL (5 min) is NOT context expiry — never recommend clearing for "inactivity".
+
+## Strict TDD Mode
+
+Enabled.