owflow 0.3.0 → 0.4.2

package/dist/commands/goal-research.md

@@ -0,0 +1,33 @@
+---
+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>]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:goal-research skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "goal-research"
+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 the orchestrated loop by using /owflow:goal-research.
+Invoke the skill now and let it sequence all research subskills with gates between them.
+
+---
+
+## About This Workflow
+
+Autonomous mode for research tasks: initializes (or resumes) the task, then invokes every required
+research subskill in sequence (plan → gather → synthesize → optional chain as chosen at the gate → finalize),
+pausing at question gates. Shares orchestrator state with assisted mode — tasks can mix both
+modes freely (assisted mode is `/owflow:research`).
+
+See `skills/goal-research/SKILL.md` for the loop rules and
+`skills/research/SKILL.md` for the dispatcher alternative.

package/dist/commands/research-brainstorm.md

@@ -0,0 +1,33 @@
+---
+name: owflow:research-brainstorm
+description: Research skill — optional step. Brainstorms solution alternatives from multiple perspectives and records them for the later convergence step. Invoking this step means you chose to brainstorm.
+argument-hint: "[task-path-or-identifier]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-brainstorm skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-brainstorm"
+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 step by using /owflow:research-brainstorm.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Part of the research workflow. See `skills/research-brainstorm/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)

package/dist/commands/research-converge.md

@@ -0,0 +1,33 @@
+---
+name: owflow:research-converge
+description: Research skill — optional step after brainstorming. Walks through every decision area one at a time — all alternatives with full detail, one question per area — and records the chosen approach for each.
+argument-hint: "[task-path-or-identifier]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-converge skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-converge"
+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 step by using /owflow:research-converge.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Part of the research workflow. See `skills/research-converge/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)

package/dist/commands/research-design.md

@@ -0,0 +1,33 @@
+---
+name: owflow:research-design
+description: Research skill — optional step. Asks for your design preferences, creates the high-level architecture design together with its decision log, and refines the diagrams. Invoking this step means you chose to design.
+argument-hint: "[task-path-or-identifier]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-design skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-design"
+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 step by using /owflow:research-design.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Part of the research workflow. See `skills/research-design/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)

package/dist/commands/research-finalize.md

@@ -0,0 +1,33 @@
+---
+name: owflow:research-finalize
+description: Research skill — terminal step. Inventories all research outputs (the research report always, brainstorm and design artifacts when they exist), presents the workflow results, and gets your confirmation that the research is correct. Marks the task complete.
+argument-hint: "[task-path-or-identifier]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-finalize skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-finalize"
+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 step by using /owflow:research-finalize.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Terminal step of the research workflow. Inventory of outputs, results box, confirmation; then assisted mode suggests development handoff. See `skills/research-finalize/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)

package/dist/commands/research-fork.md

@@ -0,0 +1,40 @@
+---
+name: owflow:research-fork
+description: 'Utility command for the research workflow — fork an existing research task into a new one that diverges at a chosen completed step (the copied state is trimmed so the fork continues from that step onwards; the source stays untouched). Pass just the task path: the skill reads the source, then asks intent, fork point, and name with suggestions derived from that research.'
+argument-hint: "<task-path-or-identifier> [\"<what this fork should explore>\"] [--from=<slug>] [--name=\"...\"]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-fork skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-fork"
+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 step by using /owflow:research-fork.
+Invoke the skill now and let it copy the task, update orchestrator state,
+and present the fork summary.
+
+---
+
+## About This Workflow
+
+Utility skill of the research workflow — NOT a pipeline step. Copies a research task directory wholesale into a new task that diverges from the previous run at a chosen fork point (`--from=<slug>`); the copied state is trimmed to continue from the fork point onwards. See `skills/research-fork/SKILL.md` for complete documentation.
+
+Usage:
+
+- `/owflow:research-fork <task-path>` — bare path; the skill asks the remaining questions
+- `/owflow:research-fork <task-path> "explore the cost angle"` — the quoted text answers the intent question
+- `--from=<step-slug>` / `--name="<short name>"` — skip the matching question entirely
+
+Related entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)
+- After forking: `/owflow:research <fork-path>` resumes the fork at the first step after the fork point.

package/dist/commands/research-gather.md

@@ -0,0 +1,33 @@
+---
+name: owflow:research-gather
+description: Research skill — reads the plan's Gathering Strategy and launches the parallel information-gatherer agent fan in ONE message, then merges per-category findings. Ends the gathering step of the research workflow (findings-gathered) and continues with research-synthesize.
+argument-hint: "[task-path-or-identifier]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-gather skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-gather"
+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 step by using /owflow:research-gather.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Part of the research workflow. See `skills/research-gather/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)

package/dist/commands/research-plan.md

@@ -0,0 +1,37 @@
+---
+name: owflow:research-plan
+description: Research skill — creates the research brief, delegates methodology selection and planning to the research-planner agent, and writes the research plan with a parsable Gathering Strategy. First work phase of the research workflow; continues with research-gather.
+argument-hint: "[task-path-or-identifier | \"description\"]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-plan skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-plan"
+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 step by using /owflow:research-plan.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Part of the research workflow. See `skills/research-plan/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)
+
+Quick lane:
+
+- `/owflow:research-quick "<description>"` — condensed research task: bootstraps a standard research task and then fuses brief, plan, gather, and synthesis into one pass — continuable with any research subskill

package/dist/commands/research-quick.md

