owflow 0.4.3 → 0.5.0

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

@@ -0,0 +1,131 @@
+---
+name: owflow:migration-plan
+description: Migration — delegates implementation planning with a rollback/checkpoint step mandated in every task group, then refines the plan with a diagram (plan-created).
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Plan — Rollback-Guarded Implementation Plan (plan-created)
+
+Work phase of the migration workflow. Delegates planning to the reused `implementation-planner` agent with the migration requirement that **every task group carries a rollback/checkpoint step**, then refines the plan with an execution diagram.
+
+## Entry Gate
+
+### 1. Argument resolution
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/migrations/` (e.g., `2026-01-12-framework-upgrade`); resolve to its path.
+- Missing argument, a path that does **not exist**, or no identifier match → print the blocked block (part 3), then STOP. Never guess or auto-pick a task.
+
+### 2. Prerequisites
+
+| Required for this skill | Where verified                                                       | Produced by                          |
+| ----------------------- | -------------------------------------------------------------------- | ------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                 | `/owflow:migration <description>` (dispatcher init) or mid-pipeline bootstrap |
+| Strategy specified      | `strategy-specified` in `completed_phases` **and** `implementation/spec.md` exists | `/owflow:migration-spec <task-path>` |
+| Rollback plan consumed  | `analysis/rollback-plan.md` exists (source of per-group rollback content) | `/owflow:migration-spec <task-path>` |
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order), each with its command:
+   - Requirements, specification & rollback/dual-run plans (`strategy-specified`) → `/owflow:migration-spec <task-path>`
+   - Target state planning (`target-planned`) → `/owflow:migration-target <task-path>` (if also missing)
+   - Current-state analysis (`state-analysed`) → `/owflow:migration-analyze <task-path>` (if also missing)
+   - State initialization → `/owflow:migration <description>` (new task)
+2. List available migration-task identifiers (directories under `.owflow/tasks/migrations/`) to resume from, if any.
+3. Hint: `Run /owflow:migration <description> to start a migration task from scratch, or pass a task path/identifier to resume.`
+
+Then STOP — never guess or auto-pick a task.
+
+### 4. Missing-state bootstrap
+
+When the only unmet prerequisite is the state file, use `question` — "No task exists at this path. Create a fresh standard migration task and start at `plan-created`?" with **Create task** / **Decline**.
+
+- **On confirm**: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template with `orchestrator.entry_point: "migration-plan (mid-pipeline bootstrap)"`, `orchestrator.started_phase: plan-created`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — `implementation/spec.md` and the rollback plan still block, so bootstrapping never skips upstream work.
+- **On decline**: print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+
+### 5. Skip/resume — artifacts before state
+
+- `implementation/implementation-plan.md` exists but `plan-created` is missing ⇒ **adopt**: append `plan-created`, backfill `phase_summaries.plan.summary` and `migration_outputs.implementation_plan` where still null.
+- `plan-created` is present but `implementation/implementation-plan.md` is missing ⇒ **drop** `plan-created` from `completed_phases` and re-run.
+- Both artifact and slug exist ⇒ report the existing plan summary and route to the Exit Gate.
+- `analysis/rollback-plan.md` is missing while `strategy-specified` holds ⇒ route back to `/owflow:migration-spec <task-path>` to regenerate the extraction — never re-author it here.
+
+### 6. Conditional activation
+
+Not applicable — `migration-plan` has no activation condition; it runs whenever its prerequisites are met.
+
+### 7. Recovery
+
+| Step                       | Max Attempts | Strategy                                                                                         |
+| -------------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
+| Implementation planning (`plan-created`) | 2 | Regenerate with the migration constraints restated: a rollback/checkpoint step in every task group and rollback content read from the strategies reference |
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), then read `../migration-spec/references/migration-strategies.md` for the rollback-step content (the rollback-plan structure and strategy patterns).
+
+| Direction | Artifact                            | Producer                                                        |
+| --------- | ----------------------------------- | --------------------------------------------------------------- |
+| Consumed  | `implementation/spec.md`            | `migration-spec` (approved specification)                       |
+| Consumed  | `analysis/rollback-plan.md`         | `migration-spec` (per-group rollback content)                   |
+| Produced  | `implementation/implementation-plan.md` | `implementation-planner` (**Task**, frozen contract)        |
+
+### Delegated Planning with Per-Group Rollback (`plan-created`)
+
+> **ANTI-PATTERN — never write `implementation-plan.md` yourself. "The groups are straightforward" is NOT a reason to skip delegation.**
+
+1. **Task tool — `implementation-planner`** (frozen contract). Pass: `task_path`, `task_description`, `migration_context.*` (type, strategy, risk level, breaking changes), `phase_summaries` (spec plus upstream), `implementation/spec.md`, and `analysis/rollback-plan.md` as the rollback source.
+2. **Injected requirement**: the delegation prompt **mandates** that every task group carries a rollback/checkpoint step, with rollback-step content read from `../migration-spec/references/migration-strategies.md`. Pass that path and the `analysis/rollback-plan.md` structures explicitly.
+3. **SELF-CHECK before the state write**: read `implementation/implementation-plan.md` and confirm every task group ends with a rollback/checkpoint step. If any group is missing one, re-invoke the planner with the requirement restated — do not append the rollback steps yourself.
+4. **Skill tool — `diagrams-mermaid`** (content-preserving) on `implementation/implementation-plan.md`: add one migration execution/state flow with rollback checkpoints. The written steps and rollback details remain authoritative; diagrams are explanatory. A skipped or failed refinement is not a failure — note it in `phase_summaries.plan.summary` and continue.
+5. **State write**: append `plan-created` to `completed_phases`; set `phase_summaries.plan.summary`, `migration_outputs.implementation_plan`; bump `orchestrator.updated`. On failure: append `plan-created` to `failed_phases`, increment `auto_fix_attempts["plan-created"]`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`plan-created`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — a failed or abandoned step is NOT appended to `completed_phases`; append its slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-migration.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ MIGRATION PLAN COMPLETE — <task name>
+
+**Task groups** — [N]
+**Total steps** — [M]
+**Rollback coverage** — ✅ every task group carries a rollback/checkpoint step
+**Execution order** — [key dependencies, 1-2 lines]
+**Diagram** — [added / skipped (optional)]
+
+**Artifacts**
+
+- `implementation/implementation-plan.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the plan is good; continue.
+- **Adjust** — regenerate the plan with the user's corrections (grouping, ordering, rollback steps), update state, re-present the results box.
+- **Discuss** — walk through the task groups, dependencies, or rollback/checkpoint design in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-plan <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:migration-implement <task-path>` — `required` next: executes the plan task group by task group with the per-group rollback/checkpoint steps and writes the work log. Remaining after: verify (→ fix when needed) → finalize.
+
+**Other options**:
+
+- `/owflow:goal-migration <task-path>` — `optional` shortcut: runs all remaining phases in one loop (implement → verify → fix when needed → finalize)
+
+Then STOP.

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

@@ -0,0 +1,135 @@
+---
+name: owflow:migration-spec
+description: Migration — gathers requirements, delegates the specification with mandated rollback/dual-run sections, extracts the standalone plans, then refines diagrams (strategy-specified).
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Spec — Requirements, Specification & Rollback/Dual-Run Plans (strategy-specified)
+
+Work phase of the migration workflow. Gathers migration requirements inline, delegates specification creation to the reused `specification-creator` agent with **mandated** rollback/dual-run sections, extracts those sections into standalone authoritative artifacts, then refines the spec with diagrams.
+
+## Entry Gate
+
+### 1. Argument resolution
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/migrations/` (e.g., `2026-01-12-framework-upgrade`); resolve to its path.
+- Missing argument, a path that does **not exist**, or no identifier match → print the blocked block (part 3), then STOP. Never guess or auto-pick a task.
+
+### 2. Prerequisites
+
+| Required for this skill | Where verified                                                            | Produced by                        |
+| ----------------------- | ------------------------------------------------------------------------- | ---------------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                      | `/owflow:migration <description>` (dispatcher init) or mid-pipeline bootstrap |
+| Target state locked     | `target-planned` in `completed_phases` **and** `analysis/target-state-plan.md` exists | `/owflow:migration-target <task-path>` |
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order), each with its command:
+   - Target state planning (`target-planned`) → `/owflow:migration-target <task-path>`
+   - Current-state analysis (`state-analysed`) → `/owflow:migration-analyze <task-path>` (if also missing)
+   - State initialization → `/owflow:migration <description>` (new task)
+2. List available migration-task identifiers (directories under `.owflow/tasks/migrations/`) to resume from, if any.
+3. Hint: `Run /owflow:migration <description> to start a migration task from scratch, or pass a task path/identifier to resume.`
+
+Then STOP — never guess or auto-pick a task.
+
+### 4. Missing-state bootstrap
+
+When the only unmet prerequisite is the state file, use `question` — "No task exists at this path. Create a fresh standard migration task and start at `strategy-specified`?" with **Create task** / **Decline**.
+
+- **On confirm**: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template with `orchestrator.entry_point: "migration-spec (mid-pipeline bootstrap)"`, `orchestrator.started_phase: strategy-specified`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — `analysis/target-state-plan.md` still blocks, so bootstrapping never skips upstream work.
+- **On decline**: print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+
+### 5. Skip/resume — artifacts before state
+
+- `implementation/spec.md` **and** `analysis/rollback-plan.md` exist but `strategy-specified` is missing ⇒ **adopt**: append `strategy-specified`, backfill `migration_context.{rollback_plan_created, dual_run_configured}`, `phase_summaries.spec.summary`, and the `migration_outputs` paths where still null; run only the missing parts.
+- `strategy-specified` is present but `implementation/spec.md` is missing ⇒ **drop** `strategy-specified` from `completed_phases` and re-run.
+- `analysis/requirements.md` exists ⇒ adopt it and skip the requirement-questions part when it already covers the topics; `analysis/dual-run-plan.md` exists ⇒ `dual_run_configured: true`.
+- Settled `rollback_plan_created` / `dual_run_configured` values are reported, not re-asked.
+
+### 6. Conditional activation
+
+Not applicable — `migration-spec` has no activation condition; the dual-run plan's presence is content-dependent (decided in the requirement questions), not an activation gate.
+
+### 7. Recovery
+
+| Step                                | Max Attempts | Strategy                                                                                     |
+| ----------------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
+| Requirements                        | 2            | Re-gather in one consolidated question round                                                  |
+| Specification (`strategy-specified`) | 2           | Re-invoke `specification-creator` with the missing mandated section explicitly demanded        |
+| Rollback/dual-run extraction        | 2            | Re-extract verbatim from `implementation/spec.md`; if a mandated section is absent, re-run the delegation step |
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), then **read `references/migration-strategies.md`** (rollback-plan and dual-run-plan structures, strategy selection).
+
+| Direction | Artifact                        | Producer                                                        |
+| --------- | ------------------------------- | --------------------------------------------------------------- |
+| Consumed  | `analysis/target-state-plan.md` | `migration-target` (locked target, type, strategy)              |
+| Produced  | `analysis/requirements.md`      | inline `question` round (3–5 questions)                         |
+| Produced  | `implementation/spec.md`        | `specification-creator` (**Task**, frozen contract)             |
+| Produced  | `analysis/rollback-plan.md`     | post-delegation verbatim extraction (always)                    |
+| Produced  | `analysis/dual-run-plan.md`     | post-delegation verbatim extraction (when dual-run applies)     |
+
+### Requirements, Specification & Extraction (`strategy-specified`)
+
+1. **Requirements gathering (inline)** — use `question` for 3–5 migration-specific questions: scope boundaries, rollback expectations and downtime tolerance, data-migration specifics, dual-run requirements, existing code/config to preserve. Frame as confirmable assumptions. Save to `analysis/requirements.md`.
+2. **Project-doc discovery (nothing persisted)** — read `.owflow/docs/INDEX.md` if present, collect the Project Documentation paths as `project_context_paths`, and pass them directly to the delegate. There is no `project_context` state key; do not write one (assumption 8).
+3. **Task tool — `specification-creator`** (frozen contract). Pass: `task_path`, `task_description`, `requirements_path` (`analysis/requirements.md`), `project_context_paths`, `migration_context.*` (type, current/target system, risk level, breaking changes), and relevant `phase_summaries`. The prompt **mandates** a `## Rollback Plan` section (always) and a `## Dual-Run Configuration` section (when dual-run applies) inside `implementation/spec.md`.
+4. **Post-delegation extraction — before the diagrams step**: as soon as the delegation returns, extract those sections **verbatim** from `implementation/spec.md` into `analysis/rollback-plan.md` (always) and `analysis/dual-run-plan.md` (when present). The standalone artifact is authoritative; the spec section becomes its summary. Never let the diagrams step run first.
+5. **Skill tool — `diagrams-mermaid`** (content-preserving) on `implementation/spec.md`: add a target-architecture and transition/compatibility visual as a supplement, never a replacement for strategy prose. Missing context → record open gaps instead of inventing systems.
+6. **State write**: append `strategy-specified` to `completed_phases`; set `migration_context.rollback_plan_created: true`, `migration_context.dual_run_configured: true/false`, `phase_summaries.spec.summary`, `migration_outputs.requirements`, `migration_outputs.spec`, `migration_outputs.rollback_plan` (+ `migration_outputs.dual_run_plan` when produced); bump `orchestrator.updated`. On failure: append `strategy-specified` to `failed_phases`, increment `auto_fix_attempts["strategy-specified"]`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`strategy-specified`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — a failed or abandoned step is NOT appended to `completed_phases`; append its slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-migration.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ MIGRATION SPEC COMPLETE — <task name>
+
+**Strategy** — [strategy from the locked target / spec]
+**Scope** — [N included / M excluded]
+**Rollback plan** — ✅ `analysis/rollback-plan.md` (standalone, authoritative)
+**Dual-run** — [configured → `analysis/dual-run-plan.md` / not applicable]
+**Diagrams** — [added / skipped (optional)]
+
+**Artifacts**
+
+- `analysis/requirements.md`
+- `implementation/spec.md` (mandates the Rollback Plan / Dual-Run Configuration sections)
+- `analysis/rollback-plan.md`
+- `analysis/dual-run-plan.md` [conditional]
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the specification and extracted plans are correct; continue.
+- **Adjust** — re-run only the affected part (requirements, spec delegation, extraction, diagrams), update state and artifacts, re-present the results box.
+- **Discuss** — walk through scope boundaries, the rollback approach, or the dual-run decision in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-spec <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:migration-plan <task-path>` — `required` next: breaks the approved spec into task groups, mandating a rollback/checkpoint step in every group. Remaining after: implement → verify (→ fix when needed) → finalize.
+
+**Other options**:
+
+- `/owflow:goal-migration <task-path>` — `optional` shortcut: runs all remaining phases in one loop (plan → implement → verify → fix when needed → finalize)
+
+Then STOP.

package/dist/skills/{migration → migration-spec}/references/migration-strategies.md

@@ -4,7 +4,7 @@
 
 **Purpose:** Pattern guide for migration execution strategies (incremental, rollback, dual-run)
 
-This reference provides decision criteria and implementation patterns for the three core migration strategies supported by the migration orchestrator.
+This reference provides decision criteria and implementation patterns for the three core migration strategies supported by the migration workflow.
 
 ---
 
@@ -21,7 +21,7 @@ This reference provides decision criteria and implementation patterns for the th
 
 ## Overview
 
-Migration strategies define **how** to execute the transition from current to target state. The migration orchestrator supports three core strategies, which can be combined:
+Migration strategies define **how** to execute the transition from current to target state. The migration workflow supports three core strategies, which can be combined:
 
 | Strategy        | Purpose                                 | Risk Level  | Use When                                     |
 | --------------- | --------------------------------------- | ----------- | -------------------------------------------- |
@@ -155,7 +155,7 @@ If success: Continue to Phase 2
 
 ### Implementation Pattern
 
-**Rollback Plan Structure** (`planning/rollback-plan.md`):
+**Rollback Plan Structure** (`analysis/rollback-plan.md`):
 
 ```markdown
 # Rollback Plan: [Migration Name]
