locus-product-planning 1.0.0 → 1.2.0

package/dist/index.js

@@ -1,114 +1,250 @@
 /**
  * Locus - OpenCode Plugin
  *
- * AI-powered project planning: Vision → Features → Design → Build
- *
- * This plugin provides the /locus commands for project planning.
- * The main skill is auto-discovered from .opencode/skills/locus/SKILL.md
+ * AI-powered project planning with skills framework.
+ * Provides custom tools for loading and discovering skills,
+ * with automatic bootstrap on session start.
  */
-import { readFileSync, existsSync, readdirSync, statSync } from "fs";
-import { join, dirname } from "path";
+import { tool } from "@opencode-ai/plugin/tool";
+import { readFileSync } from "fs";
+import { join, dirname, resolve } from "path";
 import { fileURLToPath } from "url";
+import { homedir } from "os";
+import { findSkillsInDir, findAgentsInDir, resolveSkillPath, extractFrontmatter, stripFrontmatter, getBootstrapContent, normalizePath, } from "./lib/skills-core.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-// Path to skill file (relative to dist/)
-const SKILL_PATH = join(__dirname, "..", ".opencode", "skills", "locus", "SKILL.md");
-/**
- * Read the Locus skill content
- */
-function getSkillContent() {
-    try {
-        return readFileSync(SKILL_PATH, "utf-8");
-    }
-    catch {
-        return "Locus skill not found. Please reinstall opencode-locus.";
-    }
-}
 /**
- * Get project state from .locus-state.yaml
+ * Locus Plugin for OpenCode
+ *
+ * Provides:
+ * - use_skill: Load and read a specific skill
+ * - find_skills: List all available skills
+ * - find_agents: List all available agents
+ * - Bootstrap injection on session start
  */
