owflow 0.2.0 → 0.4.2

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

@@ -0,0 +1,190 @@
+---
+name: owflow:research-fork
+description: Research utility — forks a research task by copying its directory wholesale into a NEW task, then trimming the copied state so the fork continues from a chosen completed step (fork point) onwards. Passing only the task path is enough — the skill orients on the source research, then asks the user (with suggestions) for the fork's intent, fork point, and name. The source task is never modified.
+argument-hint: "<task-path-or-identifier> [\"what this fork should explore\"] [--from=<slug>] [--name=\"...\"]"
+user-invocable: true
+---
+
+# Research Fork — Task Divergence Copy (utility, no phases)
+
+Utility skill for the research workflow. Copies an existing research task directory (`.owflow/tasks/research/<name>`) **wholesale** into a new task so it can **diverge from the previously run one** — e.g. re-run synthesis or the optional chain (brainstorm → converge → design) with different choices while the original stays intact.
+
+The copy is verbatim — every artifact, including outputs of steps after the fork point (the source keeps them too; the resumed step overwrites its outputs). The fork's `orchestrator-state.yml` is then trimmed: `completed_phases` cut at the **fork point** (a completed step slug), so the fork **continues from the point onwards**. The fork then continues at full fidelity from the fork point with every research subskill.
+
+**The task path is the only required input.** A bare `/owflow:research-fork <task-path>` is answered by a short guided setup: the skill reads the source research, then asks up to three questions — intent, fork point, name — each pre-filled with suggestions drawn from that research, and confirms the resulting plan before copying. Every question is skipped when its input is already supplied: a quoted description answers the intent question, `--from=<slug>` the fork point, `--name="..."` the name. Nothing is ever guessed silently — suggestions are proposals, the user answers.
+
+Copy mechanics live in the deterministic `fork_task` tool (delegation anti-pattern does not apply — this is a file-copy utility, NOT research work; never perform the copy with bash `cp` yourself). State lives in `orchestrator-state.yml` — this skill reads source state on entry; the tool writes the forked state.
+
+This is NOT a pipeline step: it creates a task, stops at its Exit Gate, and never chains into other skills. Fork anytime — including on `task.status: completed` tasks (`research-completed` is trimmed from the fork's `completed_phases`).
+
+## Entry Gate
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
+- Any remaining free text in the argument is the **intent description** (see Guided setup Q1). It never participates in path resolution.
+- If no path/identifier is present → `question` — "Which research task should be forked?" — listing the directory names under `.owflow/tasks/research/` as options (free-form path also accepted), then re-route. If the given argument does **not exist** or matches **no identifier** → print:
+
+```
+BLOCKED — no research task found at <arg>.
+
+Quick way out:
+  /owflow:research-fork <task-path-or-identifier> ["<what this fork should explore>"]
+
+Available research tasks:
+<list directory names under .owflow/tasks/research/, one per line, if any>
+```
+
+then STOP (never guess or auto-pick a task). For a fresh research question instead: `/owflow:research <question>`.
+
+### Prerequisites
+
+| Required for this skill | Where verified                                             | Produced by                                    |
+| ----------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml`                       | `/owflow:research <question>` or `/owflow:research-quick` |
+| Forkable research       | at least one completed step in `completed_phases`           | any research subskill                          |
+
+1. **Read `orchestrator-state.yml`** from the task path. Missing / unreadable → print the blocked block (as above, plus quality gate: forkable research needs at least one completed step — run `/owflow:research-plan <task-path>`, then `/owflow:research-gather <task-path>`, then `/owflow:research-synthesize <task-path>` first) and STOP.
+
+## Orient (read the source — suggestions depend on it)
+
+The guided setup is only as good as what the agent actually read. Before asking anything, gather just enough of the source to name its angles, its decisions, and its loose ends:
+
+1. From state: `task.title`, `research_context.research_question`, `scope.included` / `.excluded`, `research_context.phase_summaries.*` (especially `converge.decision_areas[].area|chosen_approach` and `converge.deferred_ideas`), `research_context.confidence_level`.
+2. From artifacts, when they exist: the conclusions / open questions / limitations sections of `outputs/research-report.md` and `analysis/synthesis.md`, and the alternatives in `outputs/solution-exploration.md`. Read headings and the decision-relevant parts — this is orientation, not a re-run of the research.
+3. Build the **fork-point list**: every slug in `completed_phases` (state is the truth — re-read it, don't trust memory), **excluding `research-completed`** (nothing diverges after completion), in pipeline order, each with the human step name from the [dispatcher routing table](../research/SKILL.md#routing-table-completed_phases--next-subskill):
+
+   | Fork point slug            | Step name                    | Re-runs from                          |
+   | -------------------------- | ---------------------------- | ------------------------------------- |
+   | `brief-written`            | Brief                        | research-plan                         |
+   | `plan-created`             | Plan & sources               | research-gather                       |
+   | `findings-gathered`        | Findings gathering           | research-synthesize                   |
+   | `synthesis-complete`       | Synthesis & research report  | optional chain (brainstorm / design) / finalize |
+   | `alternatives-generated`   | Solution alternatives        | research-converge                     |
+   | `approaches-chosen`        | Approach convergence         | research-design / finalize            |
+   | `design-generated`         | High-level design            | research-finalize                     |
+
+4. `--from=<slug>` given → validate it against that list — mismatch → print:
+
+```
+BLOCKED — <slug> is not a completed fork point of <task-name>.
+
+Valid fork points: <comma-separated slugs from completed_phases, minus research-completed>
+Valid fork points are completed step slugs only. Re-run:
+  /owflow:research-fork <task-path> --from=<step-slug>
+```
+
+then STOP. Never fall through to the question.
+
+## Guided setup (ask what the argument did not answer)
+
+Three questions, in this order. **Ask only the unanswered ones** — each input source short-circuits its question. Every question is a `question` call; WAIT for the answer before the next. Ask no question whose answer is already in the argument, and never invent a user's intent silently.
+
+### Q1 — Intent: "What should this fork explore?"
+
+- **Answered by** a quoted description in the argument → use it verbatim, skip the question.
+- **Otherwise ask**, with 3-4 divergence angles derived from what Orient read, marked "(Recommended)" on the one you judge most useful, each description naming the evidence it comes from:
+  - re-synthesize with a different lens (e.g. another technology, a cost/constraint focus, a different scope) — from the report's open questions or low `confidence_level`
+  - explore a deferred idea — from `converge.deferred_ideas`
+  - revisit a chosen approach with an alternative — from `converge.decision_areas[].area|chosen_approach` and the alternatives in `solution-exploration.md`
+  - narrow or widen the scope — from `scope.included` / `.excluded`
+- Free-form answers are welcome and common — do not push the user toward your options.
+
+### Q2 — Fork point: "Where should the fork diverge?"
+
+- **Answered by** `--from` → validated in Orient, skip the question.
+- **Otherwise ask**, one option per fork point in pipeline order, each description = what the fork keeps and re-runs: `"keeps up to <slug> (<step name>); re-runs <next-step command>"`, plus `"(drops N later steps)"` when N > 0. Recommend the latest completed step whose re-run matches the intent — `synthesis-complete` when the intent re-thinks the findings, `approaches-chosen` when it re-opens a chosen approach, `design-generated` when it only reshapes the design, `plan-created` / `findings-gathered` when it changes the sources or scope, `brief-written` for a full restart with a different question. Mark that option "(Recommended)"; every other option stays selectable.
+
+### Q3 — Name: "Short descriptive name for the fork?"
+
+- **Answered by** `--name="..."` → that string is the name source, skip the question.
+- **Otherwise ask** with 2-3 slug candidates you derived from the intent (recommended first, marked "(Recommended)"); free-form is fine.
+
+**Derive slugs yourself** (you are the LLM; no code derives names): from the name source — the intent text, or the chosen candidate — extract 3-5 key words (Task Name Generation, [Orchestrator Patterns §5](../orchestrator-framework/references/orchestrator-patterns.md)) → lowercase kebab-case, 3-5 words of `[a-z0-9]`, no date prefix. Example: "compare caching strategies" → `compare-caching-strategies`. The final directory is `YYYY-MM-DD-<slug>` (fork execution date).
+
+### Q4 — Plan confirmation (before anything is written)
+
+Skip only when intent, fork point, and name were ALL supplied by the argument (description + `--from` + `--name`) — nothing was left to confirm. Otherwise print the fork plan and ask:
+
+```
+Fork plan
+  Source:      <source-name> (task untouched)
+  Intent:      <one line, from Q1 or the description argument>
+  Fork point:  <slug> — <step name>
+  Keeps:       <kept slugs> (verbatim)
+  Re-runs:     <first step after the fork point>
+  New task:    YYYY-MM-DD-<slug>
+```
+
+`question` — "Create this fork?" with options: **Create the fork** (Recommended) / **Change something** (user names what — re-open only that question, keep the other answers) / **Cancel** (print the resume command and end without writing anything). On Cancel: nothing has been copied — do not create the directory.
+
+If the fork-name check later reports `NAME_TAKEN`, suggest a 1-word variation and re-ask via `question`. If it reports `INVALID_NAME`, fix the slug (pattern + message tell you what broke) and retry the same source name without re-prompting unless the fix needs more than casing/spacing.
+
+## Execute (utility pass — tool does the copy)
+
+1. Call the `fork_task` tool with:
+   - `taskRoot`: `.owflow/tasks`
+   - `source`: the resolved task path (or identifier)
+   - `slug`: your derived slug
+   - `from`: the chosen fork point slug
+   - `intent`: the one-line intent (omit the key when the user gave none)
+2. **Tool-agnostic failure handling** — any tool output starting with `INVALID_SOURCE`, `UNKNOWN_STEP`, `NAME_TAKEN`, or `INVALID_NAME` → fix per the output's Hint (re-ask name on `NAME_TAKEN`/`INVALID_NAME`; re-derive fork point on the rest) and re-call the tool. Any other failure → print it and STOP.
+3. **Validate the forked state** — run the `verify_template` tool on the FORK's `orchestrator-state.yml` (`filePath: <fork-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`) — belt-and-braces over the tool's own structural check. Any report → fix per the hint, re-run.
+4. **Present the fork summary**:
+
+```
+Fork created:            <fork-path>
+Forked from:             <source-name> (task untouched)
+Intent:                  <one line, or 'n/a'>
+Fork point:              <slug> (<step name>)
+Copied:                  everything from the source (verbatim)
+State trimmed:           completed_phases cut at <slug> — resumes at the step after <slug>
+```
+
+## Fork mechanics reference (what the tool does)
+
+1. Copies the whole source task directory recursively into `<taskRoot>/research/YYYY-MM-DD-<slug>/` — all artifacts, verbatim.
+2. Rewrites only the copied `orchestrator-state.yml`: `orchestrator.completed_phases` sliced up to and including the fork point, `orchestrator.started_phase: null`, `orchestrator.entry_point: "research-fork"`, `orchestrator.task_path` → fork dir, `task.status: in_progress`, `task.title` suffixed `(fork of <source-name>)`, and `orchestrator.options.fork_information` stamped `{forked_from, fork_point, forked_at, intent}` (`intent` only when given) — merged into any pre-existing `options`.
+3. Everything else — `research_context`, `research_outputs`, timestamps — is carried verbatim from the source; the resumed step overwrites its own outputs.
+
+Validation errors surfaced by the tool: `INVALID_NAME` (slug pattern), `INVALID_SOURCE` (no research task directory / no parseable state file), `UNKNOWN_STEP` (fork point not in `completed_phases`, or `research-completed` — nothing diverges after completion), `NAME_TAKEN` (fork directory already exists).
+
+## Exit Gate
+
+Utility skill: confirm-or-revise only ([Confirm-or-Revise Exception](../orchestrator-framework/references/confirm-or-revise-exception.md)) — no pipeline next-steps, no auto-chaining.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH FORK COMPLETE — <fork name>
+
+**Source** — <source-name> (task untouched)
+**Intent** — <one line, or n/a>
+**Fork point** — <fork-point slug> (<step name>)
+**Copied** — full source directory (verbatim)
+**State trim** — completed_phases cut at <fork-point slug>
+**Fork directory** — `<fork-path>`
+
+**Fork state**
+
+- `orchestrator-state.yml` (completed_phases trimmed at <fork-point slug>, status in_progress, `options.fork_information` stamped)
+- all source artifacts, verbatim
+
+**Next ▸** `/owflow:research <fork-path>` (resume the fork; it routes to the first step after the fork point)
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Confirm** — the fork is good; end the skill (print the Next ▸ command one more time for convenience).
+- **Revise** — user specifies what to change (wrong fork point / wrong name / wrong intent): DELETE the fork directory ONLY with explicit user confirmation in that same message (`rm -rf` is destructive-hook protected for non-whitelisted agents — run it only after the user re-confirms), or re-fork under a different name; then re-present the results box.
+- **Stop here** — print the resume command (`/owflow:research-fork <task-path>`) and end.
+
+## Integration
+
+- The fork is a normal research task from here on: `/owflow:research <fork-path>` routes it, `/owflow:goal-research <fork-path>` chains it, optional-chain choice gates apply as usual.
+- Forking a FORK works — the title suffix chains (`(fork of <fork-name>)`) and `options.fork_information.forked_from` records the immediate parent.
+- The description argument also matches the dispatcher's convention of free text narrowing scope, so `/owflow:research-fork <task> explore the cost angle` behaves like `/owflow:development <task> Implement only phase 1`.
+- Development and migration tasks are NOT forkable — this skill is research-only by design.

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

@@ -0,0 +1,133 @@
+---
+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]"
+user-invocable: true
+---
+
+# Research Gather — Parallel Findings Fan (findings-gathered)
+
+Work phase of the research workflow. Reads the gathering strategy out of the research plan and launches the parallel information-gatherer fan (`analysis/findings/*.md`, one file per category). State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-plan` (produces the plan this skill parses), `/owflow:research-synthesize` (consumes the merged findings). In the quick lane, `research-quick` may author findings inline — those are pre-existing category files for this skill.
+
+## Entry Gate
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+  1. Steps that must be completed first (in order), each with its command:
+     - Research brief & plan (`brief-written`, `plan-created`) → `/owflow:research-plan <task-path>`
+  2. List available research-task identifiers (directories under `.owflow/tasks/research/`) to resume from, if any.
+  3. Hint: `Run /owflow:research-plan <task-path> first, /owflow:research <question> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill            | Where verified                                                      | Produced by                            |
+| ---------------------------------- | -------------------------------------------------------------------- | -------------------------------------- |
+| State file exists                  | `<task-path>/orchestrator-state.yml`                                 | `/owflow:research <question>` or `/owflow:research-quick` |
+| Plan exists                        | `plan-created` in `completed_phases` + `planning/research-plan.md` exists | `/owflow:research-plan <task-path>`    |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `findings-gathered`): `question` — create a fresh standard research task starting at this step, or decline → print `No research task found at <path>. Run /owflow:research <question> to start a task from scratch.` and STOP.
+2. **Content check — plan file**: Read `planning/research-plan.md`. If the file is missing → print the blocked block, then STOP (`Run /owflow:research-plan <task-path> first.`). A missing `## Gathering Strategy` section does NOT block — Execute falls back to the default 4 categories.
+3. **Skip/resume — only missing categories re-fan**: existing files under `analysis/findings/` count as done whether or not `findings-gathered` is already in `completed_phases` (artifacts before state; quick-lane and pre-split files included). Re-fan ONLY categories with no matching file, then append `findings-gathered` once every planned category has a file. All categories already present → adopt the slug if it is missing, report existing findings, and route to the Exit Gate.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                                   | Quick mode (`research-quick`)                                                              |
+| ---------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Consumed: `planning/research-plan.md`          | parsed for `## Gathering Strategy` (fallback: 4 default categories)          | same — quick plan always keeps a `## Gathering Strategy` section, pinning gather inline vs capped fan |
+| Consumed: `information-gatherer` agents (Task tool, one per category, all N in ONE message) | N agents (cap 8)                                                     | zero agents (≤2 categories, inline) or the fan capped at 3 agents                              |
+| Produced: `analysis/findings/*.md`             | exactly one per gathering category                                         | same paths — quick-lane findings are pre-existing category files here, never re-fanned          |
+| State write                                    | `findings-gathered`; `gathering_strategy`, `research_outputs.findings_directory`, `phase_summaries.gather` | same slug and fields, condensation-noted                                             |
+
+## Execute (delegated fan)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+**Scope**: normal runs — findings authored by the `research-quick` lane are treated as pre-existing category files (Entry Gate resume check) and are NOT re-gathered.
+
+### The `information-gatherer` agent
+
+Each gathering category is delegated to ONE `information-gatherer` subagent via the Task tool — one agent per category, N categories → N agents. The agent receives the category id and the task context and writes that category's findings file itself; this skill only launches the fan and merges the results. Never gather category findings inline in this skill.
+
+### Determine the gatherer count and categories
+
+1. Read the **Gathering Strategy** section from `planning/research-plan.md` (heading may carry a numeric prefix, e.g. `## 6. Gathering Strategy` — match the heading by the words "Gathering Strategy", not the exact literal)
+2. If gathering strategy found: use specified categories and count (cap at 8 max)
+3. If no gathering strategy: fall back to the default 4 categories — codebase, documentation, configuration, external — and set `source: default`
+4. Update state: `research_context.gathering_strategy`
+
+**CRITICAL: Launch all N `information-gatherer` agents in ONE message for parallel execution.**
+
+**Parallel Execution Pattern**:
+
+```
+Read gathering strategy from planning/research-plan.md
+For each category in strategy:
+  Use Task tool: information-gatherer with source_category=[category_id] → analysis/findings/[category_id]-*.md
+```
+
+> **ANTI-PATTERN — never launch the gatherer fan as sequential Task calls or via the Skill tool. The `information-gatherer` agents go through the Task tool, one call per category, all N calls in ONE message.**
+
+### Output artifact & handoff to research-synthesize
+
+The output artifact of this skill is the **findings directory**: `analysis/findings/*.md`, exactly one file per gathering category (`[category-id]-*.md` — the category ID leads the filename; e.g. `codebase-*.md`, `docs-*.md`, plus any custom categories). The file tail adds only keywords NOT already in the category ID (no stacked/repeated slugs). `research_outputs.findings_directory` records that path in state.
+
+`research-synthesize` consumes exactly these files: it reads every `analysis/findings/*.md` (the Entry Gate verifies one file per planned category exists), cross-references them in `analysis/synthesis.md`, and feeds the merged evidence into `outputs/research-report.md`. Nothing else from this skill flows downstream — the findings files ARE the contract.
+
+### Merge & close (`findings-gathered`)
+
+1. Verify one findings file per category exists under `analysis/findings/`
+2. **State write**: append `findings-gathered` to `completed_phases`; update `research_context.gathering_strategy`, `phase_summaries.gather`; set `research_outputs.findings_directory`; bump `orchestrator.updated`. On failure (or a category permanently failing): append `findings-gathered` to `failed_phases`, increment `auto_fix_attempts["findings-gathered"]`. Then re-read state + run `verify_template` (see State Update Convention).
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`findings-gathered`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the step fails or its retries are abandoned, do NOT append to `completed_phases`; instead append the step's slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["findings-gathered"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                          | Max Attempts | Strategy                                                      |
+| ----------------------------- | ------------ | ------------------------------------------------------------- |
+| Gather (`findings-gathered`)  | 3            | Retry failed agents only, continue with successful categories |
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH GATHER COMPLETE — <research question>
+
+**Categories** — [N gathered / M planned]
+**Findings files** — [list of `analysis/findings/*.md` files]
+**Source** — [planner-specified strategy / default 4-category fallback]
+
+**Artifacts**
+
+- `analysis/findings/*.md` ([per category])
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the findings are good; continue.
+- **Adjust** — re-run only the affected categories (missing/failed agents only — successful category files stay), update state and artifacts, re-present the results box.
+- **Discuss** — walk through a specific category's findings in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-gather <task-path>`) and end. Note: on a later resume, only the missing categories re-fan.
+
+### Next steps (after Accept)
+
+- `→ /owflow:research-synthesize <task-path>` — `required` next: delegates the synthesis agent for pattern analysis (`analysis/synthesis.md`) + the comprehensive research report (`outputs/research-report.md`) with confidence per finding. Remaining after: scope → optional chain → finalize.
+
+Then STOP.

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

@@ -0,0 +1,141 @@
+---
+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\"]"
+user-invocable: true
+---
+
+# Research Plan — Brief, Methodology & Plan (brief-written, plan-created)
+
+Work phase of the research workflow. Creates the research brief, delegates methodology selection and gathering-strategy planning to the `research-planner` agent, and writes the research plan. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
+- **Research question** — anything else (free text, e.g. `"evaluate caching strategies for our API"`) is treated as a new research question — the routing table asks first.
+
+Route by argument kind:
+
+| Situation                                                     | Route                                                                        |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Task path/identifier, state + question present                | Full lane below (brief step → plan step)                                     |
+| Research question                                             | Ask via `question`: full pipeline through the dispatcher / quick fused task via `/owflow:research-quick "<question>"` / cancel |
+| Missing argument                                              | Prompt for input (path, identifier, or research question), then re-route     |
+
+If the path does **not exist** or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - State initialization (`task.*`) → `/owflow:research <question>`
+2. List available research-task identifiers (directories under `.owflow/tasks/research/`) to resume from, if any.
+3. Hint: `Run /owflow:research <question> to start a task from scratch, /owflow:research-quick "<question>" for a quick fused task, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill               | Where verified                                        | Produced by                                        |
+| ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
+| State file exists                     | `<task-path>/orchestrator-state.yml`                 | `/owflow:research <question>` (dispatcher init)    |
+| Research question resolved (resume)   | `research_context.research_question` non-null in state | brief step (`brief-written`)                     |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → a question argument follows the routing table (ask first). Otherwise mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `brief-written`): `question` — create a fresh standard research task starting at this step, or decline → print `No research task found at <path>. Run /owflow:research <question> to start a task from scratch, or /owflow:research-quick "<question>" for a quick fused task.` and STOP.
+2. **Content check (resume)**: `research_context.research_question` must be non-null. If null (state exists, question never recorded), prompt via `question` — "What is your research question?" — and let the brief step record it in state.
+
+## Input / Output Artifacts
+
+| Artifact                                                              | Normal mode (full lane)                                                           | Quick mode (`research-quick`)                                                                |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Consumed: state (`research_context.research_question`, `.research_type`, `.project_doc_paths`) | input                                                                           | same — quick bootstrap already records them (condensed brief)                                  |
+| Consumed: `references/research-methodologies.md`                      | read before delegation                                                              | read by research-quick directly (no delegation)                                                |
+| Produced: `planning/research-brief.md`                                | inline (brief step)                                                                 | inline — condensed brief, identical path                                                       |
+| Produced: `planning/research-plan.md`, `planning/sources.md`           | delegated to `research-planner` (plan step)                                         | written directly inline (the ONLY exception to the planner-delegation anti-pattern)            |
+| State write                                                           | `brief-written`, `plan-created` slugs; `methodology`, `sources`, `phase_summaries.plan` | same slugs and fields, condensation-noted                                                     |
+
+3. **Skip/resume** — artifacts before state. If the file exists but its slug is missing, adopt it (append the slug, backfill still-null fields) instead of re-running:
+   - `planning/research-brief.md` exists → append `brief-written` if missing, then skip the brief step.
+   - `planning/research-plan.md` AND `planning/sources.md` exist → append `plan-created` if missing, backfill `methodology` / `sources` / `phase_summaries.plan` when still null, report the existing plan summary, and route to the Exit Gate.
+   - A slug whose artifact is missing → drop the slug and re-run that step.
+
+## Execute (full lane — inline brief, delegated planning)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) and the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md).
+
+### Brief (`brief-written`, inline)
+
+**Artifacts**: `planning/research-brief.md`
+**Resume check**: if `planning/research-brief.md` exists, adopt it (append `brief-written` if that slug is missing) and skip to the plan step.
+
+1. Parse research question (from command or prompt user)
+2. Classify research type. If `research_context.research_type` is already one of `technical`, `requirements`, `literature`, `mixed` (the dispatcher or `goal-research` wrote it from `--type`), keep that value. The template placeholder `"technical | requirements | literature | mixed"` is not a classification — auto-detect from keywords in that case. This skill's own command does not take `--type`.
+3. Determine scope (included, excluded, constraints)
+4. Define success criteria
+5. Create research brief
+6. Update state: set `research_context.research_type`, `research_question`, `scope`
+7. **Discover project documentation**: Read `.owflow/docs/INDEX.md` (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as `research_context.project_doc_paths` in state.
+
+**State write**: append `brief-written` to `completed_phases` (the brief step's fields above go in with it); bump `orchestrator.updated`. On failure: append `brief-written` to `failed_phases`, increment `auto_fix_attempts["brief-written"]`. Then re-read state + run `verify_template` (see State Update Convention).
+
+### Plan (`plan-created`, delegated)
+
+**Artifacts**: `planning/research-plan.md`, `planning/sources.md`
+**Resume check**: if `planning/research-plan.md` AND `planning/sources.md` exist, adopt them (append `plan-created` if that slug is missing; backfill `methodology`, `sources`, and `phase_summaries.plan` when still null) and skip to the Exit Gate.
+
+> **ANTI-PATTERN — never write the research plan yourself. "The question is simple" is NOT a reason to skip delegation.**
+
+1. **Read `references/research-methodologies.md` NOW using the Read tool** — research type classification, methodology selection, gathering strategies (the reference lives in this skill's own folder).
+2. **INVOKE NOW**: Task tool - `research-planner` subagent (never the Skill tool — this is an agent). Pass (Pattern 7 — accumulated context): task_path, research_brief_path, research_type, research_question, scope, project_doc_paths (from state). Output: `planning/research-plan.md`, `planning/sources.md`.
+3. **Plan parsability**: the plan SHOULD keep a `## Gathering Strategy` section (categories + count). `research-gather` parses that section; if the planner omitted it, do NOT hand-author the section in a full-lane run — note the omission in `phase_summaries.plan` and let gather fall back to its default 4 categories.
+4. **State write**: append `plan-created` to `completed_phases`; update `research_context.methodology`, `sources`, `phase_summaries.plan`; bump `orchestrator.updated`. On failure: append `plan-created` to `failed_phases`, increment `auto_fix_attempts["plan-created"]`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (e.g. `brief-written`, `plan-created`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the step fails or its retries are abandoned, do NOT append to `completed_phases`; instead append the step's slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                        | Max Attempts | Strategy                                              |
+| --------------------------- | ------------ | ----------------------------------------------------- |
+| Brief (`brief-written`)     | 1            | Prompt user for clarification if question unclear     |
+| Plan (`plan-created`)       | 2            | Expand search patterns, use fallback mixed methodology |
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH PLAN COMPLETE — <research question>
+
+**Type** — [research type]
+**Methodology** — [methodology summary from state]
+**Gathering categories** — [N categories in the plan's Gathering Strategy]
+
+**Artifacts**
+
+- `planning/research-brief.md`
+- `planning/research-plan.md` (keeps the parsable `## Gathering Strategy` section)
+- `planning/sources.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the brief/plan are good; continue.
+- **Adjust** — re-run only the affected step (brief or plan) with the user's corrections, update state and artifacts, re-present the results box.
+- **Discuss** — walk through a specific part (research type, methodology, gathering strategy) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-plan <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:research-gather <task-path>` — `required` next: launches the parallel `information-gatherer` fan and merges per-category findings (`findings-gathered`), then `research-synthesize` fuses synthesis + research report. Remaining after: optional chain (user choice) → finalize.
+
+Then STOP.

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

@@ -0,0 +1,139 @@
+---
+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\"]"
+user-invocable: true
+---
+
+# Research Quick — Condensed Brief → Synthesis (brief-written … synthesis-complete)
+
+Quick lane of the research workflow. Bootstraps a standard research task (state file, docs discovery) and then fuses brief, plan + sources, gather, and synthesis into one condensed pass. It does NOT introduce a second state format: the task gets a standard `orchestrator-state.yml` from `orchestrator-state-research.yml` with standard artifacts on the exact paths the full lane uses, so every other research subskill can pick it up afterwards and resume at full fidelity (gather re-fans only missing categories; later subskills treat existing artifacts as pre-existing). State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-plan` (the full-lane owner of the brief and plan steps this lane condenses), `/owflow:research-gather` + `/owflow:research-synthesize` (the full-lane owners of the condensed gather and synthesis steps).
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
+- **Research question** — anything else (free text, e.g. `"evaluate caching strategies for our API"`) is treated as a new research question for quick bootstrap.
+
+Route by argument kind:
+
+| Situation                                                     | Route                                                                        |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Task path/identifier, quick lane not yet complete             | Quick pass for the missing pieces (below)                                     |
+| Task path/identifier, `synthesis-complete` present            | Quick lane already ran — report existing results and route to the Exit Gate  |
+| Research question (or no argument after prompt)               | Quick bootstrap (create task + fused brief → synthesis)                      |
+| Missing argument                                              | Prompt for input (path, identifier, or research question), then re-route     |
+
+If the path does **not exist** or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - State initialization (`task.*`) → `/owflow:research <question>`
+2. List available research-task identifiers (directories under `.owflow/tasks/research/`) to resume from, if any.
+3. Hint: `Run /owflow:research <question> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill               | Where verified                                        | Produced by                                        |
+| ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
+| State file exists                     | `<task-path>/orchestrator-state.yml`                 | `/owflow:research <question>` (dispatcher init) or the quick bootstrap below |
+| Research question resolved (resume)   | `research_context.research_question` non-null in state | quick bootstrap (`brief-written`)                |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → quick bootstrap (below). On decline → print the blocked block and STOP.
+2. **Content check (resume)**: `research_context.research_question` must be non-null. If null (state exists, question never recorded), prompt via `question` — "What is your research question?" — and let the condensed brief record it in state.
+3. **Skip/resume — artifacts before state**: adopt existing artifacts instead of re-running (`planning/research-brief.md` → `brief-written`; `planning/research-plan.md` AND `planning/sources.md` → `plan-created`; findings files → `findings-gathered`; `analysis/synthesis.md` + `outputs/research-report.md` → `synthesis-complete`), then condense ONLY the quick-pass pieces that are still missing. All pieces present → report the existing results and route to the Exit Gate.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane, for comparison)                     | Quick mode (this skill's condensed pass)                             |
+| ---------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| Consumed: argument                             | task path/identifier (subskills never bootstrap)              | task path/identifier OR a research question (bootstrap + fuse in one pass) |
+| Produced: `planning/research-brief.md`         | inline (`research-plan` brief step)                           | inline — condensed brief, identical path                                   |
+| Produced: `planning/research-plan.md`, `planning/sources.md` | delegated to `research-planner`                | written directly inline (the ONLY exception to the planner anti-pattern)   |
+| Produced: `analysis/findings/*.md`             | `information-gatherer` fan (cap 8, one agent per category)    | inline with zero agents (≤2 categories) or capped fan at 3 agents          |
+| Produced: `analysis/synthesis.md`, `outputs/research-report.md` | delegated to `research-synthesizer`          | ALWAYS inline (the ONLY exception to the synthesizer anti-pattern)         |
+| State write                                    | `brief-written`, `plan-created`, `findings-gathered`, `synthesis-complete` (owned by `research-plan`/`research-gather`/`research-synthesize`) | same slugs and fields per step, `entry_point: "research-quick"`, condensation noted in `phase_summaries.gather` / `phase_summaries.synthesize` |
+
+## Quick bootstrap (no state file, question argument)
+
+1. **Create Task Directory**: `.owflow/tasks/research/YYYY-MM-DD-task-name/` (3–5 kebab-case words from the question).
+2. **Initialize State**: create `orchestrator-state.yml` from the research template with `task.title` / `task.description` from the question, `task.status: in_progress`, and `orchestrator.entry_point: "research-quick"`.
+   - **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-research.yml`.
+3. **Discover project documentation**: read `.owflow/docs/INDEX.md` (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs — and store them in `research_context.project_doc_paths` (identical to the full lane's brief step).
+4. If `.owflow/docs/` does not exist, proceed without project documentation and note the graceful-fallback hint in the completion message: `"No AI SDLC documentation found. Consider running /owflow:flow-init to initialize project documentation and coding standards."`
+
+## Fused condensed pass
+
+**MANDATORY order — brief before plan, plan before gather, gather before synthesis:**
+
+1. **Condensed brief** — run the full lane's brief step inline (parse question, classify type, determine scope, success criteria, write `planning/research-brief.md`, docs discovery when not already done). Append `brief-written` on completion and set `research_context.research_type`, `research_question`, `scope`, and `project_doc_paths` — the same fields the full-lane brief step writes.
+2. **Condensed plan + sources — written directly, NO delegation**: read the research-plan skill's `references/research-methodologies.md` using the Read tool (methodology selection still applies), then write `planning/research-plan.md` and `planning/sources.md` as separate artifacts on the exact full-lane paths. **Quick acceptance check: the plan MUST keep a `## Gathering Strategy` section (categories + count)** — this pass uses that count to choose inline gather vs a capped fan; `research-gather` parses the same section and falls back to 4 default categories only when it is absent. **This REPLACES the `research-planner` delegation (the quick lane is the ONLY exception to the plan anti-pattern)**, and it pins the gathering categories: ≤2 categories → the gather step below stays inline with zero agents; more → fan capped at 3. Append `plan-created` on completion and set `research_context.methodology`, `sources`, and `phase_summaries.plan` — the same fields the full-lane plan step writes.
+3. **Condensed gather** — when the plan's Gathering Strategy (heading matched by the words "Gathering Strategy", numeric prefix tolerated) has ≤2 categories, write the per-category finding files into `analysis/findings/` directly, zero agents (**the quick lane is the ONLY exception to the always-fan rule**); with 3+ categories, launch the fan capped at 3 `information-gatherer` agents in ONE message (same mechanics as `/owflow:research-gather`). Append `findings-gathered` on completion; set `research_context.gathering_strategy` and `research_outputs.findings_directory`; note the condensation in `phase_summaries.gather`.
+4. **Condensed synthesis — ALWAYS inline**: write `analysis/synthesis.md` (pattern analysis, cross-references, documented gaps and uncertainties) and `outputs/research-report.md` (comprehensive report answering the research question, confidence per finding) directly (**the quick lane is the ONLY exception to the `research-synthesizer` delegation**); set `research_context.confidence_level`, `research_outputs.synthesis`, and `research_outputs.research_report`. Append `synthesis-complete` on completion — condensation noted in `phase_summaries.synthesize`.
+
+Slugs are appended individually on each step's completion — never batched (see State Update Convention). Then continue with the **Exit Gate** below.
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`brief-written`, `plan-created`, `findings-gathered`, `synthesis-complete`) plus that step's fields. Never batch multiple steps into one end-of-skill write — each slug lands on its own step's completion, with the same state fields the full-lane owner writes (`methodology`/`sources`, `gathering_strategy`, `research_outputs.findings_directory`/`synthesis`/`research_report`) and condensation noted in `phase_summaries.gather` / `phase_summaries.synthesize`.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the step fails or its retries are abandoned, do NOT append to `completed_phases`; instead append the step's slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                          | Max Attempts | Strategy                                              |
+| ----------------------------- | ------------ | ----------------------------------------------------- |
+| Brief (`brief-written`)       | 1            | Prompt user for clarification if question unclear     |
+| Plan (`plan-created`)         | 2            | Expand search patterns, use fallback mixed methodology |
+| Gather (`findings-gathered`)  | 1            | Re-run the failed category only (inline or capped fan) |
+| Synthesis (`synthesis-complete`) | 1         | Re-write from existing findings and report inputs     |
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH QUICK COMPLETE — <research question>
+
+**Type** — [research type]
+**Methodology** — [methodology summary from state]
+**Gathering categories** — [N categories in the plan's Gathering Strategy]
+**Pass** — brief → plan → gather → synthesis fused inline
+
+**Artifacts**
+
+- `planning/research-brief.md`
+- `planning/research-plan.md` (keeps the parsable `## Gathering Strategy` section)
+- `planning/sources.md`
+- `analysis/findings/*.md`
+- `analysis/synthesis.md`
+- `outputs/research-report.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the condensed-pass artifacts are good; continue.
+- **Adjust** — re-run only the affected quick-pass piece (brief, plan, gather, or synthesis) with the user's corrections, update state and artifacts, re-present the results box.
+- **Discuss** — walk through a specific part (research type, methodology, findings, report) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-quick <task-path>`) and end.
+
+### Next steps (after Accept)
+
+The task is a regular research task — the optional chain is the user's choice from here:
+
+- `→ /owflow:research-brainstorm <task-path>` — brainstorm solution alternatives (→ converge → design, when wanted).
+- `→ /owflow:research-design <task-path>` — design-only branch, seeded from the research report.
+- `→ /owflow:research-finalize <task-path>` — no optional chain: inventories the outputs and completes the task.
+
+Then STOP.