@@ -273,7 +273,7 @@ Old System (100% traffic) → Dual-Run (Old + New in parallel) → New System (1
 - Keep old system running for 7-30 days (rollback safety net)
 - After validation period, decommission old system
 
-**Dual-Run Plan Structure** (`planning/dual-run-plan.md`):
+**Dual-Run Plan Structure** (`analysis/dual-run-plan.md`):
 
 ```markdown
 # Dual-Run Plan: [Migration Name]
@@ -422,9 +422,9 @@ Phase 5: Decommission MySQL
 4. **Combine strategies** based on risk, scope, and requirements
 5. **Document procedures** before executing migration
 
-**References in SKILL.md**:
+**Read by**:
 
-- Phase 2 (Specification): Select migration strategy
-- Phase 3 (Planning): Structure implementation plan by strategy
-- Phase 4 (Execution): Execute according to selected strategy
-- Phase 5 (Verification): Test rollback procedures (non-destructive)
+- `migration-spec`: select the migration strategy and produce the rollback/dual-run plans
+- `migration-plan`: structure the implementation plan by strategy (per-task-group rollback steps)
+- `migration-implement`: execute according to the selected strategy
+- `migration-verify`: test rollback procedures non-destructively and run the compatibility checks

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

@@ -0,0 +1,134 @@
+---
+name: owflow:migration-target
+description: Migration — plans the target state and gap inventory, classifies the migration type, recommends a strategy, and records external research. Owns the risk-lock boundary (target-planned).
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Target — Target State, Type & Risk Lock (target-planned)
+
+Work phase of the migration workflow. Delegates the gap inventory to the reused `gap-analyzer` agent, then authors type classification and strategy recommendation inline from `references/migration-types.md`. The Exit Gate locks target, type, strategy, and breaking changes for the rest of the pipeline — downstream skills treat them as frozen.
+
+## Entry Gate
+
+### 1. Argument resolution
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/migrations/` (e.g., `2026-01-12-framework-upgrade`); resolve to its path.
+- Missing argument, a path that does **not exist**, or no identifier match → print the blocked block (part 3), then STOP. Never guess or auto-pick a task.
+
+### 2. Prerequisites
+
+| Required for this skill | Where verified                                                              | Produced by                          |
+| ----------------------- | --------------------------------------------------------------------------- | ------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                        | `/owflow:migration <description>` (dispatcher init) or mid-pipeline bootstrap |
+| Current state analysed  | `state-analysed` in `completed_phases` **and** `analysis/current-state-analysis.md` exists | `/owflow:migration-analyze <task-path>` |
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order), each with its command:
+   - Current-state analysis (`state-analysed`) → `/owflow:migration-analyze <task-path>`
+   - State initialization → `/owflow:migration <description>` (new task)
+2. List available migration-task identifiers (directories under `.owflow/tasks/migrations/`) to resume from, if any.
+3. Hint: `Run /owflow:migration <description> to start a migration task from scratch, or pass a task path/identifier to resume.`
+
+Then STOP — never guess or auto-pick a task.
+
+### 4. Missing-state bootstrap
+
+When the only unmet prerequisite is the state file, use `question` — "No task exists at this path. Create a fresh standard migration task and start at `target-planned`?" with **Create task** / **Decline**.
+
+- **On confirm**: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template with `orchestrator.entry_point: "migration-target (mid-pipeline bootstrap)"`, `orchestrator.started_phase: target-planned`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — `analysis/current-state-analysis.md` still blocks, so bootstrapping never skips upstream work.
+- **On decline**: print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+
+### 5. Skip/resume — artifacts before state
+
+- `analysis/target-state-plan.md` exists but `target-planned` is missing ⇒ **adopt**: append `target-planned`, backfill `migration_context.{migration_type, target_system, risk_level, breaking_changes}`, `external_research.*`, `phase_summaries.target.summary`, and `migration_outputs.target_state_plan` where still null.
+- `target-planned` is present but `analysis/target-state-plan.md` is missing ⇒ **drop** `target-planned` from `completed_phases` and re-run.
+- Both artifact and slug exist ⇒ report the existing type/strategy/risk decision and route to the Exit Gate; do not re-ask a settled type.
+- The template placeholder `"code | data | architecture | general"` is NOT a settled type — only a real classification or a dispatcher `--type` value is.
+
+### 6. Conditional activation
+
+Not applicable — `migration-target` has no activation condition; it runs whenever its prerequisites are met.
+
+### 7. Recovery
+
+| Step                      | Max Attempts | Strategy                                                                             |
+| ------------------------- | ------------ | ------------------------------------------------------------------------------------ |
+| Target planning (`target-planned`) | 2    | Re-prompt for target details; re-run the gap inventory with the clarified target      |
+| Type confirmation         | 1            | Present the detected type with its keyword evidence; fall back to the user's choice   |
+| External research         | 1            | Retry with narrower queries; on failure record `external_research.performed: false` and continue — research never blocks |
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), then **read `references/migration-types.md`** (type detection with confidence, per-type research table, per-type verification focus).
+
+**Flags** (documented here because `argument-hint` is not registered): `--type=code|data|architecture|general` is a **default, not an override** — detection still runs and low confidence still asks for confirmation; `--no-web-research` skips the research step and records `external_research.performed: false` truthfully.
+
+| Direction | Artifact                     | Producer                                                        |
+| --------- | ---------------------------- | --------------------------------------------------------------- |
+| Consumed  | `analysis/current-state-analysis.md` | `migration-analyze`                                     |
+| Produced  | `analysis/target-state-plan.md` | `gap-analyzer` (**Task**) + inline path normalization and type/strategy content |
+
+### Target Planning, Type & Risk Lock (`target-planned`)
+
+> **ANTI-PATTERN — never author the gap inventory inline. The gap analysis is delegated; the inline content is only type classification, strategy recommendation, and the research record.**
+
+1. **Task tool — `gap-analyzer`** (frozen contract, gap inventory only). Pass: `task_path`, current-state summary, target description (`task.description` + clarifications), and constraints. The agent hard-codes its output as `analysis/gap-analysis.md`.
+2. **Normalize the path**: after the agent returns, rename/move its output to the declared artifact `analysis/target-state-plan.md`.
+3. **Type classification** (inline): run the keyword/confidence algorithm from `references/migration-types.md` against the migration description. A dispatcher `--type` value is the starting default, never an override. When confidence < 100% (or the default is ambiguous), use `question` with the detected type and evidence to confirm/adjust. Write `migration_context.migration_type`.
+4. **Strategy recommendation** (inline): pick incremental / big-bang / dual-run / phased with the reference decision tree; the rationale belongs in `phase_summaries.target.summary` and the plan artifact — the vestigial `migration_strategy` block stays unwritten.
+5. **External research** (unless `--no-web-research`): WebSearch per the per-type research table. Record `external_research.performed`, `.category`, `.breaking_changes`, `.migration_guide_url` — `migration-target` is the declared single writer of the `external_research.*` block. On a deliberate skip record `performed: false` — never leave the block implying research that did not happen.
+6. **State write**: append `target-planned` to `completed_phases`; set `migration_context.target_system.description`, `migration_context.target_system.technologies`, `migration_context.risk_level`, `migration_context.breaking_changes`, `external_research.performed`, `external_research.category`, `external_research.breaking_changes`, `external_research.migration_guide_url`, `phase_summaries.target.summary`, `migration_outputs.target_state_plan`; bump `orchestrator.updated`. On failure: append `target-planned` to `failed_phases`, increment `auto_fix_attempts["target-planned"]`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`target-planned`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — a failed or abandoned step is NOT appended to `completed_phases`; append its slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-migration.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ MIGRATION TARGET COMPLETE — <task name>
+
+**Target system** — [1-line summary from state]
+**Migration type** — [code / data / architecture / general] ([confidence] / user-confirmed / `--type` default)
+**Strategy** — [incremental / big-bang / dual-run / phased] — [1-line rationale]
+**Risk level** — [low / medium / high] ([N] breaking changes; ⚠ high requires rollback + compatibility testing)
+**External research** — [performed: N queries / skipped (`--no-web-research`)]
+
+🔒 **Risk lock** — target system, migration type, strategy, and breaking changes are LOCKED at this gate; changing any of them routes back through `/owflow:migration-target`.
+
+**Artifacts**
+
+- `analysis/target-state-plan.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the locked target is correct; continue.
+- **Adjust** — re-run only the affected part (gap inventory, type, strategy, or research), update state and artifact, re-present the results box.
+- **Discuss** — walk through the type evidence, strategy rationale, or risk assessment in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-target <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:migration-spec <task-path>` — `required` next: gathers requirements, produces the specification with mandated rollback/dual-run sections, and extracts the standalone plans. Remaining after: plan → implement → verify (→ fix when needed) → finalize.
+
+**Other options**:
+
+- `/owflow:goal-migration <task-path>` — `optional` shortcut: runs all remaining phases in one loop (spec → plan → implement → verify → fix when needed → finalize)
+
+Then STOP.

