ostacky 0.5.9 → 0.6.0

package/assets/plugins/engram.ts

@@ -0,0 +1,537 @@
+/**
+ * Engram — OpenCode plugin adapter
+ *
+ * Thin layer that connects OpenCode's event system to the Engram Go binary.
+ * The Go binary runs as a local HTTP server and handles all persistence.
+ *
+ * Flow:
+ *   OpenCode events → this plugin → HTTP calls → engram serve → SQLite
+ *
+ * Session resilience:
+ *   Uses `ensureSession()` before any DB write. This means sessions are
+ *   created on-demand — even if the plugin was loaded after the session
+ *   started (restart, reconnect, etc.). The session ID comes from OpenCode's
+ *   hooks (input.sessionID) rather than relying on a session.created event.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+const ENGRAM_PORT = parseInt(process.env.ENGRAM_PORT ?? "7437")
+const ENGRAM_URL = `http://127.0.0.1:${ENGRAM_PORT}`
+const ENGRAM_BIN = process.env.ENGRAM_BIN ?? Bun.which("engram") ?? ".opencode/tools/engram/bin/engram"
+
+// Engram's own MCP tools — don't count these as "tool calls" for session stats
+const ENGRAM_TOOLS = new Set([
+  "mem_search",
+  "mem_save",
+  "mem_update",
+  "mem_delete",
+  "mem_suggest_topic_key",
+  "mem_save_prompt",
+  "mem_session_summary",
+  "mem_context",
+  "mem_stats",
+  "mem_timeline",
+  "mem_get_observation",
+  "mem_session_start",
+  "mem_session_end",
+])
+
+// ─── Memory Instructions ─────────────────────────────────────────────────────
+// These get injected into the agent's context so it knows to call mem_save.
+
+const MEMORY_INSTRUCTIONS = `## Engram Persistent Memory — Protocol
+
+You have access to Engram, a persistent memory system that survives across sessions and compactions.
+
+### WHEN TO SAVE (mandatory — not optional)
+
+Call \`mem_save\` IMMEDIATELY after any of these:
+- Bug fix completed
+- Architecture or design decision made
+- Non-obvious discovery about the codebase
+- Configuration change or environment setup
+- Pattern established (naming, structure, convention)
+- User preference or constraint learned
+
+Format for \`mem_save\`:
+- **title**: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")
+- **type**: bugfix | decision | architecture | discovery | pattern | config | preference
+- **scope**: \`project\` (default) | \`personal\`
+- **topic_key** (optional, recommended for evolving decisions): stable key like \`architecture/auth-model\`
+- **content**:
+  **What**: One sentence — what was done
+  **Why**: What motivated it (user request, bug, performance, etc.)
+  **Where**: Files or paths affected
+  **Learned**: Gotchas, edge cases, things that surprised you (omit if none)
+
+Topic rules:
+- Different topics must not overwrite each other (e.g. architecture vs bugfix)
+- Reuse the same \`topic_key\` to update an evolving topic instead of creating new observations
+- If unsure about the key, call \`mem_suggest_topic_key\` first and then reuse it
+- Use \`mem_update\` when you have an exact observation ID to correct
+
+### WHEN TO SEARCH MEMORY
+
+When the user asks to recall something — any variation of "remember", "recall", "what did we do",
+"how did we solve", or the equivalent in the user's language, or references to past work:
+1. First call \`mem_context\` — checks recent session history (fast, cheap)
+2. If not found, call \`mem_search\` with relevant keywords (FTS5 full-text search)
+3. If you find a match, use \`mem_get_observation\` for full untruncated content
+
+Also search memory PROACTIVELY when:
+- Starting work on something that might have been done before
+- The user mentions a topic you have no context on — check if past sessions covered it
+- The user's FIRST message references the project, a feature, or a problem — call \`mem_search\` with keywords from their message to check for prior work before responding
+
+### SESSION CLOSE PROTOCOL (mandatory)
+
+Before ending a session or saying "done" / "that's it", you MUST:
+1. Call \`mem_session_summary\` with this structure:
+
+## Goal
+[What we were working on this session]
+
+## Instructions
+[User preferences or constraints discovered — skip if none]
+
+## Discoveries
+- [Technical findings, gotchas, non-obvious learnings]
+
+## Accomplished
+- [Completed items with key details]
+
+## Next Steps
+- [What remains to be done — for the next session]
+
+## Relevant Files
+- path/to/file — [what it does or what changed]
+
+This is NOT optional. If you skip this, the next session starts blind.
+
+### AFTER COMPACTION
+
+If you see a message about compaction or context reset, or if you see "FIRST ACTION REQUIRED" in your context:
+1. IMMEDIATELY call \`mem_session_summary\` with the compacted summary content — this persists what was done before compaction
+2. Then call \`mem_context\` to recover any additional context from previous sessions
+3. Only THEN continue working
+
+Do not skip step 1. Without it, everything done before compaction is lost from memory.
+`
+
+// ─── HTTP Client ─────────────────────────────────────────────────────────────
+
+async function engramFetch(
+  path: string,
+  opts: { method?: string; body?: any } = {}
+): Promise<any> {
+  try {
+    const res = await fetch(`${ENGRAM_URL}${path}`, {
+      method: opts.method ?? "GET",
+      headers: opts.body ? { "Content-Type": "application/json" } : undefined,
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+    })
+    return await res.json()
+  } catch {
+    // Engram server not running — silently fail
+    return null
+  }
+}
+
+async function isEngramRunning(): Promise<boolean> {
+  try {
+    const res = await fetch(`${ENGRAM_URL}/health`, {
+      signal: AbortSignal.timeout(500),
+    })
+    return res.ok
+  } catch {
+    return false
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function extractProjectName(directory: string): string {
+  // Try git remote origin URL
+  try {
+    const result = Bun.spawnSync(["git", "-C", directory, "remote", "get-url", "origin"])
+    if (result.exitCode === 0) {
+      const url = result.stdout?.toString().trim()
+      if (url) {
+        const name = url.replace(/\.git$/, "").split(/[/:]/).pop()
+        if (name) return name
+      }
+    }
+  } catch {}
+
+  // Fallback: git root directory name (works in worktrees)
+  try {
+    const result = Bun.spawnSync(["git", "-C", directory, "rev-parse", "--show-toplevel"])
+    if (result.exitCode === 0) {
+      const root = result.stdout?.toString().trim()
+      if (root) return root.split("/").pop() ?? "unknown"
+    }
+  } catch {}
+
+  // Final fallback: cwd basename
+  return directory.split("/").pop() ?? "unknown"
+}
+
+function truncate(str: string, max: number): string {
+  if (!str) return ""
+  return str.length > max ? str.slice(0, max) + "..." : str
+}
+
+/**
+ * Strip <private>...</private> tags before sending to engram.
+ * Double safety: the Go binary also strips, but we strip here too
+ * so sensitive data never even hits the wire.
+ */
+function stripPrivateTags(str: string): string {
+  if (!str) return ""
+  return str.replace(/<private>[\s\S]*?<\/private>/gi, "[REDACTED]").trim()
+}
+
+// ─── Plugin Export ───────────────────────────────────────────────────────────
+
+export const Engram: Plugin = async (ctx) => {
+  const oldProject = ctx.directory.split("/").pop() ?? "unknown"
+  const project = extractProjectName(ctx.directory)
+
+  // Track tool counts per session (in-memory only, not critical)
+  const toolCounts = new Map<string, number>()
+
+  // Track last nudge time per session to debounce save reminders
+  const lastNudgeTime = new Map<string, number>() // sessionID -> epoch seconds
+
+  // Track which sessions we've already ensured exist in engram
+  const knownSessions = new Set<string>()
+
+  // Track sub-agent session IDs so we can suppress their tool-hook registrations.
+  // Sub-agents (Task() calls) have a parentID or a title ending in " subagent)".
+  // We must not register them as top-level Engram sessions — they cause session
+  // inflation (e.g. 170 sessions for 1 real conversation, issue #116).
+  const subAgentSessions = new Set<string>()
+
+  /**
+   * Ensure a session exists in engram. Idempotent — calls POST /sessions
+   * which uses INSERT OR IGNORE. Safe to call multiple times.
+   *
+   * Silently skips sub-agent sessions (tracked in `subAgentSessions`).
+   */
+  async function ensureSession(sessionId: string): Promise<void> {
+    if (!sessionId || knownSessions.has(sessionId)) return
+    // Do not register sub-agent sessions in Engram (issue #116).
+    if (subAgentSessions.has(sessionId)) return
+    knownSessions.add(sessionId)
+    await engramFetch("/sessions", {
+      method: "POST",
+      body: {
+        id: sessionId,
+        project,
+        directory: ctx.directory,
+      },
+    })
+  }
+
+  // Try to start engram server if not running
+  const running = await isEngramRunning()
+  if (!running) {
+    try {
+      Bun.spawn([ENGRAM_BIN, "serve"], {
+        stdout: "ignore",
+        stderr: "ignore",
+        stdin: "ignore",
+      })
+      await new Promise((r) => setTimeout(r, 500))
+    } catch {
+      // Binary not found or can't start — plugin will silently no-op
+    }
+  }
+
+  // Migrate project name if it changed (one-time, idempotent)
+  // Must run AFTER server startup to ensure the endpoint is available
+  if (oldProject !== project) {
+    await engramFetch("/projects/migrate", {
+      method: "POST",
+      body: { old_project: oldProject, new_project: project },
+    })
+  }
+
+  // Auto-import: if .engram/manifest.json exists in the project repo,
+  // run `engram sync --import` to load any new chunks into the local DB.
+  // This is how git-synced memories get loaded when cloning a repo or
+  // pulling changes. Each chunk is imported only once (tracked by ID).
+  try {
+    const manifestFile = `${ctx.directory}/.engram/manifest.json`
+    const file = Bun.file(manifestFile)
+    if (await file.exists()) {
+      Bun.spawn([ENGRAM_BIN, "sync", "--import"], {
+        cwd: ctx.directory,
+        stdout: "ignore",
+        stderr: "ignore",
+        stdin: "ignore",
+      })
+    }
+  } catch {
+    // Manifest doesn't exist or binary not found — silently skip
+  }
+
+  return {
+    // ─── Event Listeners ───────────────────────────────────────────
+
+    event: async ({ event }) => {
+      // --- Session Created ---
+      if (event.type === "session.created") {
+        // Bug fix (#116): session data is nested under event.properties.info,
+        // not event.properties directly.
+        const info = (event.properties as any)?.info
+        const sessionId = info?.id
+        const parentID = info?.parentID
+        const title: string = info?.title ?? ""
+
+        // Sub-agent sessions (created via Task()) must NOT be registered as
+        // top-level Engram sessions. They cause massive session inflation
+        // (e.g. 170 sessions for 1 real conversation).
+        //
+        // Detection heuristics:
+        //   - parentID is set on all Task() sub-agent sessions
+        //   - title ends with " subagent)" as a secondary signal
+        const isSubAgent = !!parentID || title.endsWith(" subagent)")
+
+        if (sessionId && !isSubAgent) {
+          await ensureSession(sessionId)
+        } else if (sessionId && isSubAgent) {
+          // Remember this as a sub-agent session so tool-hook calls
+          // to ensureSession() are also suppressed for it.
+          subAgentSessions.add(sessionId)
+        }
+      }
+
+      // --- Session Deleted ---
+      if (event.type === "session.deleted") {
+        // Same properties.info path as session.created.
+        const info = (event.properties as any)?.info
+        const sessionId = info?.id
+        if (sessionId) {
+          toolCounts.delete(sessionId)
+          knownSessions.delete(sessionId)
+          subAgentSessions.delete(sessionId)
+          lastNudgeTime.delete(sessionId)
+        }
+      }
+
+    },
+
+    // ─── User Prompt Capture ──────────────────────────────────────
+    // chat.message is called once per user message, before the LLM sees it.
+    // input.sessionID is always reliable here (no knownSessions workaround).
+    // output.message is typed as UserMessage (role:"user" already guaranteed).
+    // output.parts contains TextPart[] with the actual message text.
+
+    "chat.message": async (input, output) => {
+      // Skip sub-agent sessions — they inflate session counts (issue #116)
+      if (subAgentSessions.has(input.sessionID)) return
+
+      const sessionId = input.sessionID
+
+      // Extract text from parts (type:"text")
+      const content = output.parts
+        .filter((p) => p.type === "text")
+        .map((p) => (p as any).text ?? "")
+        .join("\n")
+        .trim()
+
+      // Also fallback to summary if parts yield nothing
+      const fallback = !content && output.message.summary
+        ? `${output.message.summary.title ?? ""}\n${output.message.summary.body ?? ""}`.trim()
+        : ""
+
+      const finalContent = content || fallback
+
+      // Only capture non-trivial prompts (>10 chars)
+      if (finalContent.length > 10) {
+        await ensureSession(sessionId)
+        await engramFetch("/prompts", {
+          method: "POST",
+          body: {
+            session_id: sessionId,
+            content: stripPrivateTags(truncate(finalContent, 2000)),
+            project,
+          },
+        })
+      }
+    },
+
+    // ─── Tool Execution Hook ─────────────────────────────────────
+    // Count tool calls per session (for session end stats).
+    // Also ensures the session exists — handles plugin reload / reconnect.
+    // Passive capture: when a Task tool completes, POST its output to
+    // the passive capture endpoint so the server extracts learnings.
+
+    "tool.execute.after": async (input, output) => {
+      if (ENGRAM_TOOLS.has(input.tool.toLowerCase())) return
+
+      // input.sessionID comes from OpenCode — always available
+      const sessionId = input.sessionID
+      if (sessionId) {
+        await ensureSession(sessionId)
+        toolCounts.set(sessionId, (toolCounts.get(sessionId) ?? 0) + 1)
+      }
+
+      // Passive capture: extract learnings from Task tool output
+      if (input.tool === "Task" && output && sessionId) {
+        const text = typeof output === "string" ? output : JSON.stringify(output)
+        if (text.length > 50) {
+          await engramFetch("/observations/passive", {
+            method: "POST",
+            body: {
+              session_id: sessionId,
+              content: stripPrivateTags(text),
+              project,
+              source: "task-complete",
+            },
+          })
+        }
+      }
+    },
+
+    // ─── System Prompt: Always-on memory instructions ──────────
+    // Injects MEMORY_INSTRUCTIONS into the system prompt of every message.
+    // This ensures the agent ALWAYS knows about Engram, even after compaction.
+    //
+    // We append to the last existing system entry instead of pushing a new one.
+    // Some models (Qwen3.5, Mistral/Ministral via llama.cpp) reject multiple
+    // system messages — their Jinja chat templates only allow a single system
+    // block at the beginning. By concatenating, we avoid adding extra system
+    // messages that would break these models. See: GitHub issue #23.
+
+    "experimental.chat.system.transform": async (input, output) => {
+      if (output.system.length > 0) {
+        output.system[output.system.length - 1] += "\n\n" + MEMORY_INSTRUCTIONS
+      } else {
+        output.system.push(MEMORY_INSTRUCTIONS)
+      }
+
+      // ── Save nudge ──────────────────────────────────────────────────────────
+      // If it has been a long time since the last mem_save, append a reminder
+      // to the system prompt so the agent notices. All fetches are fire-and-
+      // forget with short timeouts — any failure silently skips the nudge.
+      try {
+        const sessionID: string = input.sessionID ?? ""
+        if (!sessionID || subAgentSessions.has(sessionID)) return
+
+        // SQLite datetime('now') returns "YYYY-MM-DD HH:MM:SS" in UTC with no
+        // zone suffix; new Date() would parse that as local time. Normalize to
+        // UTC first so the thresholds are correct in every timezone.
+        const toEpochSecs = (ts: string): number => {
+          if (!ts) return 0
+          const normalized = ts.includes("T") ? ts : ts.replace(" ", "T") + "Z"
+          const ms = new Date(normalized).getTime()
+          return Number.isNaN(ms) ? 0 : Math.floor(ms / 1000)
+        }
+
+        const cooldownSecs = parseInt(process.env.ENGRAM_NUDGE_COOLDOWN_SECS ?? "900", 10)
+        const nowSecs = Math.floor(Date.now() / 1000)
+
+        // Debounce: skip if we nudged recently this session
+        const lastNudge = lastNudgeTime.get(sessionID)
+        if (lastNudge !== undefined && nowSecs - lastNudge < cooldownSecs) return
+
+        // Skip if the session is too young (< 5 minutes)
+        let sessionStartEpoch = 0
+        try {
+          const sessionRes = await fetch(`${ENGRAM_URL}/sessions/${encodeURIComponent(sessionID)}`, {
+            signal: AbortSignal.timeout(200),
+          })
+          if (sessionRes.ok) {
+            const sessionData = await sessionRes.json()
+            const startedAt: string = sessionData?.started_at ?? ""
+            if (startedAt) {
+              sessionStartEpoch = toEpochSecs(startedAt)
+            }
+          }
+        } catch {
+          // Server unreachable or timed out — skip nudge
+          return
+        }
+        if (sessionStartEpoch > 0 && nowSecs - sessionStartEpoch < 300) return
+
+        // Check when the last observation was saved for this project
+        let lastObsEpoch = 0
+        try {
+          const obsRes = await fetch(
+            `${ENGRAM_URL}/observations?project=${encodeURIComponent(project)}&limit=1&sort=created_at:desc`,
+            { signal: AbortSignal.timeout(200) }
+          )
+          if (obsRes.ok) {
+            const obsData = await obsRes.json()
+            const createdAt: string = obsData?.[0]?.created_at ?? ""
+            if (createdAt) {
+              lastObsEpoch = toEpochSecs(createdAt)
+            }
+          }
+        } catch {
+          // Server unreachable or timed out — skip nudge
+          return
+        }
+
+        // No observations yet — nothing to nudge about
+        if (lastObsEpoch === 0) return
+
+        // Only nudge if last save was more than 15 minutes ago
+        if (nowSecs - lastObsEpoch < 900) return
+
+        // Append the nudge to the last system message
+        const nudge =
+          "\n\nMEMORY REMINDER: It's been over 15 minutes since your last memory save. " +
+          "If you've made decisions, discoveries, completed significant work, or found non-obvious things, " +
+          "call mem_save now."
+        if (output.system.length > 0) {
+          output.system[output.system.length - 1] += nudge
+        } else {
+          output.system.push(nudge)
+        }
+        lastNudgeTime.set(sessionID, nowSecs)
+      } catch {
+        // Any unexpected error — silently skip the nudge, never crash the hook
+      }
+    },
+
+    // ─── Compaction Hook: Persist memory + inject context ──────────
+    // Compaction is triggered by the system (not the agent) when context
+    // gets too long. The old agent "dies" and a new one starts with the
+    // compacted summary. This is our chance to:
+    // 1. Auto-save a session checkpoint (the agent can't do this itself)
+    // 2. Inject context from previous sessions into the compaction prompt
+    // 3. Tell the compressor to remind the new agent to save memories
+
+    "experimental.session.compacting": async (input, output) => {
+      if (input.sessionID) {
+        await ensureSession(input.sessionID)
+      }
+
+      // Inject context from previous sessions
+      const data = await engramFetch(
+        `/context?project=${encodeURIComponent(project)}`
+      )
+      if (data?.context) {
+        output.context.push(data.context)
+      }
+
+      // Tell the compressor to instruct the new agent to persist the
+      // compacted summary to Engram. The new agent reads the compacted
+      // summary and this instruction, then saves it as a session summary.
+      output.context.push(
+        `CRITICAL INSTRUCTION FOR COMPACTED SUMMARY:\n` +
+        `The agent has access to Engram persistent memory via MCP tools.\n` +
+        `You MUST include the following instruction at the TOP of the compacted summary:\n\n` +
+        `"FIRST ACTION REQUIRED: Call mem_session_summary with the content of this compacted summary. ` +
+        `Use project: '${project}'. This preserves what was accomplished before compaction. Do this BEFORE any other work."\n\n` +
+        `This is NOT optional. Without this, everything done before compaction is lost from memory.`
+      )
+    },
+  }
+}

