owflow 0.2.0 → 0.4.2

package/dist/templates/orchestrator-state-development.yml

@@ -1,21 +1,22 @@
 orchestrator:
   started_phase: null
+  entry_point: null
   completed_phases: []
   failed_phases: []
   auto_fix_attempts:
-    phase-1: 0
-    phase-2: 0
-    phase-3: 0
-    phase-4: 0
-    phase-5: 0
-    phase-6: 0
-    phase-7: 0
-    phase-8: 0
-    phase-9: 0
-    phase-10: 0
-    phase-11: 0
-    phase-12: 0
-    phase-13: 0
+    codebase-analysed: 0
+    gap-analysed: 0
+    tdd-red-proven: 0
+    spec-written: 0
+    spec-audited: 0
+    plan-created: 0
+    implementation-done: 0
+    tdd-green-proven: 0
+    options-chosen: 0
+    verification-done: 0
+    e2e-run: 0
+    docs-generated: 0
+    task-completed: 0
   options:
     spec_audit_enabled: true
     skip_test_suite: true

package/dist/templates/orchestrator-state-research.yml

@@ -1,17 +1,17 @@
 orchestrator:
   started_phase: null
+  entry_point: null
   completed_phases: []
   failed_phases: []
   auto_fix_attempts:
-    phase-1: 0
-    phase-2: 0
-    phase-3: 0
-    phase-4: 0
-    phase-5: 0
-    phase-6: 0
-  options:
-    brainstorming_enabled: null
-    design_enabled: null
+    brief-written: 0
+    plan-created: 0
+    findings-gathered: 0
+    synthesis-complete: 0
+    alternatives-generated: 0
+    approaches-chosen: 0
+    design-generated: 0
+    research-completed: 0
   created: "YYYY-MM-DDTHH:MM:SSZ"
   updated: "YYYY-MM-DDTHH:MM:SSZ"
   task_path: null
@@ -38,17 +38,22 @@ research_context:
     categories: []
     count: 0
     source: "planner | default"
+  project_doc_paths: []
   phase_summaries:
-    phase-1:
+    plan:
       summary: null
       steps_completed: []
-    phase-3:
+    gather:
       summary: null
-    phase-4:
+    synthesize:
+      summary: null
+    brainstorm:
+      summary: null
+    converge:
       summary: null
       decision_areas: []
       deferred_ideas: []
-    phase-5:
+    design:
       summary: null
       architecture_style: null
       decisions_count: 0
@@ -59,3 +64,4 @@ research_outputs:
   solution_exploration: null
   high_level_design: null
   decision_log: null
+  synthesis: null

package/dist/tools/fork_task.js

@@ -0,0 +1,36 @@
+import { tool } from "@opencode-ai/plugin";
+import path from "node:path";
+import { forkTask } from "../utils/fork-task.js";
+export const fork_task = tool({
+    description: "Fork a research task: copy the whole source task directory into a new date-prefixed directory named from the slug, then trim the copied state so the fork continues from the chosen completed step (fork point) onwards. The source task is never modified.",
+    args: {
+        taskRoot: tool.schema.string().describe("Project-relative root of all tasks (typically '.owflow/tasks')"),
+        source: tool.schema.string().describe("Source task path or identifier under .owflow/tasks/research/"),
+        slug: tool.schema.string().describe("Lowercase-kebab-case slug for the fork name, 3-5 words, WITHOUT the date prefix (derived by the agent from a short descriptive name)"),
+        from: tool.schema.string().describe("Fork point: a completed step slug from the source task's completed_phases (e.g. 'synthesis-complete'); the fork continues from the step after it"),
+        intent: tool.schema.string().optional().describe("Optional one-line description of what the fork should explore; stamped into the fork's orchestrator.options.fork_information.intent"),
+    },
+    async execute(args, context) {
+        try {
+            const result = forkTask({
+                taskRoot: args.taskRoot,
+                source: args.source,
+                slug: args.slug,
+                from: args.from,
+                intent: args.intent,
+                cwd: context.directory,
+            });
+            return {
+                output: [
+                    `FORK CREATED`,
+                    `Fork path: ${path.relative(context.directory, result.forkPath).split(path.sep).join("/")}`,
+                    `Fork point: ${result.forkPoint}`,
+                    ...(args.intent ? [`Intent: ${args.intent}`] : []),
+                ].join("\n"),
+            };
+        }
+        catch (error) {
+            return { output: error.message };
+        }
+    },
+});

