owflow 0.1.10 → 0.3.0

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/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.

package/dist/skills/orchestrator-framework/references/dispatcher-handoff.md

@@ -0,0 +1,20 @@
+# Dispatcher & Handoff Pattern (Subskill Loop)
+
+How orchestrators delegate phase bodies to user-invocable **subskills**. Extracted from `orchestrator-patterns.md` (Section 7) so skills can link to it directly.
+
+Orchestrators MAY delegate phase bodies to user-invocable **subskills** instead of executing them inline. Two modes share one state file and one set of subskills:
+
+| Mode              | Entry point              | Behavior                                                                                                |
+| ----------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| Orchestrated mode | wrapper skill/command    | Invokes subskills back-to-back via Skill tool in sequence; pauses at `question` gates between subskills |
+| Assisted mode      | dispatcher skill/command | Derives next phase from state, prints the suggested command, and **STOPS**; user invokes each subskill  |
+
+## Rules
+
+1. **State file is canonical.** `orchestrator-state.yml` remains the single source of truth. Subskills read it on entry and write step results on exit. `completed_phases` values MUST stay stable so both modes intermix freely on the same task.
+   - **Value convention**: `completed_phases` / `failed_phases` / `auto_fix_attempts` keys are **descriptive step slugs**, not `phase-N` numbers. The development workflow defines the canonical slugs (`codebase-analysed`, `gap-analysed`, `tdd-red-proven`, `spec-written`, `spec-audited`, `plan-created`, `implementation-done`, `tdd-green-proven`, `options-chosen`, `verification-done`, `e2e-run`, `docs-generated`, `task-completed` — see `skills/development/SKILL.md` routing table and `templates/orchestrator-state-development.yml`). New orchestrators SHOULD use descriptive step slugs too; older orchestrators (performance, migration, research) still use `phase-N` and MUST be kept internally consistent.
+2. **Subskills are self-contained.** Each has: an entry check (validate state + prerequisite artifacts), an execute section (delegation via Skill/Task tools per the [Delegation Rules](delegation-rules.md)), and an exit (state update + closing ritual). **State updates are per-step**: a subskill writes `orchestrator-state.yml` immediately after each of its steps completes — appending only the step slug actually performed, bumping `orchestrator.updated`, recording failures in `failed_phases`/`auto_fix_attempts`, and validating with `verify_template` — never as a single end-of-skill write.
+3. **Closing ritual (handoff) → Exit Gate.** Every subskill ends with the **Exit Gate** contract, see [Gate Contract](gate-contract.md) (results box → results-acceptance question → next-step hint on accept → STOP).
+4. **Entry checks replace phase gates in assisted mode.** A subskill invoked directly must validate the same prerequisites a phase gate would (e.g., spec exists before audit) and route to the prerequisite's command if missing — via its **Entry Gate** ([Gate Contract](gate-contract.md)).
+5. **Never chain automatically.** The orchestrated wrapper invokes; subskills only SUGGEST the next command and stop. Auto-chaining from a subskill skips user review.
+6. **Assisted mode is the gate.** In assisted mode, the user explicitly invoking the next command IS the phase gate — no additional `question` confirmation before a subskill starts.

package/dist/skills/orchestrator-framework/references/gate-contract.md

