opencode-manifold 0.1.0 → 0.4.1

package/README.md

@@ -8,6 +8,28 @@ A Lead Dev agent walks through a task plan, a deterministic plugin state machine
 
 ---
 
+## Requirements
+
+Open Manifold requires:
+
+1. **opencode-codebase-index** [plugin](https://github.com/Helweg/opencode-codebase-index) — Provides semantic code search for the Clerk's research phase. The Clerk uses it to find relevant code patterns and build focused prompts for worker agents.
+
+2. **Obsidian** (optional but recommended) — The `Manifold/` folder is structured as an Obsidian vault for browsing logs, tasks, and knowledge graph.
+
+**Installation:**
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-codebase-index",
+    "opencode-manifold"
+  ]
+}
+```
+
+---
+
 ## Two Ways to Install
 
 ### Option A — npm package (Recommended)
@@ -21,7 +43,8 @@ A Lead Dev agent walks through a task plan, a deterministic plugin state machine
 }
 ```
 
-2. Run opencode. The plugin auto-installs and generates all required files on first session.
+2. Run opencode. The plugin auto-installs and generates the global template source.
+3. Run `/manifold-init` in the TUI to set up the project.
 
 ### Option B — Local plugin files
 
@@ -39,15 +62,17 @@ A Lead Dev agent walks through a task plan, a deterministic plugin state machine
      "plugin": ["/path/to/.opencode/plugins/opencode-manifold"]
    }
    ```
-4. Run opencode. The plugin generates all required files on first session.
+4. Run opencode. The plugin generates the global template source.
+5. Run `/manifold-init` in the TUI to set up the project.
 
 ---
 
 ## Quick Start
 
 1. **Install** using one of the methods above
-2. **Create a plan** — any format (markdown, TODO list, email, meeting notes)
-3. **Point the Lead Dev agent** at your plan file and tell it to execute
+2. **Run `/manifold-init`** in the opencode TUI to set up agents, skills, and the Manifold directory
+3. **Create a plan** — any format (markdown, TODO list, email, meeting notes)
+4. **Point the Lead Dev agent** at your plan file and tell it to execute
 
 The Lead Dev will:
 - Extract tasks from your plan
@@ -68,7 +93,7 @@ Lead Dev
 Plugin State Machine (TypeScript, zero LLM cost)
   │
   ├── Phase 1: Clerk research
-  │     ├── codebase-index search + wiki lookback + graph entries
+  │     ├── codebase-index search (requires opencode-codebase-index plugin) + wiki lookback + graph entries
   │     ├── Composes scoped prompt
   │     └── Creates task log file
   │
@@ -94,7 +119,7 @@ Plugin State Machine (TypeScript, zero LLM cost)
 
 | Agent | Model | Role |
 |-------|-------|------|
-| `lead-dev` | good tool calling + planning | Reads plan, dispatches tasks |
+| `manifold` | good tool calling + planning | Reads plan, dispatches tasks |
 | `clerk` | conceptualizing + large context | Researches context, composes prompts, logs results |
 | `senior-dev` | coding | Implementation specialist |
 | `junior-dev` | cheap/small coding | Review agent |
@@ -104,6 +129,76 @@ The sr/jr/debug loop enables cost-efficient workflows: a strong sr-dev paired wi
 
 ---
 
+## Customizing Agents
+
+Agents are markdown files with [opencode frontmatter](https://opencode.ai/docs/agents/) for configuration (description, mode, permissions, model) and a body that becomes the agent's system prompt.
+
+Manifold uses a three-tier template system:
+
+```
+Bundled (inside npm package)
+  └── Never edit directly — overwritten on updates
+        │
+        ▼  Plugin load (one-time, only copies missing files)
+~/.config/opencode/manifold/  ← Global templates
+  ├── agents/   (clerk.md, senior-dev.md, ...)
+  ├── skills/   (manifold-workflow/, clerk-orchestration/, ...)
+  ├── manifold/ (settings.json, schema.md, ...)
+  └── config/   (opencode.json)
+        │
+        ▼  /manifold-init (only copies missing files)
+Project root
+  ├── .opencode/agents/   ← Per-project (editable)
+  ├── .opencode/skills/
+  ├── Manifold/
+  └── opencode.json
+```
+
+### Per-project customization
+
+Edit files directly in `.opencode/agents/` or `.opencode/skills/`. These are never overwritten by `/manifold-init` — only files that don't exist yet are copied.
+
+### Global customization
+
+Edit files in `~/.config/opencode/manifold/`. All new projects initialized with `/manifold-init` will inherit your customized versions.
+
+### Resetting
+
+To reset a specific agent to its default, delete just that file and run `/manifold-init` again:
+
+```bash
+rm .opencode/agents/senior-dev.md
+# Then run /manifold-init
+```
+
+To reset all Manifold files, delete the directories and re-run:
+
+```bash
+rm -rf .opencode/agents/ .opencode/skills/ Manifold/
+# Then run /manifold-init
+```
+
+### Assigning models to agents
+
+Add a `model` field to the agent's frontmatter or your `opencode.json`:
+
+```json
+{
+  "agent": {
+    "senior-dev": {
+      "model": "anthropic/claude-sonnet-4-20250514"
+    },
+    "junior-dev": {
+      "model": "anthropic/claude-haiku-4-20250514"
+    }
+  }
+}
+```
+
+See the [Example Configurations](#example-configurations) section for model pairing suggestions.
+
+---
+
 ## Example Configurations
 
 | Budget | Senior Dev | Junior Dev | Debug |
@@ -168,10 +263,10 @@ No mid-loop state recovery needed — restart the task, the Clerk's research pha
 ## FAQ
 
 **Q: Do I need to configure agents?**
-A: No. On first run, the plugin auto-generates agent definitions, skills, and configuration from built-in templates.
+A: No. Run `/manifold-init` once per project and it sets up agent definitions, skills, and configuration from templates.
 
 **Q: Can I customize agents and skills?**
-A: Yes. Edit the files in `.opencode/agents/` and `.opencode/skills/` after they're generated.
+A: Yes. See the [Customizing Agents](#customizing-agents) section for the full three-tier template system.
 
 **Q: What is the Clerk's role?**
 A: The Clerk has full project sight. It researches context (codebase-index, wiki, graph), composes scoped prompts for workers, and maintains the wiki.
@@ -182,6 +277,35 @@ A: The Clerk gets one retry with full failure context. If that also fails, the t
 **Q: Can I define tests for tasks?**
 A: Yes. Add `test: <command>` in the task description or set `testCommand` in settings.json.
 
+**Q: What plugins does Open Manifold require?**
+A: The `opencode-codebase-index` plugin is required for semantic code search. Install it alongside `opencode-manifold`.
+
+**Q: Is Obsidian required?**
+A: No, but recommended. The `Manifold/` folder is an Obsidian vault for browsing logs, tasks, and the knowledge graph. You can use any markdown viewer.
+
+**Q: Can I use Open Manifold without semantic search?**
+A: The system is designed around the Clerk's ability to research context via semantic search. Modifying it would require significant changes to the Clerk's orchestration skill.
+
+---
+
+## Uninstall
+
+To remove Open Manifold from a project:
+
+```bash
+rm -rf .opencode/agents/ .opencode/skills/ Manifold/
+```
+
+Then remove the manifold-specific keys from `opencode.json` (`agent.manifold`, `permission.clerk`, `permission.senior-dev`, `permission.junior-dev`, `permission.debug`).
+
+To remove global templates:
+
+```bash
+rm -rf ~/.config/opencode/manifold/ ~/.config/opencode/commands/manifold-init.md
+```
+
+To fully uninstall the plugin, also remove `"opencode-manifold"` from the `plugin` array in your global or project `opencode.json`.
+
 ---
 
 ## License

package/dist/index.js

@@ -1,212 +1,149 @@
-// src/setup.ts
-import { readFile, writeFile, mkdir, readdir, stat } from "fs/promises";
+// src/init.ts
+import { readFile, writeFile, mkdir, readdir } from "fs/promises";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
-var __dirname = "/Users/don/gitthings/Open_Manifold_System/src";
-async function fileExists(path) {
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var bundledTemplatesDir = join(__dirname2, "..", "src", "templates");
+var globalTemplatesDir = join(homedir(), ".config", "opencode", "manifold");
+async function dirHasContent(dirPath) {
+  if (!existsSync(dirPath))
+    return false;
   try {
-    await stat(path);
-    return true;
+    const entries = await readdir(dirPath);
+    return entries.length > 0;
   } catch {
     return false;
   }
 }
-async function copyFile(src, dest) {
-  const destDir = dirname(dest);
-  if (!existsSync(destDir)) {
-    await mkdir(destDir, { recursive: true });
-  }
-  const content = await readFile(src);
-  await writeFile(dest, content);
-}
-async function copyDirectory(src, dest) {
-  if (!existsSync(dest)) {
-    await mkdir(dest, { recursive: true });
-  }
+async function copyMissingFiles(src, dest) {
+  if (!existsSync(src))
+    return [];
+  await mkdir(dest, { recursive: true });
+  const copied = [];
   const entries = await readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = join(src, entry.name);
     const destPath = join(dest, entry.name);
     if (entry.isDirectory()) {
-      await copyDirectory(srcPath, destPath);
-    } else {
-      await copyFile(srcPath, destPath);
+      const subCopied = await copyMissingFiles(srcPath, destPath);
+      if (subCopied.length > 0) {
+        copied.push(entry.name);
+      }
+    } else if (!existsSync(destPath)) {
+      await writeFile(destPath, await readFile(srcPath));
+      copied.push(entry.name);
     }
   }
+  return copied;
 }
-async function setupProject(directory, client) {
-  await client.app.log({
+async function mergeOpencodeConfig(projectDir) {
+  const configPath = join(projectDir, "opencode.json");
+  const templateConfigPath = join(globalTemplatesDir, "config", "opencode.json");
+  if (!existsSync(templateConfigPath))
+    return;
+  const templateConfig = JSON.parse(await readFile(templateConfigPath, "utf-8"));
+  if (!existsSync(configPath)) {
+    await writeFile(configPath, JSON.stringify(templateConfig, null, 2));
+    return;
+  }
+  const existing = JSON.parse(await readFile(configPath, "utf-8"));
+  let changed = false;
+  if (templateConfig.agent?.manifold && !existing.agent?.manifold) {
+    existing.agent = existing.agent || {};
+    existing.agent.manifold = templateConfig.agent.manifold;
+    changed = true;
+  }
+  if (templateConfig.permission) {
+    for (const [key, value] of Object.entries(templateConfig.permission)) {
+      if (!existing.permission?.[key]) {
+        existing.permission = existing.permission || {};
+        existing.permission[key] = value;
+        changed = true;
+      }
+    }
+  }
+  if (changed) {
+    await writeFile(configPath, JSON.stringify(existing, null, 2));
+  }
+}
+async function ensureGlobalTemplates(ctx) {
+  await ctx.client.app.log({
     body: {
       service: "opencode-manifold",
       level: "info",
-      message: `Checking Open Manifold setup in ${directory}`
+      message: "Checking global templates..."
     }
   });
-  const manifoldPath = join(directory, "Manifold");
-  const opencodeAgentsPath = join(directory, ".opencode", "agents");
-  const opencodeSkillsPath = join(directory, ".opencode", "skills");
-  const opencodeJsonPath = join(directory, "opencode.json");
-  const pluginSourceDir = join(directory, "..", "node_modules", "opencode-manifold", "src", "templates");
-  const manifestPath = join(pluginSourceDir, "..", "..");
-  const templateSourceDir = existsSync(manifestPath) ? manifestPath : join(__dirname, "..", "templates");
-  const manifoldExists = await fileExists(manifoldPath);
-  if (!manifoldExists) {
-    await client.app.log({
+  if (!existsSync(bundledTemplatesDir)) {
+    await ctx.client.app.log({
       body: {
         service: "opencode-manifold",
-        level: "info",
-        message: "Manifold directory not found, setting up..."
-      }
-    });
-    await mkdir(manifoldPath, { recursive: true });
-    await mkdir(join(manifoldPath, ".obsidian"), { recursive: true });
-    await mkdir(join(manifoldPath, "tasks"), { recursive: true });
-    await mkdir(join(manifoldPath, "graph"), { recursive: true });
-    const templateManifold = join(templateSourceDir, "manifold");
-    if (existsSync(templateManifold)) {
-      const files = [
-        "settings.json",
-        "plans.json",
-        "state.json",
-        "index.md",
-        "log.md",
-        "schema.md"
-      ];
-      for (const file of files) {
-        const src = join(templateManifold, file);
-        if (existsSync(src)) {
-          await copyFile(src, join(manifoldPath, file));
-        }
-      }
-    }
-    await client.app.log({
-      body: {
-        service: "opencode-manifold",
-        level: "info",
-        message: "Manifold directory created"
+        level: "error",
+        message: `Bundled templates not found at ${bundledTemplatesDir}`
       }
     });
+    return;
   }
-  const agentsExist = await fileExists(opencodeAgentsPath);
-  if (!agentsExist) {
-    await client.app.log({
-      body: {
-        service: "opencode-manifold",
-        level: "info",
-        message: "Setting up agent definitions..."
-      }
-    });
-    await mkdir(opencodeAgentsPath, { recursive: true });
-    const templateAgents = join(templateSourceDir, "agents");
-    if (existsSync(templateAgents)) {
-      const agents = [
-        "lead-dev.md",
-        "clerk.md",
-        "senior-dev.md",
-        "junior-dev.md",
-        "debug.md"
-      ];
-      for (const agent of agents) {
-        const src = join(templateAgents, agent);
-        if (existsSync(src)) {
-          await copyFile(src, join(opencodeAgentsPath, agent));
-        }
-      }
-    }
-    await client.app.log({
-      body: {
-        service: "opencode-manifold",
-        level: "info",
-        message: "Agent definitions created"
-      }
-    });
+  await copyMissingFiles(bundledTemplatesDir, globalTemplatesDir);
+  const globalCommandsDir = join(homedir(), ".config", "opencode", "commands");
+  const bundledCommandsDir = join(bundledTemplatesDir, "commands");
+  if (existsSync(bundledCommandsDir)) {
+    await copyMissingFiles(bundledCommandsDir, globalCommandsDir);
   }
-  const skillsExist = await fileExists(opencodeSkillsPath);
-  if (!skillsExist) {
-    await client.app.log({
-      body: {
-        service: "opencode-manifold",
-        level: "info",
-        message: "Setting up skills..."
-      }
-    });
-    await mkdir(opencodeSkillsPath, { recursive: true });
-    const templateSkills = join(templateSourceDir, "skills");
-    if (existsSync(templateSkills)) {
-      const skills = [
-        "clerk-orchestration",
-        "lead-dev-workflow",
-        "wiki-ingest",
-        "wiki-query"
-      ];
-      for (const skill of skills) {
-        const skillDir = join(templateSkills, skill);
-        if (existsSync(skillDir)) {
-          await copyDirectory(skillDir, join(opencodeSkillsPath, skill));
-        }
-      }
+  await ctx.client.app.log({
+    body: {
+      service: "opencode-manifold",
+      level: "info",
+      message: "Global templates ready"
     }
-    await client.app.log({
-      body: {
-        service: "opencode-manifold",
-        level: "info",
-        message: "Skills created"
-      }
-    });
-  }
-  const opencodeJsonExists = await fileExists(opencodeJsonPath);
-  if (!opencodeJsonExists) {
-    await client.app.log({
-      body: {
-        service: "opencode-manifold",
-        level: "info",
-        message: "Creating opencode.json configuration..."
-      }
-    });
-    const templateConfig = join(templateSourceDir, "config", "opencode.json");
-    if (existsSync(templateConfig)) {
-      await copyFile(templateConfig, opencodeJsonPath);
-    } else {
-      const defaultConfig = {
-        $schema: "https://opencode.ai/config.json",
-        plugin: ["opencode-manifold", "opencode-codebase-index"],
-        agent: {
-          "lead-dev": {
-            model: "minimax/minimax-2.7",
-            skill: ["lead-dev-workflow"]
-          },
-          clerk: {
-            model: "minimax/minimax-2.7",
-            skill: ["clerk-orchestration", "wiki-ingest", "wiki-query"]
-          },
-          "senior-dev": {
-            model: "minimax/minimax-2.7"
-          },
-          "junior-dev": {
-            model: "qwen/qwen3.5-27b"
-          },
-          debug: {
-            model: "anthropic/claude-sonnet-4-6-20250514"
-          }
-        }
-      };
-      await writeFile(opencodeJsonPath, JSON.stringify(defaultConfig, null, 2));
+  });
+}
+async function initProject(directory, client) {
+  const initialized = [];
+  await client.app.log({
+    body: {
+      service: "opencode-manifold",
+      level: "info",
+      message: `Running /manifold-init in ${directory}`
     }
+  });
+  if (!await dirHasContent(globalTemplatesDir)) {
     await client.app.log({
       body: {
         service: "opencode-manifold",
-        level: "info",
-        message: "opencode.json created"
+        level: "error",
+        message: `Global templates not found at ${globalTemplatesDir}. Plugin may not have loaded correctly.`
       }
     });
+    return initialized;
+  }
+  const agentsCopied = await copyMissingFiles(join(globalTemplatesDir, "agents"), join(directory, ".opencode", "agents"));
+  if (agentsCopied.length > 0) {
+    initialized.push(`agents (${agentsCopied.join(", ")})`);
+  }
+  const skillsCopied = await copyMissingFiles(join(globalTemplatesDir, "skills"), join(directory, ".opencode", "skills"));
+  if (skillsCopied.length > 0) {
+    initialized.push(`skills (${skillsCopied.join(", ")})`);
+  }
+  const manifoldCopied = await copyMissingFiles(join(globalTemplatesDir, "manifold"), join(directory, "Manifold"));
+  if (manifoldCopied.length > 0) {
+    initialized.push(`Manifold/ (${manifoldCopied.join(", ")})`);
+  }
+  const configPath = join(directory, "opencode.json");
+  if (!existsSync(configPath) || !JSON.parse(await readFile(configPath, "utf-8")).agent?.manifold) {
+    await mergeOpencodeConfig(directory);
+    initialized.push("opencode.json");
   }
   await client.app.log({
     body: {
       service: "opencode-manifold",
       level: "info",
-      message: "Open Manifold initialized successfully"
+      message: `/manifold-init complete: ${initialized.join(", ") || "already initialized"}`
     }
   });
+  return initialized;
 }
 
 // src/tools/dispatch-task.ts
@@ -1355,7 +1292,7 @@ var dispatchTaskTool = tool({
     description: tool.schema.string().describe("One-line task description"),
     plan_file: tool.schema.string().describe("Path to the plan document")
   },
-  async execute(args) {
+  async execute(args, context) {
     const { task_number, description, plan_file } = args;
     const client = getClient();
     await client.app.log({
@@ -1365,7 +1302,7 @@ var dispatchTaskTool = tool({
         message: `dispatchTask called: task ${task_number} - ${description}`
       }
     });
-    const directory = process.cwd();
+    const directory = context.directory;
     const settings = await readSettings(directory);
     await updatePlansRegistry(directory, plan_file);
     await client.app.log({
@@ -1438,6 +1375,7 @@ ${testResult.result.output}`,
 // src/index.ts
 var ManifoldPlugin = async (ctx) => {
   setPluginContext(ctx.client);
+  await ensureGlobalTemplates(ctx);
   await ctx.client.app.log({
     body: {
       service: "opencode-manifold",
@@ -1449,20 +1387,29 @@ var ManifoldPlugin = async (ctx) => {
     tool: {
       dispatchTask: dispatchTaskTool
     },
-    event: async ({ event }) => {
-      if (event.type === "session.created") {
-        await ctx.client.app.log({
-          body: {
-            service: "opencode-manifold",
-            level: "info",
-            message: "Session created, checking for Open Manifold setup"
-          }
-        });
-        await setupProject(ctx.directory, ctx.client);
+    "command.execute.before": async (input, output) => {
+      if (input.command === "manifold-init") {
+        const initialized = await initProject(ctx.directory, ctx.client);
+        if (initialized.length > 0) {
+          output.parts = [
+            {
+              type: "text",
+              text: `Manifold initialized: ${initialized.join(", ")}`
+            }
+          ];
+        } else {
+          output.parts = [
+            {
+              type: "text",
+              text: "All Manifold files already present. To reset a specific component, delete the corresponding file(s) from `.opencode/agents/`, `.opencode/skills/`, or `Manifold/`, then run `/manifold-init` again."
+            }
+          ];
+        }
       }
     }
   };
 };
+var server = ManifoldPlugin;
 export {
-  ManifoldPlugin
+  server
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-manifold",
-  "version": "0.1.0",
+  "version": "0.4.1",
   "description": "Multi-agent development system for opencode with persistent knowledge",
   "main": "dist/index.js",
   "type": "module",
@@ -15,7 +15,7 @@
   "dependencies": {
     "@opencode-ai/plugin": "latest",
     "@opencode-ai/sdk": "latest",
-    "zod": "latest"
+    "zod": "^4.1.8"
   },
   "devDependencies": {
     "@types/node": "latest",

package/src/templates/agents/{lead-dev.md → manifold.md}

@@ -1,6 +1,6 @@
-# Lead Dev Agent
+# Manifold Agent
 
-You are the **Lead Developer** for this project. Your role is to orchestrate the development process by reading a plan document and dispatching individual tasks to the system.
+You are the **Manifold Orchestrator** for this project. Your role is to orchestrate the development process by reading a plan document and dispatching individual tasks to the system.
 
 ## Your Responsibilities
 

package/src/templates/commands/manifold-init.md

@@ -0,0 +1,5 @@
+---
+description: Initialize Open Manifold multi-agent system for this project
+agent: build
+---
+Initialize the Open Manifold multi-agent system for this project. Run this once per project to set up agents, skills, and the Manifold knowledge directory.

package/src/templates/config/opencode.json

@@ -1,26 +1,8 @@
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "opencode-manifold",
-    "opencode-codebase-index"
-  ],
   "agent": {
-    "lead-dev": {
-      "model": "minimax/minimax-2.7",
-      "skill": ["lead-dev-workflow"]
-    },
-    "clerk": {
-      "model": "minimax/minimax-2.7",
-      "skill": ["clerk-orchestration", "wiki-ingest", "wiki-query"]
-    },
-    "senior-dev": {
-      "model": "minimax/minimax-2.7"
-    },
-    "junior-dev": {
-      "model": "qwen/qwen3.5-27b"
-    },
-    "debug": {
-      "model": "anthropic/claude-sonnet-4-6-20250514"
+    "manifold": {
+      "skill": ["manifold-workflow"]
     }
   },
   "permission": {
@@ -45,4 +27,4 @@
       }
     }
   }
-}
+}

package/src/templates/skills/{lead-dev-workflow → manifold-workflow}/SKILL.md

@@ -1,6 +1,6 @@
-# Lead Dev Workflow Skill
+# Manifold Workflow Skill
 
-This skill guides the Lead Dev agent through reading plans and dispatching tasks.
+This skill guides the Manifold agent through reading plans and dispatching tasks.
 
 ## Reading Any-Format Plans