package/assets/skills/{thinking → brainstorming}/SKILL.md

@@ -1,14 +1,16 @@
 ---
-name: thinking
+name: brainstorming
 description: "Thinking partner for exploring ideas, investigating problems, and designing solutions. Two modes: creative-design (structured, produces design doc) and open-explore (unstructured, no mandatory output). Use when the user wants to think through something, brainstorm, explore an idea, or design a solution before or during a change."
 ---
 
-# Thinking
+# Brainstorming
 
 A thinking partner that adapts to what the user needs: structured design when they're building something, open exploration when they're investigating or clarifying.
 
 **Follow Core Instructions** — `ostacky.md` Core Instructions section for CodeGraph and Engram usage patterns.
 
+**IMPORTANT:** Engram is an **MCP server**, not a skill. Tools `mem_save`, `mem_search`, `mem_context` are MCP tools. Do NOT use `skill("engram")` — it doesn't exist.
+
 ---
 
 ## Mode Detection
@@ -19,7 +21,7 @@ A thinking partner that adapts to what the user needs: structured design when th
 | "explore", "investigate", "think through", "what if", "how does" | **open-explore** |
 | "brainstorm", "ideate", "propose approach" | **creative-design** |
 | "check", "understand", "review existing" | **open-explore** |
-| Unclear | Ask with **question** tool: "¿Querés diseñar algo nuevo o explorar/entender algo existente?" |
+| Unclear | Ask in natural language: "¿Querés diseñar algo nuevo o explorar/entender algo existente?" |
 
 ---
 
