owflow 0.4.2 → 0.5.0

package/dist/agents/specification-creator.md

@@ -303,7 +303,7 @@ warnings: ["any non-critical observations"]
 
 ## Integration
 
-**Invoked by**: development orchestrator (Phase 5), migration orchestrator (Phase 2)
+**Invoked by**: dev-spec, migration-spec
 
 **Prerequisites**:
 

package/dist/commands/work.md

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

package/dist/configuration/commands-config.js

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

package/dist/skills/codebase-analyzer/SKILL.md

@@ -155,8 +155,8 @@ risk_level: low|low-medium|medium|medium-high|high
 
 ## Integration
 
-| Orchestrator | Phase | artifact_name |
+| Orchestrator | Step (slug) | artifact_name |
 |-------------|-------|---------------|
-| development orchestrator | Phase 1 | `codebase-analysis.md` (default) |
-| migration orchestrator | Phase 1 | `current-state-analysis.md` |
-| performance orchestrator | Phase 1 | `codebase-analysis.md` (default) |
+| development orchestrator | `codebase-analysed` | `codebase-analysis.md` (default) |
+| migration-analyze | `state-analysed` | `current-state-analysis.md` |
+| performance orchestrator | `phase-1` | `codebase-analysis.md` (default) |

package/dist/skills/dev-verify/SKILL.md

@@ -43,7 +43,7 @@ Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate C
 
 ## Execute
 
-**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) and [Issue Resolution](../orchestrator-framework/references/orchestrator-patterns.md) (Section 6).
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), the [Fix Loop Contract](../orchestrator-framework/references/fix-loop-contract.md), and [Issue Resolution](../orchestrator-framework/references/orchestrator-patterns.md) (Section 6).
 
 ### Verification Options Prompt (`options-chosen`, inline)
 
@@ -94,14 +94,7 @@ Verification Results:
 
 **Step 3**: Gate on status — `passed` → skip to State Update. `passed_with_issues` or `failed` → fix loop (Step 4).
 
-**Step 4**: User-driven fix loop (max 3 iterations):
-
-1. Present critical + warning issues as a numbered list.
-2. `question` — "Which issues should I fix?" Options: "Fix all fixable issues" / "Let me choose specific issues" / "Skip fixes, proceed as-is".
-3. Fix selected issues; **immediately** log each to `verification_context.fixes_applied` in state (not deferred to the end).
-4. After fixes: set `skip_test_suite: false` (code changed, tests must re-run).
-5. `question` — "Re-run verification to check fixes?" → re-invoke `implementation-verifier` → back to Step 2, or "No, proceed to next phase".
-6. **Immediately** update `verification_context.reverify_count` and `verification_context.last_status` in state after each verifier run.
+**Step 4**: User-driven fix loop (max 3 iterations) — follow the [Fix Loop Contract](../orchestrator-framework/references/fix-loop-contract.md): the three-option question wording, immediate `fixes_applied` writes, `skip_test_suite: false` after fixes, re-invoking `implementation-verifier` on request, and refreshing `reverify_count` / `last_status` / `issues_found` right after each verifier run.
 
 **Exit conditions**: no critical issues remain → proceed; user explicitly chooses to proceed with issues → proceed with issues logged; max 3 iterations → `question` "Proceed with known issues?" / "Stop workflow". **MUST NOT proceed with unresolved critical issues unless the user explicitly approves.**
 
@@ -111,7 +104,7 @@ Apply after EVERY phase/step above:
 
 1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed plus that step's fields. Never defer writes to the end of the skill.
 2. **Options prompt** — append `options-chosen` to `completed_phases` with the chosen `options.*` and `skip_test_suite` (written right after the options prompt, before verification starts).
