locus-product-planning 1.0.0

package/.opencode/skills/locus/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: locus
+description: Plan and build projects through a simple 4-step process (Vision → Features → Design → Build)
+license: MIT
+metadata:
+  version: "2.0.0"
+  author: locus
+  category: workflow
+---
+
+# Locus - Simple Project Planning
+
+Help users go from idea to implementation through 4 simple steps. No jargon, no complexity - just guided progress.
+
+## How It Works
+
+When a user describes something they want to build, guide them through:
+
+```
+Step 1: Vision     → What and why?
+Step 2: Features   → What will it do?
+Step 3: Design     → How will it work?
+Step 4: Build      → Make it happen
+```
+
+## User Experience
+
+### Starting (User describes their idea)
+
+When user says something like:
+- "I want to build an AI trading simulator"
+- "/locus a mobile app for..."
+- "Help me create a..."
+
+Respond with:
+
+```
+I'll help you plan and build this step by step.
+
+📋 [Project Name]
+━━━━━━━━━━━━━━━━━━
+→ Step 1: Vision      ◄ you are here
+  Step 2: Features
+  Step 3: Design
+  Step 4: Build
+
+Let's start with the vision. [Ask 1-2 clarifying questions]
+```
+
+### Progressing (User says "continue", "next", "yes", etc.)
+
+Move to the next step automatically. Show progress:
+
+```
+✓ Step 1: Vision — complete
+
+📋 [Project Name]  
+━━━━━━━━━━━━━━━━━━
+✓ Step 1: Vision
+→ Step 2: Features    ◄ you are here
+  Step 3: Design
+  Step 4: Build
+
+Now let's define the features...
+```
+
+### Checking Status (User asks "where are we?", "status", "progress")
+
+```
+📋 [Project Name]
+━━━━━━━━━━━━━━━━━━
+✓ Step 1: Vision
+✓ Step 2: Features
+→ Step 3: Design      ◄ you are here
+  Step 4: Build
+
+Progress: 50% complete
+Say "continue" to keep going.
+```
+
+## The Four Steps
+
+### Step 1: Vision
+**Purpose**: Understand what they're building and why
+
+Ask about:
+- What problem does this solve?
+- Who is it for?
+- What does success look like?
+
+**Output**: Clear vision statement (create behind the scenes)
+
+### Step 2: Features  
+**Purpose**: Define what the product will do
+
+Ask about:
+- Core features (must have)
+- Nice-to-have features
+- What's NOT included
+
+**Output**: Feature list with priorities (create behind the scenes)
+
+### Step 3: Design
+**Purpose**: Figure out how it will work
+
+Cover:
+- Key technical decisions
+- Architecture overview
+- Main components
+
+**Output**: Technical approach (create behind the scenes)
+
+### Step 4: Build
+**Purpose**: Actually create it
+
+Do:
+- Break into tasks
+- Start implementing
+- Track progress
+
+**Output**: Working code/product
+
+## Response Patterns
+
+### Keep It Conversational
+
+**Good:**
+> "Great! So we're building a trading simulator that helps people learn without risking real money. What's the most important feature it needs?"
+
+**Bad:**
+> "I have created the strategic mandate artifact for Tier 1. The gate criteria require vision_aligned=true. Proceeding to Tier 2 Product Planning phase."
+
+### Show Progress Visually
+
+Always show the simple progress bar:
+```
+📋 Project Name
+━━━━━━━━━━━━━━
+✓ Step 1: Vision
+→ Step 2: Features ◄
+  Step 3: Design
+  Step 4: Build
+```
+
+### Handle "continue" Naturally
+
+When user says: continue, next, yes, keep going, proceed, go ahead, let's do it
+
+→ Move to next step or continue current step
+
+### Handle Questions
+
+If user asks about the process:
+> "We're working through 4 steps: Vision → Features → Design → Build. You're on step 2. Just say 'continue' when you're ready to move forward."
+
+## Behind the Scenes
+
+The skill uses the Initiative Flow Framework internally but **never exposes this to the user**.
+
+| User Sees | Framework Does |
+|-----------|----------------|
+| Step 1: Vision | Creates strategic-mandate.md, passes strategic gate |
+| Step 2: Features | Creates prd.md and epics, passes product gate |
+| Step 3: Design | Creates ADRs, stories, tasks, passes design gate |
+| Step 4: Build | Creates implementation files, tracks progress |
+
+### File Management
+
+Create files silently in: `projects/{project-slug}/`
+
+```
+projects/ai-trading-simulator/
+├── locus.md          # Combined readable plan
+├── vision.md         # Step 1 output
+├── features.md       # Step 2 output  
+├── design.md         # Step 3 output
+└── tasks/            # Step 4 breakdown
+```
+
+### State Tracking
+
+Track state in a simple format:
+```yaml
+# projects/{slug}/.locus-state.yaml
+project: AI Trading Simulator
+current_step: 2
+steps:
+  1: complete
+  2: in_progress
+  3: pending
+  4: pending
+created: 2025-01-20
+```
+
+## Example Conversation
+
+```
+User: I want to build an AI trading simulator
+
+AI: I'll help you plan and build this step by step.
+
+    📋 AI Trading Simulator
+    ━━━━━━━━━━━━━━━━━━━━━━━
+    → Step 1: Vision      ◄ you are here
+      Step 2: Features
+      Step 3: Design
+      Step 4: Build
+
+    Let's start with the vision.
+    
+    What problem does this solve? Who would use it?
+
+User: People who want to learn trading without risking real money. 
+      It should use AI to help them learn faster.
+
+AI: Got it — a risk-free trading simulator with AI-powered learning.
+
+    A few quick questions:
+    1. Should it simulate real market data or simplified scenarios?
+    2. Web app, mobile, or both?
+
+User: Real market data, web app first
+
+AI: Perfect. Here's the vision:
+
+    **AI Trading Simulator**
+    A web-based trading simulator using real market data where users 
+    can practice trading strategies risk-free, with AI providing 
+    personalized feedback to accelerate learning.
+
+    ✓ Step 1: Vision — complete
+
+    📋 AI Trading Simulator
+    ━━━━━━━━━━━━━━━━━━━━━━━
+    ✓ Step 1: Vision
+    → Step 2: Features    ◄ you are here
+      Step 3: Design
+      Step 4: Build
+
+    Ready to define features?
+
+User: yes
+
+AI: Let's figure out what it needs to do.
+
+    **Must-have features** (what's essential?):
+    - Virtual portfolio with fake money
+    - Real market data
+    - Basic buy/sell trades
+    - AI feedback on trades
+    
+    **Nice-to-have** (if time permits?):
+    - Leaderboards
+    - Strategy backtesting
+    - Social features
+    
+    Does this capture it, or should we add/remove anything?
+
+User: Add paper trading competitions as nice-to-have. Otherwise good.
+
+AI: Added. Here's the feature plan:
+
+    **Must Have**
+    • Virtual portfolio ($100k starting balance)
+    • Real-time market data (stocks)
+    • Buy/sell/short trades
+    • AI coach (analyzes trades, suggests improvements)
+    • Performance dashboard
+    
+    **Nice to Have**  
+    • Leaderboards & competitions
+    • Strategy backtesting
+    • Paper trading competitions
+    • Social sharing
+    
+    ✓ Step 2: Features — complete
+
+    📋 AI Trading Simulator
+    ━━━━━━━━━━━━━━━━━━━━━━━
+    ✓ Step 1: Vision
+    ✓ Step 2: Features
+    → Step 3: Design      ◄ you are here
+      Step 4: Build
+
+    Continue to design?
+
+User: continue
+
+AI: Now let's figure out how to build this...
+    [Continues to design step]
+```
+
+## Constraints
+
+- **Never use jargon**: No "tiers", "gates", "artifacts", "epics", "ADRs"
+- **Never show file paths**: User doesn't need to know where files are
+- **Always show progress**: The 4-step visual keeps users oriented
+- **Keep it conversational**: Like talking to a helpful colleague
+- **One thing at a time**: Don't overwhelm with options

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SwiggitySwerve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# Locus Product Planning
+
+**Your center point for planning and building products with AI.**
+
+Locus guides you from idea to implementation through a simple 4-step process. No complicated commands to learn - just describe what you want to build.
+
+## Quick Start
+
+```
+You: I want to build an AI trading simulator
+
+Locus: I'll help you plan and build this step by step.
+
+       📋 AI Trading Simulator
+       ━━━━━━━━━━━━━━━━━━━━━━━
+       → Step 1: Vision ◄
+         Step 2: Features
+         Step 3: Design
+         Step 4: Build
+
+       What problem does this solve?
+```
+
+Say **"continue"** to move forward. That's it.
+
+## How It Works
+
+```
+Step 1: Vision    → What are we building and why?
+Step 2: Features  → What will it do?
+Step 3: Design    → How will it work?
+Step 4: Build     → Let's make it
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/locus` | Start or resume a project |
+| `/locus-status` | Show current project progress |
+| `/locus-list` | List all projects |
+
+Or just describe what you want: "I want to build..."
+
+## Installation
+
+### npm (Recommended)
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-locus-product-planning"]
+}
+```
+
+That's it! OpenCode will automatically install the plugin on startup.
+
+### Manual Installation
+
+Clone the repo and copy the skill:
+
+```bash
+git clone https://github.com/SwiggitySwerve/locus-product-planning.git
+cp -r locus-product-planning/.opencode/skills/locus ~/.config/opencode/skills/
+```
+
+Or reference it directly in `opencode.json`:
+
+```json
+{
+  "instructions": ["~/.config/opencode/skills/locus/SKILL.md"]
+}
+```
+
+### Development Setup
+
+```bash
+git clone https://github.com/SwiggitySwerve/locus-product-planning.git
+cd locus-product-planning
+npm install
+npm test  # 79 tests
+```
+
+## For Power Users
+
+Under the hood, Locus uses a full organizational workflow framework with:
+
+- **Machine-checkable gates** ensuring quality at each stage
+- **State machine** managing project transitions
+- **79 tests** ensuring reliability
+
+### CLI Access
+
+```bash
+npm run cli -- status INI-EXAMPLE-001
+npm run cli -- gate INI-EXAMPLE-001 product
+npm run cli -- next INI-EXAMPLE-001
+```
+
+### Project Structure
+
+```
+.opencode/
+└── skills/
+    └── locus/
+        └── SKILL.md     # Main planning skill
+
+openspec/
+├── lib/                 # TypeScript framework
+└── initiatives/         # Project artifacts
+
+opencode.json            # Command definitions
+```
+
+## Why "Locus"?
+
+**Locus** (noun): A center point; a place where something is situated or occurs.
+
+Your projects need a center point - a place where vision, planning, and execution converge. That's Locus.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * Read the Locus skill content
+ */
+declare function getSkillContent(): string;
+/**
+ * Get project state from .locus-state.yaml
+ */
+declare function getProjectState(projectPath: string): Record<string, unknown> | null;
+/**
+ * List all projects in the projects/ directory
+ */
+declare function listProjects(directory: string): Array<{
+    name: string;
+    path: string;
+    state: Record<string, unknown> | null;
+}>;
+/**
+ * Format project status for display
+ */
+declare function formatProjectStatus(state: Record<string, unknown> | null, projectName: string): string;
+/**
+ * Locus Plugin for OpenCode
+ */
+export declare const LocusPlugin: Plugin;
+export default LocusPlugin;
+export { getSkillContent, getProjectState, listProjects, formatProjectStatus };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAWlD;;GAEG;AACH,iBAAS,eAAe,IAAI,MAAM,CAMjC;AAED;;GAEG;AACH,iBAAS,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAmB5E;AAED;;GAEG;AACH,iBAAS,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAAE,CAAC,CAwBrH;AAED;;GAEG;AACH,iBAAS,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAqB/F;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,MASzB,CAAC;AAGF,eAAe,WAAW,CAAC;AAG3B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,114 @@
+/**
+ * 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
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+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
+ */
+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];
+            }
+        }
+        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 {
+        // 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
+        event: async ({ event }) => {
+            if (event.type === "session.created") {
+                // Plugin is ready
+            }
+        },
+    };
+};
+// Default export for OpenCode plugin loading
+export default LocusPlugin;
+// Named exports for programmatic use
+export { getSkillContent, getProjectState, listProjects, formatProjectStatus };

package/opencode.json

@@ -0,0 +1,17 @@
+{
+  "$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.",
+      "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-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"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "locus-product-planning",
+  "version": "1.0.0",
+  "description": "AI-powered product planning for OpenCode - Vision → Features → Design → Build",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./skill": "./.opencode/skills/locus/SKILL.md"
+  },
+  "files": [
+    "dist",
+    ".opencode/skills/locus",
+    "opencode.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.plugin.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "cli": "npx tsx openspec/bin/cli.ts"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "ai",
+    "planning",
+    "project-management",
+    "workflow"
+  ],
+  "author": "swiggityswerve",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SwiggitySwerve/locus-product-planning.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SwiggitySwerve/locus-product-planning/issues"
+  },
+  "homepage": "https://github.com/SwiggitySwerve/locus-product-planning#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.1.28",
+    "@types/node": "^20.10.0",
+    "glob": "^10.3.10",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0",
+    "yaml": "^2.3.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}