@@ -33,7 +35,7 @@ Do NOT invoke any implementation skill, write any code, or scaffold any project
 
 ### Process
 
-1. **Check Engram** — `engram_mem_search` with keywords from the user's idea. Surface any prior design decisions or similar proposals.
+1. **Check Engram** — `mem_search` with keywords from the user's idea. Surface any prior design decisions or similar proposals.
 2. **Explore via CodeGraph** — `codegraph_explore` on the affected area. Only `Read` files CodeGraph didn't cover.
 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
@@ -41,7 +43,7 @@ Do NOT invoke any implementation skill, write any code, or scaffold any project
 6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
 7. **Spec self-review** — check for placeholders, contradictions, ambiguity, scope
 8. **User reviews spec** — ask user to review before proceeding
-9. **Save to Engram** — `engram_mem_save` with the design decision and tradeoffs
+9. **Save to Engram** — `mem_save` with the design decision and tradeoffs
 10. **Transition** — based on routing decision (see Transition Rules below)
 
 ### Transition Rules
@@ -192,4 +194,4 @@ Browser use is text-only by default.
 
 - Only use the browser when the user explicitly asks for browser/visual help.
 - Do not suggest the browser just because it might explain something more clearly.
-- If the user asks for browser/visual help, read `skills/thinking/visual-companion.md` before proceeding.
+- If the user asks for browser/visual help, use illustrations and diagrams in the conversation to explain concepts.

