@codename_inc/spectre 3.7.0 → 5.0.0

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.

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

@@ -0,0 +1,129 @@
+---
+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
+- **What** — Principal systems architect review focusing on compounding decisions: architectural debt, missed abstractions, performance cliffs, unnecessary complexity
+- **Outcome** — Architecture review report with actionable findings organized by severity and type
+
+## Variables
+
+### Dynamic Variables
+- `feature_description`: Feature being reviewed — (via ARGUMENTS). If
+- `paths_or_files`: Relevant paths to examine — (via ARGUMENTS)
+- `arch_notes_or_docs`: Existing architecture context — (via ARGUMENTS, optional)
+
+### ARGUMENTS Input
+
+<ARGUMENTS>
+$ARGUMENTS
+</ARGUMENTS>
+
+## Instructions
+
+**Review Philosophy** (cross-cutting guidelines):
+- **Compounding matters**: Focus on what gets harder to change later, not what's easy to fix now
+- **Simplicity is a feature**: The best code is often less code, fewer abstractions, fewer moving parts
+- **Context is king**: A "bad" pattern in isolation might be the right choice given project constraints
+- **Be specific**: Vague feedback like "could be more modular" is useless. Point to exact files, functions, and concrete alternatives
+
+**Constraints**:
+- Don't suggest changes that would take longer to implement than the feature itself unless they're critical
+- Don't recommend adding abstractions "for future flexibility" unless there's concrete evidence we'll need them
+- If you don't have concerns in a section, say "No concerns" and move on—don't manufacture feedback
+- Be direct. "This is fine" is a valid assessment.
+
+**Adapt**
+- If ARGUMENTS is empty, gather the review scope from the current thread context.
+- If the current thread context is also ambigious, ask the user to clarify the scope of the review.
+
+## Step (1/3) - Review Existing Architecture Documents
+- **Action** - ReviewArchitecture: Find and review existing architecture documents
+  - search for docs/architecture.md and read it if it exists
+  - if not, continue and use general architectural best practices during review
+
+## Step (1/2) - Explore Implementation
+
+- **Action** — ExploreCode: Thoroughly examine the implementation
+  - Read the code at `paths_or_files`
+  - Understand the data flow
+  - Trace the dependencies
+  - Review `arch_notes_or_docs` if provided
+  - **If**: Paths unclear or missing
+  - **Then**: Ask for clarification before proceeding
+  - **Else**: Continue to review
+
+## Step (2/2) - Produce Review Report
+
+- **Action** — GenerateReview: Create structured architecture review using Report format below
+  - Apply Review Philosophy guidelines throughout
+  - Apply Constraints (no manufactured feedback, proportionate suggestions)
+  - **If**: No concerns in a section
+  - **Then**: State "No concerns" and move on
+  - **Else**: Provide specific, actionable feedback
+
+## Report
+
+**Output Format** — Architecture review with these sections:
+
+### Executive Summary
+2-3 sentences: What's the architectural story here? Is this feature setting us up well or creating future pain?
+
+### Critical Issues (address before moving on)
+Issues that will cause significant pain if left unaddressed—architectural violations, major performance problems, or patterns that will spread.
+
+For each issue:
+- **What**: The specific problem
+- **Where**: Exact file(s) and line(s)
+- **Why it matters**: The compounding cost over time
+- **Suggested fix**: Concrete, implementable alternative
+
+### Simplification Opportunities
+Places where we're overengineering, where a simpler approach would work, or where we've introduced abstractions we don't yet need.
+
+### Architecture Alignment
+- Does this follow existing project patterns, or introduce new ones?
+- If new patterns: Are they intentional improvements or accidental divergence?
+- Are there existing utilities/patterns in the codebase this should have used?
+
+### Future-Proofing Considerations
+- What assumptions is this code making that might not hold?
+- If this feature grows 10x in usage/complexity, what breaks first?
+- Are there integration points that need better contracts/interfaces?
+
+### Performance Notes
+Only mention performance if there's a clear problem or a clear win—don't speculate about micro-optimizations.
+
+### What's Done Well
+Briefly note architectural choices worth preserving or patterns worth spreading to other parts of the codebase.
+
+## Success Criteria
+
+**Step 1 - Explore Implementation**:
+- [ ] All specified paths/files read and understood
+- [ ] Data flow traced through implementation
+- [ ] Dependencies identified and examined
+- [ ] Architecture context reviewed if provided
+
+**Step 2 - Produce Review Report**:
+- [ ] Executive Summary provides clear architectural assessment (2-3 sentences)
+- [ ] Critical Issues include What/Where/Why/Suggested fix for each
+- [ ] Simplification Opportunities identify overengineering (or "No concerns")
+- [ ] Architecture Alignment addresses pattern consistency
+- [ ] Future-Proofing identifies assumptions and scaling concerns
+- [ ] Performance Notes only included if clear problem/win exists
+- [ ] What's Done Well acknowledges good patterns
+- [ ] All feedback is specific with exact files/lines
+- [ ] No manufactured feedback—"No concerns" used when appropriate
+- [ ] Suggestions proportionate to feature scope