package/dist/skills/{migration → migration-target}/references/migration-types.md

@@ -4,7 +4,7 @@
 
 **Purpose:** Pattern guide for the three migration types: Code, Data, and Architecture
 
-This reference provides characteristics, detection patterns, and workflow adaptations for each migration type supported by the migration orchestrator.
+This reference provides characteristics, detection patterns, and workflow adaptations for each migration type supported by the migration workflow.
 
 ---
 
@@ -91,27 +91,27 @@ Different types require different:
 
 ### Workflow Adaptations
 
-**Phase 1 (Current State Analysis)**:
+**`migration-analyze` (Current State Analysis)**:
 
 - Focus: Locate all source files using old framework/library
 - Analyze: Dependency tree, API usage patterns, deprecated features used
 
-**Phase 2 (Target State Planning)**:
+**`migration-target` (Target State Planning)**:
 
 - Focus: Breaking changes between versions, API equivalents
 - Output: Breaking changes list, API migration map
 
-**Phase 3 (Specification)**:
+**`migration-spec` (Specification)**:
 
 - Include: Compatibility shim requirements (if needed)
 - Rollback: Simple (revert code via git)
 
-**Phase 5 (Execution)**:
+**`migration-implement` (Execution)**:
 
 - Strategy: Incremental (by module/component)
 - Testing: Functional tests per module
 
