owflow 0.3.0 → 0.4.3

package/README.md

@@ -27,7 +27,7 @@ owflow/
 └── src/                    # Source code
     ├── __tests__/          # Test suites
     ├── agents/             # Agent definitions and prompts (.md)
-    ├── commands/           # OpenCode slash commands (.md)
+    ├── commands/           # Maintained content commands (.md); the rest are generated from skill frontmatter
     ├── configuration/      # Handlers for agent, command, and skill configurations
     ├── hooks/              # OpenCode lifecycle hooks (tool execution, compaction)
     ├── skills/             # Workflows, orchestrators, and reusable skills
@@ -137,7 +137,14 @@ You can always be explicit when you prefer - arguments and flags simply override
 | `/owflow:performance`  | Optimizing speed or resource usage          |
 | `/owflow:migration`    | Changing technologies or patterns           |
 
-Task type (feature/bug/enhancement) is auto-detected from context. Override with `--type=feature|bug|enhancement` if needed. Or use `/owflow:work` as a single entry point that routes to the right workflow.
+Use `/owflow:work` as a single entry point — it classifies the task with the `task-classifier` subagent and routes to the right workflow.
+
+### Research Utility
+
+| Command                       | Use When                                                                        |
+| ----------------------------- | -------------------------------------------------------------------------------- |
+| `/owflow:research-quick "<description>"` | Condensed research: brief → plan → gather → synthesis in one pass     |
+| `/owflow:research-fork <task-path> ["<what this fork should explore>"]` | Branch a research task and re-run from the fork point with different choices |
 
 ### Quick Commands
 
