owflow 0.3.0 → 0.4.3

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

@@ -0,0 +1,120 @@
+---
+name: owflow:research-brainstorm
+description: Research skill — optional subskill. Delegates multi-perspective solution-alternative generation to the solution-brainstormer agent, producing outputs/solution-exploration.md. Invoking this skill IS the decision to brainstorm — there is no enablement flag.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Brainstorm — Solution Alternatives (alternatives-generated)
+
+Work phase of the research workflow. Delegates divergent solution-alternative generation to the solution-brainstormer agent (`outputs/solution-exploration.md`). Optional phase — runs when the user chooses it: invoking this skill IS the decision to brainstorm (no enablement flag in state). There is no auto-continue into convergence: this skill's Exit Gate and `research-converge`'s Entry Gate make that boundary explicit. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-converge` (consumes the alternatives for per-area decisions). The brainstorming-techniques reference lives in this skill's own folder (`references/brainstorming-techniques.md`).
+
+## 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>`
+     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
+     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
+  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>` or `/owflow:research-quick` |
+| Foundation complete         | `synthesis-complete` in `completed_phases` + `analysis/synthesis.md` AND `outputs/research-report.md` exist | `/owflow:research-synthesize <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 `alternatives-generated`): `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. **Skip/resume**: if `alternatives-generated` is in `completed_phases`, validate `outputs/solution-exploration.md` exists; missing → re-run below; present → report the existing alternatives summary and route to the Exit Gate.
+3. **Prerequisite check**: `synthesis-complete` must be in `completed_phases`. If missing → print the blocked block, then STOP:
+   - Steps that must be completed first: synthesis (`synthesis-complete`).
+   - `Run /owflow:research-synthesize <task-path> first` (or the command for the earliest missing earlier step: `/owflow:research-plan` or `/owflow:research-gather`).
+   - If no task exists yet: `Run /owflow:research <question> to start a task from scratch.`
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                        | Quick mode (`research-quick`)                                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Consumed: `analysis/synthesis.md`, `outputs/research-report.md` | foundation inputs (from synthesize)                              | identical — research-quick produces the same standard artifacts, so this skill runs unchanged afterwards |
+| Produced: `outputs/solution-exploration.md`    | delegated to `solution-brainstormer` (Task tool)                 | NOT produced here — the quick lane stops at synthesis; the optional chain always runs as this skill    |
+| State write                                    | `alternatives-generated`; `phase_summaries.brainstorm`, `research_outputs.solution_exploration` | same (this skill never runs inside a quick pass)                                  |
+
+## Execute (delegated brainstorm)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+**Read `references/brainstorming-techniques.md` NOW using the Read tool** — divergent/convergent thinking techniques, interactive exploration, scope guardrails.
+
+> **ANTI-PATTERN — do NOT generate solution alternatives inline. "The question is simple" is NOT a reason to skip delegation. The solution-brainstormer agent has specialized multi-perspective analysis capabilities.**
+
+1. **INVOKE NOW**: Task tool - `solution-brainstormer` subagent (never the Skill tool — this is an agent). Pass (Pattern 7 — accumulated context):
+   - `task_path`, `synthesis_path` (`analysis/synthesis.md`), `research_report_path` (`outputs/research-report.md`)
+   - `output_path`: `outputs/solution-exploration.md` — brainstormer MUST write to this exact path
+   - Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries` (foundation slugs)
+   - `project_doc_paths` (from state)
+
+2. > **SELF-CHECK**: After the Task tool returns, verify `outputs/solution-exploration.md` exists and contains alternatives. If missing: **STOP. Do NOT proceed to convergence or design.** Re-invoke the brainstormer with corrected context (ensure `output_path` is `outputs/solution-exploration.md`). If a second attempt also fails, use `question` to report the failure and ask whether to retry or skip brainstorming.
+
+3. On a user-chosen skip (via `question` after repeated failures): record the reason in `phase_summaries.brainstorm`. Do not append `alternatives-generated` to `completed_phases` and do not append a `failed_phases` entry (a deliberate decision, not a failure). Then present the Exit Gate: the results box notes the skip, and the next step follows the user's call (`→ /owflow:research-design <task-path>` for the design-only branch, otherwise `→ /owflow:research-finalize <task-path>`).
+
+### Close (`alternatives-generated`)
+
+1. **State write**: append `alternatives-generated` to `completed_phases` after the SELF-CHECK passes; update `phase_summaries.brainstorm`; set `research_outputs.solution_exploration`; bump `orchestrator.updated`. On failure: append `alternatives-generated` to `failed_phases`, increment `auto_fix_attempts["alternatives-generated"]`. 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 (`alternatives-generated`) 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 brainstormer delegation fails or its retries are abandoned, do NOT append `alternatives-generated` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["alternatives-generated"]`. A user-chosen skip is not a failure: record the reason in `phase_summaries.brainstorm` (see Execute step 3) instead of writing `failed_phases`.
+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                                            |
+| ----------------------------------- | ------------ | ---------------------------------------------------- |
+| Brainstorm (`alternatives-generated`) | 2          | Re-invoke solution-brainstormer with adjusted context |
+
+## 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. There is no auto-continue into convergence — converge's Entry Gate re-validates the artifact. A user-chosen skip still uses this Exit Gate; its results box says the step was skipped and why.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH BRAINSTORM COMPLETE — <research question>
+
+**Type** — [research type]
+**Decision areas** — [N areas surfaced in solution-exploration.md]
+**Alternatives** — [total alternatives across areas]
+
+**Artifacts**
+
+- `outputs/solution-exploration.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the alternatives are good; continue.
+- **Adjust** — re-invoke the brainstormer with the user's corrections (refined scope or emphasis), update state and artifacts, re-present the results box.
+- **Discuss** — walk through specific alternatives or a decision area in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-brainstorm <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- Alternatives produced → `→ /owflow:research-converge <task-path>` — `required` next: presents the alternatives per decision area with identical full detail, records each `chosen_approach` in state, and resolves the combination (`approaches-chosen`). Remaining after: design (when the user wants it) → finalize.
+- User-chosen skip → `→ /owflow:research-design <task-path>` (design-only branch, seeded from the research report) or `→ /owflow:research-finalize <task-path>`, per the user's call. Do not suggest converge — there are no alternatives to converge on.
+
+Then STOP.