-function getProjectState(projectPath) {
-    const statePath = join(projectPath, ".locus-state.yaml");
-    if (!existsSync(statePath))
-        return null;
-    try {
-        const content = readFileSync(statePath, "utf-8");
-        // Simple YAML parsing for our state format
-        const state = {};
-        const lines = content.split("\n");
-        for (const line of lines) {
-            const match = line.match(/^(\w+):\s*(.+)$/);
-            if (match) {
-                state[match[1]] = match[2];
-            }
+export const LocusPlugin = async ({ client, directory }) => {
+    const homeDir = homedir();
+    // Skill directories with priority: project > personal > locus
+    const projectSkillsDir = join(directory, '.opencode/skills');
+    // Derive locus skills dir from plugin location
+    const locusSkillsDir = resolve(__dirname, '..', 'skills');
+    // Agents directory
+    const locusAgentsDir = resolve(__dirname, '..', 'agents');
+    const projectAgentsDir = join(directory, 'agents');
+    // Personal skills directory (respect OPENCODE_CONFIG_DIR if set)
+    const envConfigDir = normalizePath(process.env.OPENCODE_CONFIG_DIR, homeDir);
+    const configDir = envConfigDir || join(homeDir, '.config/opencode');
+    const personalSkillsDir = join(configDir, 'skills');
+    /**
+     * Generate bootstrap content for session injection
+     */
+    const generateBootstrap = (compact = false) => {
+        return getBootstrapContent(locusSkillsDir, compact);
+    };
+    /**
+     * Inject bootstrap via session.prompt
+     */
+    const injectBootstrap = async (sessionID, compact = false) => {
+        const bootstrapContent = generateBootstrap(compact);
+        if (!bootstrapContent)
+            return false;
+        try {
+            await client.session.prompt({
+                path: { id: sessionID },
+                body: {
+                    noReply: true,
+                    parts: [{ type: "text", text: bootstrapContent, synthetic: true }]
+                }
+            });
+            return true;
         }
-        return state;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * List all projects in the projects/ directory
- */
-function listProjects(directory) {
-    const projectsDir = join(directory, "projects");
-    if (!existsSync(projectsDir))
-        return [];
-    const projects = [];
-    try {
-        const entries = readdirSync(projectsDir);
-        for (const entry of entries) {
-            const entryPath = join(projectsDir, entry);
-            const stat = statSync(entryPath);
-            if (stat.isDirectory() && !entry.startsWith(".")) {
-                projects.push({
-                    name: entry,
-                    path: entryPath,
-                    state: getProjectState(entryPath),
-                });
-            }
+        catch {
+            return false;
         }
-    }
-    catch {
-        // Ignore errors
-    }
-    return projects;
-}
-/**
- * Format project status for display
- */
-function formatProjectStatus(state, projectName) {
-    const steps = ["Vision", "Features", "Design", "Build"];
-    if (!state) {
-        return `📋 ${projectName}\n━━━━━━━━━━━━━━━━━━\nNo state found. Start with /locus.`;
-    }
-    const currentStep = Number(state.current_step) || 1;
-    let output = `📋 ${state.project || projectName}\n━━━━━━━━━━━━━━━━━━\n`;
-    for (let i = 0; i < steps.length; i++) {
-        const stepNum = i + 1;
-        const prefix = stepNum < currentStep ? "✓" : stepNum === currentStep ? "→" : " ";
-        const suffix = stepNum === currentStep ? " ◄ you are here" : "";
-        output += `${prefix} Step ${stepNum}: ${steps[i]}${suffix}\n`;
-    }
-    const progress = Math.round(((currentStep - 1) / 4) * 100);
-    output += `\nProgress: ${progress}% complete`;
-    return output;
-}
-/**
- * Locus Plugin for OpenCode
- */
-export const LocusPlugin = async ({ directory }) => {
+    };
     return {
-        // Log when plugin loads
+        tool: {
+            /**
+             * Load and read a specific skill to guide work
+             */
+            use_skill: tool({
+                description: 'Load and read a specific skill to guide your work. Skills contain proven workflows, mandatory processes, and expert techniques for project planning and development.',
+                args: {
+                    skill_name: tool.schema.string().describe('Name of the skill to load (e.g., "locus:product-manager", "project:my-skill", or "brainstorming")')
+                },
+                execute: async (args, context) => {
+                    const { skill_name } = args;
+                    // Resolve skill with priority: project > personal > locus
+                    const resolved = resolveSkillPath(skill_name, locusSkillsDir, personalSkillsDir, projectSkillsDir);
+                    if (!resolved) {
+                        return `Error: Skill "${skill_name}" not found.\n\nRun find_skills to see available skills.`;
+                    }
+                    const fullContent = readFileSync(resolved.skillFile, 'utf-8');
+                    const { name, description } = extractFrontmatter(resolved.skillFile);
+                    const content = stripFrontmatter(fullContent);
+                    const skillDirectory = dirname(resolved.skillFile);
+                    const skillHeader = `# ${name || skill_name}
+# ${description || ''}
+# Supporting tools and docs are in ${skillDirectory}
+# ============================================`;
+                    // Insert as user message with noReply for persistence across compaction
+                    try {
+                        await client.session.prompt({
+                            path: { id: context.sessionID },
+                            body: {
+                                agent: context.agent,
+                                noReply: true,
+                                parts: [
+                                    { type: "text", text: `Loading skill: ${name || skill_name}`, synthetic: true },
+                                    { type: "text", text: `${skillHeader}\n\n${content}`, synthetic: true }
+                                ]
+                            }
+                        });
+                    }
+                    catch {
+                        // Fallback: return content directly if message insertion fails
+                        return `${skillHeader}\n\n${content}`;
+                    }
+                    return `Launching skill: ${name || skill_name}`;
+                }
+            }),
+            /**
+             * List all available skills with optional filtering
+             */
+            find_skills: tool({
+                description: 'List all available skills. Filter by category (e.g., "core", "infrastructure"), tier (e.g., "executive", "developer-specialization"), or search term.',
+                args: {
+                    category: tool.schema.string().optional().describe('Filter by category (e.g., "core", "infrastructure", "data-ai", "quality", "languages")'),
+                    tier: tool.schema.string().optional().describe('Filter by tier (e.g., "executive", "product-management", "engineering-leadership", "developer-specialization")'),
+                    search: tool.schema.string().optional().describe('Search term to filter skills by name or description'),
+                },
+                execute: async (args) => {
+                    const { category, tier, search } = args;
+                    const projectSkills = findSkillsInDir(projectSkillsDir, 'project', 4);
+                    const personalSkills = findSkillsInDir(personalSkillsDir, 'personal', 4);
+                    const locusSkills = findSkillsInDir(locusSkillsDir, 'locus', 4);
+                    let allSkills = [...projectSkills, ...personalSkills, ...locusSkills];
+                    // Apply filters
+                    if (category) {
+                        const categoryLower = category.toLowerCase();
+                        allSkills = allSkills.filter(s => s.category?.toLowerCase().includes(categoryLower) ||
+                            s.path.toLowerCase().includes(categoryLower));
+                    }
+                    if (tier) {
+                        const tierLower = tier.toLowerCase();
+                        allSkills = allSkills.filter(s => s.tier?.toLowerCase().includes(tierLower) ||
+                            s.path.toLowerCase().includes(tierLower));
+                    }
+                    if (search) {
+                        const searchLower = search.toLowerCase();
+                        allSkills = allSkills.filter(s => s.name.toLowerCase().includes(searchLower) ||
+                            s.description.toLowerCase().includes(searchLower));
+                    }
+                    if (allSkills.length === 0) {
+                        const filterDesc = [category && `category="${category}"`, tier && `tier="${tier}"`, search && `search="${search}"`]
+                            .filter(Boolean).join(', ');
+                        return filterDesc
+                            ? `No skills found matching: ${filterDesc}\n\nTry find_skills without filters to see all available skills.`
+                            : `No skills found.\n\nInstall locus skills or add personal skills to ${personalSkillsDir}/`;
+                    }
+                    let output = `Found ${allSkills.length} skill(s):\n\n`;
+                    // Group by source type
+                    const grouped = {
+                        project: allSkills.filter(s => s.sourceType === 'project'),
+                        personal: allSkills.filter(s => s.sourceType === 'personal'),
+                        locus: allSkills.filter(s => s.sourceType === 'locus'),
+                    };
+                    for (const [sourceType, skills] of Object.entries(grouped)) {
+                        if (skills.length === 0)
+                            continue;
+                        output += `## ${sourceType.charAt(0).toUpperCase() + sourceType.slice(1)} Skills\n\n`;
+                        for (const skill of skills) {
+                            const namespace = sourceType === 'personal' ? '' : `${sourceType}:`;
+                            output += `**${namespace}${skill.name}**`;
+                            if (skill.tier || skill.category) {
+                                output += ` [${[skill.tier, skill.category].filter(Boolean).join('/')}]`;
+                            }
+                            output += '\n';
+                            if (skill.description) {
+                                output += `  ${skill.description}\n`;
+                            }
+                        }
+                        output += '\n';
+                    }
+                    return output;
+                }
+            }),
+            /**
+             * List all available agents
+             */
+            find_agents: tool({
+                description: 'List all available agent definitions for specialized tasks.',
+                args: {},
+                execute: async () => {
+                    const locusAgents = findAgentsInDir(locusAgentsDir, 3);
+                    const projectAgents = findAgentsInDir(projectAgentsDir, 3);
+                    const allAgents = [...projectAgents, ...locusAgents];
+                    if (allAgents.length === 0) {
+                        return 'No agents found.';
+                    }
+                    let output = 'Available agents:\n\n';
+                    // Group by category
+                    const byCategory = new Map();
+                    for (const agent of allAgents) {
+                        const cat = agent.category || 'general';
+                        if (!byCategory.has(cat)) {
+                            byCategory.set(cat, []);
+                        }
+                        byCategory.get(cat).push(agent);
+                    }
+                    for (const [category, agents] of byCategory) {
+                        output += `## ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
+                        for (const agent of agents) {
+                            output += `**${agent.name}**\n`;
+                            if (agent.description) {
+                                // Truncate long descriptions
+                                const desc = agent.description.length > 200
+                                    ? agent.description.substring(0, 200) + '...'
+                                    : agent.description;
+                                output += `  ${desc}\n`;
+                            }
+                            output += `  Path: ${agent.path}\n\n`;
+                        }
+                    }
+                    return output;
+                }
+            }),
+        },
+        /**
+         * Event handlers for session lifecycle
+         */
         event: async ({ event }) => {
-            if (event.type === "session.created") {
-                // Plugin is ready
+            // Extract sessionID from various event structures
+            const getSessionID = () => {
+                const props = event.properties;
+                const session = event.session;
+                return props?.info?.id ||
+                    props?.sessionID ||
+                    session?.id;
+            };
+            // Inject bootstrap at session creation (before first user message)
+            if (event.type === 'session.created') {
+                const sessionID = getSessionID();
+                if (sessionID) {
+                    await injectBootstrap(sessionID, false);
+                }
+            }
+            // Re-inject bootstrap after context compaction (compact version to save tokens)
+            if (event.type === 'session.compacted') {
+                const sessionID = getSessionID();
+                if (sessionID) {
+                    await injectBootstrap(sessionID, true);
+                }
             }
         },
     };
 };
 // Default export for OpenCode plugin loading
 export default LocusPlugin;
-// Named exports for programmatic use
-export { getSkillContent, getProjectState, listProjects, formatProjectStatus };
+// Re-export utilities for programmatic use
+export * from "./lib/skills-core.js";

package/dist/lib/skills-core.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Skills Core Library
+ * Shared utilities for skill discovery, loading, and management
+ */
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    license?: string;
+    version?: string;
+    author?: string;
+    category?: string;
+    tier?: string;
+    council?: string;
+    tools?: string;
+    metadata?: {
+        version?: string;
+        tier?: string;
+        category?: string;
+        council?: string;
+        [key: string]: string | undefined;
+    };
+    [key: string]: string | Record<string, string | undefined> | undefined;
+}
+export interface SkillInfo {
+    path: string;
+    skillFile: string;
+    name: string;
+    description: string;
+    sourceType: 'project' | 'personal' | 'locus';
+    tier?: string;
+    category?: string;
+    council?: string;
+    version?: string;
+}
+export interface AgentInfo {
+    path: string;
+    name: string;
+    description: string;
+    model?: string;
+    category: string;
+}
+export interface ResolvedSkill {
+    skillFile: string;
+    sourceType: 'project' | 'personal' | 'locus';
+    skillPath: string;
+}
+/**
+ * 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 declare function extractFrontmatter(filePath: string): SkillMetadata;
+/**
+ * Strip YAML frontmatter from content, returning just the body.
+ */
+export declare function stripFrontmatter(content: string): string;
+/**
+ * Find all SKILL.md files in a directory recursively.
+ */
+export declare function findSkillsInDir(dir: string, sourceType: 'project' | 'personal' | 'locus', maxDepth?: number): SkillInfo[];
+/**
+ * Find all agent definition files in a directory.
+ */
+export declare function findAgentsInDir(dir: string, maxDepth?: number): AgentInfo[];
+/**
+ * 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 declare function resolveSkillPath(skillName: string, locusSkillsDir: string, personalSkillsDir: string | null, projectSkillsDir: string | null): ResolvedSkill | null;
+/**
+ * Get the using-locus bootstrap skill content.
+ */
+export declare function getBootstrapContent(locusSkillsDir: string, compact?: boolean): string | null;
+/**
+ * Normalize a path: trim whitespace, expand ~, resolve to absolute.
+ */
+export declare function normalizePath(p: string | undefined, homeDir: string): string | null;
+//# sourceMappingURL=skills-core.d.ts.map

package/dist/lib/skills-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-core.d.ts","sourceRoot":"","sources":["../../src/lib/skills-core.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KACnC,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CACxE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CA2GlE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsBxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,EAC5C,QAAQ,SAAI,GACX,SAAS,EAAE,CA8Cb;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,SAAS,EAAE,CAuCtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAC9B,aAAa,GAAG,IAAI,CA4BtB;AAsCD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,OAAO,UAAQ,GACd,MAAM,GAAG,IAAI,CA2Cf;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAanF"}