package/dist/tools/verify_template.js

@@ -1,8 +1,8 @@
 import { tool } from "@opencode-ai/plugin";
 import fs from "node:fs";
 import path from "node:path";
-import yaml from "yaml";
 import { fileURLToPath } from "node:url";
+import { findStructuralErrors, parseYamlFile, } from "../utils/yaml-structure.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const verify_template = tool({
     description: "Check if file in the given path exists and follows correct YAML structure by checking against the template file from /templates.",
@@ -20,39 +20,18 @@ export const verify_template = tool({
             return { output: `Template '${templateName}' not found. Hint: Verify the template name is correct and exists in the /templates folder (e.g., 'orchestrator-state-development.yml').` };
         }
         let targetYaml;
-        try {
-            const fileContent = fs.readFileSync(absolutePath, "utf8");
-            targetYaml = yaml.parse(fileContent);
-        }
-        catch (error) {
-            return { output: `YAML Syntax Error in ${filePath}: ${error.message}. Hint: Check the file content for invalid YAML formatting, such as incorrect indentation or unescaped strings, and fix them.` };
+        const parsedTarget = parseYamlFile(absolutePath);
+        if (!parsedTarget.ok) {
+            return { output: `YAML Syntax Error in ${filePath}: ${parsedTarget.error}. Hint: Check the file content for invalid YAML formatting, such as incorrect indentation or unescaped strings, and fix them.` };
         }
+        targetYaml = parsedTarget.data;
         let templateYaml;
-        try {
-            const templateContent = fs.readFileSync(templatePath, "utf8");
-            templateYaml = yaml.parse(templateContent);
-        }
-        catch (error) {
-            return { output: `Internal Error: Failed to parse reference template YAML '${templateName}': ${error.message}. Hint: The template file itself contains invalid YAML syntax.` };
-        }
-        function checkStructure(templateObj, targetObj, currentPath = "") {
-            let errors = [];
-            if (typeof templateObj !== 'object' || templateObj === null) {
-                return errors;
-            }
-            for (const key of Object.keys(templateObj)) {
-                const newPath = currentPath ? `${currentPath}.${key}` : key;
-                if (typeof targetObj !== 'object' || targetObj === null || !(key in targetObj)) {
-                    errors.push(`Missing key: ${newPath}`);
-                    continue;
-                }
-                if (typeof templateObj[key] === 'object' && templateObj[key] !== null && !Array.isArray(templateObj[key])) {
-                    errors.push(...checkStructure(templateObj[key], targetObj[key], newPath));
-                }
-            }
-            return errors;
+        const parsedTemplate = parseYamlFile(templatePath);
+        if (!parsedTemplate.ok) {
+            return { output: `Internal Error: Failed to parse reference template YAML '${templateName}': ${parsedTemplate.error}. Hint: The template file itself contains invalid YAML syntax.` };
         }
-        const errors = checkStructure(templateYaml, targetYaml);
+        templateYaml = parsedTemplate.data;
+        const errors = findStructuralErrors(templateYaml, targetYaml);
         if (errors.length > 0) {
             return { output: `YAML Structure Validation Failed. Your file is missing the following required keys:\n- ${errors.join("\n- ")}\n\nHint: Update the file at ${filePath} to include these missing keys so it matches the structure of '${templateName}'.` };
         }

package/dist/utils/file-util.js

@@ -1,19 +1,25 @@
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
-import { PLUGIN_ROOT } from "../constants.js";
+import { PLUGIN_ROOT } from "./plugin-info.js";
 export const loadMarkdownDir = (dirPath) => {
     const fullPath = path.join(PLUGIN_ROOT, dirPath);
+    let files;
     try {
-        return fs
-            .readdirSync(fullPath)
-            .filter((f) => f.endsWith(".md"))
-            .map((f) => {
-            const raw = fs.readFileSync(path.join(fullPath, f), "utf8");
-            return matter(raw);
-        });
+        files = fs.readdirSync(fullPath).filter((f) => f.endsWith(".md"));
     }
     catch {
         return [];
     }
+    const parsed = [];
+    for (const f of files) {
+        try {
+            const raw = fs.readFileSync(path.join(fullPath, f), "utf8");
+            parsed.push(matter(raw));
+        }
+        catch (e) {
+            console.warn(`[owflow] Skipping unparseable markdown file ${f} in ${dirPath}:`, e instanceof Error ? e.message : e);
+        }
+    }
+    return parsed;
 };

package/dist/utils/fork-task.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "yaml";
+import { parseYamlFile } from "./yaml-structure.js";
+/** Lowercase kebab-case, exactly 3-5 words of [a-z0-9] (Task Name Generation convention). */
+export const RESEARCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+){2,4}$/;
+const FORK_TERMINAL_STEP = "research-completed";
+/**
+ * Copies the whole source task directory into a new date-prefixed directory
+ * named from the slug, then trims the copied state so the fork continues
+ * from the fork point onwards. The source task is never modified.
+ */
+export const forkTask = (input) => {
+    const cwd = input.cwd ?? process.cwd();
+    if (!input.slug || !RESEARCH_SLUG_PATTERN.test(input.slug)) {
+        throw new Error("INVALID_NAME: slug must be lowercase kebab-case, 3-5 words of [a-z0-9] (e.g. 'compare-caching-strategies')");
+    }
+    const taskRoot = path.resolve(cwd, input.taskRoot);
+    const researchRoot = path.join(taskRoot, "research");
+    const sourceDir = [
+        path.resolve(cwd, input.source),
+        path.resolve(researchRoot, input.source),
+    ].find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isDirectory());
+    if (sourceDir === undefined) {
+        throw new Error(`INVALID_SOURCE: no task directory at ${input.source}. Hint: pass the task path or a directory name under .owflow/tasks/research/.`);
+    }
+    if (!sourceDir.startsWith(researchRoot + path.sep)) {
+        throw new Error(`INVALID_SOURCE: ${input.source} is not a research task directory under .owflow/tasks/research/.`);
+    }
+    const parsedSourceState = parseYamlFile(path.join(sourceDir, "orchestrator-state.yml"));
+    if (!parsedSourceState.ok || !parsedSourceState.data) {
+        throw new Error(`INVALID_SOURCE: ${parsedSourceState.error ?? `no orchestrator-state.yml in ${input.source}`}`);
+    }
+    const sourceState = parsedSourceState.data;
+    const completed = Array.isArray(sourceState?.orchestrator?.completed_phases)
+        ? sourceState.orchestrator.completed_phases.filter((s) => typeof s === "string")
+        : [];
+    if (input.from === FORK_TERMINAL_STEP) {
+        throw new Error(`UNKNOWN_STEP: ${FORK_TERMINAL_STEP} is not a valid fork point — nothing diverges after completion.`);
+    }
+    if (!completed.includes(input.from)) {
+        throw new Error(`UNKNOWN_STEP: ${input.from} is not completed in the source task. Completed steps: ${completed.join(", ") || "none"}`);
+    }
+    const forkName = `${new Date().toISOString().slice(0, 10)}-${input.slug}`;
+    const forkPath = path.join(researchRoot, forkName);
+    if (fs.existsSync(forkPath)) {
+        throw new Error(`NAME_TAKEN: a research task directory "${forkName}" already exists. Hint: ask the user for another short descriptive name (3-5 words).`);
+    }
+    fs.cpSync(sourceDir, forkPath, { recursive: true });
+    const forkState = structuredClone(sourceState);
+    forkState.orchestrator.started_phase = null;
+    forkState.orchestrator.completed_phases = completed.slice(0, completed.indexOf(input.from) + 1);
+    forkState.orchestrator.entry_point = "research-fork";
+    forkState.orchestrator.task_path = path
+        .relative(cwd, forkPath)
+        .split(path.sep)
+        .join("/");
+    forkState.orchestrator.options = {
+        ...(forkState.orchestrator.options ?? {}),
+        fork_information: {
+            forked_from: path.basename(sourceDir),
+            fork_point: input.from,
+            forked_at: new Date().toISOString(),
+            ...(input.intent ? { intent: input.intent } : {}),
+        },
+    };
+    forkState.task = {
+        ...forkState.task,
+        status: "in_progress",
+        title: `${forkState.task?.title ?? "Research task"} (fork of ${path.basename(sourceDir)})`,
+    };
+    fs.writeFileSync(path.join(forkPath, "orchestrator-state.yml"), yaml.stringify(forkState), "utf8");
+    return { forkPath, forkName, forkPoint: input.from };
+};

package/dist/utils/plugin-info.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PLUGIN_ROOT = path.join(__dirname, ".."); // Points to dist/ where skills/commands/agents are copied
+const UNKNOWN_VERSION = "unknown";
+export const readPluginVersion = (pluginRoot = PLUGIN_ROOT) => {
+    try {
+        const packageJsonPath = path.join(pluginRoot, "..", "package.json");
+        const raw = fs.readFileSync(packageJsonPath, "utf8");
+        const version = JSON.parse(raw).version;
+        return typeof version === "string" && version.length > 0
+            ? version
+            : UNKNOWN_VERSION;
+    }
+    catch {
+        return UNKNOWN_VERSION;
+    }
+};
+export const PLUGIN_VERSION = readPluginVersion();

package/dist/utils/yaml-structure.js

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import yaml from "yaml";
+export const parseYamlFile = (absolutePath) => {
+    try {
+        const fileContent = fs.readFileSync(absolutePath, "utf8");
+        return { ok: true, data: yaml.parse(fileContent) };
+    }
+    catch (error) {
+        return { ok: false, error: error.message };
+    }
+};
+export const findStructuralErrors = (templateObj, targetObj, currentPath = "") => {
+    const errors = [];
+    if (typeof templateObj !== "object" || templateObj === null) {
+        return errors;
+    }
+    for (const key of Object.keys(templateObj)) {
+        const newPath = currentPath ? `${currentPath}.${key}` : key;
+        if (typeof targetObj !== "object" ||
+            targetObj === null ||
+            !(key in targetObj)) {
+            errors.push(`Missing key: ${newPath}`);
+            continue;
+        }
+        if (typeof templateObj[key] === "object" &&
+            templateObj[key] !== null &&
+            !Array.isArray(templateObj[key])) {
+            errors.push(...findStructuralErrors(templateObj[key], targetObj[key], newPath));
+        }
+    }
+    return errors;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owflow",
-  "version": "0.2.0",
+  "version": "0.4.2",
   "description": "Spec-driven development AI workflow for OpenCode",
   "type": "module",
   "main": "dist/index.js",

package/dist/commands/quick-bugfix.md

@@ -1,37 +0,0 @@
----
-name: quick-bugfix
-description: Quick bug fix with TDD red/green gates and complexity escalation
-argument-hint: "[bug description]"
-generated-from-skill: true
----
-
-CRITICAL INSTRUCTION: You MUST invoke the quick-bugfix skill immediately as your FIRST action.
-
-Use the Skill tool with these exact parameters:
-name: "quick-bugfix"
-prompt: "$ARGUMENTS"
-
-DO NOT:
-
-- Analyze the task before invoking the skill
-- Decide the task is "straightforward" and skip the skill
-- Substitute your own approach or workflow
-- Execute any part of the workflow yourself
-
-WHY: The user explicitly chose this workflow by using /quick-bugfix.
-Invoke the skill now and let it orchestrate the complete workflow.
-
----
-
-## About This Workflow
-
-Quick bug fix with TDD red/green gates and complexity escalation
-
-The skill handles:
-
-- Task directory creation and state management
-- Phase execution with interactive gates
-- Subagent delegation for specialized work
-- Pause/resume capability
-
-See `skills/quick-bugfix/SKILL.md` for complete workflow documentation.

package/dist/commands/quick-dev.md

@@ -1,182 +0,0 @@
----
-name: quick-dev
-description: Implement task directly with AI SDLC standards awareness (no planning mode)
----
-
-# Quick Development with Standards Awareness
-
-Implement a task directly without entering planning mode, while still applying project standards from `.owflow/docs/`.
-
-## Usage
-
-```bash
-/quick-dev [task description]
-```
-
-## Examples
-
-```bash
-/quick-dev "Add a logout button to the navbar"
-/quick-dev "Fix the typo in the error message"
-/quick-dev "Update the API endpoint to accept JSON"
-```
-
----
-
-## When to Use
-
-**Use `/quick-dev` when:**
-
-- Task is clear and well-defined
-- You know what needs to be done
-- No architectural decisions needed
-- Quick fixes, small features, or straightforward changes
-
-**Use `/quick-plan` instead when:**
-
-- Task scope is uncertain
-- Multiple implementation approaches possible
-- Architectural decisions required
-- You want user approval before coding
-
----
-
-## Workflow
-
-### Step 1: Parse Input
-
-**Get the task description:**
-
-- If provided as argument, use it directly
-- If not provided, use question to prompt:
-  ```
-  "What would you like to implement? Please describe the task."
-  ```
-
-### Step 1b: Create Task Directory
-
-**Create a lightweight task directory for artifact anchoring.**
-
-1. Generate a task name from the task description:
-   - Extract 3–5 key words, convert to lowercase kebab-case
-   - Prepend today's date: `YYYY-MM-DD-kebab-name`
-   - Examples: "Add a logout button to the navbar" → `2026-05-28-add-navbar-logout-button`, "Update the API endpoint to accept JSON" → `2026-05-28-update-api-accept-json`
-2. Create directory: `.owflow/tasks/quick-dev/YYYY-MM-DD-task-name/`
-3. Write `task.yml` with initial state using the template [src/templates/quick-dev-task.yml](../templates/quick-dev-task.yml).
-4. **CRITICAL**: Use the `verify_template` tool immediately after creation to check YAML validity against `quick-dev-task.yml`.
-
-### Step 2: Discover Standards
-
-**Check if `.owflow/docs/INDEX.md` exists:**
-
-**If exists:**
-
-1. Read INDEX.md to discover available documentation and standards
-2. Identify which standards are relevant based on:
-   - The categories and files listed in INDEX.md
-   - The nature of the task
-   - Keywords in the task description
-3. **READ the applicable standard files** (see Standards Reading Enforcement below)
-4. **Update `task.yml`**: Add paths of standards read to `standards_applied` list
-
-**If not exists:**
-
-- Note that no standards are available
-- Suggest running `/flow-init` in completion message
-
-### Standards Reading Enforcement (MANDATORY)
-
-**BLOCKING**: Reading INDEX.md alone is NOT sufficient. You MUST read actual standard files.
-
-**Enforcement Process**:
-
-1. Read INDEX.md to discover available standards
-2. Identify which standards apply based on task description
-3. **READ each applicable standard file** using Read tool (not just note it exists)
-4. Apply standards during implementation
-5. List applied standards in completion summary
-
-**Examples of standard discovery**:
-
-- Task mentions "upload" → Read file-handling standards
-- Task mentions "form" → Read validation and accessibility standards
-- Task mentions "API" → Read api and error-handling standards
-
-### Step 3: Implement with Standards
-
-**MANDATORY**: During implementation:
-
-1. Explore the codebase to understand context (using Glob, Grep, Read)
-2. **Apply discovered standards** - Reference the standard files you read
-3. For each code change, verify it follows applicable standards
-4. If you encounter new areas while coding (e.g., auth, database), read applicable standards before proceeding
-5. Make the necessary code changes
-6. Run relevant tests if applicable
-
-### Step 4: Verify Standards Compliance
-
-**After implementation, verify:**
-
-1. Review changes against applicable standards
-2. Confirm key guidelines were followed
-3. Note any standards that were applied
-
-### Step 5: Summary
-
-**Write `summary.md`** in the task directory:
-
-```markdown
-# Task Summary
-
-**Command**: quick-dev
-**Date**: YYYY-MM-DD
-**Status**: completed
-
-## What Was Done
-[What was implemented]
-
-## Files Modified
-- `path/to/file`
-
-## Standards Applied
-- [standard]: [guideline]
-
-## Tests
-- [test file] — [result]
-
-## Commit Suggestion
-[conventional commit message]
-```
-
-**Update `task.yml`**: set `status: completed`, `updated: [now]`.
-
-**Provide completion summary to user:**
-
-- What was implemented
-- Which standards from INDEX.md were applied
-- Any tests run and their results
-- Suggestions for follow-up (if any)
-
----
-
-## What This Does
-
-1. **Parses** task description from user input
-2. **Creates** lightweight task directory with `task.yml` for artifact anchoring
-3. **Discovers** applicable standards from `.owflow/docs/INDEX.md`
-4. **READS** actual standard files (MANDATORY - not just INDEX.md)
-5. **Implements** directly without planning mode approval
-6. **Verifies** standards were followed
-7. **Writes** `summary.md` in task directory and updates `task.yml` to `completed`
-8. **Summarizes** what was done and which standards were read and applied
-
-## Graceful Fallback
-
-**If `.owflow/docs/` does not exist:**
-
-Proceed with implementation normally, then note:
-
-```
-"No AI SDLC standards found. Consider running `/flow-init` to initialize
-project documentation and coding standards for better consistency."
-```