package/dist/skills/{research → research-brainstorm}/references/brainstorming-techniques.md

@@ -1,6 +1,6 @@
 # Brainstorming Techniques
 
-These techniques guide Phase 3 (Solution Brainstorming) of the research workflow. They provide patterns for expanding the solution space, evaluating alternatives, and managing scope.
+These techniques guide the Solution Brainstorming phase of the research-brainstorm skill. They provide patterns for expanding the solution space, evaluating alternatives, and managing scope.
 
 ---
 

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

@@ -0,0 +1,130 @@
+---
+name: owflow:research-converge
+description: Research skill — optional subskill. Presents the brainstorming alternatives for EVERY decision area with identical full detail — one area, one question — records each chosen approach in phase_summaries.converge.decision_areas (approaches-chosen). Never a combined summary-table confirm.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Converge — Per-Area Decisions (approaches-chosen)
+
+Work phase of the research workflow. Interactive convergence: presents the brainstorming alternatives for each decision area — one area, one dedicated `question` — and records the chosen combination in state (state-only; no new artifacts). Conditional optional phase — runs only when brainstorming ran. There is no auto-continue from brainstorm: this skill's Entry Gate re-checks the artifact. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-brainstorm` (produces `outputs/solution-exploration.md`, which this skill parses), `/owflow:research-design` (consumes the chosen combination as `selected_approach`), `/owflow:research-finalize` (the route when design is off).
+
+## 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>`
+     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
+     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
+     - Solution alternatives (`alternatives-generated`) → `/owflow:research-brainstorm <task-path>`
+  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>` or `/owflow:research-quick` |
+| Foundation complete     | `synthesis-complete` in `completed_phases` + `analysis/synthesis.md` exists                 | `/owflow:research-synthesize <task-path>`                          |
+| Alternatives exist      | `alternatives-generated` in `completed_phases` + `outputs/solution-exploration.md` exists   | `/owflow:research-brainstorm <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 `approaches-chosen`): `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. **Prerequisite check**: `synthesis-complete` AND `alternatives-generated` must be in `completed_phases`, and `outputs/solution-exploration.md` must exist. If missing → print the blocked block, then STOP:
+   - `Run /owflow:research-brainstorm <task-path> first` (or the command for the earliest missing earlier step: `/owflow:research-plan`, `/owflow:research-gather`, or `/owflow:research-synthesize`).
+3. **Skip/resume (per-area partial resume)**: if `approaches-chosen` is in `completed_phases`, validate every `phase_summaries.converge.decision_areas` entry carries `chosen_approach` — all resolve → report the existing chosen combination and route to the Exit Gate; any area unresolved → re-ask ONLY the unresolved areas below. Also — even WITHOUT the slug — skip any area whose `decision_areas` entry already carries `chosen_approach`; only unresolved areas are ever asked.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                                | Quick mode (`research-quick`)                                                                          |
+| ---------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Consumed: `outputs/solution-exploration.md`    | parsed for decision areas + alternatives                                | identical — when the optional chain runs after a quick pass, the exploration file was produced by research-brainstorm |
+| Produced: none (state-only)                    | decisions recorded inline per area                                      | same mechanics — research-quick never converges inline                                                     |
+| State write                                    | `approaches-chosen`; `phase_summaries.converge {summary, decision_areas, deferred_ideas}` (per-area partial writes) | same slug and fields                                                          |
+
+## Execute (direct interactive — per-area convergence)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) — per-area convergence is direct interactive work (like dev-verify's interactive phases); no agents involved.
+
+> **ANTI-PATTERN**: Do NOT present all decision areas in a single summary table and ask one combined "do you agree?" question. Each area MUST get its own detailed presentation and its own question call.
+>
+> **ANTI-PATTERN**: Do NOT show full alternatives/pros/cons for the first area and then shortcut remaining areas to just a recommendation line + question. EVERY area gets the SAME level of detail — all alternatives with descriptions, pros, and cons. No exceptions.
+
+**Per-area handling** (the two guards above apply to EVERY area, including partial resumes):
+
+1. Read `outputs/solution-exploration.md`
+2. For each decision area sequentially, output ALL of the following (steps a-d) BEFORE calling question:
+   a. **Area header**: area name and why this decision matters (1-2 sentences of context)
+   b. **Alternatives detail**: For EVERY alternative in this area, show:
+      - Name and description (2-3 sentences)
+      - Pros (bullet list)
+      - Cons (bullet list)
+   c. **Recommendation**: which alternative is recommended and why (1 sentence)
+   d. **question**: this area's alternatives as options (mark recommended with "(Recommended)") + "Need more info" option
+      e. If user picks → record choice (write the per-area partial state immediately — see State Update Convention), move to next area
+      f. If "Need more info" → present the detailed trade-off analysis for the requested alternative, then re-ask
+
+> **SELF-CHECK before each question**: Did you output the alternatives with pros/cons for THIS area? If you only showed a recommendation line without listing all alternatives and their pros/cons, STOP and output the full detail before asking.
+
+3. After all areas resolved, present a brief summary of the chosen combination (this summary moves into the Exit-Gate results box below — the boundary to design/finalize stays explicit, no AUTO-CONTINUE)
+4. **GATE CHECK**: Verify that question was called for EACH decision area. If any decision area was skipped for any reason (e.g., output file missing, read failure), STOP and resolve before continuing. Do NOT mark the convergence complete without user convergence on all decision areas.
+
+### Close (`approaches-chosen`)
+
+1. **State write**: append `approaches-chosen` to `completed_phases` — ONLY after the LAST unresolved area resolves; update `phase_summaries.converge {summary, decision_areas, deferred_ideas}` (deferred ideas recorded when the exploration documents them); bump `orchestrator.updated`. On failure: append `approaches-chosen` to `failed_phases`, increment `auto_fix_attempts["approaches-chosen"]`. Then re-read state + run `verify_template` (see State Update Convention).
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately — per area**: as each decision area resolves, record the `chosen_approach` into that area's entry in `phase_summaries.converge.decision_areas` immediately (never batch all areas into one end-of-skill write — the per-area write is what makes partial resume work). The `approaches-chosen` slug is appended ONLY after the LAST unresolved area resolves.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if a question cannot fire (read failure, tool failure) or an area could not resolve, do NOT append `approaches-chosen` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["approaches-chosen"]`. A deliberate "stop here" at an area question is NOT a failure — the area simply stays unresolved and partial resume picks it up on the next run.
+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                                    |
+| ------------------------------- | ------------ | -------------------------------------------- |
+| Converge (`approaches-chosen`)  | 1            | Re-read exploration file, re-present areas   |
+
+## 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. The chosen-combination summary (step 3 above) is folded into the results box.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH CONVERGE COMPLETE — <research question>
+
+**Decision areas** — [N areas resolved]
+**Chosen combination** — [area: choice, one line per area]
+**Deferred ideas** — [one line each / none]
+**Design decision** — [feeds into design as `selected_approach` / no design planned]
+
+**Artifacts**
+
+- none (state-only) — decisions live in `phase_summaries.converge.decision_areas` of `orchestrator-state.yml`; `outputs/solution-exploration.md` stays the shared record
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the per-area decisions are good; continue.
+- **Adjust** — re-open a specific area: re-present that ONE area with full detail and re-ask its question (other areas untouched), update state, re-present the results box.
+- **Discuss** — walk through a specific area's trade-offs in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-converge <task-path>`) and end. Note: unresolved areas re-ask on the next run (per-area partial resume).
+
+### Next steps (after Accept)
+
+- `→ /owflow:research-design <task-path>` — when the user wants high-level design: Part A asks design preferences, Part B delegates the solution-designer with the chosen combination as `selected_approach`, Part D refines diagrams. Remaining after: finalize.
+- `→ /owflow:research-finalize <task-path>` — when no design is wanted: inventories the research outputs and completes the task (`research-completed`). Remaining after: none.
+
+Then STOP.

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