package/assets/skills/dispatching-parallel-agents/SKILL.md

@@ -65,13 +65,13 @@ Each agent gets:
 
 ### 3. Dispatch in Parallel
 
-```typescript
-// In Claude Code / AI environment
-Task("Fix agent-tool-abort.test.ts failures")
-Task("Fix batch-completion-behavior.test.ts failures")
-Task("Fix tool-approval-race-conditions.test.ts failures")
-// All three run concurrently
-```
+Delegate each task to a subagent with its own isolated context. All run concurrently.
+
+| Task | Agent | Context |
+|------|-------|---------|
+| Fix agent-tool-abort test | implement | Test failures, source code, error output |
+| Fix batch-completion-behavior test | implement | Test failures, source code, error output |
+| Fix tool-approval-race-conditions test | implement | Test failures, source code, error output |
 
 ### 4. Review and Integrate
 

package/assets/skills/execution-mode-evaluation/SKILL.md

@@ -8,6 +8,8 @@ metadata:
   version: "2.0"
 ---
 
+**IMPORTANT:** Engram is an **MCP server**, not a skill. Tools `mem_save`, `mem_search`, `mem_context` are MCP tools. Do NOT use `skill("engram")` — it doesn't exist.
+
 # Skill: execution-mode-evaluation
 
 Determinar el modo de ejecución óptimo entre **inline** y **subagent-driven** usando datos concretos de CodeGraph. La decisión sigue reglas estrictas en orden de precedencia.
