owflow 0.1.1 → 0.1.3

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

@@ -0,0 +1,307 @@
+---
+name: 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
+---
+
+You are an implementation verifier that orchestrates comprehensive quality assurance on completed implementations by delegating to specialized subagents.
+
+## Core Principle
+
+**Read-only verification via delegation**: Delegate all analysis to subagents. Compile results. Never fix, modify, or re-implement.
+
+## Responsibilities
+
+1. Validate prerequisites exist
+2. Delegate ALL verifications to subagents in parallel (core + optional)
+3. Compile all results into verification report
+4. Update roadmap if exists (optional)
+5. Output summary with overall verdict
+
+## Output Artifacts
+
+| Artifact                                      | Condition                   |
+| --------------------------------------------- | --------------------------- |
+| `verification/implementation-verification.md` | Always                      |
+| `verification/code-review-report.md`          | If code_review_enabled      |
+| `verification/pragmatic-review.md`            | If pragmatic_review_enabled |
+| `verification/production-readiness-report.md` | If production_check_enabled |
+| `verification/reality-check.md`               | If reality_check_enabled    |
+
+---
+
+## Invocation Context
+
+**Check for orchestrator state file** at task path:
+
+- **Orchestrator mode**: If `orchestrator-state.yml` exists, read verification options from it. Execute enabled reviews without re-prompting.
+- **Standalone mode**: If no state file, prompt user for each optional review using question.
+
+**Orchestrator options** (when present, are mandatory):
+
+- `skip_test_suite` (when true, test-suite-runner is skipped — full test suite already passed during implementation phase)
+- `code_review_enabled` / `code_review_scope`
+- `pragmatic_review_enabled`
+- `production_check_enabled`
+- `reality_check_enabled`
+
+---
+
+## Phase 1: Initialize & Validate
+
+1. **Get task path** from user or orchestrator parameter
+2. **Validate prerequisites exist**:
+   - `implementation/implementation-plan.md` (required)
+   - `implementation/spec.md` (required)
+   - `implementation/work-log.md` (required)
+3. **Read docs/INDEX.md** to understand available standards
+4. **Determine invocation context** (orchestrator or standalone)
+5. **Create task items for verification tracking** using `TaskCreate` tool:
+   - Subject: "Completeness check", activeForm: "Checking implementation completeness"
+   - Subject: "Test suite", activeForm: "Running test suite" — only if NOT skip_test_suite. When skip_test_suite is true, create task pre-completed with `metadata: {skipped: true, reason: "Full test suite passed during implementation phase"}`
+   - Subject: "Code review", activeForm: "Running code review" — only if code_review_enabled
+   - Subject: "Pragmatic review", activeForm: "Running pragmatic review" — only if pragmatic_review_enabled
+   - Subject: "Production readiness", activeForm: "Checking production readiness" — only if production_check_enabled
+   - Subject: "Reality assessment", activeForm: "Running reality assessment" — only if reality_check_enabled
+   - Subject: "Compile report", activeForm: "Compiling verification report"
+6. **Set dependencies** using `TaskUpdate` with `addBlockedBy`: "Compile report" blocked by ALL verification tasks above
+
+If prerequisites missing, report and stop.
+
+---
+
+## Phase 2: Delegate All Verifications
+
+**ANTI-PATTERN — DO NOT DO ANY OF THIS:**
+
+- ❌ "Let me run the tests..." — STOP. Delegate to test-suite-runner.
+- ❌ "I'll check implementation-plan.md..." — STOP. Delegate to implementation-completeness-checker.
+- ❌ "Let me read the standards..." — STOP. Delegate to implementation-completeness-checker.
+- ❌ "I'll verify the work-log..." — STOP. Delegate to implementation-completeness-checker.
+- ❌ Running any Bash command to execute tests — STOP. Delegate to test-suite-runner.
+- ❌ "Let me review the code quality..." — STOP. Delegate to code-reviewer.
+- ❌ "I'll check for over-engineering..." — STOP. Delegate to code-quality-pragmatist.
+- ❌ "Let me verify production readiness..." — STOP. Delegate to production-readiness-checker.
+- ❌ "I'll assess whether this solves the problem..." — STOP. Delegate to reality-assessor.
+- ❌ Reading source code to find security/performance issues — STOP. Delegate to code-reviewer.
+
+**Verifications run in two sequential steps to avoid parallel test conflicts.**
+
+### Step 1: Determine enabled optional reviews
+
+1. **Check invocation context** for each optional review:
+   - If orchestrator mode AND option is `true`: Include in verification (mandatory)
+   - If orchestrator mode AND option is `false`: Skip (mark task as completed with `metadata: {skipped: true}`)
+   - If orchestrator mode AND option is `null`: Warn and prompt user
+   - If standalone mode: Prompt user with question
+
+### Step 2: Set all tasks to in_progress
+
+2. Use `TaskUpdate` to set ALL enabled verification tasks to `status: "in_progress"`. For skipped optional reviews, use `TaskUpdate` with `status: "completed"` and `metadata: {"skipped": true}`.
+
+### Step 3a: Run test suite (sequential, if NOT skip_test_suite)
+
+**Why sequential**: Test-suite-runner and reality-assessor both run tests. Running them in parallel causes conflicts. Test-suite-runner runs first and writes results to a file that reality-assessor reads.
+
+Task tool call (if NOT skip_test_suite):
+
+- subagent_type: `test-suite-runner`
+- description: `Run full test suite`
+- prompt: Include task_path, task_description, test_command (if known). The subagent runs ALL tests, analyzes results, and writes results to `verification/test-suite-results.md`.
+
+**Wait for test-suite-runner to complete** before proceeding to Step 3b. Mark the test suite task as `completed` with results.
+
+**When `skip_test_suite: true`**: Skip Step 3a entirely. Go straight to Step 3b. The full project test suite already passed during the implementation phase. The verification report will note tests were verified during implementation.
+
+### Step 3b: Run all other verifications (parallel)
+
+**INVOKE NOW** — send ALL remaining enabled subagents in a SINGLE message (up to 5 parallel Task tool calls):
+
+Task tool call (always):
+
+- subagent_type: `implementation-completeness-checker`
+- description: `Check implementation completeness`
+- prompt: Include task_path. The subagent checks plan completion, standards compliance, and documentation completeness.
+
+Task tool call (if code_review_enabled):
+
+- subagent_type: `code-reviewer`
+- description: `Code quality review`
+- prompt: Include task_path, scope (from code_review_scope or "all"), report_path (`[task_path]/verification/code-review-report.md`)
+
+Task tool call (if pragmatic_review_enabled):
+
+- subagent_type: `code-quality-pragmatist`
+- description: `Pragmatic code review`
+- prompt: Include task_path, report_path (`[task_path]/verification/pragmatic-review.md`)
+
+Task tool call (if production_check_enabled):
+
+- subagent_type: `production-readiness-checker`
+- description: `Production readiness check`
+- prompt: Include task_path, target (production), report_path (`[task_path]/verification/production-readiness-report.md`)
+
+Task tool call (if reality_check_enabled):
+
+- subagent_type: `reality-assessor`
+- description: `Reality assessment`
+- prompt: Include task_path, report_path (`[task_path]/verification/reality-check.md`).
+  - **If test-suite-runner ran (Step 3a)**: Include `skip_test_execution: true` and path to `verification/test-suite-results.md`. Reality-assessor should read test results from that file instead of running tests.
+  - **If test-suite-runner was skipped**: Include `skip_test_execution: false`. Reality-assessor should run tests itself since no other agent did.
+
+**SELF-CHECK**: Did you invoke test-suite-runner separately in Step 3a (or skip it), then invoke all remaining subagents in a single parallel message in Step 3b? Or did you launch everything at once? If the latter, STOP — test-suite-runner must complete before the parallel batch.
+
+### Step 4: Process all results
+
+After ALL subagents return:
+
+1. Use `TaskUpdate` to set each verification task to `status: "completed"`
+2. Extract status, issues, and findings from each
+3. Aggregate issue counts
+4. Track any critical issues that would affect overall verdict
+
+### Impact on Overall Status
+
+- Code review critical issues → overall status Failed
+- Pragmatic review critical over-engineering → overall status Failed
+- Production readiness deployment blockers → overall status Failed
+- Reality assessment critical gaps → overall status Failed
+
+---
+
+## Phase 3: Compile Verification Report
+
+Use `TaskUpdate` to set "Compile report" task to `status: "in_progress"`.
+
+1. **Compile all findings** from Phase 2
+2. **Determine overall status**:
+
+   | Status                | Criteria                                                                                                                                                        |
+   | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | ✅ Passed             | 100% implementation, 95%+ tests passing (or skipped — verified in implementation), standards compliant, docs complete, no critical issues from optional reviews |
+   | ⚠️ Passed with Issues | 90-99% implementation OR 90-94% tests OR standards gaps OR optional review warnings                                                                             |
+   | ❌ Failed             | <90% implementation OR <90% tests OR critical failures OR deployment blockers                                                                                   |
+
+   **When tests skipped** (`skip_test_suite: true`): Test pass rate is inherited from implementation phase (assumed passing since implementation completed successfully). Note this in the report.
+
+3. **Write verification report** to `verification/implementation-verification.md`
+4. Use `TaskUpdate` to set "Compile report" task to `status: "completed"`
+
+   Structure:
+   - Executive summary (2-3 sentences)
+   - Implementation plan verification (from completeness checker)
+   - Test suite results (from test runner)
+   - Standards compliance (from completeness checker)
+   - Documentation completeness (from completeness checker)
+   - Optional review results (if performed)
+   - Overall assessment with breakdown table
+   - Issues requiring attention
+   - Recommendations
+   - Verification checklist
+
+---
+
+## Phase 4: Update Roadmap (Optional)
+
+1. **Check for roadmap** at `.owflow/docs/project/roadmap.md`
+2. **If exists**, find matching items and mark complete
+3. **Document** what was updated or why no matches found
+
+---
+
+## Phase 5: Finalize & Output
+
+Output summary to user:
+
+```
+Verification Complete!
+
+Task: [name]
+Location: [path]
+
+Overall Status: Passed | Passed with Issues | Failed
+
+Implementation Plan: [M]/[N] steps ([%])
+Test Suite: [P]/[N] tests ([%])
+Standards Compliance: [status]
+Documentation: [status]
+
+[If optional reviews performed]
+Code Review: [status]
+Pragmatic Review: [status]
+Production Readiness: [status]
+Reality Check: [status]
+
+Verification Report: verification/implementation-verification.md
+
+[Status-specific guidance on next steps]
+```
+
+---
+
+## Structured Output for Orchestrator
+
+When invoked by an orchestrator, return structured result alongside the report:
+
+```yaml
+status: "passed" | "passed_with_issues" | "failed"
+report_path: "verification/implementation-verification.md"
+
+issues:
+  - source: "completeness" | "test_suite" | "code_review" | "pragmatic" | "production" | "reality"
+    severity: "critical" | "warning" | "info"
+    description: "[Brief description of the issue]"
+    location: "[File path or area affected]"
+    fixable: true | false
+    suggestion: "[How to fix, if obvious]"
+
+issue_counts:
+  critical: 0
+  warning: 0
+  info: 0
+```
+
+**Guidelines for `fixable` assessment**:
+
+- `true`: Lint errors, formatting issues, missing imports, obvious typos, simple config fixes
+- `false`: Architecture decisions, design trade-offs, test logic errors, unclear requirements
+
+**The orchestrator decides** what to actually fix based on this data. Your job is to aggregate subagent results accurately.
+
+---
+
+## Guidelines
+
+### Delegation-First Verification
+
+✅ Delegate to subagents, compile results, write report, output summary
+❌ Run tests directly, review code directly, check standards directly, fix anything
+
+### Anti-Patterns to AVOID
+
+- ❌ Running Bash commands to execute tests → Use Task tool with `test-suite-runner`
+- ❌ Reading implementation-plan.md to check completion → Use Task tool with `implementation-completeness-checker`
+- ❌ Reading INDEX.md to check standards compliance → Use Task tool with `implementation-completeness-checker`
+- ❌ Reading source code for quality/security analysis → Use Task tool with `code-reviewer`
+- ❌ Checking config/monitoring/resilience directly → Use Task tool with `production-readiness-checker`
+- ❌ Performing ANY verification work inline → ALL verification is delegated to subagents
+
+### Clear Communication
+
+- Use consistent status icons in reports
+- Provide specific evidence from subagent results
+- List specific issues, not vague concerns
+- Make actionable recommendations
+
+---
+
+## Validation Checklist
+
+Before finalizing verification:
+
+- All required subagents invoked (completeness checker + test runner unless skip_test_suite)
+- Optional reviews invoked per context settings
+- All subagent results processed
+- Verification report created
+- Overall status determined from aggregated results
+- No direct analysis performed (all delegated)

