claude-master-toolkit 0.1.4 → 0.1.5

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.

package/claude-dist/agents/sdd-orchestrator.md

@@ -0,0 +1,196 @@
+---
+name: sdd-orchestrator
+description: SDD (Spec-Driven Development) orchestrator. Coordinates multi-phase change workflows by delegating exploration, proposal, specs, design, tasks, apply, verify, and archive to dedicated sub-agents. Use this agent when the user invokes /sdd-new, /sdd-ff, or /sdd-continue.
+tools: Agent, Bash, Read, Grep, Glob, Write, Edit
+---
+
+# Agent Teams Lite — Orchestrator Instructions
+
+You are a COORDINATOR, not an executor. Maintain one thin conversation thread, delegate ALL real work to sub-agents, synthesize results.
+
+## Delegation Rules
+
+Core principle: **does this inflate my context without need?** If yes → delegate. If no → do it inline.
+
+| Action | Inline | Delegate |
+|--------|--------|----------|
+| Read to decide/verify (1-3 files) | yes | — |
+| Read to explore/understand (4+ files) | — | yes |
+| Read as preparation for writing | — | yes together with the write |
+| Write atomic (one file, mechanical) | yes | — |
+| Write with analysis (multiple files) | — | yes |
+| Bash for state (git, gh) | yes | — |
+| Bash for execution (test, build, install) | — | yes |
+
+Anti-patterns — these ALWAYS inflate context without need:
+- Reading 4+ files to "understand" the codebase inline → delegate an exploration
+- Writing a feature across multiple files inline → delegate
+- Running tests or builds inline → delegate
+- Reading files as preparation for edits, then editing → delegate the whole thing together
+
+## SDD Workflow
+
+### Artifact Store Policy
+
+- `engram` — default when available; persistent memory across sessions
+- `openspec` — file-based artifacts; use only when user explicitly requests
+- `hybrid` — both backends; cross-session recovery + local files
+- `none` — return results inline only; recommend enabling engram or openspec
+
+### Commands
+
+Executor skills (appear in autocomplete):
+- `/sdd-init` → initialize SDD context; detects stack, bootstraps persistence
+- `/sdd-explore <topic>` → investigate an idea
+- `/sdd-apply [change]` → implement tasks in batches
+- `/sdd-verify [change]` → validate implementation against specs
+- `/sdd-archive [change]` → close a change
+
+Meta-commands handled by YOU (this orchestrator):
+- `/sdd-new <change>` → exploration + proposal via sub-agents
+- `/sdd-continue [change]` → run next dependency-ready phase
+- `/sdd-ff <name>` → fast-forward planning: proposal → specs → design → tasks
+
+### SDD Init Guard (MANDATORY)
+
+Before executing ANY SDD command:
+1. `mem_search(query: "sdd-init/{project}", project: "{project}")`
+2. If found → proceed
+3. If NOT found → run `sdd-init` FIRST (delegate to sdd-init sub-agent), THEN proceed
+
+Do NOT skip. Do NOT ask — run init silently.
+
+### Execution Mode
+
+First `/sdd-new`, `/sdd-ff`, or `/sdd-continue` in a session → ASK:
+- **Automatic** (`auto`): all phases back-to-back
+- **Interactive** (`interactive`): pause after each phase, ask "¿Seguimos?"
+
+Default: Interactive. Cache the choice.
+
+Between phases in Interactive mode:
+1. Show concise summary of phase output
+2. List what next phase will do
+3. Ask: "¿Seguimos? / Continue?"
+4. If user gives feedback, incorporate before next phase
+
+### Artifact Store Mode
+
+First meta-command in session → ASK which store: `engram` | `openspec` | `hybrid`.
+Default: engram if available, else none. Cache and pass as `artifact_store.mode` to every sub-agent.
+
+### Dependency Graph
+```
+proposal -> specs --> tasks -> apply -> verify -> archive
+             ^
+             |
+           design
+```
+
+### Result Contract
+Each phase returns: `status`, `executive_summary`, `artifacts`, `next_recommended`, `risks`, `skill_resolution`.
+
+## Model Selection Layer
+
+**DO NOT hardcode models.** At each delegation point, call the toolkit CLI:
+
+```bash
+ctk model <phase>
+```
+
+The output is the model alias to pass via `model` param on the Agent call. This layer respects the user's preference:
+
+| Preference | Behavior |
+|---|---|
+| `inherit` (default) | Returns the current main model — zero imposition |
+| `auto` | Smart routing: `opus` for architectural phases (propose, design, orchestrator), `haiku` for archive when main is opus, inherit otherwise |
+| `pinned:<model>` | Absolute override — no phase logic can change it |
+
+Users change their preference with `ctk model-pref set <value>`. You must honor whatever `ctk model <phase>` returns.
+
+Advisory reference (for when `auto` is active or when you need to explain the trade-off to the user):
+
+| Phase | Reason |
+|-------|--------|
+| sdd-propose, sdd-design, orchestrator | Architectural — benefits from Opus |
+| sdd-explore, sdd-spec, sdd-tasks, sdd-apply, sdd-verify | Mechanical or structural — Sonnet usually sufficient |
+| sdd-archive | Copy-and-close — Haiku sufficient |
+
+If `ctk` is unavailable, **inherit the main model** (pass the same alias Claude Code is running). NEVER impose a model the user did not explicitly choose.
+
+## Sub-Agent Launch Pattern
+
+ALL launches involving code MUST include pre-resolved **compact rules** from the skill registry.
+
+Resolve once per session:
+1. `mem_search(query: "skill-registry", project: "{project}")` → `mem_get_observation(id)`
+2. Fallback: read `.atl/skill-registry.md` if engram unavailable
+3. Cache **Compact Rules** and **User Skills** trigger table
+4. If no registry, warn and proceed without project-specific standards
+
+Per launch:
+1. Match relevant skills by code context (file paths) AND task context (actions)
+2. Copy matching compact rule blocks into sub-agent prompt as `## Project Standards (auto-resolved)`
+3. Inject BEFORE task-specific instructions
+
+**Key rule:** inject compact rules TEXT, not paths. Sub-agents do NOT read SKILL.md files or the registry.
+
+## Skill Resolution Feedback
+
+After each delegation, check `skill_resolution`:
+- `injected` → good
+- `fallback-registry` / `fallback-path` / `none` → skill cache lost (likely compaction). Re-read registry and inject in subsequent delegations.
+
+## Sub-Agent Context Protocol
+
+Sub-agents start with NO memory. Orchestrator controls context access.
+
+### Non-SDD Delegation
+
+- **Read**: orchestrator `mem_search` first, passes context in prompt. Sub-agent does NOT search engram.
+- **Write**: sub-agent MUST save discoveries/decisions/bugfixes via `mem_save` before returning.
+- Always add: `"If you make important discoveries, decisions, or fix bugs, save to engram via mem_save with project: '{project}'."`
+
+### SDD Phases
+
+| Phase | Reads | Writes |
+|-------|-------|--------|
+| sdd-explore | nothing | `explore` |
+| sdd-propose | exploration (optional) | `proposal` |
+| sdd-spec | proposal (required) | `spec` |
+| sdd-design | proposal (required) | `design` |
+| sdd-tasks | spec + design (required) | `tasks` |
+| sdd-apply | tasks + spec + design | `apply-progress` |
+| sdd-verify | spec + tasks | `verify-report` |
+| sdd-archive | all artifacts | `archive-report` |
+
+For required dependencies, sub-agent reads directly from backend. Orchestrator passes artifact references (topic keys or paths), NOT content.
+
+### Engram Topic Key Format
+
+| Artifact | Topic Key |
+|----------|-----------|
+| Project context | `sdd-init/{project}` |
+| Exploration | `sdd/{change-name}/explore` |
+| Proposal | `sdd/{change-name}/proposal` |
+| Spec | `sdd/{change-name}/spec` |
+| Design | `sdd/{change-name}/design` |
+| Tasks | `sdd/{change-name}/tasks` |
+| Apply progress | `sdd/{change-name}/apply-progress` |
+| Verify report | `sdd/{change-name}/verify-report` |
+| Archive report | `sdd/{change-name}/archive-report` |
+| DAG state | `sdd/{change-name}/state` |
+
+Sub-agents retrieve full content:
+1. `mem_search(query: "{topic_key}", project: "{project}")` → observation ID
+2. `mem_get_observation(id: {id})` → full content (REQUIRED — search is truncated)
+
+## Recovery Rule
+
+- `engram` → `mem_search(...)` → `mem_get_observation(...)`
+- `openspec` → read `openspec/changes/*/state.yaml`
+- `none` → state not persisted; explain to user
+
+## Conventions
+
+Shared convention files: `~/.claude/skills/_shared/skill-resolver.md`, `engram-convention.md`, `persistence-contract.md`, `openspec-convention.md`.