@@ -221,6 +228,21 @@ You can also append additional instructions to narrow scope or guide the workflo
 /owflow:development .owflow/tasks/research/2026-01-12-oauth-research Implement only phase 1
 ```
 
+**Fork a research task to diverge from it.** If you want to re-run part of a completed research with different choices while keeping the original intact, fork it. Passing the task path is enough — the skill reads that research, then asks what the fork should explore, where it should diverge, and what to call it, with suggestions drawn from the research itself:
+
+```bash
+/owflow:research-fork .owflow/tasks/research/2026-01-12-oauth-research
+```
+
+Answer the three questions (or supply the answers up front — each one then gets skipped):
+
+```bash
+/owflow:research-fork .owflow/tasks/research/2026-01-12-oauth-research "compare scoping alternatives" \
+  --from=synthesis-complete --name="compare-scoping-alternatives"
+```
+
+The copy is verbatim (all artifacts, including those from after the fork point) and only the fork's `completed_phases` is trimmed at the fork point, so the fork resumes at the step after it. The source task is never modified.
+
 ## Known Issues
 
 **Orchestrator may stall after long phases.** After context compaction (which typically happens after lengthy phases like implementation), the main agent may stop progressing automatically. If you notice it's idle, just type something like "continue" or "proceed" — it will pick up where it left off. You can also re-invoke the workflow in resume mode to reload the orchestrator state:

package/dist/agents/information-gatherer.md

@@ -47,14 +47,14 @@ hidden: true
 **Custom Categories**: The `source_category` parameter also accepts custom category IDs defined by the research-planner's gathering strategy (e.g., `external-apis`, `project-a-codebase`, `legacy-system`). When a custom category is provided:
 
 - Read the Gathering Strategy section from `planning/research-plan.md` to understand the focus area
-- Name output files using the category ID as prefix: `analysis/findings/[category-id]-*.md`
+- Name output files using the category ID as the leading slug: `analysis/findings/[category-id]-*.md` — the category ID IS the required prefix; the `*` tail may add fresh, specific keywords but MUST NOT repeat words already in the category ID (no stacked slugs like `v2-opencode-v2-direction.md` for category `v2`; the duplicated words add nothing — keep the tail distinct)
 - Apply the most appropriate tools based on the focus area (codebase-focused → Glob/Grep/Read, external-focused → WebSearch/WebFetch, docs-focused → Read/Grep)
 
 **When source_category is NOT `all`**:
 
 - Filter `planning/sources.md` to only include matching category (or use gathering strategy focus area for custom categories)
-- Skip summary generation (Phase 7) - handled by orchestrator merge step
-- Skip verification generation - handled by orchestrator merge step
+- Skip summary generation (Phase 7) - handled by the research-gather merge step
+- Skip verification generation - handled by the research-gather merge step
 - Write only category-specific findings files
 
 ---
@@ -104,7 +104,7 @@ You are an information gathering specialist that executes systematic data collec
    - Read the "Gathering Strategy" section from `planning/research-plan.md`
    - Find the row matching this category ID to understand the specific focus area and recommended tools
    - Use the focus area description to guide what sources to investigate
-   - Use the output prefix from the strategy for file naming
+   - Use the category ID from the strategy for file naming (`analysis/findings/[category-id]-*.md`)
 
 **Output**: Clear understanding of what to gather and how (filtered by category if specified)
 
@@ -451,7 +451,7 @@ Follow the research plan phases systematically. Typical progression:
 
 ### Phase 7: Create Findings Summary
 
-**SKIP this phase if `source_category` is NOT `all`** - summary will be created by orchestrator merge step when running in parallel mode.
+**SKIP this phase if `source_category` is NOT `all`** - summary will be created by the research-gather merge step when running in parallel mode.
 
 **Execute this phase only when `source_category` is `all` or not specified.**
 
@@ -675,17 +675,17 @@ analysis/findings/
 
 ---
 
-## Integration with Research Orchestrator
+## Integration with the Research Workflow
 
-**Input from Phase 1, Step 2**:
+**Invoked by**: the `owflow:research-gather` subskill (Task tool), one call per planned category, all calls in ONE message
 
+**Input**:
 - `planning/research-plan.md` (methodology + gathering strategy)
 - `planning/sources.md` (data sources)
 
-**Output to Phase 1, Step 4** (via merge in Step 3):
-
+**Output** (merged by the calling subskill):
 - `analysis/findings/*.md` (detailed findings by source category)
 
-**State Update**: Report back to orchestrator (Phase 1, Step 3 gathering complete)
+**State Update**: The calling subskill records `findings-gathered`
 
-**Next Step**: Orchestrator merges findings into `00-summary.md` and `99-verification.md`, then invokes research-synthesizer
+**Next Step**: `owflow:research-synthesize` merges the findings and invokes research-synthesizer

package/dist/agents/research-planner.md

@@ -239,11 +239,11 @@ You are a research planning specialist that creates structured, methodical resea
 
 ### Instances: [N] (max 8)
 
-| #   | Category ID   | Focus Area                 | Tools               | Output Prefix |
-| --- | ------------- | -------------------------- | ------------------- | ------------- |
-| 1   | codebase      | Source code analysis       | Glob, Grep, Read    | codebase      |
-| 2   | documentation | Project docs & code docs   | Read, Grep          | docs          |
-| 3   | external-apis | External API documentation | WebSearch, WebFetch | external-apis |
+| #   | Category ID   | Focus Area                 | Tools               |
+| --- | ------------- | -------------------------- | ------------------- |
+| 1   | codebase      | Source code analysis       | Glob, Grep, Read    |
+| 2   | documentation | Project docs & code docs   | Read, Grep          |
+| 3   | external-apis | External API documentation | WebSearch, WebFetch |
 
 ### Rationale
 
@@ -255,8 +255,9 @@ You are a research planning specialist that creates structured, methodical resea
 - Minimum: 1 gatherer (simple questions that only need one source type)
 - Maximum: 8 gatherers (prevent token waste and diminishing returns)
 - Each gatherer must have a distinct focus area (no overlapping categories)
-- The category ID becomes the `source_category` parameter for the information-gatherer agent
-- The output prefix becomes the file naming convention: `analysis/findings/[prefix]-*.md`
+- The category ID becomes the `source_category` parameter for the information-gatherer agent AND the findings file prefix: files are `analysis/findings/[category-id]-*.md` — the Category ID is the ONLY filename slug source (an optional short Output Prefix column previously duplicated this and caused stacked slugs like `dynamic-dynamic-approaches.md`; removed)
+- Category IDs SHOULD be short and descriptive (e.g. `codebase`, `docs`, `external`) — they lead every findings filename, and reuse of their words in the descriptive tail is duplication
+- **Heading label is fixed**: the section heading MUST be exactly `## Gathering Strategy` (no numeric prefix like `## 6. Gathering Strategy` — downstream `research-gather` parses for the exact string)
 
 **Default Fallback** (if not specified):
 When the planner does not include a Gathering Strategy section, the orchestrator falls back to 4 instances:
@@ -437,11 +438,13 @@ When the planner does not include a Gathering Strategy section, the orchestrator
 
 ---
 
-## Integration with Research Orchestrator
+## Integration with the Research Workflow
 
-**Input from Phase 1, Step 1**: `planning/research-brief.md`
-**Output to Phase 1, Step 3**: `planning/research-plan.md`, `planning/sources.md`
+**Invoked by**: the `owflow:research-plan` subskill (Task tool)
 
-**State Update**: Report back to orchestrator (Phase 1, Step 2 complete)
+**Input**: `planning/research-brief.md`
+**Output**: `planning/research-plan.md`, `planning/sources.md`
 
-**Next Step**: Orchestrator reads gathering strategy and launches information-gatherer agents
+**State Update**: The calling subskill records `plan-created`
+
+**Next Step**: `owflow:research-gather` reads the gathering strategy and launches the information-gatherer fan

package/dist/agents/research-synthesizer.md

@@ -387,15 +387,17 @@ Combine relevant elements from above frameworks based on research objectives.
 
 ---
 
-## Integration with Research Orchestrator
+## Integration with the Research Workflow
 
-**Input from Phase 1, Step 3** (Information Gathering):
+**Invoked by**: the `owflow:research-synthesize` subskill (Task tool)
+
+**Input** (information gathering):
 - `analysis/findings/*.md` (all finding files)
 
-**Output to Phase 2** (Brainstorming Decision) / **Phase 3** (Brainstorming):
+**Output**:
 - `analysis/synthesis.md` (patterns and insights)
 - `outputs/research-report.md` (comprehensive report)
 
-**State Update**: Report back to orchestrator (Phase 1, Step 4 complete)
+**State Update**: The calling subskill records `synthesis-complete`
 
-**Next Step**: Orchestrator evaluates brainstorming value (Phase 2) then creates deliverables
+**Next Step**: the user chooses the optional chain (brainstorm / design) or `owflow:research-finalize` completes the task

package/dist/agents/solution-brainstormer.md

@@ -228,18 +228,18 @@ warnings: ["any non-critical observations"]
 
 ## Integration
 
-**Invoked by**: research orchestrator (Phase 3)
+**Invoked by**: the `owflow:research-brainstorm` subskill (Task tool)
 
 **Prerequisites**:
 - Task directory exists with `analysis/` and `outputs/` subdirectories
-- `analysis/synthesis.md` exists (Phase 1 output)
-- `outputs/research-report.md` exists (Phase 1 output)
+- `analysis/synthesis.md` exists (research-synthesize output)
+- `outputs/research-report.md` exists (research-synthesize output)
 
 **Input**: Task path, research artifacts, accumulated context (no user preferences — alternatives are generated purely from evidence)
 
 **Output**: `outputs/solution-exploration.md` + structured result
 
-**Next Phase**: Orchestrator presents alternatives to user for convergence (Phase 4: Solution Convergence), then feeds chosen approach into solution-designer (Phase 5)
+**Next**: `owflow:research-converge` presents the alternatives to the user for per-area convergence, then `owflow:research-design` consumes the chosen approach.
 
 ---
 

package/dist/agents/solution-designer.md

@@ -336,24 +336,24 @@ warnings: ["any non-critical observations"]
 
 ## Integration
 
-**Invoked by**: research orchestrator (Phase 5)
+**Invoked by**: the `owflow:research-design` subskill (Task tool)
 
 **Prerequisites**:
 - Task directory exists with `analysis/` and `outputs/` subdirectories
-- `outputs/solution-exploration.md` exists (Phase 3 output)
-- `analysis/synthesis.md` exists (Phase 1 output)
-- `outputs/research-report.md` exists (Phase 1 output)
+- `analysis/synthesis.md` exists (research-synthesize output)
+- `outputs/research-report.md` exists (research-synthesize output)
+- `outputs/solution-exploration.md` exists — only when brainstorming ran; on the design-only branch `selected_approach` comes from the research report instead
 
 **Input**: Task path, solution exploration, research artifacts, selected approach, design preferences, accumulated context
 
 **Output**: `outputs/high-level-design.md` + `outputs/decision-log.md` + structured result
 
-**Next Phase**: Design documents feed into Phase 6 (Completion) and are later consumed by the development orchestrator's specification phase when development starts from research
+**Next**: `owflow:research-finalize` inventories the outputs and completes the task; the design documents are later consumed by development's specification phase.
 
 **Downstream consumption**:
 - `specification-creator` reads `high-level-design.md` as primary architectural input
 - `specification-creator` references `decision-log.md` to avoid re-deciding settled questions
-- Development orchestrator Phase 5 (Specification) incorporates architecture decisions, which can be lighter when comprehensive ADRs exist
+- Development's specification phase incorporates architecture decisions, which can be lighter when comprehensive ADRs exist
 
 ---
 

package/dist/commands/work.md

@@ -53,12 +53,12 @@ Auto-classifies tasks and routes to the appropriate workflow orchestrator. Suppo
 
 ## Workflow Type Routing
 
-| Classification | Routes To (Skill) |
-| -------------- | ----------------- |
-| development    | `development`     |
-| performance    | `performance`     |
-| migration      | `migration`       |
-| research       | `research`        |
+| Classification | Routes To (Skill)     |
+| -------------- | --------------------- |
+| development    | `owflow:development`  |
+| performance    | `owflow:performance`  |
+| migration      | `owflow:migration`    |
+| research       | `owflow:research`     |
 
 ---
 
@@ -146,7 +146,7 @@ Use Skill tool:
 Examples:
 
 - Resume development: `skill: "owflow:development"` with `args: "--resume .owflow/tasks/development/2025-10-23-fix"`
-- Restart from step: `skill: "owflow:development"` with `args: "--resume .owflow/tasks/development/2025-10-26-auth --from=verification-done"` (dev tasks use descriptive step slugs in `completed_phases`; other workflows use `phase-N`)
+- Restart from step: `skill: "owflow:development"` with `args: "--resume .owflow/tasks/development/2025-10-26-auth --from=verification-done"` (dev tasks use descriptive step slugs in `completed_phases`; performance and migration are the remaining `phase-N` holdouts — research uses the descriptive slugs in `templates/orchestrator-state-research.yml`)
 - Fresh attempts: `skill: "owflow:migration"` with `args: "--resume .owflow/tasks/migrations/2025-10-20-redux --reset-attempts"`
 
 ### Step 3: Classify & Route New Task
@@ -235,10 +235,10 @@ Display:
 
 | Workflow Type | Skill         | Args                                                |
 | ------------- | ------------- | --------------------------------------------------- |
-| development   | `development` | `--resume [path] [--from=PHASE] [--reset-attempts]` |
+| development   | `development` | `--resume [path] [--from=<slug>] [--reset-attempts]` |
 | performance   | `performance` | `--resume [path] [--from=PHASE]`                    |
 | migration     | `migration`   | `--resume [path] [--from=PHASE]`                    |
-| research      | `research`    | `--resume [path] [--from=PHASE]`                    |
+| research      | `research`    | `--resume [path] [--from=<slug>]`                   |
 
 ---
 

package/dist/configuration/commands-config.js

@@ -1,4 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
 import { loadMarkdownDir } from "../utils/file-util.js";
+import { PLUGIN_ROOT } from "../utils/plugin-info.js";
+// Keeps the rendered body independent of the line endings of this file's storage.
+const CRLF = "\r\n";
+const REQUIRED_COMMAND_KEYS = ["name", "description"];
+/**
+ * Renders the command body for one skill from its frontmatter.
+ * Pure: one frontmatter object in, one string out.
+ */
+export const renderCommandTemplate = (data) => [
+    `CRITICAL INSTRUCTION: You MUST invoke the ${data.name} skill immediately as your FIRST action.`,
+    "",
+    "Use the Skill tool with these exact parameters:",
+    `name: "${data.name}"`,
+    `prompt: "$ARGUMENTS"`,
+].join(CRLF);
+/**
+ * Reads the frontmatter of every `skills/<slug>/SKILL.md`, one level deep.
+ * I/O and parsing only — the invocable gate and the key contract live in the
+ * registration loop. Failures are never swallowed: our own source data must not
+ * register silently incomplete.
+ */
+export const readSkillFrontmatter = () => {
+    const skillsDir = path.join(PLUGIN_ROOT, "skills");
+    const skills = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
+        if (!fs.existsSync(skillFile))
+            continue;
+        skills.push({
+            slug: entry.name,
+            data: matter(fs.readFileSync(skillFile, "utf8")).data,
+        });
+    }
+    return skills;
+};
 export const configureCommands = (config) => {
     config.command = config.command || {};
     for (const { data, content } of loadMarkdownDir("commands")) {
@@ -18,4 +58,21 @@ export const configureCommands = (config) => {
             }),
         };
     }