@@ -0,0 +1,146 @@
+---
+name: owflow:research-design
+description: Research skill — optional subskill. Asks design preferences (Part A), delegates high-level architecture design to the solution-designer agent (outputs/high-level-design.md + outputs/decision-log.md), then refines diagrams via the diagrams-mermaid Skill — content-preserving (design-generated). Invoking this skill IS the decision to design — there is no enablement flag.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Design — High-Level Design (design-generated)
+
+Work phase of the research workflow. Creates the high-level architecture design from the selected solution approach — or, when brainstorming did not run, seeded from the research-report recommendations — as two artifacts (`outputs/high-level-design.md`, `outputs/decision-log.md`), then refines diagrams via the `diagrams-mermaid` Skill. Optional phase — runs when the user chooses it: invoking this skill IS the decision to design (no enablement flag in state). The design-only branch (brainstorming not run) is owned here: `selected_approach` is seeded from the research report. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-brainstorm` + `/owflow:research-converge` (produce the chosen combination consumed as `selected_approach`), `/owflow:research-finalize` (always next). The design-techniques reference lives in this skill's own folder (`references/design-techniques.md`).
+
+## 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>`
+     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
+     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
+     - Chosen approaches (`approaches-chosen`) → `/owflow:research-brainstorm <task-path>` + `/owflow:research-converge <task-path>` (only when brainstorming ran)
+  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>` or `/owflow:research-quick` |
+| Design input ready      | brainstorm ran — `approaches-chosen` in `completed_phases`; OR brainstorm did not run — `outputs/research-report.md` exists with recommendations | `/owflow:research-converge <task-path>` (or `/owflow:research-synthesize <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 `design-generated`): `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. **Prerequisite check**: `synthesis-complete` must be in `completed_phases`. If missing → print the blocked block (`→ /owflow:research-synthesize <task-path>`, or the earliest missing earlier step), then STOP.
+3. **Design input (branch resolution)**:
+   - `approaches-chosen` in `completed_phases` → brainstorm ran; the chosen combination from `phase_summaries.converge.decision_areas` is `selected_approach`.
+   - `approaches-chosen` in `completed_phases` but `phase_summaries.converge.decision_areas` has no `chosen_approach` → convergence never resolved its areas: `→ /owflow:research-converge <task-path>`, then STOP.
+   - `alternatives-generated` in `completed_phases` but `approaches-chosen` absent → the brainstorm chain is incomplete: `→ /owflow:research-converge <task-path>`, then STOP. Do NOT seed from the research report while alternatives exist.
+   - Neither slug present → brainstorming has not produced alternatives. Ask via `question`: "Brainstorming hasn't run — seed the design from the research report, or brainstorm first?" → seed from report (design-only branch): state `Brainstorming did not run — seeding the design from research-report recommendations.`, validate `outputs/research-report.md` exists (missing → `→ /owflow:research-synthesize <task-path>`, then STOP) and proceed; → brainstorm first: `→ /owflow:research-brainstorm <task-path>`, then STOP.
+4. **Skip/resume**: if `design-generated` is in `completed_phases`, validate BOTH `outputs/high-level-design.md` AND `outputs/decision-log.md` exist; either missing → re-run Parts B-D below; both present → report the existing design summary and route to the Exit Gate.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                                   | Quick mode (`research-quick`)                                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Consumed: `phase_summaries.converge.decision_areas` (chosen combination) | becomes `selected_approach` when brainstorm ran                       | same fields — when the optional chain runs after a quick pass, converge ran as the normal subskill        |
+| Consumed: `outputs/research-report.md`         | design-only branch seed (`selected_approach` from recommendations)           | identical — research-quick produces the same report artifact                                              |
+| Produced: `outputs/high-level-design.md`, `outputs/decision-log.md` | delegated to `solution-designer`, refined via `diagrams-mermaid` Skill | NOT produced in the quick pass — design always runs as this skill after the quick lane                    |
+| State write                                    | `design-generated`; `phase_summaries.design {summary, architecture_style, decisions_count}`, `research_outputs.high_level_design` + `.decision_log` | same (this skill never runs inside a quick pass)               |
+
+## Execute (Part A direct + Part B delegated + Part C direct + Part D Skill)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+**Read `references/design-techniques.md` NOW using the Read tool** — MADR format, ADR guidance, decision documentation patterns (own-folder reference).
+
+### Part A — Design Direction (direct)
+
+1. Brainstorm ran: read the chosen combination from `phase_summaries.converge.decision_areas` — it becomes `selected_approach`.
+2. Brainstorm did not run (design-only branch, resolved in Entry Gate step 3): read `outputs/research-report.md` recommendations and derive `selected_approach` from them; note the provenance (research-report recommendations, not convergence).
+3. `question` — "Any architectural constraints or preferences?" (free-form answer; empty means none). These `design_preferences` ride in the Part B context pass and are kept human-readable in `phase_summaries.design.summary` — the state template has NO dedicated `design_preferences` slot; that omission is deliberate (do NOT invent a template field).
+
+### Part B — Design Generation (subagent)
+
+> **ANTI-PATTERN — do NOT generate C4 architecture diagrams or ADRs inline. "The approach is obvious" is NOT a reason to skip delegation. The solution-designer agent has specialized architecture and MADR documentation capabilities.**
+
+1. **INVOKE NOW**: Task tool - `solution-designer` subagent (never the Skill tool — this is an agent). Pass (Pattern 7 — accumulated context):
+   - `task_path`, `synthesis_path` (`analysis/synthesis.md`), `research_report_path` (`outputs/research-report.md`)
+   - `solution_exploration_path` (`outputs/solution-exploration.md`) — only when brainstorm ran
+   - `selected_approach` (from convergence; on the no-brainstorm branch, seeded from research-report recommendations — list the provenance in the prompt)
+   - `design_preferences` (from Part A; omit when the user gave none)
+   - Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries`
+   - `project_doc_paths` (from state)
+   - MUST-contract: the designer writes BOTH `outputs/high-level-design.md` AND `outputs/decision-log.md`
+2. > **SELF-CHECK**: After the Task tool returns, verify BOTH `outputs/high-level-design.md` and `outputs/decision-log.md` exist. If either is missing: **STOP. Do NOT proceed to Part D or the Exit Gate.** Re-invoke the designer with corrected context. If a second attempt also fails, use `question` to report the failure and ask whether to retry or skip design.
+
+### Part C — Executive Summary (direct)
+
+Read `outputs/high-level-design.md` and `outputs/decision-log.md`, then present the executive summary through the Exit-Gate results box below (architecture style and key components, decision count, key decision highlights 1 line each, integration points with the existing system if applicable) — no separate presentation round.
+
+### Part D — Diagram Refinement (Skill, content-preserving)
+
+1. **INVOKE NOW**: Skill tool - `diagrams-mermaid` to refine visual communication in `outputs/high-level-design.md`.
+2. Add diagrams that supplement (NOT replace) existing architecture content:
+   - one architecture view (`C4Container` preferred; `C4Component` only if needed),
+   - one interaction/state view (`sequenceDiagram` or `flowchart`) for the critical flow.
+3. If minimum context for a diagram is missing, record explicit gaps in the document and avoid speculative components/relationships.
+
+### Close (`design-generated`)
+
+1. **State write**: append `design-generated` to `completed_phases` after the SELF-CHECK passes and Part D completes; update `research_context.phase_summaries.design {summary, architecture_style, decisions_count}` (keep the Part A preferences visible in `summary`); set `research_outputs.high_level_design` AND `research_outputs.decision_log`; bump `orchestrator.updated`. On failure: append `design-generated` to `failed_phases`, increment `auto_fix_attempts["design-generated"]`. 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 (`design-generated`) 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 designer delegation fails or its retries are abandoned, do NOT append `design-generated` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["design-generated"]`. A user-chosen skip via `question` after repeated failures is a deliberate decision, not a failure: record the reason in `phase_summaries.design.summary` and append neither `design-generated` nor a `failed_phases` entry. Then present the Exit Gate (results box notes the skip; next step is `/owflow:research-finalize <task-path>`).
+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                                       |
+| ----------------------------- | ------------ | ----------------------------------------------- |
+| Design (`design-generated`)   | 2            | Re-invoke solution-designer with adjusted context |
+
+## 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. A user-chosen skip still uses this Exit Gate; its results box says the step was skipped and why, and the next step is `/owflow:research-finalize <task-path>`.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH DESIGN COMPLETE — <research question>
+
+**Architecture style** — [style and key components]
+**Decisions recorded** — [N architectural decisions in decision-log.md]
+**Key highlights** — [1 line per key decision]
+**Integration points** — [with the existing system, if applicable]
+**Diagrams** — [refined by diagrams-mermaid / gaps recorded]
+
+**Artifacts**
+
+- `outputs/high-level-design.md`
+- `outputs/decision-log.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the architecture and decision log are good; continue.
+- **Adjust** — re-invoke the designer with the user's corrections (changed constraints or preferences), update state and artifacts, re-present the results box.
+- **Discuss** — walk through the architecture style or specific architectural decisions in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-design <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:research-finalize <task-path>` — `required` next: inventories all research outputs (including these design artifacts) and completes the task (`research-completed`). Remaining after: none — development starts from finalize's handoff (`→ /owflow:development <task-path>`).
+
+Then STOP.

package/dist/skills/{research → research-design}/references/design-techniques.md

@@ -1,6 +1,6 @@
 # Design Techniques
 
-These techniques guide Phase 3 (High-Level Design) of the research workflow. They provide patterns for capturing and documenting design decisions in a durable, traceable format.
+These techniques guide High-Level Design in the research-design skill. They provide patterns for capturing and documenting design decisions in a durable, traceable format.
 
 ---
 

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

@@ -0,0 +1,125 @@
+---
+name: owflow:research-finalize
+description: Research skill — terminal step. Inventories all research outputs (research report always; brainstorm/design artifacts conditionally), presents the workflow results box, and gets user confirmation that the research is correct. Marks the task research-completed — the Exit-Gate acceptance here is where the goal-research wrapper's loop ends.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Finalize — Completion & Handoff (research-completed)
+
+Terminal step of the research workflow. Presents research results, confirms correctness with the user, and hands off to development (or ends the workflow). No new files — summarizes existing outputs. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: all research subskills (`/owflow:research-plan` → `/owflow:research-gather` → `/owflow:research-synthesize` → the optional chain as chosen by the user). This is the terminal skill: its Exit-Gate acceptance is where the goal-research wrapper's loop ends, and where assisted mode suggests development.
+
+## 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>`
+     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
+     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
+  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>` or `/owflow:research-quick` |
+| Foundation complete     | `synthesis-complete` in `completed_phases` + `outputs/research-report.md` exists | `/owflow:research-synthesize <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 `research-completed`): `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. **Prerequisite check**: `synthesis-complete` must be in `completed_phases` and `outputs/research-report.md` must exist. The optional chain is settled by the user's own choices — invoking `research-brainstorm`/`research-design` is the decision to run them; skipping straight here settles the chain as skipped. If the foundation is missing → print the blocked block for the earliest missing step, then STOP:
+   - `Run /owflow:research-plan <task-path> first` (or the command for the earliest missing earlier step: `/owflow:research-gather` or `/owflow:research-synthesize`).
+   - If no task exists yet: `Run /owflow:research <question> to start a task from scratch.`
+3. **Skip/resume**: if `task.status` is `completed`, report the existing finalization (results box from the inventory below) and STOP (dev-finalize terminal pattern).
+4. **Always runs**: this skill always runs — every path (no optional steps / design-only / full brainstorm chain) reaches completion here. The optional phases only affect the inventory and the "Phases run" line.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                        | Quick mode (`research-quick`)                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Consumed: `outputs/research-report.md` (always) + conditional design/brainstorm artifacts | inventoried per `research_outputs.*` in state | identical — a quick-pass task brings the same standard artifacts                             |
+| Produced: none (state-only)                    | no new files — finalization is an inventory                         | same — after a quick pass this skill completes the task the same way                        |
+| State write                                    | `research-completed`; `task.status: completed`                     | same slug and field                                                                    |
+
+## Execute (direct — inline-legal finalization)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) — finalization is inline-legal ("finalization" is a simple, direct step; no agents involved).
+
+### Inventory outputs
+
+1. **Inventory all generated outputs**: `outputs/research-report.md` (always), plus conditional: `outputs/solution-exploration.md`, `outputs/high-level-design.md`, `outputs/decision-log.md` — each conditional artifact is listed only when its `research_outputs` field is set in state (and the file exists).
+2. **Results box**:
+
+```markdown
+## ✅ RESEARCH COMPLETE — <research question>
+
+**Type** — [research type]
+**Confidence** — [confidence level]
+**Phases run** — [executed slug list, e.g. brief-written → plan-created → findings-gathered → synthesis-complete → alternatives-generated → approaches-chosen → design-generated]
+**Key findings** — [2-3 one-line highlights]
+**Decisions** — [count of ADRs, if design ran]
+
+**Artifacts**
+
+- `outputs/research-report.md`
+- `outputs/solution-exploration.md` [conditional]
+- `outputs/high-level-design.md` [conditional]
+- `outputs/decision-log.md` [conditional]
+```
+
+### Close (`research-completed`)
+
+1. **State write**: append `research-completed` to `completed_phases` and set `task.status: completed` — ONLY after the results box is presented; do NOT write a `phase_summaries.finalize` slot (the template has no finalize slot — finalization is state-only, and the inventory lives in `research_outputs.*`); bump `orchestrator.updated`. On failure: append `research-completed` to `failed_phases`, increment `auto_fix_attempts["research-completed"]`. 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 (`research-completed`) plus that step's fields. Never batch multiple steps into one end-of-skill write. **No `phase_summaries.finalize` write** — the template has no such slot (finalization is state-only; the inventory lives in `research_outputs.*`).
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if finalization fails, do NOT append `research-completed` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["research-completed"]`.
+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      |
+| --------------------------------- | ------------ | -------------- |
+| Completion (`research-completed`) | 0            | Summary only   |
+
+## Exit Gate
+
+Present results, get user confirmation, then close the workflow (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill. **This acceptance is where the goal-research wrapper's loop ends** (Accept = the wrapper proceeds to its own wrapper Exit Gate; any other option ends the loop with the standard handoff block). In assisted mode, Accept prints the next steps below.
+
+### Results box
+
+The results box from the Inventory outputs step above IS the workflow-level results box — present it here as-is (single box, not two).
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — research is complete; print next steps (below).
+- **Adjust** — re-run the affected phase (re-gather → `/owflow:research-gather <task-path>`, re-brainstorm → `/owflow:research-brainstorm <task-path>`, re-design → `/owflow:research-design <task-path>`) with the user's corrections, then re-present the results box.
+- **Discuss** — walk through specific findings or decisions in more depth; then re-ask.
+- **Fork** — branch instead of re-running here: `/owflow:research-fork <task-path>` copies this task to a new one diverging at a chosen completed step (source untouched); pass a description to skip the intent question.
+- **Stop here** — print the resume command (`/owflow:research-finalize <task-path>`) and end.
+
+### Next steps (after Accept)
+
+If design artifacts exist (research report + design → development handoff), suggest starting development in a fresh session:
+
+```
+To start development based on this research, clear context first or start a new session, then run:
+→ /owflow:development <task-path>
+```
+
+Without design artifacts, the research report remains the deliverable — feed it into `/owflow:development <task-path>` the same way when development is ready, or reference it manually.
+
+Then STOP.