owflow 0.1.9 → 0.2.0

package/README.md

@@ -18,6 +18,26 @@ Started as a simple OpenCode fork of [Maister Claude Code plugin](https://github
 
 ## Getting Started
 
+### Directory Structure
+
+```
+owflow/
+├── docs/                   # Plugin documentation (commands, workflows)
+├── scripts/                # Build and utility scripts
+└── src/                    # Source code
+    ├── __tests__/          # Test suites
+    ├── agents/             # Agent definitions and prompts (.md)
+    ├── commands/           # OpenCode slash commands (.md)
+    ├── configuration/      # Handlers for agent, command, and skill configurations
+    ├── hooks/              # OpenCode lifecycle hooks (tool execution, compaction)
+    ├── skills/             # Workflows, orchestrators, and reusable skills
+    ├── templates/          # Orchestrator state and task YAML templates
+    ├── tools/              # Custom OpenCode tool implementations
+    ├── types/              # TypeScript type definitions
+    ├── utils/              # Internal utility functions
+    └── index.ts            # Main plugin entry point
+```
+
 ### Prerequisites
 
 - [Opencode](https://opencode.ai/) CLI installed and configured

package/dist/configuration/agents-config.js

@@ -0,0 +1,66 @@
+import { loadMarkdownDir } from "../utils/file-util.js";
+import matter from "gray-matter";
+/**
+ * Resolves model aliases to the configured small_model value.
+ * Maps common small/fast model aliases to OpenCode's small_model config.
+ *
+ * @param {string} modelValue - The model value from agent frontmatter
+ * @param {string} smallModel - The small_model from OpenCode config
+ * @returns {string|undefined} - Resolved model value or undefined
+ */
+const resolveModelAlias = (modelValue, smallModel) => {
+    // Aliases that should map to small_model
+    const SMALL_MODEL_ALIASES = [
+        "haiku", // Claude Code alias
+        "gpt-4o-mini", // OpenAI small model
+        "small", // Generic alias
+        "fast", // Generic alias
+    ];
+    // If no model specified or it's 'inherit', return undefined (let OpenCode decide)
+    if (!modelValue || modelValue === "inherit") {
+        return undefined;
+    }
+    // If it's a small model alias and we have a configured small_model, use it
+    if (SMALL_MODEL_ALIASES.includes(modelValue.toLowerCase())) {
+        if (smallModel) {
+            return smallModel;
+        }
+        // If no small_model configured, return undefined (inherit)
+        console.warn(`[owflow] Agent uses '${modelValue}' but no small_model configured in opencode.json - falling back to inherit`);
+        return undefined;
+    }
+    // Otherwise, pass through the original value
+    return modelValue;
+};
+const prepareAgent = ({ data, content }, smallModel) => {
+    return {
+        prompt: content,
+        ...(data.description && { description: data.description }),
+        // Resolve model aliases (haiku, gpt-4o-mini, etc.) to small_model
+        ...(() => {
+            const resolvedModel = resolveModelAlias(data.model, smallModel);
+            return resolvedModel ? { model: resolvedModel } : {};
+        })(),
+        ...(data.mode && { mode: data.mode }),
+        // Add skills array if present
+        ...(data.skills && Array.isArray(data.skills) && { skills: data.skills }),
+        ...(data.hidden === "true" && { hidden: true }),
+    };
+};
+export const configureAgents = (config, smallModel) => {
+    config.agent = config.agent || {};
+    for (const markdown of loadMarkdownDir("agents")) {
+        const name = markdown.data.name;
+        if (!name)
+            continue;
+        // Don't overwrite agents the user has explicitly configured
+        if (config.agent[name])
+            continue;
+        try {
+            config.agent[name] = prepareAgent(markdown, smallModel);
+        }
+        catch (error) {
+            console.warn(`[owflow] Failed to register agent '${name}': ${error.message}`);
+        }
+    }
+};

package/dist/configuration/commands-config.js

@@ -0,0 +1,21 @@
+import { loadMarkdownDir } from "../utils/file-util.js";
+export const configureCommands = (config) => {
+    config.command = config.command || {};
+    for (const { data, content } of loadMarkdownDir("commands")) {
+        const name = data.name;
+        if (!name)
+            continue;
+        // Don't overwrite commands the user has explicitly configured
+        if (config.command[name])
+            continue;
+        config.command[name] = {
+            template: content,
+            ...(data.description && { description: data.description }),
+            ...(data.agent && { agent: data.agent }),
+            ...(data.model && { model: data.model }),
+            ...(data.subtask !== undefined && {
+                subtask: data.subtask === "true",
+            }),
+        };
+    }
+};

package/dist/configuration/skills-config.js

@@ -0,0 +1,10 @@
+import path from "node:path";
+import { PLUGIN_ROOT } from "../constants.js";
+export const configureSkills = (config) => {
+    config.skills = config.skills || {};
+    config.skills.paths = config.skills.paths || [];
+    const skillsDir = path.join(PLUGIN_ROOT, "skills");
+    if (!config.skills.paths.includes(skillsDir)) {
+        config.skills.paths.push(skillsDir);
+    }
+};

package/dist/constants.js

@@ -0,0 +1,4 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PLUGIN_ROOT = __dirname; // Points to dist/ where skills/commands/agents are copied

package/dist/hooks/before-tool.js

@@ -0,0 +1,19 @@
+export const guardAgainstDestructiveActions = async (input, output, agentBySessionMap) => {
+    if (input.tool !== "bash")
+        return;
+    const agentName = agentBySessionMap.get(input.sessionID) ?? "main";
+    const WHITELIST = [
+        "task-group-implementer",
+        "test-suite-runner",
+        "e2e-test-verifier",
+        "user-docs-generator",
+        "docs-operator",
+    ];
+    if (WHITELIST.includes(agentName))
+        return;
+    const cmd = output?.args?.command ?? "";
+    const DESTRUCTIVE = /git\s+stash|git\s+reset\s+--hard|git\s+checkout\s+--\s+\.|git\s+checkout\s+\.\s*(?:$|\s)|git\s+clean|git\s+push\s+(?:--force|-f)|rm\s+-[rf]{2}/i;
+    if (DESTRUCTIVE.test(cmd)) {
+        throw new Error(`Blocked: destructive command not permitted for agent "${agentName}"`);
+    }
+};

package/dist/hooks/session-compaction.js

@@ -0,0 +1,19 @@
+import { $ } from "bun";
+/**
+ * Post-compaction reminder.
+ * Injects orchestrator state reminder into the compaction context so the
+ * AI knows to re-read orchestrator-state.yml after the context is rebuilt.
+ */
+export const rereadOrchestratorState = async (directory, output) => {
+    const tasksDir = `${directory}/.owflow/tasks`;
+    try {
+        await $ `test -d ${tasksDir}`;
+        output.context.push(`## owflow Workflow State
+If an orchestrator workflow was active before compaction, you MUST re-read
+orchestrator-state.yml in that task's directory to verify completed_phases
+and determine the next phase. Use the question tool at Phase Gates.`);
+    }
+    catch {
+        // No .owflow/tasks directory — not a owflow project, skip injection
+    }
+};

package/dist/index.js

@@ -4,72 +4,13 @@
  */
 import path from "node:path";
 import fs from "node:fs";
-import { fileURLToPath } from "url";
-import matter from "gray-matter";
 import { verify_template } from "./tools/verify_template.js";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PLUGIN_ROOT = __dirname; // Points to dist/ where skills/commands/agents are copied
-/**
- * Resolves model aliases to the configured small_model value.
- * Maps common small/fast model aliases to OpenCode's small_model config.
- *
- * @param {string} modelValue - The model value from agent frontmatter
- * @param {string} smallModel - The small_model from OpenCode config
- * @returns {string|undefined} - Resolved model value or undefined
- */
-const resolveModelAlias = (modelValue, smallModel) => {
-    // Aliases that should map to small_model
-    const SMALL_MODEL_ALIASES = [
-        "haiku", // Claude Code alias
-        "gpt-4o-mini", // OpenAI small model
-        "small", // Generic alias
-        "fast", // Generic alias
-    ];
-    // If no model specified or it's 'inherit', return undefined (let OpenCode decide)
-    if (!modelValue || modelValue === "inherit") {
-        return undefined;
-    }
-    // If it's a small model alias and we have a configured small_model, use it
-    if (SMALL_MODEL_ALIASES.includes(modelValue.toLowerCase())) {
-        if (smallModel) {
-            return smallModel;
-        }
-        // If no small_model configured, return undefined (inherit)
-        console.warn(`[owflow] Agent uses '${modelValue}' but no small_model configured in opencode.json - falling back to inherit`);
-        return undefined;
-    }
-    // Otherwise, pass through the original value
-    return modelValue;
-};
-const loadMarkdownDir = (dirPath) => {
-    try {
-        return fs
-            .readdirSync(dirPath)
-            .filter((f) => f.endsWith(".md"))
-            .map((f) => {
-            const raw = fs.readFileSync(path.join(dirPath, f), "utf8");
-            return matter(raw);
-        });
-    }
-    catch {
-        return [];
-    }
-};
-const prepareAgent = ({ data, content }, smallModel) => {
-    return {
-        prompt: content,
-        ...(data.description && { description: data.description }),
-        // Resolve model aliases (haiku, gpt-4o-mini, etc.) to small_model
-        ...(() => {
-            const resolvedModel = resolveModelAlias(data.model, smallModel);
-            return resolvedModel ? { model: resolvedModel } : {};
-        })(),
-        ...(data.mode && { mode: data.mode }),
-        // Add skills array if present
-        ...(data.skills && Array.isArray(data.skills) && { skills: data.skills }),
-        ...(data.hidden === "true" && { hidden: true }),
-    };
-};
+import { rereadOrchestratorState } from "./hooks/session-compaction.js";
+import { guardAgainstDestructiveActions } from "./hooks/before-tool.js";
+import { configureSkills } from "./configuration/skills-config.js";
+import { configureCommands } from "./configuration/commands-config.js";
+import { configureAgents } from "./configuration/agents-config.js";
+// Only the plugin factory method should be exported from this file due to OpenCode plugin handling
 const OwflowPlugin = async ({ $, directory }) => {
     const agentBySession = new Map();
     return {
@@ -81,6 +22,7 @@ const OwflowPlugin = async ({ $, directory }) => {
          * them without requiring manual config file edits.
          */
         config: async (config) => {
+            console.log("[owflow] Starting plugin installation...");
             let typedConfig = config;
             // Get small_model config for alias resolution
             // Try from config parameter first, fallback to reading opencode.json
@@ -99,69 +41,14 @@ const OwflowPlugin = async ({ $, directory }) => {
                     console.warn(`Couldn't read or parse opencode.json config - small_model remains undefined`);
                 }
             }
-            // --- Skills ---
-            typedConfig.skills = typedConfig.skills || {};
-            typedConfig.skills.paths = typedConfig.skills.paths || [];
-            const skillsDir = path.join(PLUGIN_ROOT, "skills");
-            if (!typedConfig.skills.paths.includes(skillsDir)) {
-                typedConfig.skills.paths.push(skillsDir);
-            }
-            // --- Commands ---
-            typedConfig.command = typedConfig.command || {};
-            const commandsDir = path.join(PLUGIN_ROOT, "commands");
-            for (const { data, content } of loadMarkdownDir(commandsDir)) {
-                const name = data.name;
-                if (!name)
-                    continue;
-                // Don't overwrite commands the user has explicitly configured
-                if (typedConfig.command[name])
-                    continue;
-                typedConfig.command[name] = {
-                    template: content,
-                    ...(data.description && { description: data.description }),
-                    ...(data.agent && { agent: data.agent }),
-                    ...(data.model && { model: data.model }),
-                    ...(data.subtask !== undefined && {
-                        subtask: data.subtask === "true",
-                    }),
-                };
-            }
-            // --- Agents ---
-            typedConfig.agent = typedConfig.agent || {};
-            const agentsDir = path.join(PLUGIN_ROOT, "agents");
-            for (const markdown of loadMarkdownDir(agentsDir)) {
-                const name = markdown.data.name;
-                if (!name)
-                    continue;
-                // Don't overwrite agents the user has explicitly configured
-                if (typedConfig.agent[name])
-                    continue;
-                try {
-                    typedConfig.agent[name] = prepareAgent(markdown, smallModel);
-                }
-                catch (error) {
-                    console.warn(`[owflow] Failed to register agent '${name}': ${error.message}`);
-                }
-            }
+            configureSkills(typedConfig);
+            configureCommands(typedConfig);
+            configureAgents(typedConfig, smallModel);
             config = typedConfig;
+            console.log("[owflow] Plugin installation completed successfully.");
         },
-        /**
-         * Post-compaction reminder.
-         * Injects orchestrator state reminder into the compaction context so the
-         * AI knows to re-read orchestrator-state.yml after the context is rebuilt.
-         */
         "experimental.session.compacting": async (input, output) => {
-            const tasksDir = `${directory}/.owflow/tasks`;
-            try {
-                await $ `test -d ${tasksDir}`;
-                output.context.push(`## owflow Workflow State
-If an orchestrator workflow was active before compaction, you MUST re-read
-orchestrator-state.yml in that task's directory to verify completed_phases
-and determine the next phase. Use the question tool at Phase Gates.`);
-            }
-            catch {
-                // No .owflow/tasks directory — not a owflow project, skip injection
-            }
+            await rereadOrchestratorState(directory, output);
         },
         "chat.message": async (input, _output) => {
             try {
@@ -173,23 +60,7 @@ and determine the next phase. Use the question tool at Phase Gates.`);
         },
         "tool.execute.before": async (input, output) => {
             try {
-                if (input.tool !== "bash")
-                    return;
-                const agentName = agentBySession.get(input.sessionID) ?? "main";
-                const WHITELIST = [
-                    "task-group-implementer",
-                    "test-suite-runner",
-                    "e2e-test-verifier",
-                    "user-docs-generator",
-                    "docs-operator",
-                ];
-                if (WHITELIST.includes(agentName))
-                    return;
-                const cmd = output?.args?.command ?? "";
-                const DESTRUCTIVE = /git\s+stash|git\s+reset\s+--hard|git\s+checkout\s+--\s+\.|git\s+checkout\s+\.\s*(?:$|\s)|git\s+clean|git\s+push\s+(?:--force|-f)|rm\s+-[rf]{2}/i;
-                if (DESTRUCTIVE.test(cmd)) {
-                    throw new Error(`Blocked: destructive command not permitted for agent "${agentName}"`);
-                }
+                await guardAgainstDestructiveActions(input, output, agentBySession);
             }
             catch (e) {
                 // Re-throw only intentional blocks; swallow unexpected errors

package/dist/utils/file-util.js

@@ -0,0 +1,19 @@
+import matter from "gray-matter";
+import fs from "node:fs";
+import path from "node:path";
+import { PLUGIN_ROOT } from "../constants.js";
+export const loadMarkdownDir = (dirPath) => {
+    const fullPath = path.join(PLUGIN_ROOT, dirPath);
+    try {
+        return fs
+            .readdirSync(fullPath)
+            .filter((f) => f.endsWith(".md"))
+            .map((f) => {
+            const raw = fs.readFileSync(path.join(fullPath, f), "utf8");
+            return matter(raw);
+        });
+    }
+    catch {
+        return [];
+    }
+};

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "owflow",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Spec-driven development AI workflow for OpenCode",
   "type": "module",
-  "module": "index.ts",
   "main": "dist/index.js",
   "exports": "./dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,10 +12,12 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc && bun run copy-markdowns",
-    "copy-markdowns": "node ./scripts/copy-markdowns.js",
+    "build": "rm -rf dist && bun run type-check && bun run test && bun run copy-markdowns",
+    "copy-markdowns": "bun run ./scripts/copy-markdowns.js",
+    "local-install": "bun run build && opencode plugin \"$(pwd)\" --global --force",
     "prepack": "bun run build",
-    "test": "bun test"
+    "test": "bun test src",
+    "type-check": "bun tsc"
   },
   "keywords": [
     "opencode",
@@ -31,11 +32,11 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@opencode-ai/plugin": "^1.18.4",
     "gray-matter": "^4.0.3",
     "yaml": "^2.4.1"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "^1.18.4",
     "@types/bun": "^1.3.13"
   },
   "peerDependencies": {

package/dist/__tests__/verify_template.test.js

@@ -1,102 +0,0 @@
-import { expect, test, describe, beforeAll, afterAll } from "bun:test";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { verify_template } from "../tools/verify_template.js";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-describe("verify_template tool", () => {
-    const templatesDir = path.join(__dirname, "../templates");
-    const testDir = path.join(__dirname, "test_tmp_dir");
-    const testTemplateName = "test-template.yml";
-    const testTemplatePath = path.join(templatesDir, testTemplateName);
-    beforeAll(() => {
-        // Ensure templates dir exists
-        if (!fs.existsSync(templatesDir)) {
-            fs.mkdirSync(templatesDir, { recursive: true });
-        }
-        // Create a dummy template
-        fs.writeFileSync(testTemplatePath, `
-key1: value1
-key2:
-  subKey1: subValue1
-      `);
-        // Ensure test dir exists
-        if (!fs.existsSync(testDir)) {
-            fs.mkdirSync(testDir, { recursive: true });
-        }
-    });
-    afterAll(() => {
-        // Cleanup
-        if (fs.existsSync(testTemplatePath)) {
-            fs.rmSync(testTemplatePath);
-        }
-        if (fs.existsSync(testDir)) {
-            fs.rmSync(testDir, { recursive: true, force: true });
-        }
-    });
-    test("should return error if file not found", async () => {
-        const result = await verify_template.execute({ filePath: "nonexistent.yml", templateName: testTemplateName }, { directory: testDir });
-        expect(result.output).toContain("File not found at nonexistent.yml");
-    });
-    test("should return error if template not found", async () => {
-        const filePath = "target.yml";
-        fs.writeFileSync(path.join(testDir, filePath), "key1: value");
-        const result = await verify_template.execute({ filePath, templateName: "nonexistent-template.yml" }, { directory: testDir });
-        expect(result.output).toContain("Template 'nonexistent-template.yml' not found");
-    });
-    test("should return error if target file has invalid YAML syntax", async () => {
-        const filePath = "invalid.yml";
-        fs.writeFileSync(path.join(testDir, filePath), "key1: : value\n  invalid");
-        const result = await verify_template.execute({ filePath, templateName: testTemplateName }, { directory: testDir });
-        expect(result.output).toContain("YAML Syntax Error in invalid.yml");
-    });
-    test("should return error if target file is missing keys from template", async () => {
-        const filePath = "missing-keys.yml";
-        // Missing key2
-        fs.writeFileSync(path.join(testDir, filePath), "key1: some-value");
-        const result = await verify_template.execute({ filePath, templateName: testTemplateName }, { directory: testDir });
-        expect(result.output).toContain("YAML Structure Validation Failed");
-        expect(result.output).toContain("- Missing key: key2");
-    });
-    test("should pass if target file matches template structure", async () => {
-        const filePath = "valid.yml";
-        fs.writeFileSync(path.join(testDir, filePath), `
-key1: different_value
-key2:
-  subKey1: different_sub_value
-extraKey: this is fine
-      `);
-        const result = await verify_template.execute({ filePath, templateName: testTemplateName }, { directory: testDir });
-        expect(result.output).toBe("File exists and follows the correct YAML structure.");
-    });
-    test("should pass if template has null or non-object values and target has them too", async () => {
-        const nullTemplateName = "null-template.yml";
-        const nullTemplatePath = path.join(templatesDir, nullTemplateName);
-        fs.writeFileSync(nullTemplatePath, "key: null\nother: 123");
-        const filePath = "valid-null.yml";
-        fs.writeFileSync(path.join(testDir, filePath), "key: something\nother: 456");
-        const result = await verify_template.execute({ filePath, templateName: nullTemplateName }, { directory: testDir });
-        expect(result.output).toBe("File exists and follows the correct YAML structure.");
-        fs.rmSync(nullTemplatePath);
-    });
-    describe("real templates validation", () => {
-        let templateFiles = [];
-        try {
-            const files = fs.readdirSync(templatesDir);
-            templateFiles = files.filter(f => f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.md'));
-            // Filter out our dummy test template
-            templateFiles = templateFiles.filter(f => f !== "test-template.yml" && f !== "null-template.yml");
-        }
-        catch (e) {
-            // templates dir might not exist or be readable in some contexts, though beforeAll ensures it exists
-        }
-        for (const templateName of templateFiles) {
-            test(`should successfully validate a valid instance of ${templateName}`, async () => {
-                // We use the templates directory as the working directory 
-                // and the template name as the filePath, effectively comparing the template to itself to ensure it's structurally valid.
-                const result = await verify_template.execute({ filePath: templateName, templateName }, { directory: templatesDir });
-                expect(result.output).toBe("File exists and follows the correct YAML structure.");
-            });
-        }
-    });
-});