-**Phase 6 (Verification)**:
+**`migration-verify` (Verification)**:
 
 - Focus: Functional equivalence (behavior unchanged)
 - Tests: Full test suite, manual testing of critical flows
@@ -176,28 +176,28 @@ Different types require different:
 
 ### Workflow Adaptations
 
-**Phase 1 (Current State Analysis)**:
+**`migration-analyze` (Current State Analysis)**:
 
 - Focus: Database schema, row counts, data volume, stored procedures
 - Analyze: Data relationships, foreign keys, indexes, constraints
 
-**Phase 2 (Target State Planning)**:
+**`migration-target` (Target State Planning)**:
 
 - Focus: Data transformation requirements, data mapping (old → new schema)
 - Output: Data transformation specification, estimated migration time
 
-**Phase 3 (Specification)**:
+**`migration-spec` (Specification)**:
 
 - Include: Data validation procedures, integrity checks, rollback procedures
 - Rollback: Complex (requires backup/restore strategies)
 - Dual-Run: Often required (zero-downtime)
 
-**Phase 5 (Execution)**:
+**`migration-implement` (Execution)**:
 
 - Strategy: Incremental + Dual-Run (high confidence in strategy choice)
 - Testing: Data integrity checks after each batch
 
-**Phase 6 (Verification)**:
+**`migration-verify` (Verification)**:
 
 - Focus: Data integrity (100% row count match, checksums, data validation)
 - Tests: Full test suite + data integrity tests + performance benchmarks