@@ -17,7 +19,7 @@ Determinar el modo de ejecución óptimo entre **inline** y **subagent-driven**
 | Dato | Fuente | Obligatorio |
 |------|--------|-------------|
 | Tasks del change | `tasks.md` del cambio activo | ✅ |
-| Archivos que modifica cada task | `codegraph_context` o lectura directa | ✅ |
+| Archivos que modifica cada task | `codegraph_explore` o lectura directa | ✅ |
 | Blast radius por símbolo | `codegraph_impact` | Para alta precisión |
 | Contratos entre tasks | `design.md` | Para evaluar dependencias |
 
@@ -25,11 +27,11 @@ Determinar el modo de ejecución óptimo entre **inline** y **subagent-driven**
 
 ### Paso 0: Verificar datos existentes en contexto
 
-Si ya tenés output de `codegraph_context` para el área del cambio **Y** ese output distingue archivos por task → **saltá al Paso 0.5**. Si no, ejecutá el Paso 1.
+Si ya tenés output de `codegraph_explore` para el área del cambio **Y** ese output distingue archivos por task → **saltá al Paso 0.5**. Si no, ejecutá el Paso 1.
 
 ### Paso 0.1: Consultar Engram por decisiones previas
 
-`engram_mem_search` con keywords del cambio (nombre del módulo, área afectada). Si existe una decisión de modo de ejecución anterior para un cambio similar, considerarla como referencia — no como vinculante. Las condiciones pueden haber cambiado.
+`mem_search` con keywords del cambio (nombre del módulo, área afectada). Si existe una decisión de modo de ejecución anterior para un cambio similar, considerarla como referencia — no como vinculante. Las condiciones pueden haber cambiado.
 
 ### Paso 0.5: Early exit para cambios pequeños
 
