@syntesseraai/opencode-feature-factory 0.2.19 → 0.2.20

package/README.md

@@ -4,6 +4,8 @@ OpenCode plugin that provides Feature Factory agents for structured software dev
 
 ## Installation
 
+### 1. Install the Plugin
+
 Add the plugin to your `opencode.json`:
 
 ```json
@@ -13,7 +15,19 @@ Add the plugin to your `opencode.json`:
 }
 ```
 
-On the next OpenCode startup, the plugin will automatically install the FF agents into your project's `.opencode/agent/` directory.
+### 2. Install Agents, Skills, and MCP (Optional)
+
+To install Feature Factory agents, skills, and MCP servers globally, run:
+
+```bash
+npx @syntesseraai/opencode-feature-factory install
+```
+
+This will:
+
+- Copy agents to `~/.config/opencode/agents/`
+- Copy skills to `~/.config/opencode/skills/`
+- Configure MCP servers in `~/.config/opencode/opencode.json`
 
 ## Agents Provided
 
@@ -34,9 +48,9 @@ On the next OpenCode startup, the plugin will automatically install the FF agent
 
 ## Behavior
 
-- **Silent autosync**: On every OpenCode startup, the plugin ensures all `ff-*.md` agents exist in `.opencode/agent/`.
-- **Never overwrites**: If an agent file already exists, it is never overwritten. This respects any user customizations.
-- **Project-level only**: Agents are installed per-project, not globally.
+- **Manual install**: Agents and skills are installed via the `npx install` command, not automatically
+- **Never overwrites**: If an agent or skill file already exists, it is never overwritten. This respects any user customizations.
+- **Global install**: Agents and skills are installed to `~/.config/opencode/` for use across all projects
 
 ## Agent Scope Boundaries
 

package/bin/ff-deploy.js

