opencode-hive 0.2.0

package/README.md

@@ -0,0 +1,91 @@
+# opencode-hive
+
+[![npm version](https://img.shields.io/npm/v/opencode-hive)](https://www.npmjs.com/package/opencode-hive)
+[![License: MIT with Commons Clause](https://img.shields.io/badge/License-MIT%20with%20Commons%20Clause-blue.svg)](../../LICENSE)
+
+**From Vibe Coding to Hive Coding** — The OpenCode plugin that brings structure to AI-assisted development.
+
+## Why Hive?
+
+Stop losing context. Stop repeating decisions. Start shipping with confidence.
+
+```
+Vibe: "Just make it work"
+Hive: Plan → Review → Approve → Execute → Ship
+```
+
+## Installation
+
+```bash
+npm install opencode-hive
+```
+
+## The Workflow
+
+1. **Create Feature** — `hive_feature_create("dark-mode")`
+2. **Write Plan** — AI generates structured plan
+3. **Review** — You review in VS Code, add comments
+4. **Approve** — `hive_plan_approve()`
+5. **Execute** — Tasks run in isolated git worktrees
+6. **Ship** — Clean commits, full audit trail
+
+## Tools
+
+### Feature Management
+| Tool | Description |
+|------|-------------|
+| `hive_feature_create` | Create a new feature |
+| `hive_feature_list` | List all features |
+| `hive_feature_switch` | Switch to a feature |
+| `hive_feature_complete` | Mark feature as complete |
+| `hive_status` | Get feature overview |
+
+### Planning
+| Tool | Description |
+|------|-------------|
+| `hive_plan_write` | Write plan.md |
+| `hive_plan_read` | Read plan and comments |
+| `hive_plan_approve` | Approve plan for execution |
+
+### Tasks
+| Tool | Description |
+|------|-------------|
+| `hive_tasks_sync` | Generate tasks from plan |
+| `hive_task_create` | Create manual task |
+| `hive_task_update` | Update task status/summary |
+
+### Execution
+| Tool | Description |
+|------|-------------|
+| `hive_exec_start` | Start work on task (creates worktree) |
+| `hive_exec_complete` | Complete task (applies changes) |
+| `hive_exec_abort` | Abort task (discard changes) |
+
+## Plan Format
+
+```markdown
+# Feature Name
+
+## Overview
+What we're building and why.
+
+## Tasks
+
+### 1. Task Name
+Description of what to do.
+
+### 2. Another Task
+Description.
+```
+
+## Pair with VS Code
+
+For the full experience, install [vscode-hive](https://marketplace.visualstudio.com/items?itemName=tctinh.vscode-hive) to review plans inline with comments.
+
+## License
+
+MIT with Commons Clause — Free for personal and non-commercial use. See [LICENSE](../../LICENSE) for details.
+
+---
+
+**Stop vibing. Start hiving.** 🐝

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type Plugin } from "@opencode-ai/plugin";
+declare const plugin: Plugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,307 @@
+import * as path from 'path';
+import { tool } from "@opencode-ai/plugin";
+import { WorktreeService } from "./services/worktreeService.js";
+import { FeatureService } from "./services/featureService.js";
+import { PlanService } from "./services/planService.js";
+import { TaskService } from "./services/taskService.js";
+const HIVE_SYSTEM_PROMPT = `
+## Hive - Feature Development System
+
+Plan-first development: Write plan → User reviews → Approve → Execute tasks
+
+### Tools (13 total)
+
+| Domain | Tools |
+|--------|-------|
+| Feature | hive_feature_create, hive_feature_list, hive_feature_switch, hive_feature_complete, hive_status |
+| Plan | hive_plan_write, hive_plan_read, hive_plan_approve |
+| Task | hive_tasks_sync, hive_task_create, hive_task_update |
+| Exec | hive_exec_start, hive_exec_complete, hive_exec_abort |
+
+### Workflow
+
+1. \`hive_feature_create(name)\` - Create feature
+2. \`hive_plan_write(content)\` - Write plan.md
+3. User adds comments in VSCode → \`hive_plan_read\` to see them
+4. Revise plan → User approves
+5. \`hive_tasks_sync()\` - Generate tasks from plan
+6. \`hive_exec_start(task)\` → work → \`hive_exec_complete(task, summary)\`
+
+### Plan Format
+
+\`\`\`markdown
+# Feature Name
+
+## Overview
+What we're building and why.
+
+## Tasks
+
+### 1. Task Name
+Description of what to do.
+
+### 2. Another Task
+Description.
+\`\`\`
+
+\`hive_tasks_sync\` parses \`### N. Task Name\` headers.
+`;
+const plugin = async (ctx) => {
+    const { directory } = ctx;
+    const featureService = new FeatureService(directory);
+    const planService = new PlanService(directory);
+    const taskService = new TaskService(directory);
+    const worktreeService = new WorktreeService({
+        baseDir: directory,
+        hiveDir: path.join(directory, '.hive'),
+    });
+    const captureSession = (toolContext) => {
+        const activeFeature = featureService.getActive();
+        if (!activeFeature)
+            return;
+        const ctx = toolContext;
+        if (ctx?.sessionID) {
+            const currentSession = featureService.getSession(activeFeature);
+            if (currentSession !== ctx.sessionID) {
+                featureService.setSession(activeFeature, ctx.sessionID);
+            }
+        }
+    };
+    return {
+        "experimental.chat.system.transform": async (_input, output) => {
+            output.system.push(HIVE_SYSTEM_PROMPT);
+            const activeFeature = featureService.getActive();
+            if (activeFeature) {
+                const info = featureService.getInfo(activeFeature);
+                if (info) {
+                    let statusHint = `\n### Current Hive Status\n`;
+                    statusHint += `**Active Feature**: ${info.name} (${info.status})\n`;
+                    statusHint += `**Progress**: ${info.tasks.filter(t => t.status === 'done').length}/${info.tasks.length} tasks\n`;
+                    if (info.commentCount > 0) {
+                        statusHint += `**Comments**: ${info.commentCount} unresolved - address with hive_plan_read\n`;
+                    }
+                    output.system.push(statusHint);
+                }
+            }
+        },
+        tool: {
+            hive_feature_create: tool({
+                description: 'Create a new feature and set it as active',
+                args: {
+                    name: tool.schema.string().describe('Feature name'),
+                    ticket: tool.schema.string().optional().describe('Ticket reference'),
+                },
+                async execute({ name, ticket }) {
+                    const feature = featureService.create(name, ticket);
+                    return `Feature "${name}" created. Status: ${feature.status}. Write a plan with hive_plan_write.`;
+                },
+            }),
+            hive_feature_list: tool({
+                description: 'List all features',
+                args: {},
+                async execute() {
+                    const features = featureService.list();
+                    const active = featureService.getActive();
+                    if (features.length === 0)
+                        return "No features found.";
+                    const list = features.map(f => {
+                        const info = featureService.getInfo(f);
+                        return `${f === active ? '* ' : '  '}${f} (${info?.status || 'unknown'})`;
+                    });
+                    return list.join('\n');
+                },
+            }),
+            hive_feature_switch: tool({
+                description: 'Switch to a different feature',
+                args: { name: tool.schema.string().describe('Feature name') },
+                async execute({ name }) {
+                    featureService.setActive(name);
+                    return `Switched to feature "${name}"`;
+                },
+            }),
+            hive_feature_complete: tool({
+                description: 'Mark feature as completed (irreversible)',
+                args: { name: tool.schema.string().optional().describe('Feature name (defaults to active)') },
+                async execute({ name }) {
+                    const feature = name || featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    featureService.complete(feature);
+                    return `Feature "${feature}" marked as completed`;
+                },
+            }),
+            hive_status: tool({
+                description: 'Get overview of active feature',
+                args: { name: tool.schema.string().optional().describe('Feature name (defaults to active)') },
+                async execute({ name }) {
+                    const feature = name || featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const info = featureService.getInfo(feature);
+                    if (!info)
+                        return `Error: Feature "${feature}" not found`;
+                    return JSON.stringify(info, null, 2);
+                },
+            }),
+            hive_plan_write: tool({
+                description: 'Write plan.md (clears existing comments)',
+                args: { content: tool.schema.string().describe('Plan markdown content') },
+                async execute({ content }, toolContext) {
+                    captureSession(toolContext);
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const planPath = planService.write(feature, content);
+                    return `Plan written to ${planPath}. Comments cleared for fresh review.`;
+                },
+            }),
+            hive_plan_read: tool({
+                description: 'Read plan.md and user comments',
+                args: {},
+                async execute(_args, toolContext) {
+                    captureSession(toolContext);
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const result = planService.read(feature);
+                    if (!result)
+                        return "Error: No plan.md found";
+                    return JSON.stringify(result, null, 2);
+                },
+            }),
+            hive_plan_approve: tool({
+                description: 'Approve plan for execution',
+                args: {},
+                async execute(_args, toolContext) {
+                    captureSession(toolContext);
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const comments = planService.getComments(feature);
+                    if (comments.length > 0) {
+                        return `Error: Cannot approve - ${comments.length} unresolved comment(s). Address them first.`;
+                    }
+                    planService.approve(feature);
+                    return "Plan approved. Run hive_tasks_sync to generate tasks.";
+                },
+            }),
+            hive_tasks_sync: tool({
+                description: 'Generate tasks from approved plan',
+                args: {},
+                async execute() {
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const featureData = featureService.get(feature);
+                    if (!featureData || featureData.status === 'planning') {
+                        return "Error: Plan must be approved first";
+                    }
+                    const result = taskService.sync(feature);
+                    if (featureData.status === 'approved') {
+                        featureService.updateStatus(feature, 'executing');
+                    }
+                    return `Tasks synced: ${result.created.length} created, ${result.removed.length} removed, ${result.kept.length} kept`;
+                },
+            }),
+            hive_task_create: tool({
+                description: 'Create manual task (not from plan)',
+                args: {
+                    name: tool.schema.string().describe('Task name'),
+                    order: tool.schema.number().optional().describe('Task order'),
+                },
+                async execute({ name, order }) {
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const folder = taskService.create(feature, name, order);
+                    return `Manual task created: ${folder}`;
+                },
+            }),
+            hive_task_update: tool({
+                description: 'Update task status or summary',
+                args: {
+                    task: tool.schema.string().describe('Task folder name'),
+                    status: tool.schema.string().optional().describe('New status: pending, in_progress, done, cancelled'),
+                    summary: tool.schema.string().optional().describe('Summary of work'),
+                },
+                async execute({ task, status, summary }) {
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const updated = taskService.update(feature, task, {
+                        status: status,
+                        summary,
+                    });
+                    return `Task "${task}" updated: status=${updated.status}`;
+                },
+            }),
+            hive_exec_start: tool({
+                description: 'Create worktree and begin work on task',
+                args: { task: tool.schema.string().describe('Task folder name') },
+                async execute({ task }) {
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const taskInfo = taskService.get(feature, task);
+                    if (!taskInfo)
+                        return `Error: Task "${task}" not found`;
+                    if (taskInfo.status === 'done')
+                        return "Error: Task already completed";
+                    const worktree = await worktreeService.create(feature, task);
+                    taskService.update(feature, task, { status: 'in_progress' });
+                    return `Worktree created at ${worktree.path}\nBranch: ${worktree.branch}`;
+                },
+            }),
+            hive_exec_complete: tool({
+                description: 'Complete task: apply changes, write report',
+                args: {
+                    task: tool.schema.string().describe('Task folder name'),
+                    summary: tool.schema.string().describe('Summary of what was done'),
+                },
+                async execute({ task, summary }) {
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    const taskInfo = taskService.get(feature, task);
+                    if (!taskInfo)
+                        return `Error: Task "${task}" not found`;
+                    if (taskInfo.status !== 'in_progress')
+                        return "Error: Task not in progress";
+                    const diff = await worktreeService.getDiff(feature, task);
+                    if (diff?.hasDiff) {
+                        await worktreeService.applyDiff(feature, task);
+                    }
+                    const report = `# ${task}\n\n## Summary\n\n${summary}\n`;
+                    taskService.writeReport(feature, task, report);
+                    taskService.update(feature, task, { status: 'done', summary });
+                    await worktreeService.remove(feature, task);
+                    return `Task "${task}" completed. Changes applied.`;
+                },
+            }),
+            hive_exec_abort: tool({
+                description: 'Abort task: discard changes, reset status',
+                args: { task: tool.schema.string().describe('Task folder name') },
+                async execute({ task }) {
+                    const feature = featureService.getActive();
+                    if (!feature)
+                        return "Error: No active feature";
+                    await worktreeService.remove(feature, task);
+                    taskService.update(feature, task, { status: 'pending' });
+                    return `Task "${task}" aborted. Status reset to pending.`;
+                },
+            }),
+        },
+        command: {
+            hive: {
+                description: "Create a new feature: /hive <feature-name>",
+                async run(args) {
+                    const name = args.trim();
+                    if (!name)
+                        return "Usage: /hive <feature-name>";
+                    return `Create feature "${name}" using hive_feature_create tool.`;
+                },
+            },
+        },
+    };
+};
+export default plugin;

package/dist/services/featureService.d.ts

@@ -0,0 +1,16 @@
+import { FeatureJson, FeatureStatusType, FeatureInfo } from '../types.js';
+export declare class FeatureService {
+    private projectRoot;
+    constructor(projectRoot: string);
+    create(name: string, ticket?: string): FeatureJson;
+    get(name: string): FeatureJson | null;
+    list(): string[];
+    getActive(): string | null;
+    setActive(name: string): void;
+    updateStatus(name: string, status: FeatureStatusType): FeatureJson;
+    getInfo(name: string): FeatureInfo | null;
+    private getTasks;
+    complete(name: string): FeatureJson;
+    setSession(name: string, sessionId: string): void;
+    getSession(name: string): string | undefined;
+}

package/dist/services/featureService.js

@@ -0,0 +1,117 @@
+import * as fs from 'fs';
+import { getFeaturePath, getFeaturesPath, getFeatureJsonPath, getContextPath, getTasksPath, getActiveFeaturePath, getPlanPath, getCommentsPath, ensureDir, readJson, writeJson, readText, writeText, fileExists, } from '../utils/paths.js';
+export class FeatureService {
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    create(name, ticket) {
+        const featurePath = getFeaturePath(this.projectRoot, name);
+        if (fileExists(featurePath)) {
+            throw new Error(`Feature '${name}' already exists`);
+        }
+        ensureDir(featurePath);
+        ensureDir(getContextPath(this.projectRoot, name));
+        ensureDir(getTasksPath(this.projectRoot, name));
+        const feature = {
+            name,
+            status: 'planning',
+            ticket,
+            createdAt: new Date().toISOString(),
+        };
+        writeJson(getFeatureJsonPath(this.projectRoot, name), feature);
+        this.setActive(name);
+        return feature;
+    }
+    get(name) {
+        return readJson(getFeatureJsonPath(this.projectRoot, name));
+    }
+    list() {
+        const featuresPath = getFeaturesPath(this.projectRoot);
+        if (!fileExists(featuresPath))
+            return [];
+        return fs.readdirSync(featuresPath, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name);
+    }
+    getActive() {
+        return readText(getActiveFeaturePath(this.projectRoot))?.trim() || null;
+    }
+    setActive(name) {
+        const feature = this.get(name);
+        if (!feature)
+            throw new Error(`Feature '${name}' not found`);
+        writeText(getActiveFeaturePath(this.projectRoot), name);
+    }
+    updateStatus(name, status) {
+        const feature = this.get(name);
+        if (!feature)
+            throw new Error(`Feature '${name}' not found`);
+        feature.status = status;
+        if (status === 'approved' && !feature.approvedAt) {
+            feature.approvedAt = new Date().toISOString();
+        }
+        if (status === 'completed' && !feature.completedAt) {
+            feature.completedAt = new Date().toISOString();
+        }
+        writeJson(getFeatureJsonPath(this.projectRoot, name), feature);
+        return feature;
+    }
+    getInfo(name) {
+        const feature = this.get(name);
+        if (!feature)
+            return null;
+        const tasks = this.getTasks(name);
+        const hasPlan = fileExists(getPlanPath(this.projectRoot, name));
+        const comments = readJson(getCommentsPath(this.projectRoot, name));
+        const commentCount = comments?.threads?.length || 0;
+        return {
+            name: feature.name,
+            status: feature.status,
+            tasks,
+            hasPlan,
+            commentCount,
+        };
+    }
+    getTasks(featureName) {
+        const tasksPath = getTasksPath(this.projectRoot, featureName);
+        if (!fileExists(tasksPath))
+            return [];
+        const folders = fs.readdirSync(tasksPath, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name)
+            .sort();
+        return folders.map(folder => {
+            const statusPath = `${tasksPath}/${folder}/status.json`;
+            const status = readJson(statusPath);
+            const name = folder.replace(/^\d+-/, '');
+            return {
+                folder,
+                name,
+                status: status?.status || 'pending',
+                origin: status?.origin || 'plan',
+                summary: status?.summary,
+            };
+        });
+    }
+    complete(name) {
+        const feature = this.get(name);
+        if (!feature)
+            throw new Error(`Feature '${name}' not found`);
+        if (feature.status === 'completed') {
+            throw new Error(`Feature '${name}' is already completed`);
+        }
+        return this.updateStatus(name, 'completed');
+    }
+    setSession(name, sessionId) {
+        const feature = this.get(name);
+        if (!feature)
+            throw new Error(`Feature '${name}' not found`);
+        feature.sessionId = sessionId;
+        writeJson(getFeatureJsonPath(this.projectRoot, name), feature);
+    }
+    getSession(name) {
+        const feature = this.get(name);
+        return feature?.sessionId;
+    }
+}

package/dist/services/index.d.ts

@@ -0,0 +1,5 @@
+export { WorktreeService, createWorktreeService } from "./worktreeService.js";
+export type { WorktreeInfo, DiffResult, ApplyResult, WorktreeConfig } from "./worktreeService.js";
+export { FeatureService } from "./featureService.js";
+export { PlanService } from "./planService.js";
+export { TaskService } from "./taskService.js";

package/dist/services/index.js

@@ -0,0 +1,4 @@
+export { WorktreeService, createWorktreeService } from "./worktreeService.js";
+export { FeatureService } from "./featureService.js";
+export { PlanService } from "./planService.js";
+export { TaskService } from "./taskService.js";

package/dist/services/planService.d.ts

@@ -0,0 +1,11 @@
+import { PlanComment, PlanReadResult } from '../types.js';
+export declare class PlanService {
+    private projectRoot;
+    constructor(projectRoot: string);
+    write(featureName: string, content: string): string;
+    read(featureName: string): PlanReadResult | null;
+    approve(featureName: string): void;
+    getComments(featureName: string): PlanComment[];
+    addComment(featureName: string, comment: Omit<PlanComment, 'id' | 'timestamp'>): PlanComment;
+    clearComments(featureName: string): void;
+}

package/dist/services/planService.js

@@ -0,0 +1,59 @@
+import { getPlanPath, getCommentsPath, getFeatureJsonPath, readJson, writeJson, readText, writeText, fileExists, } from '../utils/paths.js';
+export class PlanService {
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    write(featureName, content) {
+        const planPath = getPlanPath(this.projectRoot, featureName);
+        writeText(planPath, content);
+        this.clearComments(featureName);
+        return planPath;
+    }
+    read(featureName) {
+        const planPath = getPlanPath(this.projectRoot, featureName);
+        const content = readText(planPath);
+        if (content === null)
+            return null;
+        const feature = readJson(getFeatureJsonPath(this.projectRoot, featureName));
+        const comments = this.getComments(featureName);
+        return {
+            content,
+            status: feature?.status || 'planning',
+            comments,
+        };
+    }
+    approve(featureName) {
+        const featurePath = getFeatureJsonPath(this.projectRoot, featureName);
+        const feature = readJson(featurePath);
+        if (!feature)
+            throw new Error(`Feature '${featureName}' not found`);
+        if (!fileExists(getPlanPath(this.projectRoot, featureName))) {
+            throw new Error(`No plan.md found for feature '${featureName}'`);
+        }
+        feature.status = 'approved';
+        feature.approvedAt = new Date().toISOString();
+        writeJson(featurePath, feature);
+    }
+    getComments(featureName) {
+        const commentsPath = getCommentsPath(this.projectRoot, featureName);
+        const data = readJson(commentsPath);
+        return data?.threads || [];
+    }
+    addComment(featureName, comment) {
+        const commentsPath = getCommentsPath(this.projectRoot, featureName);
+        const data = readJson(commentsPath) || { threads: [] };
+        const newComment = {
+            ...comment,
+            id: `comment-${Date.now()}`,
+            timestamp: new Date().toISOString(),
+        };
+        data.threads.push(newComment);
+        writeJson(commentsPath, data);
+        return newComment;
+    }
+    clearComments(featureName) {
+        const commentsPath = getCommentsPath(this.projectRoot, featureName);
+        writeJson(commentsPath, { threads: [] });
+    }
+}

package/dist/services/taskService.d.ts

@@ -0,0 +1,16 @@
+import { TaskStatus, TasksSyncResult, TaskInfo } from '../types.js';
+export declare class TaskService {
+    private projectRoot;
+    constructor(projectRoot: string);
+    sync(featureName: string): TasksSyncResult;
+    create(featureName: string, name: string, order?: number): string;
+    private createFromPlan;
+    update(featureName: string, taskFolder: string, updates: Partial<Pick<TaskStatus, 'status' | 'summary'>>): TaskStatus;
+    get(featureName: string, taskFolder: string): TaskInfo | null;
+    list(featureName: string): TaskInfo[];
+    writeReport(featureName: string, taskFolder: string, report: string): string;
+    private listFolders;
+    private deleteTask;
+    private getNextOrder;
+    private parseTasksFromPlan;
+}