-3. **Per verifier run** — update `verification_context.last_status`, `issues_found`, `fixes_applied`, and `reverify_count` immediately after each `implementation-verifier` run and after each fix-loop iteration (per steps 3/6 above), so an interruption loses nothing.
+3. **Per verifier run** — update `verification_context.last_status`, `issues_found`, `fixes_applied`, and `reverify_count` immediately after each `implementation-verifier` run and after each fix-loop iteration (per the [Fix Loop Contract](../orchestrator-framework/references/fix-loop-contract.md)'s immediate-write cadence), so an interruption loses nothing.
 4. **Completion** — append `verification-done` to `completed_phases` only at skill exit: status `passed`, or user-approved proceed with issues logged. Bump `orchestrator.updated` on every write.
 5. **Failures** — if `implementation-verifier` itself fails or the workflow stops with unresolved critical issues, do NOT append `verification-done` to `completed_phases`; append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["verification-done"]`.
 6. **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-development.yml`. Fix any reported issue immediately before proceeding.

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

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

package/dist/skills/diagrams-mermaid/references/reference.md

@@ -138,10 +138,10 @@ Better:
 
 Integrated into:
 - `src/skills/flow-init/SKILL.md` - Phase 6 (architecture and tech-stack doc refinement)
-- `src/skills/development/SKILL.md` - Phase 5 (spec refinement), Phase 7 (plan refinement)
-- `src/skills/research/SKILL.md` - Phase 5 (high-level design refinement)
-- `src/skills/performance/SKILL.md` - Phase 3 (spec refinement), Phase 5 (plan refinement)
-- `src/skills/migration/SKILL.md` - Phase 3 (spec refinement), Phase 4 (plan refinement)
+- `src/skills/dev-spec/SKILL.md` - `spec-written` (spec refinement); `src/skills/dev-plan/SKILL.md` - `plan-created` (plan refinement)
+- `src/skills/research-design/SKILL.md` - `design-generated` (high-level design refinement)
+- `src/skills/performance/SKILL.md` - `phase-3` (spec refinement), `phase-5` (plan refinement)
+- `src/skills/migration-spec/SKILL.md` - `strategy-specified` (spec refinement); `src/skills/migration-plan/SKILL.md` - `plan-created` (plan refinement)
 
 Reference files:
 - `src/skills/flow-init/references/architecture-template.md`

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

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

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

@@ -0,0 +1,114 @@
+---
+name: owflow:goal-migration
+description: Full orchestrated migration wrapper — runs ALL migration steps in one session by invoking every migration-* subskill in sequence with question gates between them. Use /owflow:migration for the same lifecycle in assisted mode — tasks can mix both modes freely.
+argument-hint: "[task description | task-path] [--from=<slug>] [--type=TYPE] [--no-web-research]"
+user-invocable: true
+---
+
+# Orchestrated Migration Wrapper
+
+Autonomous mode for migration tasks. Initializes (or resumes) the task, then invokes every required `migration-*` subskill back-to-back via the Skill tool, pausing at gates between subskills. Shares `orchestrator-state.yml` with assisted mode (`/owflow:migration`) — tasks can mix both modes freely. There is no migration quick lane.
+
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — orchestrated mode exception: each subskill's own Exit Gate acceptance question IS the loop gate (Accept = continue to the next subskill).
+
+## Input / Output Artifacts
+
+| Artifact                             | Behavior (this wrapper)                                                                        |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| Consumed: argument (description / path) | migration description (new task) or task path/identifier (resume)                           |
+| Consumed/produced: all task artifacts | owned entirely by the invoked subskills (none here — delegate, never inline)                  |
+| State write                           | `orchestrator.task_ids` (task items) + `orchestrator.updated` only; first-time initialization per the dispatcher's Step 3 is the one permitted write outside the loop |
+
+## Entry Gate
+
+Identical to the migration dispatcher — complete ALL of its entry-gate steps first (see `../migration/SKILL.md` Entry Gate):
+
+1. Read the framework reference files NOW, exactly as the migration dispatcher's Step 1: the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md), the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), and the [Orchestrator Patterns](../orchestrator-framework/references/orchestrator-patterns.md).
+2. Resolve the argument the same way the migration dispatcher does: task path or identifier (a directory, or a directory name under `.owflow/tasks/migrations/`) → **resume mode** (read `orchestrator-state.yml`, artifact-validate `completed_phases` against the dispatcher's marker table; find the first step slug NOT in `completed_phases` whose condition holds, with `--from=<slug>` overriding after prerequisite validation); a migration description (free text) → new task; nothing provided → ask via `question` — "What technology, platform, or architecture should be migrated, and to what?" — then WAIT. Missing state file → print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+3. Initialize (new task) exactly as the dispatcher's Step 3: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template — `task.title` / `task.description` from the description, `task.status: in_progress`, `orchestrator.started_phase: state-analysed`, `orchestrator.entry_point: "migration"`, `orchestrator.task_path`, flags recorded (`--type` → `migration_context.migration_type`; `--no-web-research` is forwarded to `migration-target` per invocation — nothing is persisted for it). **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-migration.yml`. First-time initialization is the one permitted write outside the loop.
+4. Create ONE task item via `TaskCreate` per subskill in the upcoming loop (subject: `"<step name>: <subskill>"`, e.g. `"Spec: migration-spec"`), then set the execution order with `TaskUpdate addBlockedBy` (analyze → target → spec → plan → implement → verify → fix → finalize). Record the ids in `orchestrator.task_ids`. On resume, refresh the already-evidenced items instead of re-creating them. Update statuses as the loop progresses.
+
+**Output**:
+
+```
+🚀 Orchestrated Migration
+
+Task: [migration description]
+Directory: [task-path]
+Loop: migration-analyze → migration-target → migration-spec → migration-plan → migration-implement → migration-verify → [migration-fix] → migration-finalize
+```
+
+---
+
+## The Loop
+
+For each subskill in sequence, execute — skipping any row whose condition is not met (a row whose slug is already in `completed_phases` counts as done). **Compatibility re-verification fallback**: when the loop finds no runnable row and `verification-done` is complete with `verification_context.compatibility_status != passed` (failed or null/invalidated), invoke `migration-verify` once (re-verification, overriding slug completeness), then re-read state and continue from the first row whose condition holds; it does not re-fire while the Fix row is runnable; a recorded data-integrity HALT keeps the user-confirmed rollback path dominant.
+
+1. **Announce**: 1-line step banner.
+2. **Invoke**: Skill tool with `name: "owflow:<subskill>"` and `prompt: "<task-path> [flags relevant to that subskill]"`. The subskill owns its Entry Gate, delegation, and state updates. Flags forwarded per subskill: `--type` and `--no-web-research` to `migration-target`.
+3. **Verify handback**: after the skill returns, re-read `orchestrator-state.yml` — confirm the expected step slug(s) were appended to `completed_phases` per the Sequence and Conditionals table. If a subskill stopped early (its Entry Gate failed), STOP the loop and relay its routing message to the user verbatim.
+4. **Gate (subskill's Exit Gate is the loop gate)**: each subskill presents its results box and fires its own results-acceptance `question` before its handoff hint (Orchestrated-mode exception, [Gate Contract](../orchestrator-framework/references/gate-contract.md)). [Rule 5 of the Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md) — "subskills only SUGGEST the next command" — is superseded for Accept: when the user answers **Accept** to the subskill's Exit Gate question pointing at the next subskill in this loop, treat that as "continue to the next subskill" and invoke it. Any other answer (Adjust / Discuss / Stop / other options picked) ends the loop: print the standard handoff block (next command + `/owflow:migration <task-path>` resume hint) and end.
+   - **Non-loop-gate questions**: the in-phase questions inside subskills (analyze clarifiers, spec requirement questions, verify's options step, fix's per-iteration questions) are part of that subskill's own decision flow — they are NOT the loop gate and are NEVER auto-accepted or answered by this wrapper. There is exactly ONE gate definition per subskill hop; the wrapper adds NO second consecutive `question`.
+   - **No quick lane**: migration has no quick lane — every row runs at full fidelity.
+
+### Sequence and Conditionals
+
+| Order | Subskill           | Run when (re-read from state)                                                                                          |
+| ----- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| 1     | migration-analyze  | Always (new task or partial foundation)                                                                                  |
+| 2     | migration-target   | `state-analysed` in `completed_phases`                                                                                  |
+| 3     | migration-spec     | `target-planned` completed                                                                                              |
+| 4     | migration-plan     | `strategy-specified` completed                                                                                          |
+| 5     | migration-implement | `plan-created` completed                                                                                               |
+| 6     | migration-verify   | `migration-executed` completed                                                                                          |
+| 7     | migration-fix      | `verification-done` completed **and** (`verification_context.compatibility_status = failed` **or** (`verification_context.last_status != passed` **and** no recorded deliberate skip)); otherwise the row is skipped and `migration-finalize`'s own Entry Gate routes forward |
+| 8     | migration-finalize | `verification-done` completed **and** `verification_context.compatibility_status = passed` **and** the fix phase is settled (`issues-resolved` present, or `last_status = passed`, or a recorded deliberate skip) |
+
+`task-completed` already in `completed_phases` → the task is TERMINAL: skip the loop and present the wrapper Exit Gate.
+
+**Interruptible**: at any gate the user may answer "stop" — print the standard handoff block (next command + `/owflow:migration <task-path>` resume hint) and end the session. The task resumes later in either mode; a fresh invocation of this wrapper resumes from state, never from loop memory.
+
+---
+
+## Exit Gate
+
+When migration-finalize completes (`task.status: completed`):
+
+1. Mark the final task item completed via `TaskUpdate`.
+2. Present the workflow results box:
+
+```markdown
+## ✅ MIGRATION WORKFLOW COMPLETE — <task name>
+
+**Migration** — [current → target, type]
+**Strategy** — [incremental / big-bang / dual-run / phased]
+**Steps** — [executed step slugs, e.g. state-analysed → target-planned → strategy-specified → plan-created → migration-executed → options-chosen → verification-done → issues-resolved → docs-generated → task-completed]
+**Verification** — [final verifier verdict + overall compatibility verdict]
+**Fixes** — [N applied / none required / deliberately skipped]
+**Operator guide** — [generated / skipped (`docs_enabled` not enabled)]
+
+**Artifacts** — [artifact inventory: `analysis/current-state-analysis.md`, `analysis/target-state-plan.md`, `analysis/requirements.md`, `analysis/rollback-plan.md`, `implementation/spec.md`, `implementation/implementation-plan.md`, `implementation/work-log.md`, `verification/implementation-verification.md`, `verification/compatibility-test-results.md`, `documentation/migration-guide.md` (conditional)]
+```
+
+3. Use `question` — "Are these results correct?" with options: **Accept** (print follow-up suggestions: review the artifacts, commit personally — the workflow performs no commits; `/owflow:reviews-pragmatic <task-path>` if desired; then end) / **Adjust** (re-open the relevant `/owflow:migration-*` skill with the corrections) / **Discuss** (walk through the migration summary) / **Stop here** (print the resume command `/owflow:migration <task-path>` and end).
+
+Then end. No further owflow phase commands are required.
+
+---
+
+## Loop Rules
+
+- **Delegate, never inline**: the wrapper only sequences — all step work happens inside subskills. If you catch yourself analyzing/migrating outside a subskill, STOP and invoke the subskill instead.
+- **State is the truth**: gates and routing read `orchestrator-state.yml`, not memory. Re-read after every subskill returns.
+- **Same state schema as assisted mode**: `completed_phases` step slugs (`state-analysed` … `task-completed`) are identical; resume works across modes.
+- **Wrapper writes almost nothing**: step slugs, summaries, and outputs belong to the subskills — this wrapper writes ONLY `orchestrator.task_ids` (task items) and `orchestrator.updated` (timestamps); the sole exception is first-time initialization per the dispatcher's Step 3.
+- **Zero added pause points**: one full pass asks at most the 8 subskill Exit Gates + this terminal gate = 9 — fewer when the conditional `migration-fix` row is skipped; the same asks as assisted mode. There is no per-hop back-to-back `question` exception: the wrapper adds no question inside the loop, and its only wrapper-level `question` is this terminal gate (the finalize gate and the wrapper gate are the one legitimate consecutive pair).
+
+## Command Integration
+
+Invoked via:
+
+- `/owflow:goal-migration [description] [--type=TYPE] [--no-web-research]` (new)
+- `/owflow:goal-migration [task-path] [--from=<slug>]` (resume)
+
+Alternative: `/owflow:migration` — same task in assisted mode (one subskill per invocation, fresh context each step).

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

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

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

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