package/dist/skills/migration/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: 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
+---
+
+# Migration Orchestrator
+
+Systematic migration workflow from current state analysis to verified migration with rollback capabilities.
+
+## Initialization
+
+**BEFORE executing any phase, you MUST complete these steps:**
+
+### Step 1: Load Framework Patterns
+
+**Read the framework reference file NOW using the Read tool:**
+
+1. `../orchestrator-framework/references/orchestrator-patterns.md` - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution
+
+### Step 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
+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**:
+
+```
+🚀 Migration Orchestrator Started
+
+Task: [migration description]
+Directory: [task-path]
+
+Starting Phase 1: Analyze current state...
+```
+
+---
+
+## When to Use
+
+Use for:
+
+- Migrating from one framework/library to another (e.g., Vue 2 → Vue 3, Express → Fastify)
+- Changing database platforms (e.g., MySQL → PostgreSQL, MongoDB → DynamoDB)
+- Refactoring architecture patterns (e.g., REST → GraphQL, Monolith → Microservices)
+- Upgrading major versions with breaking changes
+
+**DO NOT use for**: New features, bug fixes, pure refactoring without technology change.
+
+---
+
+## Core Principles
+
+1. **Analyze Before Migrating**: Understand current system before planning target state
+2. **Risk Assessment**: Classify migration type (code/data/architecture) and assess complexity
+3. **Incremental Execution**: Support phased migration with rollback points
+4. **Rollback Planning**: Document undo procedures for each migration phase
+5. **Dual-Run Support**: Enable running old and new systems in parallel during transition
+
+---
+
+## Migration Types
+
+| Type             | Keywords                             | Strategy                 | Risk Focus                        |
+| ---------------- | ------------------------------------ | ------------------------ | --------------------------------- |
+| **Code**         | framework, library, upgrade          | Incremental or phased    | Breaking changes, API differences |
+| **Data**         | database, schema, data migration     | Dual-run (zero downtime) | Data integrity, checksums         |
+| **Architecture** | REST→GraphQL, monolith→microservices | Dual-run or phased       | Compatibility, rollback           |
+
+---
+
+## Phase Configuration
+
+| Phase | content                                           | activeForm                                             | Agent/Skill                               |
+| ----- | ------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------- |
+| 1     | "Analyze current state"                           | "Analyzing current state"                              | codebase-analyzer                         |
+| 2     | "Plan target state and gaps"                      | "Planning target state and gaps"                       | gap-analyzer                              |
+| 3     | "Gather requirements & create migration strategy" | "Gathering requirements & creating migration strategy" | Direct + specification-creator (subagent) |
+| 4     | "Plan implementation"                             | "Planning implementation"                              | implementation-planner (subagent)         |
+| 5     | "Execute migration"                               | "Executing migration"                                  | implementation-plan-executor              |
+| 6     | "Verify and test compatibility"                   | "Verifying and testing compatibility"                  | implementation-verifier                   |
+| 7     | "Resolve verification issues"                     | "Resolving verification issues"                        | Direct (conditional)                      |
+| 8     | "Generate documentation"                          | "Generating documentation"                             | user-docs-generator (optional)            |
+
+---
+
+## Workflow Phases
+
+### Phase 1: Current State Analysis & Clarifications
+
+**Purpose**: Comprehensive analysis of current system before migration, followed by scope/requirements clarification
+**Execute**:
+
+1. Skill tool - `codebase-analyzer`
+2. Update state with analysis results
+3. Direct - use question for max 5 critical clarifying questions about migration scope, target system, and constraints
+4. Save clarifications to `analysis/clarifications.md`
+   **Output**: `analysis/current-state-analysis.md`, `analysis/clarifications.md`
+   **State**: Update task_context with current system info, `task_context.clarifications_resolved`
+
+→ **AUTO-CONTINUE** — Do NOT end turn, do NOT prompt user. Proceed immediately to Phase 2.
+
+---
+
+### Phase 2: Target State Planning & Gap Analysis
+
+**Purpose**: Define target system and identify migration gaps
+**Execute**: Task tool - `gap-analyzer` subagent
+**Output**: `analysis/target-state-plan.md`
+**State**: Update `migration_context.migration_type`, `target_system`, `risk_level`, `breaking_changes`
+
+**Gap Analyzer Tasks**:
+
+1. Define target system from migration description
+2. Identify gaps (features to migrate, APIs to adapt, data to transform)
+3. Classify migration type (code/data/architecture)
+4. Recommend migration strategy (incremental/big-bang/dual-run/phased)
+5. External research via WebSearch for version upgrades
+
+→ Pause
+
+question - Display executive summary before asking. Extract from gap analysis: current system overview, target system, migration type classified, number of gaps identified, recommended strategy, risk level. Format as brief overview then "Continue to migration strategy?"
+
+---
+
+### Phase 3: Migration Requirements & Strategy Specification
+
+> **Phase gate**: Requires `question` confirmation from Phase 2 before executing.
+
+**Purpose**: Gather migration requirements, then create detailed migration specification with rollback procedures
+**Execute**:
+
+**Part A — Migration Requirements Gathering (inline)**:
+
+1. Direct - use question for migration-specific requirements (3-5 questions):
+   - Migration scope and boundaries (what's in/out of migration)
+   - Rollback expectations and downtime tolerance
+   - Data migration specifics (if data migration type)
+   - Dual-run requirements (if applicable)
+   - Existing code/config to preserve
+   - Frame as confirmable assumptions: "I assume X, is that correct?"
+2. Save gathered requirements to `analysis/requirements.md`
+
+**Part B — Specification Creation (subagent)**: 3. Task tool - `specification-creator` subagent
+
+**Context to pass to subagent**: task_path, task_type (migration), task_description, requirements_path (analysis/requirements.md), project_context_paths (INDEX.md + project_doc_paths from state — all discovered project docs), migration_type, current_system, target_system, risk_level, breaking_changes, phase_summaries (current_state_analysis, gap_analysis)
+
+**Output**: `analysis/requirements.md`, `implementation/spec.md`, `analysis/rollback-plan.md`, optionally `analysis/dual-run-plan.md`
+**State**: Update `rollback_plan_created`, `dual_run_configured`
+
+→ Pause
+
+question - Display executive summary before asking. Read `implementation/spec.md` and extract: migration strategy chosen, scope boundaries, rollback approach, breaking changes identified, key constraints. Format as brief overview then "Continue to implementation planning?"
+
+---
+
+### Phase 4: Implementation Planning
+
+> **Phase gate**: Requires `question` confirmation from Phase 3 before executing.
+
+**Purpose**: Break migration into task groups with rollback steps
+**Execute**: Task tool - `implementation-planner` subagent
+**Output**: `implementation/implementation-plan.md` with rollback procedures
+**State**: Update task groups and dependencies
+
+**Context to pass to subagent**: task_path, task_type (migration), migration_type, task_description, phase_summaries (current_state_analysis, gap_analysis, specification)
+
+→ Pause
+
+question - Display executive summary before asking. Read `implementation/implementation-plan.md` and extract: number of task groups, total steps, rollback steps included, key dependencies, execution sequence. Format as brief overview then "Continue to execute migration?"
+
+---
+
+### Phase 5: Migration Execution
+
+> **Phase gate**: Requires `question` confirmation from Phase 4 before executing.
+
+**Purpose**: Execute migration steps with incremental verification
+
+**ANTI-PATTERN — DO NOT DO THIS:**
+
+- ❌ "Let me implement this directly..." — STOP. Delegate to implementation-plan-executor.
+- ❌ "This migration is simple enough to code inline..." — STOP. Simplicity is NOT a reason to skip delegation.
+
+**INVOKE NOW** — Skill tool call:
+
+**Execute**: Skill tool - `implementation-plan-executor`
+**Output**: Implemented migration changes, `implementation/work-log.md`
+**State**: Update implementation progress, extract phase_summaries.implementation
+
+📋 **Standards Reminder**: Review `.owflow/docs/INDEX.md` before implementing.
+
+**SELF-CHECK**: Did you just invoke the Skill tool with `implementation-plan-executor`? Or did you start writing migration code yourself? If the latter, STOP immediately and invoke the Skill tool instead.
+
+**⚠️ POST-IMPLEMENTATION CONTINUATION** — After the skill completes and returns control:
+
+1. Read `orchestrator-state.yml` to confirm you are the orchestrator
+2. Update state: add Phase 5 to `completed_phases`
+3. Proceed to Phase 6
+
+→ Pause
+
+question - Display executive summary before asking. Extract from `phase_summaries.implementation` and `implementation/work-log.md`: migration steps completed, files changed, test results, rollback readiness status. Format as brief overview then "Continue to verification?"
+
+---
+
+### Phase 6: Verification + Compatibility Testing
+
+> **Phase gate**: Requires `question` confirmation from Phase 5 before executing.
+
+**Purpose**: Verify migration success with compatibility and rollback testing
+**Execute**: Skill tool - `implementation-verifier`
+**Output**: `verification/implementation-verification.md`, `verification/compatibility-test-results.md`
+**State**: Update verification results
+
+**Migration-Specific Checks**:
+
+- Verify old system still works (if dual-run)
+- Test rollback procedures (non-destructive)
+- Validate data integrity (for data migrations)
+- Check performance benchmarks (before/after)
+
+**⚠️ POST-VERIFICATION CONTINUATION** — After the skill completes and returns control:
+
+1. Read `orchestrator-state.yml` to confirm you are the orchestrator
+2. Update state: add Phase 6 to `completed_phases`
+3. Evaluate verdict: if PASS → Phase 8, if fixable issues → Phase 7, otherwise stop workflow
+
+→ Pause
+
+question - Display executive summary before asking. Extract from verification results: overall verdict, issue counts by severity, compatibility test results, data integrity status, rollback test results. Format as detailed overview then "Continue to Phase [7 or 8]?"
+
+---
+
+### Phase 7: Migration Issue Resolution (Conditional)
+
+> **Phase gate**: Requires `question` confirmation from Phase 6 before executing.
+
+**Purpose**: Fix verification issues through direct editing and re-verification
+**Execute**: Direct - apply fixes, re-verify
+**Output**: Updated code, `verification_context.fixes_applied`
+**State**: Update `reverify_count`, `decisions_made`
+
+**Skip if**: verdict = PASS
+
+**Process**:
+
+1. Display detailed issue breakdown grouped by category and severity, listing location, description, and fixability
+2. Present all critical + warning issues as a numbered list
+3. question — "Which issues should I fix?" with options: "Fix all fixable issues" / "Let me choose specific issues" / "Skip fixes, proceed as-is"
+4. Fix selected issues
+5. question — "Re-run verification to check fixes?" with options: "Yes, re-run verification" / "No, proceed to next phase"
+6. If re-run → re-invoke `implementation-verifier` → return to Step 1
+7. Max 3 iterations
+
+**Data Safety Critical**: HALT on any data integrity issue - never auto-fix data problems. Always present data issues to user with rollback option.
+
+**Exit Conditions**:
+
+- ✅ No critical issues remain → Proceed to Phase 8
+- ⚠️ Max iterations (3) reached → Ask user: proceed with warnings or rollback
+- ❌ Data integrity issues → HALT immediately, recommend rollback
+
+→ Pause
+
+question - Display executive summary: total issues found, issues fixed, issues remaining by severity. Then "Continue to documentation?"
+
+---
+
+### Phase 8: Documentation (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
+
+**Skip if**: `options.docs_enabled = false`
+
+**Documentation Covers**:
+
+- Migration overview and goals
+- Prerequisites and preparation steps
+- Step-by-step migration procedure
+- Rollback procedures
+- Troubleshooting common issues
+
+→ End of workflow
+
+---
+
+## Domain Context (State Extensions)
+
+Migration-specific fields in `orchestrator-state.yml`:
+
+```yaml
+migration_context:
+  migration_type: "code" | "data" | "architecture" | "general"
+  current_system:
+    description: null
+    technologies: []
+  target_system:
+    description: null
+    technologies: []
+  migration_strategy:
+    approach: "incremental" | "big-bang" | "dual-run" | "phased"
+    phases: []
+  risk_level: null
+  breaking_changes: []
+  rollback_plan_created: false
+  dual_run_configured: false
+
+external_research:
+  performed: false
+  category: null
+  breaking_changes: []
+  migration_guide_url: null
+
+verification_context:
+  last_status: null
+  issues_found: null
+  fixes_applied: []
+  decisions_made: []
+  reverify_count: 0
+
+options:
+  docs_enabled: false
+```
+
+---
+
+## Task Structure
+
+```
+.owflow/tasks/migrations/YYYY-MM-DD-migration-name/
+├── orchestrator-state.yml
+├── analysis/
+│   ├── current-state-analysis.md     # Phase 1
+│   ├── target-state-plan.md          # Phase 2
+│   ├── requirements.md               # Phase 3
+│   ├── rollback-plan.md              # Phase 3
+│   └── dual-run-plan.md              # Phase 3 (if dual-run)
+├── implementation/
+│   ├── spec.md                       # Phase 3
+│   ├── implementation-plan.md        # Phase 4
+│   └── work-log.md                   # Phase 5
+├── verification/
+│   ├── implementation-verification.md    # Phase 6
+│   └── compatibility-test-results.md     # Phase 6
+└── documentation/
+    └── migration-guide.md            # Phase 8 (optional)
+```
+
+---
+
+## Auto-Recovery
+
+| Phase | Max Attempts | Strategy                                                                          |
+| ----- | ------------ | --------------------------------------------------------------------------------- |
+| 1     | 2            | Expand search patterns, prompt user for file paths                                |
+| 2     | 2            | Re-prompt for target details                                                      |
+| 3     | 2            | Re-gather requirements, re-invoke spec-creator subagent, regenerate rollback plan |
+| 4     | 2            | Regenerate with migration constraints                                             |
+| 5     | 5            | Fix syntax errors, prompt user on repeated failure                                |
+| 6     | 3            | Fix-then-reverify. **HALT on data integrity issues**                              |
+| 8     | 1            | Generate text-only without screenshots                                            |
+
+---
+
+## Command Integration
+
+Invoked via:
+
+- `/migration [description] [--type=TYPE]` (new)
+- `/migration [task-path] [--from=PHASE]` (resume)
+
+Task directory: `.owflow/tasks/migrations/YYYY-MM-DD-task-name/`