@codename_inc/spectre 3.7.0 → 5.0.0

package/README.md

@@ -35,7 +35,7 @@ That's it. You just start with 1 command to build features.
 ### Within Codex
 
 ```bash
-npx spectre install codex
+npx @codename_inc/spectre install codex
 ```
 
 When prompted, choose `project` to install into the current repo's `.codex`, or `user` to install into `~/.codex`.
@@ -47,7 +47,7 @@ If you choose `user`, restart or open your normal Codex session.
 Then run a Spectre command such as:
 
 ```plaintext
-spectre-scope
+scope
 ```
 
 Current Codex behavior:
@@ -65,7 +65,7 @@ Session continuity deep dive: [`docs/codex-sessionstart-memory.md`](./docs/codex
 
 ## 🔁 How It Works
 
-- run one of the kickoff prompts in Claude Code - `/spectre:scope` is the main command for building new features, but also `/spectre:kickoff` for high ambiguity new features (includes web research), `/spectre:research` for codebase research "how might we build …” style Qs, or `/spectre:ux_spec` to define user flows, components, and layout for a new feature.
+- run one of the kickoff prompts in Claude Code - `/spectre:scope` is the main command for building new features, but also `/spectre:kickoff` for high ambiguity new features (includes web research), `/spectre:research` for codebase research "how might we build …” style Qs, or `/spectre:ux` to define user flows, components, and layout for a new feature.
 
 - follow the prompts/instructions to create the related canonical document and Claude Code will suggest the next step in the SPECTRE workflow automatically (e.g., going from `scope` to `plan` to `tasks` and so on)
 
@@ -281,7 +281,7 @@ Although I do sometimes use @spectre:web-research for web research. It's like mi
 
 - start /spectre:scope to get crisp on what's in/out. this is non-negotiable unless the feature is a one line ask.
 
-  - if the feature's ux/user flow is unclear to me, or I want to make sure to really nail it, i run /spectre:ux_spec. Its similar to /spectre:scope but focuses on getting clear on the core user flows.
+  - if the feature's ux/user flow is unclear to me, or I want to make sure to really nail it, i run /spectre:ux. Its similar to /spectre:scope but focuses on getting clear on the core user flows.
 
 - /spectre:plan to build out a well researched technical design or set of tasks
 
@@ -367,7 +367,7 @@ I use /spectre:fix for pretty much all bugs I run into.
 | --- | --- |
 | `/spectre:sweep` | Light cleanup pass — lint, test, descriptive commits |
 | `/spectre:learn` | Capture knowledge for future sessions |
-| `/spectre:ux_spec` | UX specification for UI-heavy features |
+| `/spectre:ux` | UX specification for UI-heavy features |
 | `/spectre:fix` | Investigate bugs & implement fixes |
 
 ## 📁 Repository Structure
@@ -380,10 +380,9 @@ spectre/
 │   └── spectre/
 │       ├── .claude-plugin/
 │       │   └── plugin.json   # Plugin manifest
-│       ├── commands/         # Slash commands
 │       ├── agents/           # Subagent definitions
 │       ├── hooks/            # Session memory hooks
-│       └── skills/           # Skills
+│       └── skills/           # Slash workflows + knowledge skills
 ├── scripts/              # Release & utility scripts
 └── CLAUDE.md
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codename_inc/spectre",
-  "version": "3.7.0",
+  "version": "5.0.0",
   "type": "module",
   "bin": {
     "spectre": "./bin/spectre.js"
@@ -13,7 +13,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test src/**/*.test.js plugins/spectre/hooks/scripts/test_*.cjs",
+    "test": "node --test src/**/*.test.js plugins/spectre/hooks/scripts/test_*.mjs scripts/test_sync-codex.cjs",
+    "sync-codex": "node scripts/sync-codex.cjs",
     "tokens": "node scripts/count-tokens.js",
     "release": "node scripts/release.js"
   },

package/plugins/spectre/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "spectre",
-  "version": "3.7.0",
+  "version": "5.0.0",
   "description": "Agentic coding workflow with session memory. spectre guides you through Scope, Plan, Execute, Clean, Test, Rebase, and Extract phases."
 }

