@codename_inc/spectre 3.7.0

package/plugins/spectre/hooks/scripts/handoff-resume.cjs

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * handoff-resume.cjs
+ *
+ * SessionStart hook that injects context from the last /spectre:handoff.
+ * Consolidates the previous session-resume-hook.sh + format-resume-context.py.
+ *
+ * Outputs JSON for Claude Code hook system:
+ * - systemMessage: User-visible notice
+ * - hookSpecificOutput.additionalContext: Full session context in <session-context> tags
+ *
+ * Background modes:
+ * - --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');
+
+// ──────────────────────────────────────────────────────────────────
+// Plugin reference copying (background fork #1)
+// ──────────────────────────────────────────────────────────────────
+
+function copyPluginReferences() {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!pluginRoot) return;
+
+  const referencesSrc = path.join(pluginRoot, 'references');
+  if (!fs.existsSync(referencesSrc)) return;
+
+  const referencesDst = path.join('.claude', 'spectre');
+  fs.mkdirSync(referencesDst, { recursive: true });
+
+  const files = fs.readdirSync(referencesSrc).filter(f => f.endsWith('.md'));
+  for (const file of files) {
+    const dst = path.join(referencesDst, file);
+    if (!fs.existsSync(dst)) {
+      fs.copyFileSync(path.join(referencesSrc, file), dst);
+    }
+  }
+
+  // Append to .gitignore if it exists and .claude/ not already ignored
+  const gitignorePath = '.gitignore';
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (!content.includes('.claude/') && !content.includes('.claude/spectre/')) {
+      fs.appendFileSync(gitignorePath, '\n# spectre plugin files\n.claude/spectre/\n');
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Session discovery
+// ──────────────────────────────────────────────────────────────────
+
+function findLatestHandoff(sessionDir) {
+  if (!fs.existsSync(sessionDir)) return null;
+
+  // Only look at top-level files, not in archive/
+  const files = fs.readdirSync(sessionDir)
+    .filter(f => f.endsWith('_handoff.json'))
+    .map(f => ({
+      name: f,
+      full: path.join(sessionDir, f),
+      mtime: fs.statSync(path.join(sessionDir, f)).mtimeMs
+    }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  return files.length > 0 ? files[0].full : null;
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Formatting helpers
+// ──────────────────────────────────────────────────────────────────
+
+function formatList(items, prefix) {
+  prefix = prefix != null ? prefix : '- ';
+  if (!items || !items.length) return `${prefix}None`;
+  return items.map(item => `${prefix}${item}`).join('\n');
+}
+
+function buildCheckboxTree(tasks) {
+  if (!tasks || !tasks.length) return 'No tasks found.';
+
+  const byParent = {};
+  for (const task of tasks) {
+    const parent = task.parent || null;
+    if (!byParent[parent]) byParent[parent] = [];
+    byParent[parent].push(task);
+  }
+
+  function renderTask(task, indent) {
+    indent = indent || 0;
+    const lines = [];
+    const prefix = '  '.repeat(indent);
+    const checkbox = task.completed ? '[x]' : '[ ]';
+    const status = task.status || 'open';
+    const title = task.title || 'Untitled';
+    const taskId = task.id || 'unknown';
+
+    if (task.completed) {
+      lines.push(`${prefix}- ${checkbox} ${title} (${taskId}) - COMPLETED`);
+    } else {
+      const cmd = task.resume_command || `bd update ${taskId} --status in_progress`;
+      const statusBadge = status !== 'open' ? `[${status}]` : '';
+      lines.push(`${prefix}- ${checkbox} ${title} (${taskId}) ${statusBadge} - \`${cmd}\``);
+    }
+
+    // Render children
+    const childrenIds = task.children || [];
+    if (childrenIds.length) {
+      for (const childTask of tasks) {
+        if (childrenIds.includes(childTask.id) || childTask.parent === taskId) {
+          lines.push(...renderTask(childTask, indent + 1));
+        }
+      }
+    }
+
+    return lines;
+  }
+
+  // Start with root tasks (no parent or parent is null)
+  const rootTasks = (byParent[null] || []).concat(byParent['null'] || []);
+
+  // If no root tasks found, just list all tasks flat
+  const startTasks = rootTasks.length ? rootTasks : tasks;
+
+  const lines = [];
+  const renderedIds = new Set();
+
+  for (const task of startTasks) {
+    if (!renderedIds.has(task.id)) {
+      const taskLines = renderTask(task);
+      lines.push(...taskLines);
+      renderedIds.add(task.id);
+      for (const t of tasks) {
+        if (t.parent === task.id) {
+          renderedIds.add(t.id);
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Main context formatter
+// ──────────────────────────────────────────────────────────────────
+
+function formatContext(data, opts) {
+  opts = opts || {};
+  const handoffPath = opts.handoffPath;
+
+  const taskName = data.task_name || 'unknown';
+  const branchName = data.branch_name || 'unknown';
+
+  // Progress update fields (v1.1 schema)
+  const progress = data.progress_update || {};
+  const summary = progress.summary || 'No summary available.';
+  const goal = progress.goal || '';
+  const constraints = progress.constraints || [];
+  const decisions = progress.decisions || [];
+  const accomplished = progress.accomplished || [];
+  const now = progress.now || '';
+  const nextSteps = progress.next_steps || [];
+  const blockers = progress.blockers || [];
+  const openQuestions = progress.open_questions || [];
+  const confidence = progress.confidence || 'unknown';
+  const risks = progress.risks || [];
+
+  // Working set (v1.1 schema) - fall back to context.key_files for v1.0
+  const workingSet = data.working_set || {};
+  let keyFiles = workingSet.key_files || [];
+  const activeIds = workingSet.active_ids || [];
+  const recentCommands = workingSet.recent_commands || [];
+
+  // Fall back to old context structure if working_set not present
+  if (!keyFiles.length) {
+    const ctx = data.context || {};
+    keyFiles = ctx.key_files || [];
+  }
+
+  // Beads tasks
+  const beads = data.beads || {};
+  const beadsAvailable = beads.available != null ? beads.available : true;
+  const tasks = beads.tasks || [];
+
+  // Context
+  const context = data.context || {};
+  const lastCommit = context.last_commit || 'unknown';
+  const wipState = context.wip_state || 'unknown';
+
+  // Build checkbox tree for beads tasks
+  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];
+  noticeLines.push(`\n\ud83d\udd04 Session Resumed: ${taskName} | Branch: ${branchName}`);
+
+  if (goal) {
+    noticeLines.push(`\n\ud83c\udfaf Goal: ${goal}`);
+  }
+
+  noticeLines.push(`\n\ud83d\udcdd Summary: ${summary}`);
+
+  if (nextSteps.length) {
+    noticeLines.push('\n\u27a1\ufe0f Next Steps:');
+    for (const step of nextSteps) {
+      noticeLines.push(`  - ${step}`);
+    }
+  }
+
+  if (handoffPath) {
+    noticeLines.push(`\n\ud83d\udcc1 Full details: ${handoffPath}`);
+  }
+
+  noticeLines.push('\n\ud83d\udca1 Run /spectre:forget to clear session memory and start fresh.');
+
+  const visibleNotice = noticeLines.join('\n');
+
+  // Build the hidden context sections
+  const sections = [];
+
+  sections.push(`# Session Context: ${taskName}`);
+
+  // Last session summary
+  sections.push(`\n## Last Session Summary\n${summary}`);
+
+  // Goal (if available - v1.1)
+  if (goal) {
+    sections.push(`\n### Goal\n${goal}`);
+  }
+
+  // Constraints (if available - v1.1)
+  if (constraints.length) {
+    sections.push(`\n### Constraints\n${formatList(constraints)}`);
+  }
+
+  // What we accomplished
+  sections.push(`\n### What We Accomplished\n${formatList(accomplished)}`);
+
+  // What we were working on (critical for resume - v1.1)
+  if (now) {
+    sections.push(`\n### Active Work (Resume Here)\n**${now}**`);
+  }
+
+  // What's next
+  sections.push(`\n### What's Next\n${formatList(nextSteps)}`);
+
+  // Blockers
+  if (blockers.length) {
+    sections.push(`\n### Blockers\n${formatList(blockers)}`);
+  }
+
+  // Open questions (v1.1)
+  if (openQuestions.length) {
+    sections.push(`\n### Open Questions\n${formatList(openQuestions)}`);
+  }
+
+  // Decisions
+  if (decisions.length) {
+    sections.push(`\n### Decisions Made\n${formatList(decisions)}`);
+  }
+
+  // Confidence and risks
+  const risksStr = risks.length ? formatList(risks, '') : 'None identified';
+  sections.push(`\n**Confidence**: ${confidence} | **Risks**: ${risksStr}`);
+
+  // Working set (v1.1)
+  const wsLines = [];
+  if (keyFiles.length) {
+    wsLines.push(`- **Key Files**: ${keyFiles.join(', ')}`);
+  }
+  if (activeIds.length) {
+    wsLines.push(`- **Active IDs**: ${activeIds.join(', ')}`);
+  }
+  if (recentCommands.length) {
+    wsLines.push(`- **Recent Commands**: ${recentCommands.join(', ')}`);
+  }
+
+  if (wsLines.length) {
+    sections.push('\n### Working Set\n' + wsLines.join('\n'));
+  }
+
+  // Context
+  sections.push(
+    '\n---\n\n' +
+    '## Context\n' +
+    `- **Branch**: ${branchName}\n` +
+    `- **Last Commit**: ${lastCommit}\n` +
+    `- **WIP State**: ${wipState}`
+  );
+
+  // Beads tasks (if available)
+  if (beadsAvailable && checkboxTree) {
+    sections.push(`\n### Beads Tasks\n${checkboxTree}`);
+  }
+
+  const hiddenContext = `<session-context>\n${sections.join('')}\n</session-context>`;
+
+  return {
+    systemMessage: visibleNotice,
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: hiddenContext
+    }
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Main entry point
+// ──────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Handle background fork modes
+  if (process.argv[2] === '--bg-copy-refs') {
+    try { copyPluginReferences(); } catch (_) {}
+    process.exit(0);
+  }
+
+  // Read stdin
+  await readStdinWithTimeout();
+
+  // Fork to copy plugin references in background (non-blocking)
+  const copyChild = fork(__filename, ['--bg-copy-refs'], {
+    detached: true,
+    stdio: 'ignore'
+  });
+  copyChild.unref();
+
+  // Get project directory from environment or cwd
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  // Get branch name
+  const branchName = getGitBranch();
+
+  // Find session logs directory
+  const sessionDir = path.join(projectDir, 'docs', 'tasks', branchName, 'session_logs');
+
+  // Find latest handoff
+  const latestHandoff = findLatestHandoff(sessionDir);
+
+  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 tips = [
+      '',
+      'Getting Started with SPECTRE:',
+      '',
+      '\u2699\ufe0f  Tip: Turn off auto-compact via /config \u2014 SPECTRE works best with manual context management',
+      '\ud83d\udcbe  Use /spectre:handoff when context is getting full but you\'re still going \u2014 saves state for the next session',
+      '\ud83e\uddf9  Use /spectre:forget to clear session memory and start fresh',
+      '\ud83d\ude80  Use /spectre:scope to start building features with the full SPECTRE workflow',
+      '\ud83c\udf93  Use /spectre:learn to create a documentation skill that your Agent will auto-load when relevant.'
+    ].join('\n');
+
+    const welcome = {
+      systemMessage: asciiBanner + '\n' + tips
+    };
+    process.stdout.write(JSON.stringify(welcome) + '\n');
+    process.exit(0);
+  }
+
+  // Read and parse handoff JSON
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(latestHandoff, 'utf8'));
+  } catch (_) {
+    process.exit(0);
+  }
+
+  // Compute relative path to handoff for user reference
+  let handoffRelative;
+  try {
+    handoffRelative = path.relative(projectDir, latestHandoff);
+  } catch (_) {
+    handoffRelative = latestHandoff;
+  }
+
+  // Format and output context
+  const output = formatContext(data, {
+    handoffPath: handoffRelative
+  });
+  process.stdout.write(JSON.stringify(output) + '\n');
+
+  process.exit(0);
+}
+
+// Export for testing
+if (typeof module !== 'undefined') {
+  module.exports = { copyPluginReferences, formatContext, buildCheckboxTree };
+}
+
+main();

package/plugins/spectre/hooks/scripts/lib.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lib.cjs
+ *
+ * Shared utilities for spectre hook scripts.
+ */
+
+const { execSync } = require('child_process');
+
+const STDIN_TIMEOUT = 2000; // milliseconds
+
+/**
+ * Read stdin with a timeout to avoid blocking indefinitely.
+ * @param {number} [timeout=2000] - Timeout in milliseconds
+ * @returns {Promise<string|null>} - stdin content or null on timeout
+ */
+function readStdinWithTimeout(timeout) {
+  timeout = timeout != null ? timeout : STDIN_TIMEOUT;
+
+  return new Promise((resolve) => {
+    // If stdin is a TTY (no piped data), resolve immediately
+    if (process.stdin.isTTY) {
+      resolve(null);
+      return;
+    }
+
+    let data = '';
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+        try { process.stdin.pause(); } catch (_) {}
+        resolve(data || null);
+      }
+    }, timeout);
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(data || null);
+      }
+    });
+    process.stdin.on('error', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(null);
+      }
+    });
+    process.stdin.resume();
+  });
+}
+
+/**
+ * Get current git branch name.
+ * @param {string} [cwd] - Working directory for git command
+ * @returns {string} Branch name or 'unknown'
+ */
+function getGitBranch(cwd) {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      timeout: 5000,
+      encoding: 'utf8',
+      cwd: cwd || undefined,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (_) {
+    return 'unknown';
+  }
+}
+
+module.exports = { readStdinWithTimeout, getGitBranch, STDIN_TIMEOUT };

