owflow 0.2.0 → 0.4.2

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

@@ -1,5 +1,5 @@
 ---
-name: diagrams-mermaid
+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.
 user-invocable: true
 ---
@@ -8,6 +8,8 @@ user-invocable: true
 
 Generate Mermaid diagrams from task context. Focus on visual structure and communication flow, not domain invention.
 
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — the "Output Contract" below IS this skill's Exit Gate, and Step 1 (Extract Context) IS the Entry Gate: when required inputs are missing, ask targeted clarification questions (never invent them) before drawing.
+
 ## 🚨 Core Rules
 
 1. **Read `references/reference.md`** (located in the `references/` subdirectory of this skill) before generating any diagram.

package/dist/skills/docs-manager/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: docs-manager
+name: owflow:docs-manager
 description: Internal engine for managing project documentation and technical standards in .owflow/docs/. Handles file operations, INDEX.md generation, and AGENTS.md integration. Invoked by flow-init, standards-update, and standards-discover skills.
 user-invocable: false
 ---
@@ -117,8 +117,8 @@ Use this when a project doesn't have `.owflow/docs/` or needs documentation for
 
      _Not initialized for this project. If you need frontend standards, you can:_
 
-     - _Add them manually using the docs-manager skill_
-     - _Run `/standards-discover --scope=frontend` to auto-discover_
+     - _Add them manually using the owflow:docs-manager skill_
+     - _Run `/owflow:standards-discover --scope=frontend` to auto-discover_
      ```
 
 6. **MANDATORY - Update AGENTS.md:**
@@ -144,7 +144,7 @@ Use this when a project doesn't have `.owflow/docs/` or needs documentation for
 **Note on Skipped Standards**: If standard categories are skipped during initialization, teams can add them later using:
 
 - "Add Documentation File" operation to add specific standards
-- `/standards-discover` command to auto-discover standards from codebase
+- `/owflow:standards-discover` command to auto-discover standards from codebase
 
 ---
 

package/dist/skills/docs-manager/references/agents-md-template.md

@@ -21,7 +21,7 @@ When you notice recurring patterns, fixes, or conventions during implementation
 - The same type of fix is needed across multiple files
 - A new library/pattern is adopted that should be documented
 
-When this happens, briefly suggest the standard to the user. If approved, invoke `/standards-update` with the identified pattern.
+When this happens, briefly suggest the standard to the user. If approved, invoke `/owflow:standards-update` with the identified pattern.
 
 ## owflow Workflows
 

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

@@ -1,5 +1,5 @@
 ---
-name: flow-init
+name: owflow:flow-init
 description: Initialize AI SDLC framework with intelligent project analysis and documentation generation
 argument-hint: [--standards-from=PATH]
 user-invocable: true
@@ -9,8 +9,14 @@ user-invocable: true
 
 Initialize `.owflow/docs/` with intelligent project analysis and meaningful documentation generation based on actual codebase inspection.
 
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md).
+
 **NOTE**: This skill invokes other skills and subagents at specific phases. Use the **Task tool with `docs-operator` subagent** (subagent_type: `docs-operator`) for all docs-manager operations, and **Task tool** for project-analyzer. Use the **Skill tool** only for standards-discover (Phase 8, last phase). The Task tool returns control to this skill after completion; the Skill tool does not.
 
+## Entry Gate
+
+PHASE 1 (Pre-flight Checks) below IS the entry gate of this skill. It validates the `--standards-from=PATH` argument (resolve it; abort with an informative message if the referenced project lacks `.owflow/docs/standards/`) and detects the pre-existing state of `.owflow/` — routing to backup, update, or cancel accordingly. Complete it before any other phase.
+
 ## Phase Configuration
 
 | Phase | Subject                            | activeForm                       |
@@ -163,7 +169,7 @@ Write each file to `.owflow/docs/project/`.
 
 ---
 
-## PHASE 7: Validate
+## PHASE 7: Validate → Exit Gate
 
 **Step 1**: Invoke `docs-operator` subagent via Task tool (subagent_type: `docs-operator`) with prompt:
 
@@ -179,17 +185,32 @@ Wait for docs-operator to complete, then immediately continue with Step 2.
 - Verify selected standards directories exist
 - Verify AGENTS.md integration
 
-**Step 3**: Display comprehensive summary:
-
-- Project analysis results (type, language, framework, architecture)
-- Structure created (tree with check marks for created items)
-- Documentation status (which docs generated, which standards initialized)
-- Key findings (strengths, opportunities)
-- Next steps:
-  1. Review generated documentation
-  2. Customize for your team
-  3. Start development with `/work`
-  4. Keep documentation current
+**Step 3: Results box** — present the summary as:
+
+```markdown
+## ✅ FLOW INIT COMPLETE — <project name>
+
+**Project type** — [type, language, framework, architecture]
+**Structure** — [tree with check marks for created items]
+**Docs** — [which docs generated, which standards initialized]
+**Standards** — [discovered count, applied]
+**Key findings** — [strengths, opportunities]
+
+**Created** — `.owflow/docs/INDEX.md`
+```
+
+**Step 4: Results-acceptance question** — use `question` — "Are these results correct?" with options:
+
+- **Accept** — initialization is complete; print next steps below.
+- **Adjust** — regenerate the affected artifact (analysis, doc, standards) with the user's corrections, then re-present the results box.
+- **Discuss** — walk through the generated structure and findings in more depth; then re-ask.
+- **Stop here** — end; everything is already written to `.owflow/docs/`.
+
+**Next steps (after Accept)**:
+
+1. Review and customize the generated documentation and standards for your team
+2. Start development with `/owflow:development "<task description>"` (or project work)
+3. Keep documentation current via `/owflow:standards-update "<convention>"`
 
 ---
 

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

@@ -0,0 +1,96 @@
+---
+name: owflow:goal-development
+description: Full orchestrated development wrapper — runs ALL development phases in one session by invoking every dev-* subskill in sequence with question gates between them. Equivalent to the classic unified orchestrator.
+argument-hint: "[task description | task-path] [--from=<step-slug>] [--research=PATH] [--e2e] [--user-docs]"
+user-invocable: true
+---
+
+# Orchestrated Development Wrapper
+
+Autonomous mode for development tasks. Initializes (or resumes) the task, then invokes every required `dev-*` subskill back-to-back via the Skill tool, pausing at gates between subskills. Shares `orchestrator-state.yml` with assisted mode (`/owflow:development`) — 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).
+
+## Entry Gate
+
+Identical to the dispatcher — complete ALL of its entry-gate steps first:
+
+1. Read the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md) and the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+2. Detect prior work context: research folder path or `--research=<path>` flag (same detection and state setup as the development dispatcher — see `../development/SKILL.md` Entry Gate). Dev-bugfix tasks (`.owflow/tasks/development/` entries with `entry_point: "dev-bugfix"`) need no special handling — they are standard development tasks; route from the first missing slug.
+3. Initialize (new task) or resume (task path): create task directory + `orchestrator-state.yml` with `verify_template` validation, discover `.owflow/docs/INDEX.md` project docs, write command flags to `options.*`. On resume, find the first step slug NOT in `completed_phases` (validate artifacts; `--from=<step-slug>` overrides).
+4. Create ONE task item via `TaskCreate` per subskill in the upcoming loop (subject: `"<step names>: <subskill>"`, e.g. `"Analysis: dev-analyze"`); update statuses as the loop progresses.
+
+**Output**:
+
+```
+🚀 Orchestrated Development
+
+Task: [description]
+Directory: [task-path]
+Loop: dev-analyze → [dev-tdd-red] → dev-spec → dev-plan → dev-implement → dev-verify → dev-finalize
+```
+
+---
+
+## The Loop
+
+For each subskill in sequence (skipping conditionals below), execute:
+
+1. **Announce**: 1-line phase 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). 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**: no separate gate between `dev-analyze` and `dev-tdd-red` when the red gate activates — these two run back-to-back (mirrors the AUTO-CONTINUE of the classic orchestrator). A gate still applies between analysis and spec.
+
+### Sequence and Conditionals
+
+| Order | Subskill      | Run when (from state)                                    |
+| ----- | ------------- | -------------------------------------------------------- |
+| 1     | dev-analyze   | Always                                                   |
+| 2     | dev-tdd-red   | `task_characteristics.has_reproducible_defect: true`     |
+| 3     | dev-spec      | Analysis complete (`gap-analysed` in `completed_phases`) |
+| 4     | dev-plan      | `implementation/spec.md` exists                          |
+| 5     | dev-implement | Spec + plan exist                                        |
+| 6     | dev-verify    | `implementation-done` completed                          |
+| 7     | dev-finalize  | `verification-done` completed; honors `e2e_enabled`/`user_docs_enabled` internally |
+
+**Interruptible**: at any gate the user may answer "stop" — print the standard handoff block (next command + `/owflow:development <task-path>` resume hint) and end the session. The task resumes later in either mode.
+
+---
+
+## Exit Gate
+
+When dev-finalize completes (`task.status: completed`):
+
+1. Mark the final task item completed via `TaskUpdate`.
+2. Present the workflow results box:
+
+```markdown
+## ✅ DEVELOPMENT WORKFLOW COMPLETE — <task name>
+
+**Steps** — [executed step slugs]
+**Verification** — [final verification outcome]
+**Artifacts** — [task directory artifact summary]
+**Commit message** — [template]
+```
+
+3. Use `question` — "Are these results correct?" with options: **Accept** (print follow-up suggestions: `/owflow:reviews-pragmatic <task-path>`, `/owflow:standards-update "<lesson>"`, commit/PR, then end) / **Adjust** (re-open the relevant `/owflow:dev-*` skill) / **Discuss** (walk through the summary) / **Stop here** (print the resume command and end).
+
+Then end. No further owflow phase commands are required.
+
+---
+
+## Loop Rules
+
+- **Delegate, never inline**: the wrapper only sequences — all phase work happens inside subskills. If you catch yourself implementing/analyzing 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 (`codebase-analysed` … `task-completed`) are identical; resume works across modes.
+
+## Command Integration
+
+Invoked via:
+
+- `/owflow:goal-development [description] [--e2e] [--user-docs] [--research=PATH]` (new)
+- `/owflow:goal-development [task-path] [--from=<step-slug>]` (resume)
+
+Alternative: `/owflow:development` — same task in assisted mode (one subskill per invocation, fresh context each phase).

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

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

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

@@ -1,5 +1,5 @@
 ---
-name: html-renderer
+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`.
 disable-model-invocation: true
 user-invocable: true