@@ -271,28 +271,28 @@ Different types require different:
 
 ### Workflow Adaptations
 
-**Phase 1 (Current State Analysis)**:
+**`migration-analyze` (Current State Analysis)**:
 
 - Focus: System components, communication patterns, dependencies between components
 - Analyze: Coupling/cohesion, service boundaries, data flow
 
-**Phase 2 (Target State Planning)**:
+**`migration-target` (Target State Planning)**:
 
 - Focus: New architecture structure, component boundaries, communication patterns
 - Output: Architecture diagram, component mapping (old → new)
 
-**Phase 3 (Specification)**:
+**`migration-spec` (Specification)**:
 
 - Include: Strangler fig pattern (if applicable), component interaction diagrams
 - Rollback: Moderate to complex (depends on dual-run feasibility)
 - Dual-Run: Often required (old and new architectures in parallel)
 
-**Phase 5 (Execution)**:
+**`migration-implement` (Execution)**:
 
 - Strategy: Incremental (by component/service) + Dual-Run (if possible)
 - Testing: Integration tests, end-to-end tests, performance tests
 
-**Phase 6 (Verification)**:
+**`migration-verify` (Verification)**:
 
 - Focus: System-level behavior (end-to-end flows work), performance comparison
 - Tests: Full test suite + integration tests + E2E tests