package/plugins/spectre/hooks/scripts/load-knowledge.cjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * load-knowledge.cjs
+ *
+ * SessionStart hook that injects the apply skill content with embedded registry
+ * directly into Claude's context.
+ *
+ * Reads:
+ * - Apply skill from plugin: skills/spectre-apply/SKILL.md
+ * - Registry from project: .claude/skills/spectre-recall/references/registry.toon
+ *
+ * Combines them by replacing the Registry Location section with actual registry content.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+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 main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || '';
+
+  const applySkillPath = path.join(pluginRoot, 'skills', 'spectre-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(projectDir, '.claude', 'skills', '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);
+
+  // Replace the Registry Location section with embedded registry or empty notice
+  let registrySection;
+  if (entryCount > 0) {
+    registrySection =
+      '## Registry\n\n' +
+      '**Format**: `skill-name|category|triggers|description`\n\n' +
+      '```\n' +
+      registryContent + '\n' +
+      '```\n\n' +
+      'Each entry corresponds to a skill that can be loaded via `Skill({skill-name})`\n\n' +
+      '**Categories:** feature, gotchas, patterns, decisions, procedures, integration, performance, testing, ux, strategy';
+  } else {
+    registrySection =
+      '## Registry\n\n' +
+      'No knowledge has been captured for this project yet. The behavioral rules in this document still apply.\n\n' +
+      'To capture knowledge from this session, use `/spectre:learn` after completing significant work.\n\n' +
+      '**Categories:** feature, gotchas, patterns, decisions, procedures, integration, performance, testing, ux, strategy';
+  }
+
+  // Replace the Registry Location section
+  applyContent = applyContent.replace(
+    /## Registry Location[\s\S]*?(?=## Workflow)/,
+    registrySection + '\n\n'
+  );
+
+  // Build final context
+  const context = `<spectre-knowledge>\n${applyContent}\n</spectre-knowledge>`;
+
+  // 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',
+      additionalContext: context
+    }
+  };
+
+  process.stdout.write(JSON.stringify(output) + '\n');
+  process.exit(0);
+}
+
+main();

package/plugins/spectre/hooks/scripts/precompact-warning.cjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * precompact-warning.cjs
+ *
+ * PreCompact hook that suggests using /spectre:handoff + /clear
+ * instead of auto-compact for better context continuity.
+ */
+
+const output = {
+  systemMessage:
+    '\u26a0\ufe0f Auto-compact can cause context loss. ' +
+    'For full continuity: /spectre:handoff \u2192 /clear \u2192 new session. ' +
+    'Consider disabling auto-compact in /config.'
+};
+
+process.stdout.write(JSON.stringify(output) + '\n');
+process.exit(0);