@@ -9,6 +9,8 @@ user-invocable: true
 
 Turn a markdown plan/idea/RFC into a single self-contained HTML page that follows the warm editorial design system bundled in this skill.
 
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — "Inputs and outputs" below IS the Entry Gate; Workflow step 7 (Verify) plus the Exit Gate block at the close.
+
 ## When to use
 
 The user gives you a markdown file (or pastes markdown) describing a plan, idea, proposal, RFC, design note, or brief, and wants a clean HTML representation they can share. Output is *always* a portable single-file `.html` with the stylesheet inlined — no external assets, no JS.
@@ -43,6 +45,17 @@ Reuse existing classes and tokens before inventing anything. If the user asks fo
    - `<body>` containing `<main class="hr-page">` wrapping the sectioned content.
 6. **Write** the file as `<basename>.html` next to the source.
 7. **Verify**: re-open the output and confirm every `class="hr-..."` you emitted exists in the inlined CSS.
+8. **Exit Gate**: present the results box, then confirm (Exit Gate contract, [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+```markdown
+## ✅ HTML RENDER COMPLETE
+
+**Source** — `<source.md>`
+**Output** — `<basename>.html` (single file, self-contained)
+**Sections** — [count] · **Diagrams** — [count, if any]
+```
+
+Use `question` — "Is the rendering correct?" with options: **Accept** (open the file in a browser and stop) / **Adjust** (user names layout/section issues; fix and re-present) / **Discuss** (explain a mapping or class choice) / **Stop here**. Note: visual correctness can only be confirmed by the user in a browser — offer to open it via the user's preferred `open`/`xdg-open` command.
 
 ## Markdown → HTML mapping
 

package/dist/skills/implementation-plan-executor/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: implementation-plan-executor
+name: owflow:implementation-plan-executor
 description: Execute implementation plans by delegating each task group to task-group-implementer subagent. Main agent coordinates prepares context, invokes subagent, processes output, marks checkboxes, updates work-log. Uses lazy standards loading from INDEX.md with keyword-triggered discovery.
 user-invocable: false
 ---

package/dist/skills/implementation-verifier/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: implementation-verifier
+name: owflow:implementation-verifier
 description: Verify completed implementations for quality assurance. Delegates all verification work to specialized subagents - completeness checking, test execution, code review, pragmatic review, production readiness, and reality assessment. Compiles results into comprehensive verification report. Read-only verification - reports issues but does not fix them. Use after implementation is complete and before code review/commit.
 user-invocable: false
 ---

package/dist/skills/migration/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: migration
+name: owflow:migration
 description: Orchestrates the complete migration workflow from current state analysis through implementation to compatibility verification. Handles technology migrations, platform changes, and architecture pattern transitions with adaptive risk assessment, incremental execution, and rollback planning. Use when migrating technologies, platforms, or architecture patterns.
 user-invocable: true
 ---
@@ -8,23 +8,35 @@ user-invocable: true
 
 Systematic migration workflow from current state analysis to verified migration with rollback capabilities.
 
-## Initialization
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md).
+
+## Entry Gate
 
 **BEFORE executing any phase, you MUST complete these steps:**
 
-### Step 1: Load Framework Patterns
+### Argument resolution
+
+- **Migration description provided** → use it as the task description.
+- **Task path / identifier** (directory under `.owflow/tasks/migrations/`) → resume mode: read `orchestrator-state.yml`, find the first incomplete phase (`--from=PHASE` overrides), validate existing artifacts, then continue from there.
+- **Nothing provided** → ask via `question`: "What technology, platform, or architecture should be migrated, and to what?" — capture source and target state before proceeding.
+
+### Prerequisites
 
-**Read the framework reference file NOW using the Read tool:**
+| Required for this skill | Where verified                                        | Produced by                |
+| ----------------------- | ----------------------------------------------------- | -------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml` (resume mode)    | prior `/owflow:migration` run |
 
-1. `../orchestrator-framework/references/orchestrator-patterns.md` - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution
+On resume, if the state file is missing → print: `No migration task found at <path>. Run /owflow:migration <description> to start from scratch.` and STOP. Validate expected artifacts for completed phases (remove entries with missing artifacts).
 
-### Step 2: Initialize Workflow
+### Execution steps
 
-1. **Create Task Items**: Use `TaskCreate` for all phases (see Phase Configuration), then set dependencies with `TaskUpdate addBlockedBy`
-2. **Create Task Directory**: `.owflow/tasks/migrations/YYYY-MM-DD-task-name/`
-3. **Initialize State**: Create `orchestrator-state.yml` with migration context
-   - **CRITICAL**: Use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-migration.yml`.
-4. **Discover project documentation**: Read `.owflow/docs/INDEX.md` (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as `project_context.project_doc_paths` in state.
+1. **Load framework patterns** — Read `../orchestrator-framework/references/orchestrator-patterns.md` NOW: delegation rules, interactive mode, state schema, initialization, context passing, issue resolution.
+2. **Initialize workflow:**
+   1. **Create Task Items**: Use `TaskCreate` for all phases (see Phase Configuration), then set dependencies with `TaskUpdate addBlockedBy`
+   2. **Create Task Directory**: `.owflow/tasks/migrations/YYYY-MM-DD-task-name/`
+   3. **Initialize State**: Create `orchestrator-state.yml` with migration context
+      - **CRITICAL**: Use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-migration.yml`.
+   4. **Discover project documentation**: Read `.owflow/docs/INDEX.md` (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as `project_context.project_doc_paths` in state.
 
 **Output**:
 
@@ -282,14 +294,14 @@ question - Display executive summary: total issues found, issues fixed, issues r
 
 ---
 
-### Phase 8: Documentation (Optional)
+### Phase 8: Documentation → Exit Gate (Optional)
 
 > **Phase gate**: Requires `question` confirmation from the preceding phase before executing.
 
-**Purpose**: Create migration guide for end users
-**Execute**: Task tool - `user-docs-generator` subagent
-**Output**: `documentation/migration-guide.md`
-**State**: Set documentation complete
+**Purpose**: Create migration guide (optional) and run the Exit Gate
+**Execute**: Task tool - `user-docs-generator` subagent (conditional) + Direct (Exit Gate)
+**Output**: `documentation/migration-guide.md` (conditional)
+**State**: Set documentation complete, then `task.status: completed`
 
 **Skip if**: `options.docs_enabled = false`
 
@@ -301,6 +313,39 @@ question - Display executive summary: total issues found, issues fixed, issues r
 - Rollback procedures
 - Troubleshooting common issues
 
+**Results box** (present regardless of whether docs ran):
+
+```markdown
+## ✅ MIGRATION COMPLETE — <task name>
+
+**Migration type** — [code / data / architecture]
+**Strategy** — [incremental / big-bang / dual-run / phased]
+**Verification** — [final verdict]
+**Rollback plan** — [path / status]
+**Migration guide** — [path] / not generated
+
+**Artifacts**
+- `analysis/current-state-analysis.md`
+- `analysis/target-state-plan.md`
+- `analysis/rollback-plan.md`
+- `implementation/work-log.md`
+- `verification/implementation-verification.md`
+- `documentation/migration-guide.md` [conditional]
+```
+
+**Results-acceptance question** — use `question` — "Are these results correct?" with options:
+
+- **Accept** — migration is complete; print next steps below.
+- **Adjust** — re-run the affected phase (fixes, re-verification, docs) with the user's corrections, then re-present the results box.
+- **Discuss** — walk through specific results (verification verdicts, rollback readiness, guide contents) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration <task-path>`) and end.
+
+**Next steps (after Accept)**:
+
+- `/owflow:reviews-pragmatic <task-path>` — post-migration over-engineering check
+- `/owflow:standards-update "<lesson learned>"` — capture migration learnings as standards
+- Commit the changes and open a PR using the migration guide's procedures
+
 → End of workflow
 
 ---
@@ -355,7 +400,7 @@ Refer to the template [src/templates/orchestrator-state-migration.yml](../../tem
 
 Invoked via:
 
-- `/migration [description] [--type=TYPE]` (new)
-- `/migration [task-path] [--from=PHASE]` (resume)
+- `/owflow:migration [description] [--type=TYPE]` (new)
+- `/owflow:migration [task-path] [--from=PHASE]` (resume)
 
 Task directory: `.owflow/tasks/migrations/YYYY-MM-DD-task-name/`

package/dist/skills/orchestrator-framework/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: orchestrator-framework
+name: owflow:orchestrator-framework
 description: Shared orchestration patterns for all workflow orchestrators. NOT an executable skill - provides reference documentation for phase execution, state management, interactive mode, and initialization. All orchestrators reference these patterns.
 user-invocable: false
 ---

package/dist/skills/orchestrator-framework/references/command-namespacing.md

@@ -0,0 +1,7 @@
+# Command Namespacing
+
+How commands and skills are named and referenced. Extracted from `orchestrator-patterns.md` (Section 8) so skills can link to it directly.
+
+- Slash commands registered from `src/commands/*.md` use `name: owflow:<command>` in frontmatter; users invoke `/owflow:<command>`.
+- **Skill `name:` fields are prefixed too.** Skill-tool invocations (`skill: "owflow:development"`, `skills:` frontmatter preloads, work.md routing) always reference `owflow:`-prefixed skill names.
+- Handoff messages, docs, and cross-references always display the prefixed slash command — never the bare skill name — in user-facing text.

package/dist/skills/orchestrator-framework/references/confirm-or-revise-exception.md

@@ -0,0 +1,20 @@
+# Confirm-or-Revise Exception
+
+Extension of the [Gate Contract](gate-contract.md) for utility skills with explicit no-follow-up contracts — currently `agents-md-generator` and `rule-reviewer`.
+
+## Rule
+
+The standard Exit Gate's results-acceptance question offers four options (Accept / Adjust / Discuss / Stop). Utility skills whose whole purpose is to produce a single artifact and stop **narrow this to confirm-or-revise only**:
+
+- **Confirm** — the artifact is good; end the skill.
+- **Revise** — user specifies what to change; re-work only the affected parts of the artifact, then re-present it and re-ask.
+
+## What stays prohibited
+
+- No follow-up suggestions, "next steps" hints, or "Other options" blocks after Confirm.
+- No auto-chaining into other skills or workflows.
+- Follow-up work happens only if the user explicitly asks for it.
+
+## Why
+
+Utility skills end their contract with the artifact itself — there is no pipeline to continue — so offering pipeline-style next steps would imply a workflow that does not exist.

package/dist/skills/orchestrator-framework/references/delegation-rules.md

@@ -0,0 +1,54 @@
+# Delegation Rules
+
+Shared rules for how orchestrators and subskills delegate work. Extracted from `orchestrator-patterns.md` (Section 1) so skills can link to it directly.
+
+---
+
+**Always use Skill/Task tools to delegate. Never execute delegated work inline.**
+
+When a phase requires delegation:
+
+1. Use the **Skill tool** for **skills** — loads SKILL.md instructions into the main agent's context; the main agent executes the skill's instructions and continues with the orchestrator workflow afterward
+2. Use the **Task tool** for **subagents/agents** — spawns an isolated subprocess that returns results when complete
+3. Wait for completion before continuing
+
+**Skills and agents are NOT interchangeable.** Skills always use Skill tool; agents always use Task tool. Never invoke a skill via Task tool (`subagent_type`) — it will fail with "Agent type not found."
+
+**Why skills MUST use Skill tool**: Skills like `codebase-analyzer`, `implementation-plan-executor`, and `implementation-verifier` spawn their own subagents (Explore agents, reporters, planners). Subagents cannot spawn other subagents — so these skills must run in the main agent context via Skill tool.
+
+**Companion agent pattern** (e.g., `docs-operator`): Only works for skills that do NOT spawn subagents (like `docs-manager` which only does file operations). A companion agent preloads the skill via the `skills` frontmatter field and is invoked via Task tool. This pattern fails for any skill that needs to spawn subagents.
+
+## Anti-Patterns
+
+| Anti-Pattern                            | Why It's Wrong                              | Correct Approach                                      |
+| --------------------------------------- | ------------------------------------------- | ----------------------------------------------------- |
+| "I'll analyze the codebase..."          | Bypasses codebase-analyzer skill            | Use `Skill` tool with `codebase-analyzer`             |
+| "Let me create the specification..."    | Bypasses specification-creator              | Use `Task` tool with `specification-creator` subagent |
+| "Looking at the gaps between..."        | Bypasses gap-analyzer subagent              | Use `Task` tool with `gap-analyzer`                   |
+| "I'll implement this by..."             | Bypasses implementation-plan-executor skill | Use `Skill` tool with `implementation-plan-executor`  |
+| Reading a SKILL.md then doing the work  | Skill files are instructions FOR skills     | Use Skill tool to invoke                              |
+| Spawning Explore agents in orchestrator | Codebase-analyzer manages its own agents    | Invoke skill, let IT spawn agents                     |
+
+## When Inline Execution is Acceptable
+
+These do NOT require delegation:
+
+1. **Clarifying questions phases** — question is direct
+2. **State updates** — Reading/writing orchestrator-state.yml
+3. **Phase announcements** — Outputting status messages
+4. **Simple decisions** — Enabling/disabling optional phases
+5. **Finalization** — Creating summary, updating metadata
+
+For all analysis, planning, implementation, and verification phases: **ALWAYS DELEGATE**.
+
+**Never acceptable inline** (regardless of perceived task simplicity):
+
+- Specification creation → always delegate to `specification-creator` subagent
+- Implementation planning → always delegate to `implementation-planner` subagent
+- Gap analysis → always delegate to `gap-analyzer` subagent
+- Codebase analysis → always delegate to `codebase-analyzer` skill
+- Code review → always delegate to `code-reviewer` subagent
+- Test execution → always delegate to `test-suite-runner` subagent
+- Implementation completeness → always delegate to `implementation-completeness-checker` subagent
+
+"The task is simple" is NOT a valid reason to skip delegation.