owflow 0.4.2 → 0.4.3

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

@@ -1,139 +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.
+---
+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.

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

@@ -1,127 +1,127 @@
----
-name: owflow:research-synthesize
-description: Research skill — delegates synthesis and evidence-based reporting to the research-synthesizer agent, producing the synthesis document and the comprehensive research report with per-finding confidence. Closes the research foundation (synthesis-complete) at the boundary with the optional chain (user choice).
-argument-hint: "[task-path-or-identifier]"
-user-invocable: true
----
-
-# Research Synthesize — Synthesis & Research Report (synthesis-complete)
-
-Work phase of the research workflow. Delegates pattern synthesis and evidence-based reporting to the research-synthesizer agent (`analysis/synthesis.md` + `outputs/research-report.md`). This is the research-foundation boundary: the Exit Gate is the pause between the foundation and the optional-phase decision. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
-
-Related phases: `/owflow:research-gather` (produces the merged findings); the optional chain (`research-brainstorm` / `research-design`) and `/owflow:research-finalize` follow, per the user's choice.
-
-## 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>`
-  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` |
-| Findings exist                       | `findings-gathered` in `completed_phases` + `analysis/findings/` has per-category files | `/owflow:research-gather <task-path>` (or the quick lane's condensed gather) |
-| Research question recorded           | `research_context.research_question` non-null in state                          | `/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 `synthesis-complete`): `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 — findings present**: the per-category files under `analysis/findings/` must exist (artifacts before state — drop the `findings-gathered` entry and route back to `/owflow:research-gather <task-path>` when they do not).
-3. **Skip/resume**: if `analysis/synthesis.md` AND `outputs/research-report.md` both exist, adopt them — append `synthesis-complete` if it is missing, backfill `research_outputs.synthesis` and `research_outputs.research_report` when those fields are still null, report the existing summaries, and route to the Exit Gate. Either file missing → re-run below (drop a stale `synthesis-complete` entry first).
-
-## Input / Output Artifacts
-
-| Artifact                                       | Normal mode (full lane)                                                                        | Quick mode (`research-quick`)                                             |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| Consumed: `analysis/findings/*.md`             | all per-category files (the gather contract)                                                     | same — quick-lane findings feed the inline synthesis                                        |
-| Consumed: `research-synthesizer` agent (Task tool) | 1 delegated call                                                                             | n/a — synthesis is ALWAYS inline in the quick lane (the ONLY exception to this delegation)  |
-| Produced: `analysis/synthesis.md`              | delegated (patterns, cross-references, gaps)                                                     | written directly inline                                                                     |
-| Produced: `outputs/research-report.md`         | delegated (report + per-finding confidence)                                                      | written directly inline                                                                     |
-| State write                                    | `synthesis-complete`; `confidence_level`, `phase_summaries.synthesize`, `research_outputs.synthesis` + `.research_report` | same slug and fields, condensation-noted                     |
-
-## Execute (delegated synthesis)
-
-**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
-
-> **ANTI-PATTERN — never write synthesis.md or research-report.md yourself. "The findings are few" is NOT a reason to skip delegation. (The quick lane is the ONLY exception — research-quick synthesizes inline and skips this section.)**
-
-1. **INVOKE NOW**: Task tool - `research-synthesizer` subagent (never the Skill tool — this is an agent). Pass (Pattern 7 — accumulated context): task_path, findings_directory_path, research_question, research_type, methodology (from state).
-
-**Synthesizer produces**:
-
-- Pattern analysis and cross-references → `analysis/synthesis.md`
-- Comprehensive research report answering research question → `outputs/research-report.md`
-- Confidence levels for each finding
-- Documented gaps and uncertainties
-
-> **SELF-CHECK on both artifacts**: after the Task tool returns, verify `analysis/synthesis.md` AND `outputs/research-report.md` exist (synthesis documents gaps; report carries confidence per finding). If missing: **STOP. Re-invoke the research-synthesizer with corrected context.** If the second attempt also fails, use `question` to report the failure and ask whether to retry (after targeted re-gathering if the gaps require it) or stop. There is no continue-without-synthesis path — every later step reads these artifacts. On stop, record the failure per the State Update Convention and print the resume command.
-
-### Post-synthesis decision re-cap (direct, condensable)
-
-The synthesizer's key outcomes are surfaced to the user here before the Exit Gate (decisions from subagents must go to the user — never silently skipped): overall `confidence_level`, top patterns, documented gaps. Extract a 1-2 sentence summary into `phase_summaries.synthesize`.
-
-### Close (`synthesis-complete`)
-
-1. **State write**: append `synthesis-complete` to `completed_phases`; update `research_context.confidence_level`, `phase_summaries.synthesize`; set `research_outputs.synthesis` and `research_outputs.research_report`; bump `orchestrator.updated`. On failure: append `synthesis-complete` to `failed_phases`, increment `auto_fix_attempts["synthesis-complete"]`. 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 (`synthesis-complete`) 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["synthesis-complete"]`.
-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                              |
-| --------------------------------- | ------------ | ------------------------------------- |
-| Synthesize (`synthesis-complete`) | 2            | Request targeted re-gathering for gaps |
-
-## 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 SYNTHESIZE COMPLETE — <research question>
-
-**Type** — [research type]
-**Confidence** — [confidence level from state]
-**Key patterns** — [2-3 one-line pattern highlights from synthesis]
-**Gaps** — [documented gaps and uncertainties, 1 line]
-
-**Artifacts**
-
-- `analysis/synthesis.md`
-- `outputs/research-report.md`
-```
-
-### Results-acceptance question
-
-Use `question` — "Are these results correct?" with options:
-
-- **Accept** — synthesis and report are good; continue.
-- **Adjust** — re-run the affected part with the user's corrections (targeted re-gathering for gaps, then re-synthesize), update state and artifacts, re-present the results box.
-- **Discuss** — walk through specific findings or confidence levels in more depth; then re-ask.
-- **Stop here** — print the resume command (`/owflow:research-synthesize <task-path>`) and end.
-
-### Next steps (after Accept)
-
-Research foundation complete (initialized, planned, gathered, synthesized). Continue to optional-phase evaluation?
-
-- `→ /owflow:research-brainstorm <task-path>` — when the user wants solution alternatives brainstormed. Remaining after: converge → design (when wanted) → finalize.
-- `→ /owflow:research-design <task-path>` — design-only branch (no brainstorming), seeded from the research report. Remaining after: finalize.
-- `→ /owflow:research-finalize <task-path>` — when neither is wanted: inventories the outputs and completes the task. If the foundation alone was the goal, this is the route — the task stays resumable.
-
-Then STOP.
+---
+name: owflow:research-synthesize
+description: Research skill — delegates synthesis and evidence-based reporting to the research-synthesizer agent, producing the synthesis document and the comprehensive research report with per-finding confidence. Closes the research foundation (synthesis-complete) at the boundary with the optional chain (user choice).
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Synthesize — Synthesis & Research Report (synthesis-complete)
+
+Work phase of the research workflow. Delegates pattern synthesis and evidence-based reporting to the research-synthesizer agent (`analysis/synthesis.md` + `outputs/research-report.md`). This is the research-foundation boundary: the Exit Gate is the pause between the foundation and the optional-phase decision. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-gather` (produces the merged findings); the optional chain (`research-brainstorm` / `research-design`) and `/owflow:research-finalize` follow, per the user's choice.
+
+## 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>`
+  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` |
+| Findings exist                       | `findings-gathered` in `completed_phases` + `analysis/findings/` has per-category files | `/owflow:research-gather <task-path>` (or the quick lane's condensed gather) |
+| Research question recorded           | `research_context.research_question` non-null in state                          | `/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 `synthesis-complete`): `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 — findings present**: the per-category files under `analysis/findings/` must exist (artifacts before state — drop the `findings-gathered` entry and route back to `/owflow:research-gather <task-path>` when they do not).
+3. **Skip/resume**: if `analysis/synthesis.md` AND `outputs/research-report.md` both exist, adopt them — append `synthesis-complete` if it is missing, backfill `research_outputs.synthesis` and `research_outputs.research_report` when those fields are still null, report the existing summaries, and route to the Exit Gate. Either file missing → re-run below (drop a stale `synthesis-complete` entry first).
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                                                        | Quick mode (`research-quick`)                                             |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Consumed: `analysis/findings/*.md`             | all per-category files (the gather contract)                                                     | same — quick-lane findings feed the inline synthesis                                        |
+| Consumed: `research-synthesizer` agent (Task tool) | 1 delegated call                                                                             | n/a — synthesis is ALWAYS inline in the quick lane (the ONLY exception to this delegation)  |
+| Produced: `analysis/synthesis.md`              | delegated (patterns, cross-references, gaps)                                                     | written directly inline                                                                     |
+| Produced: `outputs/research-report.md`         | delegated (report + per-finding confidence)                                                      | written directly inline                                                                     |
+| State write                                    | `synthesis-complete`; `confidence_level`, `phase_summaries.synthesize`, `research_outputs.synthesis` + `.research_report` | same slug and fields, condensation-noted                     |
+
+## Execute (delegated synthesis)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+> **ANTI-PATTERN — never write synthesis.md or research-report.md yourself. "The findings are few" is NOT a reason to skip delegation. (The quick lane is the ONLY exception — research-quick synthesizes inline and skips this section.)**
+
+1. **INVOKE NOW**: Task tool - `research-synthesizer` subagent (never the Skill tool — this is an agent). Pass (Pattern 7 — accumulated context): task_path, findings_directory_path, research_question, research_type, methodology (from state).
+
+**Synthesizer produces**:
+
+- Pattern analysis and cross-references → `analysis/synthesis.md`
+- Comprehensive research report answering research question → `outputs/research-report.md`
+- Confidence levels for each finding
+- Documented gaps and uncertainties
+
+> **SELF-CHECK on both artifacts**: after the Task tool returns, verify `analysis/synthesis.md` AND `outputs/research-report.md` exist (synthesis documents gaps; report carries confidence per finding). If missing: **STOP. Re-invoke the research-synthesizer with corrected context.** If the second attempt also fails, use `question` to report the failure and ask whether to retry (after targeted re-gathering if the gaps require it) or stop. There is no continue-without-synthesis path — every later step reads these artifacts. On stop, record the failure per the State Update Convention and print the resume command.
+
+### Post-synthesis decision re-cap (direct, condensable)
+
+The synthesizer's key outcomes are surfaced to the user here before the Exit Gate (decisions from subagents must go to the user — never silently skipped): overall `confidence_level`, top patterns, documented gaps. Extract a 1-2 sentence summary into `phase_summaries.synthesize`.
+
+### Close (`synthesis-complete`)
+
+1. **State write**: append `synthesis-complete` to `completed_phases`; update `research_context.confidence_level`, `phase_summaries.synthesize`; set `research_outputs.synthesis` and `research_outputs.research_report`; bump `orchestrator.updated`. On failure: append `synthesis-complete` to `failed_phases`, increment `auto_fix_attempts["synthesis-complete"]`. 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 (`synthesis-complete`) 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["synthesis-complete"]`.
+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                              |
+| --------------------------------- | ------------ | ------------------------------------- |
+| Synthesize (`synthesis-complete`) | 2            | Request targeted re-gathering for gaps |
+
+## 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 SYNTHESIZE COMPLETE — <research question>
+
+**Type** — [research type]
+**Confidence** — [confidence level from state]
+**Key patterns** — [2-3 one-line pattern highlights from synthesis]
+**Gaps** — [documented gaps and uncertainties, 1 line]
+
+**Artifacts**
+
+- `analysis/synthesis.md`
+- `outputs/research-report.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — synthesis and report are good; continue.
+- **Adjust** — re-run the affected part with the user's corrections (targeted re-gathering for gaps, then re-synthesize), update state and artifacts, re-present the results box.
+- **Discuss** — walk through specific findings or confidence levels in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-synthesize <task-path>`) and end.
+
+### Next steps (after Accept)
+
+Research foundation complete (initialized, planned, gathered, synthesized). Continue to optional-phase evaluation?
+
+- `→ /owflow:research-brainstorm <task-path>` — when the user wants solution alternatives brainstormed. Remaining after: converge → design (when wanted) → finalize.
+- `→ /owflow:research-design <task-path>` — design-only branch (no brainstorming), seeded from the research report. Remaining after: finalize.
+- `→ /owflow:research-finalize <task-path>` — when neither is wanted: inventories the outputs and completes the task. If the foundation alone was the goal, this is the route — the task stays resumable.
+
+Then STOP.

package/dist/skills/rule-reviewer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: owflow:rule-reviewer
-description: Score an AI rules file on 5 axes and return concrete actionable fixes
+description: "Score a rule-for-AI markdown file (CLAUDE.md, AGENTS.md, or any rules file) on 5 axes and return concrete actionable fixes"
 argument-hint: "[path/to/rules.md]"
 user-invocable: true
 ---

package/dist/skills/standards-discover/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: owflow:standards-discover
 description: Discover coding standards from project configuration files, code patterns, documentation, and external sources (PRs, CI/CD)
+argument-hint: "[task description]"
 user-invocable: true
 ---
 

package/package.json

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