@codename_inc/spectre 3.7.0 → 4.0.0

package/plugins/{spectre/hooks/scripts/handoff-resume.cjs → spectre-codex/hooks/scripts/handoff-resume.mjs}

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-'use strict';
 
 /**
- * handoff-resume.cjs
+ * handoff-resume.mjs
  *
  * SessionStart hook that injects context from the last /spectre:handoff.
  * Consolidates the previous session-resume-hook.sh + format-resume-context.py.
@@ -15,17 +14,25 @@
  * - --bg-copy-refs: Copy plugin references (fork #1)
  */
 
-const fs = require('fs');
-const path = require('path');
-const { fork } = require('child_process');
-const { readStdinWithTimeout, getGitBranch } = require('./lib.cjs');
+import fs from 'node:fs';
+import path from 'node:path';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readStdinWithTimeout, getGitBranch } from './lib.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function getPluginRoot() {
+  return process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..', '..');
+}
 
 // ──────────────────────────────────────────────────────────────────
 // Plugin reference copying (background fork #1)
 // ──────────────────────────────────────────────────────────────────
 
 function copyPluginReferences() {
-  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  const pluginRoot = getPluginRoot();
   if (!pluginRoot) return;
 
   const referencesSrc = path.join(pluginRoot, 'references');
@@ -198,14 +205,7 @@ function formatContext(data, opts) {
   const checkboxTree = (beadsAvailable && tasks.length) ? buildCheckboxTree(tasks) : '';
 
   // User-visible notice
-  const asciiBanner = [
-    '',
-    '\u2591\u2588\u2580\u2580\u2591\u2588\u2580\u2588\u2591\u2588\u2580\u2580\u2591\u2588\u2580\u2580\u2591\u2580\u2588\u2580\u2591\u2588\u2580\u2584\u2591\u2588\u2580\u2580',
-    '\u2591\u2580\u2580\u2588\u2591\u2588\u2580\u2580\u2591\u2588\u2580\u2580\u2591\u2588\u2591\u2591\u2591\u2591\u2588\u2591\u2591\u2588\u2580\u2584\u2591\u2588\u2580\u2580',
-    '\u2591\u2580\u2580\u2580\u2591\u2580\u2591\u2591\u2591\u2580\u2580\u2580\u2591\u2580\u2580\u2580\u2591\u2591\u2580\u2591\u2591\u2580\u2591\u2580\u2591\u2580\u2580\u2580'
-  ].join('\n');
-
-  const noticeLines = [asciiBanner];
+  const noticeLines = ['\ud83d\udc7b SPECTRE'];
   noticeLines.push(`\n\ud83d\udd04 Session Resumed: ${taskName} | Branch: ${branchName}`);
 
   if (goal) {
@@ -353,12 +353,7 @@ async function main() {
 
   if (!latestHandoff) {
     // No session to resume - show welcome banner with tips
-    const asciiBanner = [
-      '',
-      '\u2591\u2588\u2580\u2580\u2591\u2588\u2580\u2588\u2591\u2588\u2580\u2580\u2591\u2588\u2580\u2580\u2591\u2580\u2588\u2580\u2591\u2588\u2580\u2584\u2591\u2588\u2580\u2580',
-      '\u2591\u2580\u2580\u2588\u2591\u2588\u2580\u2580\u2591\u2588\u2580\u2580\u2591\u2588\u2591\u2591\u2591\u2591\u2588\u2591\u2591\u2588\u2580\u2584\u2591\u2588\u2580\u2580',
-      '\u2591\u2580\u2580\u2580\u2591\u2580\u2591\u2591\u2591\u2580\u2580\u2580\u2591\u2580\u2580\u2580\u2591\u2591\u2580\u2591\u2591\u2580\u2591\u2580\u2591\u2580\u2580\u2580'
-    ].join('\n');
+    const banner = '\ud83d\udc7b SPECTRE';
     const tips = [
       '',
       'Getting Started with SPECTRE:',
@@ -371,7 +366,7 @@ async function main() {
     ].join('\n');
 
     const welcome = {
-      systemMessage: asciiBanner + '\n' + tips
+      systemMessage: banner + '\n' + tips
     };
     process.stdout.write(JSON.stringify(welcome) + '\n');
     process.exit(0);
@@ -402,9 +397,8 @@ async function main() {
   process.exit(0);
 }
 
-// Export for testing
-if (typeof module !== 'undefined') {
-  module.exports = { copyPluginReferences, formatContext, buildCheckboxTree };
-}
+export { copyPluginReferences, formatContext, buildCheckboxTree };
 
-main();
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}

package/plugins/{spectre/hooks/scripts/lib.cjs → spectre-codex/hooks/scripts/lib.mjs}

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
-'use strict';
 
 /**
- * lib.cjs
+ * lib.mjs
  *
  * Shared utilities for spectre hook scripts.
  */
 
-const { execSync } = require('child_process');
+import { execSync } from 'node:child_process';
 
 const STDIN_TIMEOUT = 2000; // milliseconds
 
@@ -80,4 +79,4 @@ function getGitBranch(cwd) {
   }
 }
 
-module.exports = { readStdinWithTimeout, getGitBranch, STDIN_TIMEOUT };
+export { readStdinWithTimeout, getGitBranch, STDIN_TIMEOUT };

package/plugins/spectre-codex/hooks/scripts/load-knowledge.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+/**
+ * load-knowledge.mjs
+ *
+ * SessionStart hook that refreshes the managed SPECTRE knowledge block in
+ * AGENTS.override.md and returns a short visible status line.
+ *
+ * Reads:
+ * - Apply skill from plugin: skills/apply/SKILL.md
+ * - Registry from project: .agents/skills/spectre-recall/references/registry.toon
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function getPluginRoot() {
+  return process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..', '..');
+}
+
+function resolvePluginSkillPath(pluginRoot, skillName, ...parts) {
+  const candidates = [
+    path.join(pluginRoot, 'skills', skillName, ...parts),
+    path.join(pluginRoot, '..', 'skills', skillName, ...parts),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
+}
+
+function skillBaseDir(projectDir) {
+  const agentsDir = path.join(projectDir, '.agents', 'skills');
+  if (fs.existsSync(agentsDir)) return agentsDir;
+  return path.join(projectDir, '.claude', 'skills');
+}
+
+function countRegistryEntries(lines) {
+  let count = 0;
+  for (const line of lines) {
+    if (line.trim() && line.includes('|') && !line.startsWith('#')) {
+      count++;
+    }
+  }
+  return count;
+}
+
+function stripFrontmatter(content) {
+  if (content.startsWith('---')) {
+    const end = content.indexOf('---', 3);
+    if (end !== -1) {
+      return content.slice(end + 3).trim();
+    }
+  }
+  return content;
+}
+
+function normalizeOverrideFile(content) {
+  return content
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function managedOverridePattern(startMarker, endMarker) {
+  return new RegExp(`\\n?${escapeRegExp(startMarker)}[\\s\\S]*?${escapeRegExp(endMarker)}\\n?`, 'm');
+}
+
+function writeManagedOverride(overridePath, startMarker, endMarker, bodyContent) {
+  const current = fs.existsSync(overridePath) ? fs.readFileSync(overridePath, 'utf8') : '';
+  const pattern = managedOverridePattern(startMarker, endMarker);
+  const blockContent = `${startMarker}\n${bodyContent}\n${endMarker}`;
+  let updated;
+
+  if (pattern.test(current)) {
+    updated = current.replace(pattern, `${blockContent}\n`);
+  } else if (current.trim()) {
+    updated = `${current.trimEnd()}\n\n${blockContent}\n`;
+  } else {
+    updated = `${blockContent}\n`;
+  }
+
+  const normalized = normalizeOverrideFile(updated);
+  fs.writeFileSync(overridePath, normalized ? `${normalized}\n` : '');
+}
+
+function hasProjectKnowledgeSurface(projectDir, registryPath) {
+  const overridePath = path.join(projectDir, 'AGENTS.override.md');
+  const overrideContent = fs.existsSync(overridePath) ? fs.readFileSync(overridePath, 'utf8') : '';
+  return fs.existsSync(path.join(projectDir, '.spectre', 'manifest.json'))
+    || fs.existsSync(registryPath)
+    || overrideContent.includes('<!-- spectre-knowledge:start -->')
+    || overrideContent.includes('<!-- spectre-session:start -->');
+}
+
+function buildKnowledgeOverrideBody(applyContent) {
+  return [
+    '## SPECTRE Knowledge Context',
+    '',
+    'This block is managed by SPECTRE and replaced automatically on session start.',
+    'Use it before searching or implementing work in this repository.',
+    '',
+    applyContent.trim()
+  ].join('\n');
+}
+
+function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const pluginRoot = getPluginRoot();
+
+  const applySkillPath = resolvePluginSkillPath(pluginRoot, 'apply', 'SKILL.md');
+
+  if (!fs.existsSync(applySkillPath)) {
+    process.exit(0);
+  }
+
+  // Paths - check new name first, fall back to old names for migration
+  let registryPath = path.join(skillBaseDir(projectDir), 'spectre-recall', 'references', 'registry.toon');
+  const oldRegistryPath = path.join(projectDir, '.claude', 'skills', 'spectre-find', 'references', 'registry.toon');
+
+  // Support old "spectre-find" path for projects that haven't migrated
+  if (!fs.existsSync(registryPath) && fs.existsSync(oldRegistryPath)) {
+    registryPath = oldRegistryPath;
+  }
+
+  // Read registry if it exists
+  let registryContent = '';
+  let entryCount = 0;
+  if (fs.existsSync(registryPath)) {
+    registryContent = fs.readFileSync(registryPath, 'utf8').trim();
+    const lines = registryContent ? registryContent.split('\n') : [];
+    entryCount = countRegistryEntries(lines);
+  }
+
+  // Read apply skill and strip frontmatter
+  let applyContent = fs.readFileSync(applySkillPath, 'utf8');
+  applyContent = stripFrontmatter(applyContent);
+  applyContent = applyContent.replaceAll('.claude/skills/', '.agents/skills/').replaceAll('/spectre:', '');
+
+  if (hasProjectKnowledgeSurface(projectDir, registryPath)) {
+    writeManagedOverride(
+      path.join(projectDir, 'AGENTS.override.md'),
+      '<!-- spectre-knowledge:start -->',
+      '<!-- spectre-knowledge:end -->',
+      buildKnowledgeOverrideBody(applyContent)
+    );
+  }
+
+  // Visible notice
+  let visibleNotice;
+  if (entryCount > 0) {
+    visibleNotice = `\ud83d\udc7b spectre: ${entryCount} knowledge skills available`;
+  } else {
+    visibleNotice = '\ud83d\udc7b spectre: ready \u2014 capture knowledge with /spectre:learn';
+  }
+
+  const output = {
+    systemMessage: visibleNotice,
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart'
+    }
+  };
+
+  process.stdout.write(JSON.stringify(output) + '\n');
+  process.exit(0);
+}
+
+export {
+  buildKnowledgeOverrideBody,
+  countRegistryEntries,
+  hasProjectKnowledgeSurface,
+  resolvePluginSkillPath,
+  stripFrontmatter
+};
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}

package/plugins/spectre-codex/hooks/scripts/register_learning.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+/**
+ * register_learning.mjs
+ *
+ * Registers a spectre learning and manages the project-level recall skill.
+ *
+ * Responsibilities:
+ * 1. Create/update registry at .claude/skills/spectre-recall/references/registry.toon
+ * 2. Read recall-template.md from plugin
+ * 3. Generate .claude/skills/spectre-recall/SKILL.md with embedded registry
+ *
+ * Usage:
+ *   node register_learning.mjs \
+ *     --project-root "/path/to/project" \
+ *     --skill-name "feature-my-feature" \
+ *     --category "feature" \
+ *     --triggers "keyword1, keyword2" \
+ *     --description "Use when doing X or Y"
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function getRegistryHeader() {
+  return [
+    '# SPECTRE Knowledge Registry',
+    '# Format: skill-name|category|triggers|description',
+    ''
+  ];
+}
+
+function updateRegistry(registryPath, entry, skillName) {
+  const entryPrefix = skillName + '|';
+  let lines;
+
+  if (fs.existsSync(registryPath)) {
+    const content = fs.readFileSync(registryPath, 'utf8').trim();
+    lines = content ? content.split('\n') : [];
+  } else {
+    lines = getRegistryHeader();
+  }
+
+  let entryExists = false;
+  const updatedLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith(entryPrefix)) {
+      updatedLines.push(entry);
+      entryExists = true;
+    } else {
+      updatedLines.push(line);
+    }
+  }
+
+  if (!entryExists) {
+    updatedLines.push(entry);
+  }
+
+  let content = updatedLines.join('\n');
+  if (!content.endsWith('\n')) {
+    content += '\n';
+  }
+
+  fs.writeFileSync(registryPath, content);
+  return content;
+}
+
+function generateFindSkill(findSkillPath, templatePath, registryContent) {
+  if (!fs.existsSync(templatePath)) {
+    process.stderr.write(`Warning: Template not found at ${templatePath}\n`);
+    return;
+  }
+
+  const template = fs.readFileSync(templatePath, 'utf8');
+  const skillContent = template.replace('{{REGISTRY}}', registryContent.trim());
+
+  fs.mkdirSync(path.dirname(findSkillPath), { recursive: true });
+  fs.writeFileSync(findSkillPath, skillContent);
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return null;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return null;
+  return {
+    fmBlock: content.slice(4, end),
+    body: content.slice(end + 4)
+  };
+}
+
+function injectTriggerIntoSkill(skillPath, triggers) {
+  if (!fs.existsSync(skillPath)) return;
+
+  const content = fs.readFileSync(skillPath, 'utf8');
+  const parsed = parseFrontmatter(content);
+  if (!parsed) return;
+
+  const { fmBlock, body } = parsed;
+
+  const lines = fmBlock.split('\n');
+  const descIdx = lines.findIndex(l => /^description:\s*/.test(l));
+  if (descIdx === -1) return;
+
+  const descLine = lines[descIdx];
+  const rawValue = descLine.replace(/^description:\s*/, '').trim();
+
+  // Extract the plain description text and count lines to replace
+  let descText;
+  let linesToRemove = 1;
+
+  if (rawValue === '|' || rawValue === '>') {
+    // Block scalar — collect indented continuation lines
+    const continuationParts = [];
+    for (let i = descIdx + 1; i < lines.length; i++) {
+      if (/^\s+/.test(lines[i])) {
+        continuationParts.push(lines[i].trim());
+        linesToRemove++;
+      } else {
+        break;
+      }
+    }
+    descText = continuationParts.join(' ');
+  } else {
+    descText = rawValue;
+    // Strip surrounding quotes
+    if ((descText.startsWith('"') && descText.endsWith('"')) ||
+        (descText.startsWith("'") && descText.endsWith("'"))) {
+      descText = descText.slice(1, -1);
+    }
+  }
+
+  // Strip any existing TRIGGER clause so we can re-append with fresh triggers
+  descText = descText.replace(/\s*TRIGGER when:.*$/, '').trim();
+
+  // Single-line description with trigger appended
+  const newDesc = `description: ${descText} TRIGGER when: ${triggers}`;
+
+  // Idempotent: if the line is already exactly right, skip the write
+  if (linesToRemove === 1 && lines[descIdx] === newDesc) return;
+
+  lines.splice(descIdx, linesToRemove, newDesc);
+
+  const newFmBlock = lines.join('\n');
+  fs.writeFileSync(skillPath, `---\n${newFmBlock}\n---${body}`);
+}
+
+function migrateAllTriggers(projectRoot, registryContent) {
+  const skillsDir = skillBaseDir(projectRoot);
+  const lines = registryContent.trim().split('\n');
+  for (const line of lines) {
+    if (!line.trim() || line.startsWith('#')) continue;
+    const parts = line.split('|');
+    if (parts.length < 3) continue;
+    const skillName = parts[0];
+    const triggers = parts[2];
+    const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
+    injectTriggerIntoSkill(skillPath, triggers);
+  }
+}
+
+function skillBaseDir(projectRoot) {
+  const agentsDir = path.join(projectRoot, '.agents', 'skills');
+  if (fs.existsSync(agentsDir)) return agentsDir;
+  return path.join(projectRoot, '.claude', 'skills');
+}
+
+function resolvePluginSkillPath(pluginRoot, skillName, ...parts) {
+  const candidates = [
+    path.join(pluginRoot, 'skills', skillName, ...parts),
+    path.join(pluginRoot, '..', 'skills', skillName, ...parts),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
+}
+
+function parseArgs(argv) {
+  const args = {};
+  const flags = ['--project-root', '--skill-name', '--category', '--triggers', '--description'];
+
+  for (let i = 0; i < argv.length; i++) {
+    if (flags.includes(argv[i]) && i + 1 < argv.length) {
+      // Convert --project-root to projectRoot
+      const key = argv[i].slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      args[key] = argv[i + 1];
+      i++;
+    }
+  }
+
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const required = ['projectRoot', 'skillName', 'category', 'triggers', 'description'];
+  for (const key of required) {
+    if (!args[key]) {
+      process.stderr.write(`Error: missing required argument --${key.replace(/[A-Z]/g, c => '-' + c.toLowerCase())}\n`);
+      process.exit(1);
+    }
+  }
+
+  const projectRoot = args.projectRoot;
+
+  // New paths: registry lives inside spectre-recall skill
+  const recallDir = path.join(skillBaseDir(projectRoot), 'spectre-recall');
+  const registryDir = path.join(recallDir, 'references');
+  const registryPath = path.join(registryDir, 'registry.toon');
+  const recallSkillPath = path.join(recallDir, 'SKILL.md');
+
+  // Template is in the plugin — resolve via env var (hooks) or this script (manual invocation)
+  let pluginRoot;
+  if (process.env.CLAUDE_PLUGIN_ROOT) {
+    pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  } else {
+    // Fallback: resolve relative to this script
+    // Script is at: <plugin_root>/hooks/scripts/register_learning.mjs
+    pluginRoot = path.resolve(__dirname, '..', '..');
+  }
+  const templatePath = resolvePluginSkillPath(pluginRoot, 'learn', 'references', 'recall-template.md');
+
+  // Ensure directories exist
+  fs.mkdirSync(registryDir, { recursive: true });
+
+  // Build the registry entry
+  const entry = `${args.skillName}|${args.category}|${args.triggers}|${args.description}`;
+
+  // Update registry and get full content
+  const registryContent = updateRegistry(registryPath, entry, args.skillName);
+
+  // Generate recall skill with embedded registry
+  generateFindSkill(recallSkillPath, templatePath, registryContent);
+
+  // Reconcile triggers into all skill frontmatter descriptions
+  migrateAllTriggers(projectRoot, registryContent);
+
+  process.stdout.write(`Registered: ${entry}\n`);
+}
+
+export {
+  getRegistryHeader,
+  updateRegistry,
+  generateFindSkill,
+  parseFrontmatter,
+  injectTriggerIntoSkill,
+  migrateAllTriggers,
+  resolvePluginSkillPath,
+  parseArgs
+};
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}

package/plugins/spectre-codex/skills/apply/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "apply"
+description: "Use when starting implementation, debugging, or feature work on a project with captured knowledge."
+user-invocable: false
+---
+
+# Apply Knowledge
+
+## Why This Exists
+
+SPECTRE captures knowledge — patterns, gotchas, decisions, and feature context — across sessions. Loading it first prevents repeated mistakes, maintains consistency, and tells you WHERE to look before searching.
+
+## The Rule
+
+<CRITICAL>
+If ANY skill's triggers or description match your current task, you MUST load the skill FIRST using the Skill tool.
+
+**Trigger matches are sufficient.** If a trigger word appears in the user's request, load the skill — you don't need the description to also match. Don't reframe the user's request to avoid triggers.
+
+DO NOT search the codebase or dispatch agents BEFORE loading relevant knowledge — even if you think you already have enough context. Partial context from Read results or error messages is not a substitute for the complete picture in the skill.
+
+**When a command explicitly tells you to load a skill, you MUST call the Skill tool to load it.** Do not improvise the workflow based on what you think the skill does. The skill defines a specific workflow with precise steps, output formats, file locations, and integrations. Your improvised version will be wrong.
+
+**You are also responsible for keeping knowledge current.** After completing significant work, proactively check whether loaded skills need updating and whether new skills should be captured via `Skill(learn)`. Do NOT wait for the user to ask.
+</CRITICAL>
+
+## Path Convention
+
+`{{project_root}}` refers to **the current working directory** (`$PWD`). NEVER traverse up to a parent git root or main worktree. If in a git worktree, `{{project_root}}` is the worktree — not the main repository.
+
+## How to Find Skills
+
+Your available skills are listed in context at the start of every session. Each skill's description includes `TRIGGER when:` keywords.
+
+Scan the skill list for trigger matches against your current task. Load matches with `Skill({skill-name})`.
+
+The registry at `{{project_root}}/.agents/skills/spectre-recall/references/registry.toon` remains the source of truth for registration, but you do NOT need to read it for discovery — the skill list already has what you need.
+
+## Workflow
+
+1. **Scan available skills** in your context — match trigger keywords or descriptions to your task
+2. **For each match**, load the skill: `Skill({skill-name})`
+3. **Apply the knowledge** — use it to guide your approach, know where to look
+4. **Then proceed** — now you can search/implement with context
+5. **No matches?** Proceed normally
+
+## Keeping Knowledge Current
+
+After completing work, check:
+
+1. **Loaded skill now outdated?** → Update it immediately
+2. **Discovered something capture-worthy?** (gotcha, pattern, decision) → Capture via `Skill(learn)`
+3. **Changed key files, flows, or architecture?** → Update the relevant feature skill
+4. **Made a decision with non-obvious rationale?** → Capture before the session ends
+
+Stale knowledge is worse than no knowledge — it actively misleads future sessions. Update skills before moving to the next task.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "Let me search the codebase first" | Knowledge tells you WHERE to search. Load the skill first. |
+| "I already have context from a Read/system message" | Partial context is dangerous. The skill has the full picture — including related changes you don't know about yet. |
+| "This seems simple / the edit is surgical" | Simple tasks benefit from captured patterns. Skills reveal if similar changes are needed elsewhere. |
+| "I understand the intent, I don't need the skill" | Understanding intent ≠ knowing the implementation. Skills define WHERE files go, WHAT format to use, and HOW to register outputs. |
+| "The command says to load a skill, but I can handle it directly" | When a command tells you to load a skill, that is a mandatory Skill tool call, not a suggestion. |
+| "I'll update the skill later" | Later never comes. Update before moving to the next task. |
+
+## Failure Pattern
+
+**Common scenario**: Task matches triggers (e.g., "spectre", "release", "learn"), but agent rationalizes skipping the skill load.
+
+**Rationalizations that fail**: "I already have the file contents", "The error points to the exact path", "This is really about X not Y", "I can figure this out faster by searching."
+
+**What skills provide that context doesn't**: Architectural relationships, related files you don't know about, exact workflows with registration steps, correct output paths. Partial context from Read results is not a substitute.
+
+**The cost**: Extra tool calls, wrong output locations, missed registration steps, inconsistent changes.
+
+## Example
+
+User: "How does /spectre work?"
+
+Skill list shows: `feature-spectre-plugin` with trigger `spectre`
+
+Action: `Skill(feature-spectre-plugin)`
+
+Then: Use the key files and patterns from that knowledge to guide your work.