@codename_inc/spectre 3.7.0 → 4.0.0

package/plugins/spectre/hooks/scripts/{test_load-knowledge.cjs → test_load-knowledge.mjs}

@@ -1,31 +1,44 @@
 #!/usr/bin/env node
-'use strict';
 
 /**
- * Tests for load-knowledge.cjs SessionStart hook.
+ * Tests for load-knowledge.mjs SessionStart hook.
  *
- * Run with: node --test plugins/spectre/hooks/scripts/test_load-knowledge.cjs
+ * Run with: node --test plugins/spectre/hooks/scripts/test_load-knowledge.mjs
  */
 
-const { describe, it } = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { execFileSync } = require('child_process');
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
-const SCRIPT_PATH = path.join(__dirname, 'load-knowledge.cjs');
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SCRIPT_PATH = path.join(__dirname, 'load-knowledge.mjs');
 
 function createTmpDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'spectre-lk-'));
 }
 
 function createApplySkill(pluginDir) {
-  const skillPath = path.join(pluginDir, 'skills', 'spectre-apply', 'SKILL.md');
+  const skillPath = path.join(pluginDir, 'skills', 'apply', 'SKILL.md');
   fs.mkdirSync(path.dirname(skillPath), { recursive: true });
   fs.writeFileSync(skillPath,
-    '---\nname: spectre-apply\n---\n\n# Apply Knowledge\n\n' +
-    '## Registry Location\n\nThe registry is at somewhere\n\n' +
+    '---\nname: apply\n---\n\n# Apply Knowledge\n\n' +
+    '## How to Find Skills\n\nScan available skills.\n\n' +
+    '## Workflow\n\nDo things.\n'
+  );
+  return skillPath;
+}
+
+function createCodexApplySkill(codexHome) {
+  const skillPath = path.join(codexHome, 'skills', 'apply', 'SKILL.md');
+  fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+  fs.writeFileSync(skillPath,
+    '---\nname: apply\n---\n\n# Apply Knowledge\n\n' +
+    '## How to Find Skills\n\nScan available skills.\n\n' +
     '## Workflow\n\nDo things.\n'
   );
   return skillPath;
@@ -41,6 +54,13 @@ function createRegistry(projectDir, entries, subdir) {
   return registryPath;
 }
 
+function createManifest(projectDir) {
+  const manifestPath = path.join(projectDir, '.spectre', 'manifest.json');
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, '{"version":1}\n');
+  return manifestPath;
+}
+
 function runHook(opts) {
   opts = opts || {};
   const env = Object.assign({}, process.env);
@@ -73,12 +93,15 @@ function cleanup(dir) {
 }
 
 describe('LoadKnowledge - Core behavior', () => {
-  it('exits silently when no plugin root', () => {
+  it('falls back to script-relative plugin root when no plugin root env is set', () => {
     const tmp = createTmpDir();
     try {
       const result = runHook({ pluginRoot: '', cwd: tmp });
       assert.equal(result.exitCode, 0);
-      assert.equal(result.stdout.trim(), '');
+      const output = JSON.parse(result.stdout.trim());
+      assert.match(output.systemMessage, /spectre: ready/);
+      assert.deepEqual(output.hookSpecificOutput, { hookEventName: 'SessionStart' });
+      assert.ok(!fs.existsSync(path.join(tmp, 'AGENTS.override.md')));
     } finally {
       cleanup(tmp);
     }
@@ -100,6 +123,7 @@ describe('LoadKnowledge - Core behavior', () => {
     const pluginDir = path.join(tmp, 'plugin');
     fs.mkdirSync(pluginDir);
     createApplySkill(pluginDir);
+    createManifest(tmp);
 
     try {
       const result = runHook({ pluginRoot: pluginDir, cwd: tmp });
@@ -107,6 +131,30 @@ describe('LoadKnowledge - Core behavior', () => {
       const output = JSON.parse(result.stdout);
       assert.ok(output.systemMessage.includes('ready'));
       assert.ok(output.systemMessage.includes('/spectre:learn'));
+      assert.deepEqual(output.hookSpecificOutput, { hookEventName: 'SessionStart' });
+      const overrideContent = fs.readFileSync(path.join(tmp, 'AGENTS.override.md'), 'utf8');
+      assert.match(overrideContent, /<!-- spectre-knowledge:start -->/);
+      assert.match(overrideContent, /# Apply Knowledge/);
+      assert.doesNotMatch(overrideContent, /additionalContext/);
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('resolves apply skill from Codex home when hooks are under spectre runtime', () => {
+    const tmp = createTmpDir();
+    const codexHome = path.join(tmp, 'codex-home');
+    const runtimeRoot = path.join(codexHome, 'spectre');
+    fs.mkdirSync(path.join(runtimeRoot, 'hooks', 'scripts'), { recursive: true });
+    createCodexApplySkill(codexHome);
+
+    try {
+      const result = runHook({ pluginRoot: runtimeRoot, cwd: tmp });
+      assert.equal(result.exitCode, 0);
+      const output = JSON.parse(result.stdout);
+      assert.ok(output.systemMessage.includes('ready'));
+      assert.deepEqual(output.hookSpecificOutput, { hookEventName: 'SessionStart' });
+      assert.ok(!fs.existsSync(path.join(tmp, 'AGENTS.override.md')));
     } finally {
       cleanup(tmp);
     }
@@ -136,6 +184,10 @@ describe('LoadKnowledge - Core behavior', () => {
       assert.equal(result.exitCode, 0);
       const output = JSON.parse(result.stdout);
       assert.ok(output.systemMessage.includes('2 knowledge skills'));
+      assert.deepEqual(output.hookSpecificOutput, { hookEventName: 'SessionStart' });
+      const overrideContent = fs.readFileSync(path.join(projectDir, 'AGENTS.override.md'), 'utf8');
+      assert.match(overrideContent, /# Apply Knowledge/);
+      assert.doesNotMatch(overrideContent, /feature-auth\|feature\|auth, login\|Auth system knowledge/);
     } finally {
       cleanup(tmp);
     }
@@ -214,25 +266,50 @@ describe('LoadKnowledge - Core behavior', () => {
     }
   });
 
-  it('output contains spectre-knowledge tag', () => {
+  it('writes spectre-knowledge block into AGENTS.override.md', () => {
+    const tmp = createTmpDir();
+    const pluginDir = path.join(tmp, 'plugin');
+    fs.mkdirSync(pluginDir);
+    createApplySkill(pluginDir);
+    createManifest(tmp);
+
+    try {
+      const result = runHook({ pluginRoot: pluginDir, cwd: tmp });
+      assert.equal(result.exitCode, 0);
+      const output = JSON.parse(result.stdout);
+      assert.deepEqual(output.hookSpecificOutput, { hookEventName: 'SessionStart' });
+      const overrideContent = fs.readFileSync(path.join(tmp, 'AGENTS.override.md'), 'utf8');
+      assert.match(overrideContent, /<!-- spectre-knowledge:start -->/);
+      assert.match(overrideContent, /## SPECTRE Knowledge Context/);
+      assert.match(overrideContent, /# Apply Knowledge/);
+      assert.match(overrideContent, /<!-- spectre-knowledge:end -->/);
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('does not append to unrelated AGENTS.override.md outside a Spectre project', () => {
     const tmp = createTmpDir();
     const pluginDir = path.join(tmp, 'plugin');
     fs.mkdirSync(pluginDir);
     createApplySkill(pluginDir);
+    fs.writeFileSync(path.join(tmp, 'AGENTS.override.md'), 'User-owned override content.\n');
 
     try {
       const result = runHook({ pluginRoot: pluginDir, cwd: tmp });
       assert.equal(result.exitCode, 0);
       const output = JSON.parse(result.stdout);
-      const context = output.hookSpecificOutput.additionalContext;
-      assert.ok(context.startsWith('<spectre-knowledge>'));
-      assert.ok(context.endsWith('</spectre-knowledge>'));
+      assert.deepEqual(output.hookSpecificOutput, { hookEventName: 'SessionStart' });
+      assert.equal(
+        fs.readFileSync(path.join(tmp, 'AGENTS.override.md'), 'utf8'),
+        'User-owned override content.\n'
+      );
     } finally {
       cleanup(tmp);
     }
   });
 
-  it('registry content embedded in context', () => {
+  it('registry content is NOT embedded in context', () => {
     const tmp = createTmpDir();
     const pluginDir = path.join(tmp, 'plugin');
     fs.mkdirSync(pluginDir);
@@ -248,8 +325,12 @@ describe('LoadKnowledge - Core behavior', () => {
       });
       assert.equal(result.exitCode, 0);
       const output = JSON.parse(result.stdout);
-      const context = output.hookSpecificOutput.additionalContext;
-      assert.ok(context.includes('embedded-skill|feature|embed|Embedded skill'));
+      assert.deepEqual(output.hookSpecificOutput, { hookEventName: 'SessionStart' });
+      const overrideContent = fs.readFileSync(path.join(tmp, 'AGENTS.override.md'), 'utf8');
+      assert.ok(!overrideContent.includes('embedded-skill|feature|embed|Embedded skill'),
+        'Registry entries should not be embedded in context');
+      assert.ok(overrideContent.includes('# Apply Knowledge'),
+        'Scaffold content should still be present');
     } finally {
       cleanup(tmp);
     }

package/plugins/spectre/hooks/scripts/test_register-learning.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+
+/**
+ * Tests for register_learning.mjs
+ *
+ * Run with: node --test plugins/spectre/hooks/scripts/test_register-learning.mjs
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SCRIPT_PATH = path.join(__dirname, 'register_learning.mjs');
+
+function createTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'spectre-rl-'));
+}
+
+function cleanup(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function runScript(args, opts) {
+  opts = opts || {};
+  const env = Object.assign({}, process.env);
+  if (opts.pluginRoot) {
+    env.CLAUDE_PLUGIN_ROOT = opts.pluginRoot;
+  } else {
+    delete env.CLAUDE_PLUGIN_ROOT;
+  }
+
+  try {
+    const stdout = execFileSync(process.execPath, [SCRIPT_PATH, ...args], {
+      env,
+      timeout: 10000,
+      encoding: 'utf8'
+    });
+    return { stdout, exitCode: 0 };
+  } catch (err) {
+    return { stdout: err.stdout || '', stderr: err.stderr || '', exitCode: err.status };
+  }
+}
+
+describe('register_learning', () => {
+  it('creates new registry with entry', () => {
+    const tmp = createTmpDir();
+    try {
+      const result = runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-auth',
+        '--category', 'feature',
+        '--triggers', 'auth, login',
+        '--description', 'Use when working on authentication'
+      ]);
+
+      assert.equal(result.exitCode, 0);
+      assert.ok(result.stdout.includes('Registered:'));
+
+      const registryPath = path.join(tmp, '.claude', 'skills', 'spectre-recall', 'references', 'registry.toon');
+      assert.ok(fs.existsSync(registryPath));
+
+      const content = fs.readFileSync(registryPath, 'utf8');
+      assert.ok(content.includes('# SPECTRE Knowledge Registry'));
+      assert.ok(content.includes('feature-auth|feature|auth, login|Use when working on authentication'));
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('updates existing entry by skill name', () => {
+    const tmp = createTmpDir();
+    try {
+      // First registration
+      runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-auth',
+        '--category', 'feature',
+        '--triggers', 'auth',
+        '--description', 'Old description'
+      ]);
+
+      // Second registration with same skill name
+      runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-auth',
+        '--category', 'feature',
+        '--triggers', 'auth, login, oauth',
+        '--description', 'Updated description'
+      ]);
+
+      const registryPath = path.join(tmp, '.claude', 'skills', 'spectre-recall', 'references', 'registry.toon');
+      const content = fs.readFileSync(registryPath, 'utf8');
+
+      // Should have the updated entry, not the old one
+      assert.ok(content.includes('Updated description'));
+      assert.ok(!content.includes('Old description'));
+
+      // Should only have one entry for feature-auth
+      const entries = content.split('\n').filter(l => l.startsWith('feature-auth|'));
+      assert.equal(entries.length, 1);
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('generates recall skill with template', () => {
+    const tmp = createTmpDir();
+    const pluginRoot = path.join(tmp, 'plugin');
+
+    // Create template
+    const templateDir = path.join(pluginRoot, 'skills', 'learn', 'references');
+    fs.mkdirSync(templateDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(templateDir, 'recall-template.md'),
+      '# Recall Skill\n\nRegistry:\n{{REGISTRY}}\n\nEnd.\n'
+    );
+
+    try {
+      runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-test',
+        '--category', 'feature',
+        '--triggers', 'test',
+        '--description', 'Test skill'
+      ], { pluginRoot });
+
+      const skillPath = path.join(tmp, '.claude', 'skills', 'spectre-recall', 'SKILL.md');
+      assert.ok(fs.existsSync(skillPath));
+
+      const content = fs.readFileSync(skillPath, 'utf8');
+      assert.ok(content.includes('# Recall Skill'));
+      assert.ok(content.includes('feature-test|feature|test|Test skill'));
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('resolves recall template from Codex home when hooks are under spectre runtime', () => {
+    const tmp = createTmpDir();
+    const codexHome = path.join(tmp, 'codex-home');
+    const runtimeRoot = path.join(codexHome, 'spectre');
+
+    const templateDir = path.join(codexHome, 'skills', 'learn', 'references');
+    fs.mkdirSync(templateDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(templateDir, 'recall-template.md'),
+      '# Codex Recall Skill\n\nRegistry:\n{{REGISTRY}}\n\nEnd.\n'
+    );
+
+    try {
+      runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-codex',
+        '--category', 'feature',
+        '--triggers', 'codex',
+        '--description', 'Codex skill'
+      ], { pluginRoot: runtimeRoot });
+
+      const skillPath = path.join(tmp, '.claude', 'skills', 'spectre-recall', 'SKILL.md');
+      assert.ok(fs.existsSync(skillPath));
+
+      const content = fs.readFileSync(skillPath, 'utf8');
+      assert.ok(content.includes('# Codex Recall Skill'));
+      assert.ok(content.includes('feature-codex|feature|codex|Codex skill'));
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('fails with missing required arguments', () => {
+    const result = runScript(['--project-root', '/tmp/fake']);
+    assert.notEqual(result.exitCode, 0);
+  });
+});
+
+describe('register_learning - trigger migration', () => {
+  it('injects TRIGGER into single-line description', () => {
+    const tmp = createTmpDir();
+    try {
+      const skillDir = path.join(tmp, '.claude', 'skills', 'feature-auth');
+      fs.mkdirSync(skillDir, { recursive: true });
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'),
+        '---\nname: feature-auth\ndescription: Use when working on authentication\nuser-invocable: false\n---\n\n# Auth Knowledge\n'
+      );
+
+      runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-auth',
+        '--category', 'feature',
+        '--triggers', 'auth, login',
+        '--description', 'Use when working on authentication'
+      ]);
+
+      const content = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+      assert.ok(content.includes('description: Use when working on authentication TRIGGER when: auth, login'),
+        'Should be single-line with description and trigger');
+      assert.ok(!content.includes('description: |'), 'Should NOT use block scalar');
+      assert.ok(content.includes('# Auth Knowledge'), 'Body should be preserved');
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('injects TRIGGER into block scalar description', () => {
+    const tmp = createTmpDir();
+    try {
+      const skillDir = path.join(tmp, '.claude', 'skills', 'feature-release');
+      fs.mkdirSync(skillDir, { recursive: true });
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'),
+        '---\nname: feature-release\ndescription: |\n  Use when releasing the plugin or bumping versions.\nuser-invocable: true\n---\n\n# Release\n'
+      );
+
+      runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-release',
+        '--category', 'procedures',
+        '--triggers', 'release, version',
+        '--description', 'Use when releasing the plugin or bumping versions.'
+      ]);
+
+      const content = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+      assert.ok(content.includes('description: Use when releasing the plugin or bumping versions. TRIGGER when: release, version'),
+        'Should collapse block scalar to single-line with trigger');
+      assert.ok(!content.includes('description: |'), 'Block scalar should be removed');
+      assert.ok(content.includes('# Release'), 'Body should be preserved');
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('trigger injection is idempotent', () => {
+    const tmp = createTmpDir();
+    try {
+      const skillDir = path.join(tmp, '.claude', 'skills', 'feature-auth');
+      fs.mkdirSync(skillDir, { recursive: true });
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'),
+        '---\nname: feature-auth\ndescription: Use when working on authentication\nuser-invocable: false\n---\n\n# Auth\n'
+      );
+
+      const args = [
+        '--project-root', tmp,
+        '--skill-name', 'feature-auth',
+        '--category', 'feature',
+        '--triggers', 'auth, login',
+        '--description', 'Use when working on authentication'
+      ];
+
+      runScript(args);
+      runScript(args);
+
+      const content = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+      const matches = content.match(/TRIGGER when:/g);
+      assert.equal(matches.length, 1, 'Should have exactly one TRIGGER line');
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('skips missing skill files gracefully', () => {
+    const tmp = createTmpDir();
+    try {
+      // Register a skill with no SKILL.md on disk
+      const result = runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-missing',
+        '--category', 'feature',
+        '--triggers', 'missing',
+        '--description', 'Nonexistent skill'
+      ]);
+
+      assert.equal(result.exitCode, 0, 'Should not error on missing skill files');
+    } finally {
+      cleanup(tmp);
+    }
+  });
+
+  it('migrates all registry entries on any registration', () => {
+    const tmp = createTmpDir();
+    try {
+      // Create two existing skills without triggers
+      for (const name of ['feature-alpha', 'feature-beta']) {
+        const dir = path.join(tmp, '.claude', 'skills', name);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'SKILL.md'),
+          `---\nname: ${name}\ndescription: Use when working on ${name}\n---\n\n# ${name}\n`
+        );
+      }
+
+      // Seed registry with alpha
+      const registryDir = path.join(tmp, '.claude', 'skills', 'spectre-recall', 'references');
+      fs.mkdirSync(registryDir, { recursive: true });
+      fs.writeFileSync(path.join(registryDir, 'registry.toon'),
+        '# SPECTRE Knowledge Registry\n# Format: skill-name|category|triggers|description\n\n' +
+        'feature-alpha|feature|alpha, first|Use when working on feature-alpha\n' +
+        'feature-beta|feature|beta, second|Use when working on feature-beta\n'
+      );
+
+      // Register a third skill — should trigger migration of alpha and beta too
+      const gammaDir = path.join(tmp, '.claude', 'skills', 'feature-gamma');
+      fs.mkdirSync(gammaDir, { recursive: true });
+      fs.writeFileSync(path.join(gammaDir, 'SKILL.md'),
+        '---\nname: feature-gamma\ndescription: Use when working on gamma\n---\n\n# Gamma\n'
+      );
+
+      runScript([
+        '--project-root', tmp,
+        '--skill-name', 'feature-gamma',
+        '--category', 'feature',
+        '--triggers', 'gamma, third',
+        '--description', 'Use when working on gamma'
+      ]);
+
+      // All three should now have triggers
+      for (const [name, triggers] of [
+        ['feature-alpha', 'alpha, first'],
+        ['feature-beta', 'beta, second'],
+        ['feature-gamma', 'gamma, third']
+      ]) {
+        const content = fs.readFileSync(
+          path.join(tmp, '.claude', 'skills', name, 'SKILL.md'), 'utf8'
+        );
+        assert.ok(content.includes(`TRIGGER when: ${triggers}`),
+          `${name} should have triggers: ${triggers}`);
+      }
+    } finally {
+      cleanup(tmp);
+    }
+  });
+});

package/plugins/spectre/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}}/.claude/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.

package/plugins/spectre/{commands/architecture_review.md → skills/architecture_review/SKILL.md}

@@ -1,7 +1,16 @@
 ---
+name: architecture_review
 description: 👻 | Conduct principal architecture review
+user-invocable: true
 ---
 
+# architecture_review
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
 # architecture_review: Technical review of completed features
 
 ## Description

package/plugins/spectre/{commands/clean.md → skills/clean/SKILL.md}

@@ -1,6 +1,15 @@
 ---
+name: clean
 description: 👻 | Complete cleanup flow - clean, inspect, lint, test - primary agent
+user-invocable: true
 ---
+
+# clean
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
 # clean: Analyze recent changes for dead code and artifacts from failed branches
 
 ## Description

package/plugins/spectre/{commands/code_review.md → skills/code_review/SKILL.md}

@@ -1,6 +1,15 @@
 ---
+name: code_review
 description: 👻 | Independent LLM Code Review - subagent
+user-invocable: true
 ---
+
+# code_review
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
 # code_review: Comprehensive Code Analysis
 
 ## Description