locus-product-planning 1.0.0 → 1.2.0

package/dist/lib/skills-core.js

@@ -0,0 +1,361 @@
+/**
+ * Skills Core Library
+ * Shared utilities for skill discovery, loading, and management
+ */
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+/**
+ * Extract YAML frontmatter from a skill or agent file.
+ *
+ * Supports:
+ * - Simple key: value pairs
+ * - Multiline values with |
+ * - Nested objects (one level deep, e.g., metadata:)
+ *
+ * Format:
+ * ---
+ * name: skill-name
+ * description: Use when [condition] - [what it does]
+ * metadata:
+ *   version: "1.0.0"
+ *   tier: developer
+ * ---
+ */
+export function extractFrontmatter(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        // Normalize line endings (handle Windows \r\n)
+        const lines = content.replace(/\r\n/g, '\n').split('\n');
+        let inFrontmatter = false;
+        const metadata = { name: '', description: '' };
+        let currentKey = '';
+        let multilineValue = '';
+        let inNestedObject = false;
+        let nestedKey = '';
+        const nestedObject = {};
+        for (const line of lines) {
+            const trimmedLine = line.trim();
+            if (trimmedLine === '---') {
+                if (inFrontmatter)
+                    break;
+                inFrontmatter = true;
+                continue;
+            }
+            if (inFrontmatter) {
+                // Check for nested object entry (starts with 2 spaces)
+                if (inNestedObject && line.match(/^ {2}\w+:/)) {
+                    const nestedMatch = line.match(/^ {2}(\w+):\s*(.*)$/);
+                    if (nestedMatch) {
+                        const [, key, value] = nestedMatch;
+                        nestedObject[key] = value.trim().replace(/^["']|["']$/g, ''); // Strip quotes
+                    }
+                    continue;
+                }
+                // Check for top-level key
+                const match = line.match(/^(\w+):\s*(.*)$/);
+                if (match) {
+                    // Save previous nested object if any
+                    if (inNestedObject && nestedKey) {
+                        metadata[nestedKey] = { ...nestedObject };
+                        // Also flatten common nested fields to top level for convenience
+                        if (nestedKey === 'metadata') {
+                            for (const [k, v] of Object.entries(nestedObject)) {
+                                if (v && !metadata[k]) {
+                                    metadata[k] = v;
+                                }
+                            }
+                        }
+                        inNestedObject = false;
+                        nestedKey = '';
+                        // Clear nested object for next use
+                        for (const k of Object.keys(nestedObject)) {
+                            delete nestedObject[k];
+                        }
+                    }
+                    // Save previous multiline value if any
+                    if (currentKey && multilineValue) {
+                        metadata[currentKey] = multilineValue.trim();
+                    }
+                    const [, key, value] = match;
+                    currentKey = key;
+                    // Handle nested object (value is empty, next lines are indented)
+                    if (value.trim() === '') {
+                        inNestedObject = true;
+                        nestedKey = key;
+                        currentKey = '';
+                        multilineValue = '';
+                    }
+                    // Handle multiline values starting with |
+                    else if (value.trim() === '|') {
+                        multilineValue = '';
+                    }
+                    else {
+                        metadata[key] = value.trim();
+                        currentKey = '';
+                        multilineValue = '';
+                    }
+                }
+                else if (currentKey && line.startsWith('  ')) {
+                    // Continuation of multiline value
+                    multilineValue += line.trim() + ' ';
+                }
+            }
+        }
+        // Save final nested object
+        if (inNestedObject && nestedKey) {
+            metadata[nestedKey] = { ...nestedObject };
+            if (nestedKey === 'metadata') {
+                for (const [k, v] of Object.entries(nestedObject)) {
+                    if (v && !metadata[k]) {
+                        metadata[k] = v;
+                    }
+                }
+            }
+        }
+        // Save final multiline value
+        if (currentKey && multilineValue) {
+            metadata[currentKey] = multilineValue.trim();
+        }
+        return metadata;
+    }
+    catch {
+        return { name: '', description: '' };
+    }
+}
+/**
+ * Strip YAML frontmatter from content, returning just the body.
+ */
+export function stripFrontmatter(content) {
+    const lines = content.split('\n');
+    let inFrontmatter = false;
+    let frontmatterEnded = false;
+    const contentLines = [];
+    for (const line of lines) {
+        if (line.trim() === '---') {
+            if (inFrontmatter) {
+                frontmatterEnded = true;
+                continue;
+            }
+            inFrontmatter = true;
+            continue;
+        }
+        if (frontmatterEnded || !inFrontmatter) {
+            contentLines.push(line);
+        }
+    }
+    return contentLines.join('\n').trim();
+}
+/**
+ * Find all SKILL.md files in a directory recursively.
+ */
+export function findSkillsInDir(dir, sourceType, maxDepth = 4) {
+    const skills = [];
+    if (!existsSync(dir))
+        return skills;
+    function recurse(currentDir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const fullPath = join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                // Check for SKILL.md in this directory
+                const skillFile = join(fullPath, 'SKILL.md');
+                if (existsSync(skillFile)) {
+                    const meta = extractFrontmatter(skillFile);
+                    skills.push({
+                        path: fullPath,
+                        skillFile,
+                        name: meta.name || entry.name,
+                        description: meta.description || '',
+                        sourceType,
+                        tier: typeof meta.tier === 'string' ? meta.tier : undefined,
+                        category: typeof meta.category === 'string' ? meta.category : undefined,
+                        council: typeof meta.council === 'string' ? meta.council : undefined,
+                        version: typeof meta.version === 'string' ? meta.version : undefined,
+                    });
+                }
+                // Recurse into subdirectories
+                recurse(fullPath, depth + 1);
+            }
+        }
+    }
+    recurse(dir, 0);
+    return skills;
+}
+/**
+ * Find all agent definition files in a directory.
+ */
+export function findAgentsInDir(dir, maxDepth = 3) {
+    const agents = [];
+    if (!existsSync(dir))
+        return agents;
+    function recurse(currentDir, depth, category) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const fullPath = join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                // Use directory name as category
+                recurse(fullPath, depth + 1, entry.name);
+            }
+            else if (entry.name.endsWith('.md')) {
+                const { name, description } = extractFrontmatter(fullPath);
+                const agentName = name || basename(entry.name, '.md');
+                agents.push({
+                    path: fullPath,
+                    name: agentName,
+                    description: description || '',
+                    category: category || 'general',
+                });
+            }
+        }
+    }
+    recurse(dir, 0, '');
+    return agents;
+}
+/**
+ * Resolve a skill name to its file path, handling namespacing and shadowing.
+ * Priority: project > personal > locus
+ *
+ * Skill names can be:
+ * - "skill-name" - searches all locations
+ * - "project:skill-name" - forces project skills only
+ * - "locus:skill-name" - forces locus skills only
+ */
+export function resolveSkillPath(skillName, locusSkillsDir, personalSkillsDir, projectSkillsDir) {
+    // Parse namespace prefix
+    const forceProject = skillName.startsWith('project:');
+    const forceLocus = skillName.startsWith('locus:');
+    const actualSkillName = skillName
+        .replace(/^project:/, '')
+        .replace(/^locus:/, '');
+    // Try project skills first (unless forcing locus)
+    if (!forceLocus && projectSkillsDir) {
+        const resolved = findSkillByName(projectSkillsDir, actualSkillName, 'project');
+        if (resolved)
+            return resolved;
+    }
+    // If forcing project and not found, return null
+    if (forceProject)
+        return null;
+    // Try personal skills (unless forcing locus)
+    if (!forceLocus && personalSkillsDir) {
+        const resolved = findSkillByName(personalSkillsDir, actualSkillName, 'personal');
+        if (resolved)
+            return resolved;
+    }
+    // Try locus skills
+    const resolved = findSkillByName(locusSkillsDir, actualSkillName, 'locus');
+    if (resolved)
+        return resolved;
+    return null;
+}
+/**
+ * Find a skill by name in a directory (searches recursively).
+ */
+function findSkillByName(baseDir, skillName, sourceType) {
+    if (!existsSync(baseDir))
+        return null;
+    // Direct path check
+    const directPath = join(baseDir, skillName);
+    const directSkillFile = join(directPath, 'SKILL.md');
+    if (existsSync(directSkillFile)) {
+        return {
+            skillFile: directSkillFile,
+            sourceType,
+            skillPath: skillName,
+        };
+    }
+    // Search in subdirectories (for categorized skills like 01-executive-suite/ceo-strategist)
+    const skills = findSkillsInDir(baseDir, sourceType);
+    for (const skill of skills) {
+        if (skill.name === skillName || basename(skill.path) === skillName) {
+            return {
+                skillFile: skill.skillFile,
+                sourceType,
+                skillPath: skill.path.replace(baseDir + '/', '').replace(baseDir + '\\', ''),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Get the using-locus bootstrap skill content.
+ */
+export function getBootstrapContent(locusSkillsDir, compact = false) {
+    // Try to find the main locus skill
+    const usingLocusPath = join(locusSkillsDir, 'using-locus', 'SKILL.md');
+    const legacyLocusPath = join(locusSkillsDir, 'locus', 'SKILL.md');
+    let skillFile = null;
+    if (existsSync(usingLocusPath)) {
+        skillFile = usingLocusPath;
+    }
+    else if (existsSync(legacyLocusPath)) {
+        skillFile = legacyLocusPath;
+    }
+    if (!skillFile)
+        return null;
+    const fullContent = readFileSync(skillFile, 'utf-8');
+    const content = stripFrontmatter(fullContent);
+    const toolMapping = compact
+        ? `**Tool Mapping:** TodoWrite->update_plan, Task->@mention, Skill->use_skill
+
+**Skills naming (priority order):** project: > personal: > locus:`
+        : `**Tool Mapping for OpenCode:**
+When skills reference tools you don't have, substitute OpenCode equivalents:
+- \`TodoWrite\` -> \`update_plan\`
+- \`Task\` tool with subagents -> Use OpenCode's subagent system (@mention)
+- \`Skill\` tool -> \`use_skill\` custom tool
+- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` -> Your native tools
+
+**Skills naming (priority order):**
+- Project skills: \`project:skill-name\` (in .opencode/skills/ or project skills dir)
+- Personal skills: \`skill-name\` (in ~/.config/opencode/skills/)
+- Locus skills: \`locus:skill-name\`
+- Project skills override personal, which override locus when names match`;
+    return `<EXTREMELY_IMPORTANT>
+You have access to Locus skills.
+
+**IMPORTANT: The using-locus skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the use_skill tool to load "using-locus" - that would be redundant. Use use_skill only for OTHER skills.**
+
+${content}
+
+${toolMapping}
+</EXTREMELY_IMPORTANT>`;
+}
+/**
+ * Normalize a path: trim whitespace, expand ~, resolve to absolute.
+ */
+export function normalizePath(p, homeDir) {
+    if (!p || typeof p !== 'string')
+        return null;
+    let normalized = p.trim();
+    if (!normalized)
+        return null;
+    // Expand ~ to home directory
+    if (normalized.startsWith('~/')) {
+        normalized = join(homeDir, normalized.slice(2));
+    }
+    else if (normalized === '~') {
+        normalized = homeDir;
+    }
+    return normalized;
+}

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run-hook.cmd

@@ -0,0 +1,32 @@
+@echo off
+REM Windows wrapper for running bash hooks
+REM Tries: Git Bash > WSL > native cmd fallback
+
+setlocal enabledelayedexpansion
+
+set "HOOK_NAME=%~1"
+set "SCRIPT_DIR=%~dp0"
+set "HOOK_PATH=%SCRIPT_DIR%%HOOK_NAME%"
+
+REM Try Git Bash first (most common on Windows dev machines)
+where bash >nul 2>&1
+if %ERRORLEVEL% EQU 0 (
+    bash "%HOOK_PATH%"
+    exit /b %ERRORLEVEL%
+)
+
+REM Try WSL
+where wsl >nul 2>&1
+if %ERRORLEVEL% EQU 0 (
+    wsl bash "%HOOK_PATH%"
+    exit /b %ERRORLEVEL%
+)
+
+REM Fallback to native Windows implementation
+if "%HOOK_NAME%"=="session-start.sh" (
+    call "%SCRIPT_DIR%session-start.cmd"
+    exit /b %ERRORLEVEL%
+)
+
+REM Unknown hook, output minimal JSON
+echo {"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"Locus skills available. Read skills/using-locus/SKILL.md to get started."}}

package/hooks/session-start.cmd

@@ -0,0 +1,13 @@
+@echo off
+REM Locus Bootstrap Hook for Claude Code (Windows native fallback)
+REM Outputs JSON context for session injection
+
+setlocal enabledelayedexpansion
+
+set "SCRIPT_DIR=%~dp0"
+set "PLUGIN_ROOT=%SCRIPT_DIR%.."
+set "SKILL_FILE=%PLUGIN_ROOT%\skills\using-locus\SKILL.md"
+
+REM Output the bootstrap JSON
+REM Note: This is a simplified version since Windows cmd has limited string handling
+echo {"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"<EXTREMELY_IMPORTANT>\nYou have access to Locus skills for AI-powered project planning.\n\n**How to Use Skills:**\nRead the SKILL.md file to load a skill. Start with:\n- Read skills/using-locus/SKILL.md - Main planning workflow (Vision -> Features -> Design -> Build)\n\n**Available Skill Categories:**\n- skills/01-executive-suite/ - CEO, CTO, CPO, CFO, COO perspectives\n- skills/02-product-management/ - Product manager, project manager, scrum master\n- skills/03-engineering-leadership/ - Tech lead, staff engineer, principal engineer\n- skills/04-developer-specializations/ - Frontend, backend, devops, data, AI specialists\n- skills/05-specialists/ - Compliance and other specialists\n\n**The Rule:** If there's even a 1%% chance a skill might apply, load it and check.\n\n**Quick Start:** Say 'I want to build...' or use /locus command.\n</EXTREMELY_IMPORTANT>"}}

package/hooks/session-start.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Locus Bootstrap Hook for Claude Code
+# Outputs JSON context for session injection
+
+set -e
+
+# Get the directory where this script lives
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Read the using-locus skill content
+SKILL_FILE="$PLUGIN_ROOT/skills/using-locus/SKILL.md"
+
+if [ ! -f "$SKILL_FILE" ]; then
+  # Fallback: output minimal context
+  cat <<'EOF'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have access to Locus skills for project planning.\n\nTo use a skill, read its SKILL.md file. Start with:\n- skills/using-locus/SKILL.md - Main planning workflow\n\nSkills are in: skills/01-executive-suite/, skills/02-product-management/, etc.\n</EXTREMELY_IMPORTANT>"
+  }
+}
+EOF
+  exit 0
+fi
+
+# Read and escape skill content for JSON
+SKILL_CONTENT=$(cat "$SKILL_FILE" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g' | sed 's/\t/\\t/g')
+
+# Build the bootstrap context
+BOOTSTRAP="<EXTREMELY_IMPORTANT>
+You have access to Locus skills.
+
+**IMPORTANT: The using-locus skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the Skill tool to load \\\"using-locus\\\" - that would be redundant. Use Skill tool only for OTHER skills.**
+
+--- SKILL CONTENT START ---
+$SKILL_CONTENT
+--- SKILL CONTENT END ---
+
+**Tool Mapping for Claude Code:**
+When skills reference tools you don't have, substitute Claude Code equivalents:
+- \\\`TodoWrite\\\` -> Use the built-in todo/task tracking
+- \\\`Task\\\` tool with subagents -> Use Claude's task delegation
+- \\\`Skill\\\` tool -> Read the skill file directly with Read tool
+- \\\`Read\\\`, \\\`Write\\\`, \\\`Edit\\\`, \\\`Bash\\\` -> Your native tools
+
+**Skills Location:**
+Skills are in the plugin directory under skills/:
+- skills/using-locus/ - Main planning skill
+- skills/01-executive-suite/ - Executive perspectives
+- skills/02-product-management/ - Product skills
+- skills/03-engineering-leadership/ - Tech leadership
+- skills/04-developer-specializations/ - Developer skills
+- skills/05-specialists/ - Specialist skills
+
+To load a skill: Read the SKILL.md file in that directory.
+</EXTREMELY_IMPORTANT>"
+
+# Escape the bootstrap for JSON
+ESCAPED_BOOTSTRAP=$(echo "$BOOTSTRAP" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
+
+# Output the JSON
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "$ESCAPED_BOOTSTRAP"
+  }
+}
+EOF

package/opencode.json

@@ -2,16 +2,20 @@
   "$schema": "https://opencode.ai/config.json",
   "command": {
     "locus": {
-      "template": "Load the 'locus' skill and help the user plan their project.\n\nIf they provided a project idea: $ARGUMENTS\nStart with Step 1: Vision.\n\nIf no idea provided, ask what they want to build.",
+      "template": "Use the use_skill tool to load 'locus:using-locus' and help the user plan their project.\n\nIf they provided a project idea: $ARGUMENTS\nStart with Step 1: Vision.\n\nIf no idea provided, ask what they want to build.",
       "description": "Start or resume a project (Vision → Features → Design → Build)"
     },
-    "locus-status": {
-      "template": "Show the current Locus project status.\n\nLook in projects/ for the most recent project.\nRead .locus-state.yaml and display progress visually.\nKeep it simple - no file paths or technical jargon.",
-      "description": "Show current project progress"
+    "locus-skills": {
+      "template": "Use the find_skills tool to list all available skills.\n\nIf the user specified a filter: $ARGUMENTS\nApply it as a category, tier, or search filter.\n\nShow the results in a clean, organized format.",
+      "description": "List available skills (optionally filter by category/tier/search)"
     },
-    "locus-list": {
-      "template": "List all Locus projects in the projects/ directory.\n\nFor each, show: name, current step, last updated.\nDisplay as a clean list. If none exist, suggest starting one with /locus.",
-      "description": "List all projects"
+    "locus-skill": {
+      "template": "Use the use_skill tool to load the requested skill: $ARGUMENTS\n\nIf no skill name provided, use find_skills to show available options.",
+      "description": "Load a specific skill by name"
+    },
+    "locus-agents": {
+      "template": "Use the find_agents tool to list all available agent definitions.\n\nShow them grouped by category with descriptions.",
+      "description": "List available agents"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locus-product-planning",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "AI-powered product planning for OpenCode - Vision → Features → Design → Build",
   "type": "module",
   "main": "dist/index.js",
@@ -10,11 +10,15 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./skill": "./.opencode/skills/locus/SKILL.md"
+    "./skills": "./skills",
+    "./skills/*": "./skills/*"
   },
   "files": [
     "dist",
-    ".opencode/skills/locus",
+    "skills",
+    "agents",
+    "hooks",
+    ".claude-plugin",
     "opencode.json"
   ],
   "scripts": {
@@ -24,15 +28,20 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "cli": "npx tsx openspec/bin/cli.ts"
   },
   "keywords": [
     "opencode",
     "opencode-plugin",
+    "claude",
+    "claude-code",
     "ai",
     "planning",
     "project-management",
-    "workflow"
+    "workflow",
+    "skills"
   ],
   "author": "swiggityswerve",
   "license": "MIT",
@@ -53,9 +62,14 @@
     }
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@opencode-ai/plugin": "^1.1.28",
     "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.53.1",
+    "@typescript-eslint/parser": "^8.53.1",
+    "eslint": "^9.39.2",
     "glob": "^10.3.10",
+    "globals": "^17.0.0",
     "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.3.0",