+    for (const { slug, data } of readSkillFrontmatter()) {
+        if (data["user-invocable"] !== true)
+            continue;
+        const missing = REQUIRED_COMMAND_KEYS.filter((key) => typeof data[key] !== "string" || data[key] === "");
+        if (missing.length > 0) {
+            throw new Error(`[owflow] Skill '${slug}' is user-invocable but is missing required frontmatter: ${missing.join(", ")}`);
+        }
+        const name = data.name;
+        // Don't overwrite commands the user has explicitly configured
+        if (config.command[name])
+            continue;
+        config.command[name] = {
+            template: renderCommandTemplate(data),
+            // A folded YAML description scalar parses with a trailing newline
+            description: data.description.trimEnd(),
+        };
+    }
 };

package/dist/configuration/skills-config.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { PLUGIN_ROOT } from "../constants.js";
+import { PLUGIN_ROOT } from "../utils/plugin-info.js";
 export const configureSkills = (config) => {
     config.skills = config.skills || {};
     config.skills.paths = config.skills.paths || [];

package/dist/index.js

@@ -4,7 +4,9 @@
  */
 import path from "node:path";
 import fs from "node:fs";
+import { PLUGIN_VERSION } from "./utils/plugin-info.js";
 import { verify_template } from "./tools/verify_template.js";
+import { fork_task } from "./tools/fork_task.js";
 import { rereadOrchestratorState } from "./hooks/session-compaction.js";
 import { guardAgainstDestructiveActions } from "./hooks/before-tool.js";
 import { configureSkills } from "./configuration/skills-config.js";
@@ -16,13 +18,14 @@ const OwflowPlugin = async ({ $, directory }) => {
     return {
         tool: {
             verify_template,
+            fork_task,
         },
         /**
          * Register owflow's skills, commands, and agents so OpenCode discovers
          * them without requiring manual config file edits.
          */
         config: async (config) => {
-            console.log("[owflow] Starting plugin installation...");
+            console.log(`[owflow] Starting plugin installation (v${PLUGIN_VERSION})...`);
             let typedConfig = config;
             // Get small_model config for alias resolution
             // Try from config parameter first, fallback to reading opencode.json
@@ -45,7 +48,7 @@ const OwflowPlugin = async ({ $, directory }) => {
             configureCommands(typedConfig);
             configureAgents(typedConfig, smallModel);
             config = typedConfig;
-            console.log("[owflow] Plugin installation completed successfully.");
+            console.log(`[owflow] Plugin installation completed successfully (v${PLUGIN_VERSION}).`);
         },
         "experimental.session.compacting": async (input, output) => {
             await rereadOrchestratorState(directory, output);

package/dist/skills/diagrams-mermaid/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: owflow:diagrams-mermaid
 description: Creates Mermaid diagrams for planning flows, component communication, and architecture views with adaptive detail selection (including C4 levels). This skill should be used when the user asks for a workflow, interaction, or architecture visualization from provided task context.
+argument-hint: "[diagram description]"
 user-invocable: true
 ---
 

package/dist/skills/flow-init/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: owflow:flow-init
 description: Initialize AI SDLC framework with intelligent project analysis and documentation generation
-argument-hint: [--standards-from=PATH]
+argument-hint: "[--standards-from=PATH]"
 user-invocable: true
 ---
 

package/dist/skills/goal-research/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: owflow:goal-research
+description: Full orchestrated research wrapper — runs ALL research steps in one session by invoking every research-* subskill in sequence with question gates between them (equivalent to the classic unified orchestrator for research). Use /owflow:research for the same lifecycle in assisted mode — tasks can mix both modes freely.
+argument-hint: "[task description | task-path] [--from=<slug>] [--type=<type>]"
+user-invocable: true
+---
+
+# Orchestrated Research Wrapper
+
+Autonomous mode for research tasks. Initializes (or resumes) the task, then invokes every required `research-*` subskill back-to-back via the Skill tool, pausing at gates between subskills. Shares `orchestrator-state.yml` with assisted mode (`/owflow:research`) — tasks can mix both modes freely.
+
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — orchestrated mode exception: each subskill's own Exit Gate acceptance question IS the loop gate (Accept = continue to the next subskill).
+
+## Input / Output Artifacts
+
+| Artifact                            | Normal mode (this wrapper)                                                  | Quick mode (`research-quick`)                                                                |
+| ----------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Consumed: argument (question / path)| research question (new task) or task path/identifier (resume)                 | n/a — this wrapper never starts a quick run; a completed quick pass just skips rows 2-3            |
+| Consumed/produced: all task artifacts| owned entirely by the invoked subskills (none here — delegate, never inline) | same — the subskills run at full fidelity after a quick pass                                       |
+| State write                         | `orchestrator.task_ids` (task items) + `orchestrator.updated` only            | none additional — state was already written by the quick pass                                      |
+
+## Entry Gate
+
+Identical to the research dispatcher — complete ALL of its entry-gate steps first (see `../research/SKILL.md` Entry Gate):
+
+1. Read the framework reference files NOW, exactly as the research dispatcher's Step 1: the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md), the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), and the [Orchestrator Patterns](../orchestrator-framework/references/orchestrator-patterns.md).
+2. Resolve the argument the same way the research dispatcher does: task path or identifier (a directory, or a directory name under `.owflow/tasks/research/`) → **resume mode** (read `orchestrator-state.yml`, validate expected artifacts for `completed_phases`; find the first step slug NOT in `completed_phases`, with `--from=<slug>` overriding); a research question (free text) → new task; nothing provided → ask via `question` — "What is your research question?" — then WAIT. Missing state file → print `No research task found at <path>. Run /owflow:research <question> to start from scratch.` and STOP.
+3. Initialize (new task) exactly as the dispatcher: create `.owflow/tasks/research/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the research template — `task.title` / `task.description` from the question, `task.status: in_progress`, `orchestrator.task_path`, `orchestrator.entry_point: "research"`. **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-research.yml`. No project-docs discovery at this layer — the `research-plan` brief step owns it.
+4. Command flags: `--type=TYPE` → `research_context.research_type`. Subskills read it from there. This wrapper never forwards quick runs. The optional brainstorm/design chain has no flags — the chain decision is asked at the gate after synthesis (row 4 below) or made by manually invoking the optional subskills.
+5. Create ONE task item via `TaskCreate` per subskill in the upcoming loop (subject: `"<step name>: <subskill>"`, e.g. `"Brief + plan: research-plan"`), then set the execution order with `TaskUpdate addBlockedBy` (plan → gather → synthesize → optional chain (gate question) → finalize). On resume, refresh the already-evidenced items instead of re-creating them. Update statuses as the loop progresses.
+
+**Output**:
+
+```
+🚀 Orchestrated Research
+
+Task: [research question]
+Directory: [task-path]
+Loop: research-plan → research-gather → research-synthesize → [research-brainstorm] → [research-converge] → [research-design] → research-finalize (chain asked at the gate)
+```
+
+---
+
+## The Loop
+
+For each subskill in sequence, execute — skipping any row whose condition is not met (a row whose slug is already in `completed_phases` counts as done):
+
+1. **Announce**: 1-line step banner.
+2. **Invoke**: Skill tool with `name: "<subskill>"` and `prompt: "<task-path> [flags relevant to that subskill]"`. The subskill owns its Entry Gate, delegation, and state updates.
+3. **Verify handback**: after the skill returns, re-read `orchestrator-state.yml` — confirm the expected step slugs were appended to `completed_phases` (per the Sequence and Conditionals table). A user-chosen skip of `research-brainstorm` or `research-design` appends no slug — the gate answer itself settles the decision, and the loop continues to the next selected row (or to finalize). Do not treat a skipped optional subskill as an early stop. If a subskill stopped early (entry check failed), STOP the loop and relay its routing message to the user.
+4. **Gate (subskill's Exit Gate is the loop gate)**: each subskill presents its results box and fires its own results-acceptance `question` before its handoff hint (Orchestrated-mode exception, [Gate Contract](../orchestrator-framework/references/gate-contract.md)). [Rule 5 of the Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md) — "subskills only SUGGEST the next command" — is superseded for Accept: when the user answers **Accept** to the subskill's Exit Gate question pointing at the next subskill in this loop, treat that as "continue to the next subskill" and invoke it. Any other answer (Adjust / Discuss / Stop / other options picked) ends the loop the same way a rejected gate would.
+   - **Exception**: the per-area convergence `question`s `research-converge` fires (one area, one question) are part of that subskill's own decision flow — they are NOT the loop gate and are NEVER auto-accepted or answered by this wrapper. There is exactly ONE gate definition per subskill hop; the wrapper adds NO second consecutive `question`.
+   - **Condensed lane**: this wrapper never starts a quick run. A task already started with `/owflow:research-quick` enters the loop with `brief-written` … `synthesis-complete` already recorded, so those rows are skipped like any other completed slug. An interrupted quick pass (those slugs missing) is not finished condensed here — the user runs `/owflow:research-quick <task-path>` for that.
+
+### Sequence and Conditionals
+
+| Order | Subskill           | Run when (from state)                                                                                             |
+| ----- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| 1     | research-plan      | Always (new task or partial foundation)                                                                                 |
+| 2     | research-gather    | `plan-created` completed (parses `## Gathering Strategy`, or falls back to 4 default categories; existing findings count as done) |
+| 3     | research-synthesize| `findings-gathered` completed                                                                                       |
+| 4     | chain decision     | `synthesis-complete` completed — the wrapper asks via `question`: brainstorm → converge → design, design-only, or straight to finalize |
+| 5     | research-brainstorm| User chose brainstorming at the gate (invoking/sequencing the skill IS the decision)                                 |
+| 6     | research-converge  | `alternatives-generated` completed (brainstorm ran)                                                                 |
+| 7     | research-design    | User chose design — after `approaches-chosen`, or the design-only branch (seeded from the research report)           |
+| 8     | research-finalize  | Foundation complete + optional chain settled (every step the user chose to run is recorded)                          |
+
+A completed quick pass already recorded `brief-written` … `synthesis-complete`, so rows 2-3 are skipped as already done and the loop continues at row 4 (the chain decision). This wrapper never starts a quick run.
+
+The optional chain is the user's choice — asked at the gate (row 4) or made by manually invoking the optional subskills. There is no enablement flag in state:
+
+- Brainstorm chosen → `research-brainstorm` → `research-converge` → design (if chosen) → finalize.
+- Design-only chosen → skip the brainstorm + converge rows → `research-design` → finalize.
+- Neither chosen → all conditional rows are skipped → `research-finalize`.
+
+`research-completed` already in `completed_phases` → the task is TERMINAL: skip the Loop and present the wrapper Exit Gate.
+
+**Interruptible**: at any gate the user may answer "stop" — print the standard handoff block (next command + `/owflow:research <task-path>` resume hint) and end the session. The task resumes later in either mode.
+
+---
+
+## Exit Gate
+
+When research-finalize completes (`task.status: completed`):
+
+1. Mark the final task item completed via `TaskUpdate`.
+2. Present the workflow results box:
+
+```markdown
+## ✅ RESEARCH WORKFLOW COMPLETE — <research question>
+
+**Steps** — [executed step slugs, e.g. brief-written → plan-created → findings-gathered → synthesis-complete → alternatives-generated → approaches-chosen → design-generated → research-completed]
+**Confidence** — [research_context.confidence_level]
+**Decisions** — [count of ADRs in the decision log, if design ran]
+**Artifacts** — [artifact inventory: outputs/research-report.md always; outputs/solution-exploration.md / outputs/high-level-design.md / outputs/decision-log.md conditionally]
+```
+
+3. Use `question` — "Are these results correct?" with options: **Accept** (print follow-up suggestions: clear context, then `/owflow:development <task-path>` to build on this research, `/owflow:standards-update "<lesson>"` if a standard surfaced, then end) / **Adjust** (re-open the relevant `/owflow:research-*` skill with the corrections) / **Discuss** (walk through the research summary) / **Stop here** (print the resume command `/owflow:research <task-path>` and end).
+
+Then end. No further owflow phase commands are required.
+
+---
+
+## Loop Rules
+
+- **Delegate, never inline**: the wrapper only sequences — all step work happens inside subskills. If you catch yourself researching/authoring outside a subskill, STOP and invoke the subskill instead.
+- **State is the truth**: gates and routing read `orchestrator-state.yml`, not memory. Re-read after every subskill returns.
+- **Same state schema as assisted mode**: `completed_phases` step slugs (`brief-written` … `research-completed`) are identical; resume works across modes.
+- **Wrapper writes almost nothing**: step slugs, summaries, and outputs belong to the subskills — this wrapper writes ONLY `orchestrator.task_ids` (task items) and `orchestrator.updated` (timestamps).
+
+## Command Integration
+
+Invoked via:
+
+- `/owflow:goal-research [question] [--type=TYPE]` (new)
+- `/owflow:goal-research [task-path] [--from=<slug>]` (resume)
+
+Alternative: `/owflow:research` — same task in assisted mode (one subskill per invocation, fresh context each step).

package/dist/skills/html-renderer/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: owflow:html-renderer
 description: Render a markdown plan, idea, RFC, or design note into a self-contained, share-ready HTML file using the warm editorial visual system bundled under `references/`. Use this skill whenever the user asks to "render", "convert", "turn into HTML", "make a nice HTML version", "share this as a page", or "make this look good" for a markdown file containing a plan, proposal, idea, brief, RFC, design note, or pitch — even if they don't explicitly say "HTML". The output is a single .html file with all CSS inlined, written next to the source .md, that visually matches the reference layout in `references/index.html` and uses tokens from `references/tokens.json`.
+argument-hint: "[path to markdown file]"
 disable-model-invocation: true
 user-invocable: true
 ---

package/dist/skills/migration/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: owflow:migration
 description: Orchestrates the complete migration workflow from current state analysis through implementation to compatibility verification. Handles technology migrations, platform changes, and architecture pattern transitions with adaptive risk assessment, incremental execution, and rollback planning. Use when migrating technologies, platforms, or architecture patterns.
+argument-hint: "[task description]"
 user-invocable: true
 ---
 

package/dist/skills/orchestrator-framework/references/command-namespacing.md

@@ -2,6 +2,6 @@
 
 How commands and skills are named and referenced. Extracted from `orchestrator-patterns.md` (Section 8) so skills can link to it directly.
 
-- Slash commands registered from `src/commands/*.md` use `name: owflow:<command>` in frontmatter; users invoke `/owflow:<command>`.
+- Slash commands registered from `src/skills/*/SKILL.md` and from the maintained `src/commands/*.md` use `name: owflow:<command>` in frontmatter; users invoke `/owflow:<command>`.
 - **Skill `name:` fields are prefixed too.** Skill-tool invocations (`skill: "owflow:development"`, `skills:` frontmatter preloads, work.md routing) always reference `owflow:`-prefixed skill names.
 - Handoff messages, docs, and cross-references always display the prefixed slash command — never the bare skill name — in user-facing text.

package/dist/skills/orchestrator-framework/references/dispatcher-handoff.md

@@ -12,7 +12,14 @@ Orchestrators MAY delegate phase bodies to user-invocable **subskills** instead
 ## Rules
 
 1. **State file is canonical.** `orchestrator-state.yml` remains the single source of truth. Subskills read it on entry and write step results on exit. `completed_phases` values MUST stay stable so both modes intermix freely on the same task.
-   - **Value convention**: `completed_phases` / `failed_phases` / `auto_fix_attempts` keys are **descriptive step slugs**, not `phase-N` numbers. The development workflow defines the canonical slugs (`codebase-analysed`, `gap-analysed`, `tdd-red-proven`, `spec-written`, `spec-audited`, `plan-created`, `implementation-done`, `tdd-green-proven`, `options-chosen`, `verification-done`, `e2e-run`, `docs-generated`, `task-completed` — see `skills/development/SKILL.md` routing table and `templates/orchestrator-state-development.yml`). New orchestrators SHOULD use descriptive step slugs too; older orchestrators (performance, migration, research) still use `phase-N` and MUST be kept internally consistent.
+   - **Value convention**: `completed_phases` / `failed_phases` / `auto_fix_attempts` keys are **descriptive step slugs**, not `phase-N` numbers. Canonical slugs per workflow:
+
+   | Workflow     | Slugs                                                                                                                                                                      | Routing table                    | Template                                       |
+   | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ---------------------------------------------- |
+   | development  | `codebase-analysed`, `gap-analysed`, `tdd-red-proven`, `spec-written`, `spec-audited`, `plan-created`, `implementation-done`, `tdd-green-proven`, `options-chosen`, `verification-done`, `e2e-run`, `docs-generated`, `task-completed` | `skills/development/SKILL.md`  | `templates/orchestrator-state-development.yml` |
+   | research     | `brief-written`, `plan-created`, `findings-gathered`, `synthesis-complete`, `alternatives-generated`, `approaches-chosen`, `design-generated`, `research-completed`        | `skills/research/SKILL.md`       | `templates/orchestrator-state-research.yml`    |
+   | performance  | `phase-N` (legacy holdout — kept internally consistent)                                                                                                                     | `skills/performance/SKILL.md`    | `templates/orchestrator-state-performance.yml` |
+   | migration    | `phase-N` (legacy holdout — kept internally consistent)                                                                                                                     | `skills/migration/SKILL.md`      | `templates/orchestrator-state-migration.yml`   |
 2. **Subskills are self-contained.** Each has: an entry check (validate state + prerequisite artifacts), an execute section (delegation via Skill/Task tools per the [Delegation Rules](delegation-rules.md)), and an exit (state update + closing ritual). **State updates are per-step**: a subskill writes `orchestrator-state.yml` immediately after each of its steps completes — appending only the step slug actually performed, bumping `orchestrator.updated`, recording failures in `failed_phases`/`auto_fix_attempts`, and validating with `verify_template` — never as a single end-of-skill write.
 3. **Closing ritual (handoff) → Exit Gate.** Every subskill ends with the **Exit Gate** contract, see [Gate Contract](gate-contract.md) (results box → results-acceptance question → next-step hint on accept → STOP).
 4. **Entry checks replace phase gates in assisted mode.** A subskill invoked directly must validate the same prerequisites a phase gate would (e.g., spec exists before audit) and route to the prerequisite's command if missing — via its **Entry Gate** ([Gate Contract](gate-contract.md)).