package/plugins/spectre/bin/spectre-register

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Thin wrapper so skills can call `spectre-register` from Bash.
+# Delegates to the hook registration runtime.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "$SCRIPT_DIR/../hooks/scripts/register_learning.mjs" "$@"

package/plugins/spectre/hooks/hooks.json

@@ -1,31 +1,20 @@
 {
   "hooks": {
-    "PreCompact": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/precompact-warning.cjs"
-          }
-        ]
-      }
-    ],
     "SessionStart": [
       {
         "matcher": "startup|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/bootstrap.cjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/bootstrap.mjs"
           },
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/handoff-resume.cjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/handoff-resume.mjs"
           },
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/load-knowledge.cjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/load-knowledge.mjs"
           }
         ]
       }

package/plugins/spectre/hooks/scripts/bootstrap.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * bootstrap.mjs
+ *
+ * SessionStart hook that removes stale files from older plugin versions.
+ *
+ * When users update the plugin via marketplace, old files that were deleted
+ * from the repo may still linger in their cached copy. This script runs on
+ * every session start and cleans them up.
+ *
+ * To add new files to the cleanup list, append to STALE_PATHS below.
+ * Paths are relative to CLAUDE_PLUGIN_ROOT.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readStdinWithTimeout } from './lib.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ──────────────────────────────────────────────────────────────────
+// Stale paths to remove (relative to CLAUDE_PLUGIN_ROOT)
+// ──────────────────────────────────────────────────────────────────
+
+const STALE_PATHS = [
+  // Python scripts replaced by JS hook equivalents (v3.x migration)
+  'hooks/scripts/capture-todos.py',
+  'hooks/scripts/handoff-resume.py',
+  'hooks/scripts/load-knowledge.py',
+  'hooks/scripts/precompact-warning.py',
+  'hooks/scripts/precompact-warning.mjs',
+  'hooks/scripts/register_learning.py',
+  'hooks/scripts/test_handoff_resume.py',
+  'hooks/scripts/test_load_knowledge.py',
+
+  // Old skill directory replaced by spectre-guide
+  'skills/spectre-next-steps',
+];
+
+// ──────────────────────────────────────────────────────────────────
+// Cleanup logic
+// ──────────────────────────────────────────────────────────────────
+
+function cleanupStalePaths(pluginRoot) {
+  let removed = 0;
+
+  for (const relPath of STALE_PATHS) {
+    const fullPath = path.join(pluginRoot, relPath);
+
+    try {
+      const stat = fs.statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        fs.rmSync(fullPath, { recursive: true, force: true });
+        removed++;
+      } else {
+        fs.unlinkSync(fullPath);
+        removed++;
+      }
+    } catch (_) {
+      // File doesn't exist or can't be removed — skip silently
+    }
+  }
+
+  return removed;
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Main
+// ──────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Drain stdin so the hook system doesn't hang
+  await readStdinWithTimeout();
+
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..', '..');
+
+  const removed = cleanupStalePaths(pluginRoot);
+
+  if (removed > 0) {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `bootstrap: cleaned ${removed} stale file${removed > 1 ? 's' : ''} from previous plugin version`
+    }) + '\n');
+  } else {
+    process.stdout.write(JSON.stringify({}) + '\n');
+  }
+
+  process.exit(0);
+}
+
+export { cleanupStalePaths, STALE_PATHS };
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}

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

@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+
+/**
+ * handoff-resume.mjs
+ *
+ * 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)
+ */
+
+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 = getPluginRoot();
+  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 noticeLines = ['\ud83d\udc7b SPECTRE'];
+  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 banner = '\ud83d\udc7b SPECTRE';
+    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: banner + '\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 { copyPluginReferences, formatContext, buildCheckboxTree };
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}