@@ -0,0 +1,104 @@
+# Gate Contract — Entry Gate & Exit Gate (Skill Contract)
+
+Shared contract for how every user-invocable skill opens and closes. Extracted from `orchestrator-patterns.md` (Section 9) so skills can link to it directly.
+
+Every **user-invocable** skill (orchestrators, subskills, dispatchers, utility commands) opens with an **Entry Gate** and closes with an **Exit Gate**. Internal skills (subagent-invoked, `user-invocable: false`) use lightweight input/structured-output contracts instead and never call `question`.
+
+## Entry Gate
+
+The Entry Gate runs BEFORE any phase work. It validates that this skill is allowed to run and routes to what is missing instead of guessing.
+
+1. **Argument resolution** — resolve the argument in priority order: full path → identifier (directory name under the workflow's task type) → fresh description. If missing, ambiguous, or unmatched:
+   - Print a structured ask: the exact inputs accepted, with format examples, then WAIT.
+   - NEVER guess, auto-pick a task, or proceed with a resolved-by-hope path.
+2. **Prerequisite check** — verify each required upstream artifact, expressed as a table the skill keeps at the top of its body:
+
+   | Required for this skill | Where verified                                                      | Produced by                  |
+   | ----------------------- | ------------------------------------------------------------------- | ---------------------------- |
+   | State file exists       | `<task-path>/orchestrator-state.yml`                                | `/owflow:development <desc>` |
+   | Analysis done           | `gap-analysed` in `completed_phases` + `analysis/gap-analysis.md` exists | `/owflow:dev-analyze`        |
+   | Spec approved           | `implementation/spec.md` exists                                     | `/owflow:dev-spec`           |
+
+   Verify **presence and, where cheap, content** (state field values like `has_reproducible_defect`, marker artifacts like `implementation/tdd-red-gate.md`), not just file existence.
+
+3. **Blocked output** — when a prerequisite is unmet, print the blocked block and STOP:
+   1. Numbered "Steps that must be completed first (in order)", each with its exact prefixed command (`/owflow:dev-analyze <task-path>`).
+   2. List of resumable task identifiers (directories under the workflow's task type), if any exist.
+   3. Fresh-start hint: `Run /owflow:<entry-command> <description> to start a task from scratch.`
+4. **Skip/resume semantics** — when the skill's steps are already in `completed_phases` (validate artifacts before trusting state): report the existing results briefly and route to the Exit Gate instead of re-executing.
+5. **Conditional activation** — skills that only apply under a state condition (e.g., TDD red gate requires `has_reproducible_defect: true`) check it as part of the Entry Gate and route to the correct alternative command when inactive.
+
+### Missing-state bootstrap (mid-pipeline entry)
+
+When a dev-* subskill is invoked with a task path/identifier whose `orchestrator-state.yml` exists nowhere (no task, no state file) and the ONLY unmet prerequisite is the state file itself, the skill does not blindly send the user back to the full pipeline — the user chose to enter mid-pipeline. Instead:
+
+1. **Ask** via `question`: "No development task exists at this path. Create a fresh standard development task and start at `<this skill's first step slug>`?"
+2. **On confirm (bootstrap)**:
+   - Create the task directory `.owflow/tasks/development/YYYY-MM-DD-task-name/` (name derived from the argument or the user's input) — mark `orchestrator.entry_point: "<skill> (mid-pipeline bootstrap)"` and `started_phase` with this skill's starting step slug.
+   - Create `orchestrator-state.yml` from `orchestrator-state-development.yml`, honoring any of the skill's command flags into `options.*`; leave `completed_phases` empty (upstream steps stay unrecorded).
+   - Run `verify_template` against `orchestrator-state-development.yml`.
+   - Then continue into Execute. Because bootstrapping creates **state only — never upstream artifacts**, later artifact prerequisites (e.g., `implementation/spec.md` before planning) still block with the normal precondition loop, so an incorrectly early bootstrap cannot silently skip work.
+3. **On decline** — print the blocked block with the fresh-start hint (`Run /owflow:development <description> to start a task from scratch.`) and STOP.
+
+Skill starting points (used for the bootstrap question and `started_phase`): dev-analyze → `codebase-analysed`; dev-tdd-red → `tdd-red-proven`; dev-spec → `spec-written`; dev-plan → `plan-created`; dev-implement → `implementation-done`; dev-verify → `options-chosen`; dev-finalize → `e2e-run`.
+
+### Deterministic entry checks (future)
+
+Entry-gate checks above are currently executed by the agent reading state. For more deterministic routing, future work considers (a) a small script that checks whether `orchestrator-state.yml` exists, parses it, and answers slug/next-step queries, and (b) an OpenCode lifecycle hook that automates these entry-gate checks for dev-* skills before they run. Until then, follow the rules above exactly as written.
+
+## Exit Gate
+
+The Exit Gate runs after all phase work and state updates are final. It presents results, asks the user to confirm them, and only then hands off.
+
+1. **Results box** — one-screen markdown summary (no ASCII borders, markdown headings/bold carry the emphasis):
+
+   ```markdown
+   ## ✅ <SKILL> COMPLETE — <task name>
+
+   **<Field 1>** — [key outcome]
+   **<Field 2>** — [key outcome]
+
+   **Artifacts**
+
+   - `relative/path/to/artifact.md`
+
+   **Next ▸** `/owflow:<next-skill> <task-path>`
+   ```
+
+   Conventions:
+   - Status glyphs follow the outcome: ✅ pass/success, ⚠ pass-with-concerns/partial, ❌ fail.
+   - Set the **Next ▸** line to the suggested next command for this skill; omit it when the next-step hint depends on the Accept response (the handoff block is printed after Accept anyway).
+
+2. **Results-acceptance question** (MANDATORY, fires before any handoff hint):
+
+   Use `question` — "Are these results correct?" with options:
+   - **Accept** — results are good; proceed to the next-step hint.
+   - **Adjust** — user specifies what to change; re-work ONLY the affected parts, update artifacts/state, then re-present the results box and re-ask.
+   - **Discuss** — walk through a specific result in more depth (evidence, reasoning, alternatives); after the discussion, re-ask.
+   - **Stop here** — artifacts persist; print the resume command (`/owflow:<this-skill> <task-path>` or the next phase command) and end.
+
+3. **Next-step hint** — only after Accept: print the suggested next command derived from state, plus an "Other options" block of alternative valid commands. Every suggested command is a **compact annotated entry**:
+   - **Purpose** — one line stating what the proposed skill does.
+   - **Requirement tag** — `required` (mandatory next phase) or `optional` (shortcut, standalone utility, or conditional step) with its activation condition, e.g. `optional — only when has_reproducible_defect: true`.
+   - **Remaining plan** (for optional/alternative paths) — one compact line listing the phases still ahead in execution order, marking which are optional.
+   - Standalone review/utility commands are annotated `optional — does not advance phases`.
+
+   Example shape (~5 lines):
+
+   ```
+   → /owflow:dev-verify <task-path>
+     What: runs the verification pipeline (completeness, code review, fixes) — required before commit. Remaining after: /owflow:dev-finalize (required).
+   Other options:
+   /owflow:reviews-code <task-path> — optional, does not advance phases (standalone re-run of code review)
+   /owflow:goal-development <task-path> — optional shortcut: runs all remaining phases in one loop (… → verify → finalize)
+   ```
+
+   Then STOP. Never auto-invoke the next skill.
+
+4. **Gate ordering** — per the Phase Gate Behavior state ordering rule in `orchestrator-patterns.md`: finish phase work → present results box → acceptance question → user responds → THEN the state is already consistent (per-step writes happened during Execute); the Exit Gate never mutates phase state on its own except recording the user's acceptance decision where the state schema has a field for it.
+
+## Exceptions
+
+- **Dispatchers** (`development`): the Exit Gate's acceptance question is adapted — the results box is the handoff block, and the question asks how to proceed (hand off to the suggested subskill / switch to autonomous mode / adjust / stop).
+- **Utility skills with explicit no-follow-up contracts** (`agents-md-generator`, `rule-reviewer`): the acceptance question is confirm-or-revise only; follow-up suggestions stay prohibited unless the user asks. See [confirm-or-revise exception](confirm-or-revise-exception.md).
+- **Orchestrated mode** (`goal-development`): the subskill's own Exit Gate acceptance question IS the loop gate — Accept means "continue to the next subskill". The wrapper MUST NOT add a second consecutive `question`.