@@ -351,7 +351,13 @@ async function deploy(updateMCP) {
 
 // Parse command line arguments
 const args = process.argv.slice(2);
-const updateMCP = args.includes('--mcp') || args.includes('-m');
+
+// Check if running install command
+const isInstall = args[0] === 'install' || args.length === 0;
+
+// Always update MCP config when installing (no flag required)
+const skipMCP = args.includes('--no-mcp');
+const updateMCP = isInstall && !skipMCP;
 
 // Run deployment
 deploy(updateMCP);

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",

package/dist/agent-context.d.ts

@@ -1,54 +0,0 @@
-import type { PluginInput } from '@opencode-ai/plugin';
-export interface AgentContext {
-    /** Unique UUID for this agent instance */
-    id: string;
-    /** Agent type (planning, building, reviewing, etc.) */
-    agent: string;
-    /** Task title */
-    title: string;
-    /** Task description */
-    description: string;
-    /** Working directory/folder */
-    folder: string;
-    /** Current status */
-    status: 'in-progress' | 'completed' | 'delegated' | 'failed';
-    /** ISO timestamp when agent started */
-    started: string;
-    /** OpenCode session ID */
-    session: string;
-    /** Parent agent UUID (if delegated) */
-    parent?: string;
-    /** List of child agent UUIDs (if this agent delegated work) */
-    delegated_to?: string[];
-    /** Additional notes */
-    notes?: string;
-}
-/**
- * Write an agent context file
- * File naming: {agent}-{uuid}.md
- */
-export declare function writeAgentContext(input: PluginInput, context: AgentContext): Promise<string>;
-/**
- * Read an agent context file by UUID
- */
-export declare function readAgentContextById(input: PluginInput, id: string): Promise<AgentContext | null>;
-/**
- * Update agent status in context file
- */
-export declare function updateAgentStatus(input: PluginInput, id: string, status: AgentContext['status']): Promise<boolean>;
-/**
- * List all active agents
- */
-export declare function listActiveAgents(input: PluginInput, sessionId?: string, agentType?: string): Promise<AgentContext[]>;
-/**
- * Find agent files by various criteria
- */
-export declare function findAgentFiles(input: PluginInput, agentType?: string, sessionId?: string): Promise<string[]>;
-/**
- * Find agent file by UUID
- */
-export declare function findAgentFilesById(input: PluginInput, id: string): Promise<string[]>;
-/**
- * Find all agent files
- */
-export declare function findAllAgentFiles(input: PluginInput): Promise<string[]>;

package/dist/agent-context.js

@@ -1,273 +0,0 @@
-import { isValidUUID } from './uuid.js';
-/**
- * Generate the content for an agent context file
- */
-function generateContextFileContent(context) {
-    const frontmatter = `---
-id: "${context.id}"
-agent: ${context.agent}
-title: "${context.title}"
-description: "${context.description}"
-folder: "${context.folder}"
-status: ${context.status}
-started: "${context.started}"
-session: "${context.session}"
-${context.parent ? `parent: "${context.parent}"` : 'parent: null'}
-${context.delegated_to && context.delegated_to.length > 0 ? `delegated_to:\n${context.delegated_to.map((id) => `  - "${id}"`).join('\n')}` : 'delegated_to: []'}
----`;
-    const body = `
-
-## Task Context
-
-${context.notes || 'No additional notes.'}
-
-## Progress
-
-- [ ] Task started
-
-## Delegated Work
-
-${context.delegated_to && context.delegated_to.length > 0 ? context.delegated_to.map((id) => `- Agent ${id} (pending)`).join('\n') : 'No delegated work.'}
-`;
-    return frontmatter + body;
-}
-/**
- * Write an agent context file
- * File naming: {agent}-{uuid}.md
- */
-export async function writeAgentContext(input, context) {
-    const { directory, $ } = input;
-    const fileName = `${context.agent}-${context.id}.md`;
-    const filePath = `${directory}/.feature-factory/agents/${fileName}`;
-    const content = generateContextFileContent(context);
-    try {
-        // Use echo to write file (Bun shell)
-        await $ `echo ${content} > ${filePath}`.quiet();
-        return filePath;
-    }
-    catch (error) {
-        throw new Error(`Failed to write agent context file: ${error}`);
-    }
-}
-/**
- * Read an agent context file by UUID
- */
-export async function readAgentContextById(input, id) {
-    const { directory, $ } = input;
-    if (!isValidUUID(id)) {
-        return null;
-    }
-    try {
-        // Find file with this UUID
-        const result = await $ `ls ${directory}/.feature-factory/agents/ | grep "-${id}.md"`.quiet();
-        const fileName = result.text().trim();
-        if (!fileName) {
-            return null;
-        }
-        const filePath = `${directory}/.feature-factory/agents/${fileName}`;
-        const content = await $ `cat ${filePath}`.quiet();
-        return parseAgentContext(content.text());
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Parse agent context from markdown content
- */
-function parseAgentContext(content) {
-    try {
-        // Extract frontmatter
-        const frontmatterMatch = content.match(/---\n([\s\S]*?)\n---/);
-        if (!frontmatterMatch) {
-            return null;
-        }
-        const frontmatter = frontmatterMatch[1];
-        const lines = frontmatter.split('\n');
-        const context = {};
-        for (const line of lines) {
-            const match = line.match(/^([a-z_]+):\s*(.*)$/);
-            if (match) {
-                const [, key, value] = match;
-                const cleanValue = value.replace(/^["']|["']$/g, ''); // Remove quotes
-                if (key === 'delegated_to') {
-                    // Handle array - this is simplified, real YAML parsing would be better
-                    continue;
-                }
-                else if (key === 'parent' && cleanValue === 'null') {
-                    context[key] = undefined;
-                }
-                else {
-                    context[key] = cleanValue;
-                }
-            }
-        }
-        // Parse delegated_to array manually from content
-        const delegatedMatch = content.match(/delegated_to:\n((?: {2}- ".*"\n?)*)/);
-        if (delegatedMatch) {
-            const delegatedLines = delegatedMatch[1].trim().split('\n');
-            context.delegated_to = delegatedLines
-                .map((line) => line.match(/- "([^"]+)"/)?.[1])
-                .filter((id) => !!id);
-        }
-        return context;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Update agent status in context file
- */
-export async function updateAgentStatus(input, id, status) {
-    const { directory, $ } = input;
-    try {
-        const result = await $ `ls ${directory}/.feature-factory/agents/ | grep "-${id}.md"`.quiet();
-        const fileName = result.text().trim();
-        if (!fileName) {
-            return false;
-        }
-        const filePath = `${directory}/.feature-factory/agents/${fileName}`;
-        // Read current content
-        const content = await $ `cat ${filePath}`.quiet();
-        let text = content.text();
-        // Replace status line
-        text = text.replace(/status: \w+/, `status: ${status}`);
-        // Write back
-        await $ `echo ${text} > ${filePath}`.quiet();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * List all active agents
- */
-export async function listActiveAgents(input, sessionId, agentType) {
-    const { directory, $ } = input;
-    const agentsDir = `${directory}/.feature-factory/agents`;
-    try {
-        // Check if directory exists
-        await $ `test -d ${agentsDir}`.quiet();
-    }
-    catch {
-        return [];
-    }
-    try {
-        const result = await $ `ls ${agentsDir}/*.md 2>/dev/null || echo ""`.quiet();
-        const files = result
-            .text()
-            .trim()
-            .split('\n')
-            .filter((f) => f.endsWith('.md'));
-        const agents = [];
-        for (const filePath of files) {
-            try {
-                const content = await $ `cat ${filePath}`.quiet();
-                const context = parseAgentContext(content.text());
-                if (context) {
-                    // Apply filters
-                    if (sessionId && context.session !== sessionId) {
-                        continue;
-                    }
-                    if (agentType && context.agent !== agentType) {
-                        continue;
-                    }
-                    agents.push(context);
-                }
-            }
-            catch {
-                // Skip files that can't be read
-                continue;
-            }
-        }
-        return agents;
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Find agent files by various criteria
- */
-export async function findAgentFiles(input, agentType, sessionId) {
-    const { directory, $ } = input;
-    const agentsDir = `${directory}/.feature-factory/agents`;
-    try {
-        await $ `test -d ${agentsDir}`.quiet();
-    }
-    catch {
-        return [];
-    }
-    try {
-        let pattern = '*.md';
-        if (agentType) {
-            pattern = `${agentType}-*.md`;
-        }
-        const result = await $ `ls ${agentsDir}/${pattern} 2>/dev/null || echo ""`.quiet();
-        const files = result
-            .text()
-            .trim()
-            .split('\n')
-            .filter((f) => f && f.endsWith('.md'));
-        if (sessionId) {
-            // Filter by session ID (need to read files)
-            const filteredFiles = [];
-            for (const file of files) {
-                try {
-                    const content = await $ `cat ${file}`.quiet();
-                    if (content.text().includes(`session: "${sessionId}"`)) {
-                        filteredFiles.push(file);
-                    }
-                }
-                catch {
-                    continue;
-                }
-            }
-            return filteredFiles;
-        }
-        return files;
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Find agent file by UUID
- */
-export async function findAgentFilesById(input, id) {
-    const { directory, $ } = input;
-    if (!isValidUUID(id)) {
-        return [];
-    }
-    try {
-        const result = await $ `ls ${directory}/.feature-factory/agents/*-${id}.md 2>/dev/null || echo ""`.quiet();
-        return result
-            .text()
-            .trim()
-            .split('\n')
-            .filter((f) => f && f.endsWith('.md'));
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Find all agent files
- */
-export async function findAllAgentFiles(input) {
-    const { directory, $ } = input;
-    const agentsDir = `${directory}/.feature-factory/agents`;
-    try {
-        const result = await $ `ls ${agentsDir}/*.md 2>/dev/null || echo ""`.quiet();
-        return result
-            .text()
-            .trim()
-            .split('\n')
-            .filter((f) => f && f.endsWith('.md'));
-    }
-    catch {
-        return [];
-    }
-}

package/dist/discovery.d.ts

@@ -1,18 +0,0 @@
-import type { CommandStep, QualityGateConfig } from './types.js';
-type BunShell = any;
-/**
- * Resolve the command plan based on configuration and discovery.
- *
- * Resolution order:
- * 1. Configured commands (qualityGate.lint/build/test) - highest priority
- * 2. management/ci.sh (Feature Factory convention) - only if no configured commands
- * 3. Conventional discovery (Node/Rust/Go/Python) - only if no ci.sh
- *
- * @returns Array of command steps to execute, or empty if nothing found
- */
-export declare function resolveCommands(args: {
-    $: BunShell;
-    directory: string;
-    config: QualityGateConfig;
-}): Promise<CommandStep[]>;
-export {};

package/dist/discovery.js

@@ -1,189 +0,0 @@
-import { DEFAULT_QUALITY_GATE, fileExists, hasConfiguredCommands, readJsonFile, } from './quality-gate-config.js';
-// ============================================================================
-// Package Manager Detection
-// ============================================================================
-/**
- * Detect the package manager based on lockfile presence.
- * Priority: pnpm > bun > yarn > npm
- */
-async function detectPackageManager($, directory, override) {
-    if (override && override !== 'auto') {
-        return override;
-    }
-    // Priority order: pnpm > bun > yarn > npm
-    if (await fileExists($, `${directory}/pnpm-lock.yaml`))
-        return 'pnpm';
-    if (await fileExists($, `${directory}/bun.lockb`))
-        return 'bun';
-    if (await fileExists($, `${directory}/bun.lock`))
-        return 'bun';
-    if (await fileExists($, `${directory}/yarn.lock`))
-        return 'yarn';
-    if (await fileExists($, `${directory}/package-lock.json`))
-        return 'npm';
-    return 'npm'; // fallback
-}
-/**
- * Build the run command for a given package manager and script name
- */
-function buildRunCommand(pm, script) {
-    switch (pm) {
-        case 'pnpm':
-            return `pnpm -s run ${script}`;
-        case 'bun':
-            return `bun run ${script}`;
-        case 'yarn':
-            return `yarn -s ${script}`;
-        case 'npm':
-            return `npm run -s ${script}`;
-    }
-}
-// ============================================================================
-// Node.js Discovery
-// ============================================================================
-/**
- * Discover Node.js lint/build/test commands from package.json scripts
- */
-async function discoverNodeCommands($, directory, pm) {
-    const pkgJson = await readJsonFile($, `${directory}/package.json`);
-    if (!pkgJson?.scripts)
-        return [];
-    const scripts = pkgJson.scripts;
-    const steps = [];
-    // Lint: prefer lint:ci, then lint
-    const lintScript = scripts['lint:ci'] ? 'lint:ci' : scripts['lint'] ? 'lint' : null;
-    if (lintScript) {
-        steps.push({ step: 'lint', cmd: buildRunCommand(pm, lintScript) });
-    }
-    // Build: prefer build:ci, then build
-    const buildScript = scripts['build:ci'] ? 'build:ci' : scripts['build'] ? 'build' : null;
-    if (buildScript) {
-        steps.push({ step: 'build', cmd: buildRunCommand(pm, buildScript) });
-    }
-    // Test: prefer test:ci, then test
-    const testScript = scripts['test:ci'] ? 'test:ci' : scripts['test'] ? 'test' : null;
-    if (testScript) {
-        steps.push({ step: 'test', cmd: buildRunCommand(pm, testScript) });
-    }
-    return steps;
-}
-// ============================================================================
-// Rust Discovery
-// ============================================================================
-/**
- * Discover Rust commands from Cargo.toml presence
- */
-async function discoverRustCommands($, directory, includeClippy) {
-    if (!(await fileExists($, `${directory}/Cargo.toml`)))
-        return [];
-    const steps = [{ step: 'lint (fmt)', cmd: 'cargo fmt --check' }];
-    if (includeClippy) {
-        steps.push({
-            step: 'lint (clippy)',
-            cmd: 'cargo clippy --all-targets --all-features',
-        });
-    }
-    steps.push({ step: 'build', cmd: 'cargo build' });
-    steps.push({ step: 'test', cmd: 'cargo test' });
-    return steps;
-}
-// ============================================================================
-// Go Discovery
-// ============================================================================
-/**
- * Discover Go commands from go.mod presence
- */
-async function discoverGoCommands($, directory) {
-    if (!(await fileExists($, `${directory}/go.mod`)))
-        return [];
-    return [{ step: 'test', cmd: 'go test ./...' }];
-}
-// ============================================================================
-// Python Discovery
-// ============================================================================
-/**
- * Discover Python test commands with strong signal detection
- */
-async function discoverPythonCommands($, directory) {
-    // Only add pytest if we have strong signal
-    const hasPytestIni = await fileExists($, `${directory}/pytest.ini`);
-    const hasPyproject = await fileExists($, `${directory}/pyproject.toml`);
-    if (!hasPytestIni && !hasPyproject)
-        return [];
-    // pytest.ini is strong signal
-    if (hasPytestIni) {
-        return [{ step: 'test', cmd: 'pytest' }];
-    }
-    // Check if pyproject.toml mentions pytest
-    if (hasPyproject) {
-        try {
-            const result = await $ `cat ${directory}/pyproject.toml`.quiet();
-            const content = result.text();
-            if (content.includes('pytest')) {
-                return [{ step: 'test', cmd: 'pytest' }];
-            }
-        }
-        catch {
-            // Ignore read errors - return empty array if file can't be read
-        }
-    }
-    return [];
-}
-// ============================================================================
-// Main Resolution Logic
-// ============================================================================
-/**
- * Resolve the command plan based on configuration and discovery.
- *
- * Resolution order:
- * 1. Configured commands (qualityGate.lint/build/test) - highest priority
- * 2. management/ci.sh (Feature Factory convention) - only if no configured commands
- * 3. Conventional discovery (Node/Rust/Go/Python) - only if no ci.sh
- *
- * @returns Array of command steps to execute, or empty if nothing found
- */
-export async function resolveCommands(args) {
-    const { $, directory, config } = args;
-    const mergedConfig = { ...DEFAULT_QUALITY_GATE, ...config };
-    // 1. Configured commands take priority (do NOT run ci.sh if these exist)
-    if (hasConfiguredCommands(config)) {
-        const steps = [];
-        const order = mergedConfig.steps;
-        for (const stepName of order) {
-            const cmd = config[stepName];
-            if (cmd) {
-                steps.push({ step: stepName, cmd });
-            }
-        }
-        return steps;
-    }
-    // 2. Feature Factory CI script (only if no configured commands)
-    if (mergedConfig.useCiSh !== 'never') {
-        const ciShPath = `${directory}/management/ci.sh`;
-        if (await fileExists($, ciShPath)) {
-            return [{ step: 'ci', cmd: `bash ${ciShPath}` }];
-        }
-    }
-    // 3. Conventional discovery (only if no ci.sh)
-    const pm = await detectPackageManager($, directory, mergedConfig.packageManager);
-    // Try Node first (most common)
-    if (await fileExists($, `${directory}/package.json`)) {
-        const nodeSteps = await discoverNodeCommands($, directory, pm);
-        if (nodeSteps.length > 0)
-            return nodeSteps;
-    }
-    // Rust
-    const rustSteps = await discoverRustCommands($, directory, mergedConfig.include?.rustClippy ?? true);
-    if (rustSteps.length > 0)
-        return rustSteps;
-    // Go
-    const goSteps = await discoverGoCommands($, directory);
-    if (goSteps.length > 0)
-        return goSteps;
-    // Python
-    const pythonSteps = await discoverPythonCommands($, directory);
-    if (pythonSteps.length > 0)
-        return pythonSteps;
-    // No commands discovered
-    return [];
-}

package/dist/discovery.test.d.ts

@@ -1,10 +0,0 @@
-/**
- * Unit tests for discovery module
- *
- * Tests focus on the pure function:
- * - buildRunCommand: builds package manager-specific run commands
- *
- * Note: Most functions in discovery.ts require shell access ($) so they're
- * integration-tested elsewhere. This file tests the pure utility functions.
- */
-export {};