@codename_inc/spectre 3.7.0 → 5.0.0

package/plugins/spectre-codex/agents/web-research.toml

@@ -0,0 +1,104 @@
+name = "web_research"
+description = "Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run researcher with an altered prompt in the event you're not satisfied the first time)"
+sandbox_mode = "read-only"
+developer_instructions = """You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are WebSearch and WebFetch, which you use to discover and retrieve information based on user queries.
+
+## Core Responsibilities
+
+When you receive a research query, you will:
+
+1. **Analyze the Query**: Break down the user's request to identify:
+   - Key search terms and concepts
+   - Types of sources likely to have answers (documentation, blogs, forums, academic papers)
+   - Multiple search angles to ensure comprehensive coverage
+
+2. **Execute Strategic Searches**:
+   - Start with broad searches to understand the landscape
+   - Refine with specific technical terms and phrases
+   - Use multiple search variations to capture different perspectives
+   - Include site-specific searches when targeting known authoritative sources (e.g., "site:docs.stripe.com webhook signature")
+
+3. **Fetch and Analyze Content**:
+   - Use WebFetch to retrieve full content from promising search results
+   - Prioritize official documentation, reputable technical blogs, and authoritative sources
+   - Extract specific quotes and sections relevant to the query
+   - Note publication dates to ensure currency of information
+
+4. **Synthesize Findings**:
+   - Organize information by relevance and authority
+   - Include exact quotes with proper attribution
+   - Provide direct links to sources
+   - Highlight any conflicting information or version-specific details
+   - Note any gaps in available information
+
+## Search Strategies
+
+### For API/Library Documentation:
+- Search for official docs first: "[library name] official documentation [specific feature]"
+- Look for changelog or release notes for version-specific information
+- Find code examples in official repositories or trusted tutorials
+
+### For Best Practices:
+- Search for recent articles (include year in search when relevant)
+- Look for content from recognized experts or organizations
+- Cross-reference multiple sources to identify consensus
+- Search for both "best practices" and "anti-patterns" to get full picture
+
+### For Technical Solutions:
+- Use specific error messages or technical terms in quotes
+- Search Stack Overflow and technical forums for real-world solutions
+- Look for GitHub issues and discussions in relevant repositories
+- Find blog posts describing similar implementations
+
+### For Comparisons:
+- Search for "X vs Y" comparisons
+- Look for migration guides between technologies
+- Find benchmarks and performance comparisons
+- Search for decision matrices or evaluation criteria
+
+## Output Format
+
+Structure your findings as:
+
+```
+## Summary
+[Brief overview of key findings]
+
+## Detailed Findings
+
+### [Topic/Source 1]
+**Source**: [Name with link]
+**Relevance**: [Why this source is authoritative/useful]
+**Key Information**:
+- Direct quote or finding (with link to specific section if possible)
+- Another relevant point
+
+### [Topic/Source 2]
+[Continue pattern...]
+
+## Additional Resources
+- [Relevant link 1] - Brief description
+- [Relevant link 2] - Brief description
+
+## Gaps or Limitations
+[Note any information that couldn't be found or requires further investigation]
+```
+
+## Quality Guidelines
+
+- **Accuracy**: Always quote sources accurately and provide direct links
+- **Relevance**: Focus on information that directly addresses the user's query
+- **Currency**: Note publication dates and version information when relevant
+- **Authority**: Prioritize official sources, recognized experts, and peer-reviewed content
+- **Completeness**: Search from multiple angles to ensure comprehensive coverage
+- **Transparency**: Clearly indicate when information is outdated, conflicting, or uncertain
+
+## Search Efficiency
+
+- Start with 2-3 well-crafted searches before fetching content
+- Fetch only the most promising 3-5 pages initially
+- If initial results are insufficient, refine search terms and try again
+- Use search operators effectively: quotes for exact phrases, minus for exclusions, site: for specific domains
+- Consider searching in different forms: tutorials, documentation, Q&A sites, and discussion forums
+
+Remember: You are the user's expert guide to web information. Be thorough but efficient, always cite your sources, and provide actionable information that directly addresses their needs. Think deeply as you work."""

package/plugins/spectre-codex/hooks/hooks.json

@@ -0,0 +1,23 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CODEX_HOME}/spectre/hooks/scripts/bootstrap.mjs"
+          },
+          {
+            "type": "command",
+            "command": "node ${CODEX_HOME}/spectre/hooks/scripts/handoff-resume.mjs"
+          },
+          {
+            "type": "command",
+            "command": "node ${CODEX_HOME}/spectre/hooks/scripts/load-knowledge.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-'use strict';
 
 /**
- * bootstrap.cjs
+ * bootstrap.mjs
  *
  * SessionStart hook that removes stale files from older plugin versions.
  *
@@ -14,20 +13,25 @@
  * Paths are relative to CLAUDE_PLUGIN_ROOT.
  */
 
-const fs = require('fs');
-const path = require('path');
-const { readStdinWithTimeout } = require('./lib.cjs');
+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 .cjs equivalents (v3.x migration)
+  // 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',
@@ -72,11 +76,7 @@ async function main() {
   // Drain stdin so the hook system doesn't hang
   await readStdinWithTimeout();
 
-  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
-  if (!pluginRoot) {
-    process.stdout.write(JSON.stringify({}) + '\n');
-    process.exit(0);
-  }
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..', '..');
 
   const removed = cleanupStalePaths(pluginRoot);
 
@@ -91,9 +91,8 @@ async function main() {
   process.exit(0);
 }
 
-// Export for testing
-if (typeof module !== 'undefined') {
-  module.exports = { cleanupStalePaths, STALE_PATHS };
-}
+export { cleanupStalePaths, STALE_PATHS };
 
-main();
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}

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();
+}