@@ -49,7 +51,7 @@ Si el change tiene **≤2 tasks** Y **no comparten archivos entre sí** → devo
 ### Paso 1: Obtener datos de CodeGraph
 
 ```
-codegraph_context con task: "<descripción del cambio>"
+codegraph_explore con query: "<área del cambio>"
 ```
 
 Si el output es muy general → `codegraph_impact` sobre símbolos centrales para blast radius preciso.
@@ -108,7 +110,7 @@ Para cada fase de `tasks.md`, evaluar intra-fase:
 {
   "recommendation": "INLINE" | "SUBAGENT_DRIVEN",
   "reasons": ["razón principal", "razón secundaria"],
-  "codegraphUsed": ["codegraph_context"],
+  "codegraphUsed": ["codegraph_explore"],
   "taskCount": <N>,
   "sharedFiles": { "src/archivo.ts": ["task1", "task2"] },
   "fileClusters": [["task1", "task2"], ["task3"]],
@@ -122,7 +124,7 @@ Para cada fase de `tasks.md`, evaluar intra-fase:
 }
 ```
 
-**Output para el usuario (mostrar con `question` tool):**
+**Output para el usuario (mostrar en lenguaje natural):**
 
 ```markdown
 ## Análisis de modo de ejecución
@@ -166,7 +168,7 @@ Para cada fase de `tasks.md`, evaluar intra-fase:
 | `estLines` | Estimación conservadora |
 | `hasExplicitContract` | `true` si design.md explicita contratos |
 
-**⚠️ Este skill provee ANÁLISIS, no autorización.** El coordinador muestra el snapshot al usuario y pide confirmación con `question` tool.
+**⚠️ Este skill provee ANÁLISIS, no autorización.** El coordinador muestra el snapshot al usuario y pide confirmación en lenguaje natural, luego espera la respuesta.
 
 ## Ejemplo compacto
 
@@ -176,7 +178,7 @@ Para cada fase de `tasks.md`, evaluar intra-fase:
 
 ## Checklist
 
-- [ ] Ejecuté `codegraph_context` (o verifiqué datos existentes)?
+- [ ] Ejecuté `codegraph_explore` (o verifiqué datos existentes)?
 - [ ] Construí mapa de dependencias con `fileClusters`?
 - [ ] Identifiqué clusters (componentes conectados)?
 - [ ] Verifiqué deps ENTRE clusters (no solo intra)?