@@ -0,0 +1,37 @@
+---
+name: owflow:research-quick
+description: Research skill — the quick lane. Bootstraps a standard research task and fuses brief, plan + sources, gather, and synthesis into one condensed pass — the only place where the planner delegation, the gatherer fan, and the synthesizer delegation are condensable. Produces the same standard artifacts and state as the full lane; continuable by any research subskill at full fidelity.
+argument-hint: "[task-path-or-identifier | \"description\"]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-quick skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-quick"
+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 step by using /owflow:research-quick.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Part of the research workflow. See `skills/research-quick/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)
+
+Quick lane:
+
+- `/owflow:research-quick "<description>"` — condensed research task: bootstraps a standard research task and then fuses brief, plan, gather, and synthesis into one pass — continuable with any research subskill

package/dist/commands/research-synthesize.md

@@ -0,0 +1,33 @@
+---
+name: owflow:research-synthesize
+description: Research skill — delegates synthesis and evidence-based reporting to the research-synthesizer agent, producing the synthesis document and the comprehensive research report with per-finding confidence. Closes the research foundation (synthesis-complete) at the boundary with the optional chain (user choice).
+argument-hint: "[task-path-or-identifier]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research-synthesize skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research-synthesize"
+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 step by using /owflow:research-synthesize.
+Invoke the skill now and let it execute the step, update orchestrator state,
+and present results with next-step suggestions.
+
+---
+
+## About This Workflow
+
+Part of the research workflow. See `skills/research-synthesize/SKILL.md` for complete step documentation.
+
+Entry points:
+
+- `/owflow:research <description | task-path>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)

package/dist/commands/research.md

@@ -1,36 +1,55 @@
----
-name: owflow:research
-description: Orchestrates comprehensive research workflows from question definition through findings documentation. Handles technical, requirements, literature, and mixed research types with adaptive methodology, multi-source gathering, pattern synthesis, and evidence-based reporting. Supports standalone research tasks and embedded research phase in other workflows.
-argument-hint: [task description]
----
-
-CRITICAL INSTRUCTION: You MUST invoke the owflow:research skill immediately as your FIRST action.
-
-Use the Skill tool with these exact parameters:
-name: "research"
-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 /owflow:research.
-Invoke the skill now and let it orchestrate the complete workflow.
-
----
-
-## About This Workflow
-
-Orchestrates comprehensive research workflows from question definition through findings documentation. Handles technical, requirements, literature, and mixed research types with adaptive methodology, multi-source gathering, pattern synthesis, and evidence-based reporting. Supports standalone research tasks and embedded research phase in other workflows.
-
-The skill handles:
-
-- Task directory creation and state management
-- Phase execution with interactive gates
-- Subagent delegation for specialized work
-- Pause/resume capability
-
-See `skills/research/SKILL.md` for complete workflow documentation.
+---
+name: owflow:research
+description: Research workflow dispatcher. Initializes/resumes research tasks, derives the next step from state, and hands off to the matching /owflow:research-* subskill. Handles comprehensive research and analysis — technical, requirements, literature, and mixed research types with adaptive methodology, multi-source gathering, pattern synthesis, and evidence-based artifact outputs (findings documentation). Supports standalone research tasks and embedded research phases feeding development workflows.
+argument-hint: "[task description | task-path] [--from=<slug>] [--type=<type>]"
+---
+
+CRITICAL INSTRUCTION: You MUST invoke the owflow:research skill immediately as your FIRST action.
+
+Use the Skill tool with these exact parameters:
+name: "research"
+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 /owflow:research.
+Invoke the skill now and let it dispatch the matching research step.
+
+---
+
+## About This Workflow
+
+Research workflow **dispatcher** (assisted mode). The skill handles:
+
+- Task initialization/resume and state management (`orchestrator-state.yml`)
+- Research context intake and `--type` flag handling
+- Deriving the next pending step from state (descriptive slugs, NOT phase numbers)
+- Handing off to the matching `/owflow:research-*` subskill, then stopping
+
+Run `/owflow:goal-research` instead for autonomous mode (all subskills in one session with gates).
+
+Quick lane: starts only via `/owflow:research-quick "<description>"` — a condensed research task that fuses brief, plan, gather, and synthesis into one pass, continuable by any research subskill.
+
+Forking: `/owflow:research-fork <task-path> ["<what this fork should explore>"] [--from=<slug>]` copies a research task to a new task diverging at a chosen completed step (directory copied verbatim, `completed_phases` trimmed) — original task untouched. A bare task path is enough: the skill asks for the intent, fork point, and name with suggestions taken from that research.
+
+Entry points:
+
+- `/owflow:research <description>` — start or resume a research task (assisted mode)
+- `/owflow:goal-research <description>` — run all steps in one loop (orchestrated mode)
+
+Steps (each works on the shared task directory):
+
+- `/owflow:research-plan <description | task-path>` — brief, methodology & plan
+- `/owflow:research-gather <task-path>` — parallel findings fan
+- `/owflow:research-synthesize <task-path>` — synthesis & research report
+- `/owflow:research-brainstorm <task-path>` — solution alternatives (optional, user's choice)
+- `/owflow:research-converge <task-path>` — per-area decisions (after brainstorming)
+- `/owflow:research-design <task-path>` — high-level design (optional, user's choice)
+- `/owflow:research-finalize <task-path>` — completion & handoff
+
+See `skills/research/SKILL.md` for the routing table and `skills/research-*/SKILL.md` for step documentation.

package/dist/commands/work.md

@@ -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/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/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).