@@ -333,7 +333,7 @@ Different types require different:
 
 ### Workflow Adaptations
 
-**Phase 1-2 (Analysis + Planning)**:
+**`migration-analyze` → `migration-target` (Analysis + Target Planning)**:
 
 - Spend extra time clarifying scope
 - Prompt user to specify what's changing (code, data, architecture, or all)
@@ -423,7 +423,7 @@ Terms: "refactor to", "architecture", "pattern", "system design", "restructure"
 
 ## Web Research Requirements by Type
 
-External research is automatically triggered by the gap-analyzer during Phase 2 (Target State Planning). The level of research depends on migration type.
+External research runs inline in `migration-target` — the `gap-analyzer` agent performs the gap inventory only and has no web access. The level of research depends on migration type, and the outcome is recorded in `external_research.*` (including `performed: false` when skipped).
 
 | Migration Type             | External Research | Query Focus                                       | Priority Sources                                  |
 | -------------------------- | ----------------- | ------------------------------------------------- | ------------------------------------------------- |
@@ -482,9 +482,8 @@ External research is automatically triggered by the gap-analyzer during Phase 2
 3. **Architecture**: Focus on system-level behavior, strangler fig pattern, high risk
 4. **General**: Conservative defaults, extra clarification with user
 
-**References in SKILL.md**:
+**Read by**:
 
-- Initialization (Step 2): Type detection algorithm
-- Phase 1 (Analysis): Type-specific analysis focus
-- Phase 2 (Target Planning): Type-specific gap analysis + external research
-- Phase 6 (Verification): Type-specific verification requirements
+- `migration-target`: type detection algorithm (with confidence scoring), type-specific gap analysis, external research requirements
+- `migration-analyze`: type-specific analysis focus
+- `migration-verify`: type-specific verification requirements