@uoyo/mvtt 2.0.0-beta.0 → 2.0.0-beta.2

package/sources/skills/mvt-quick-dev/business.md

@@ -0,0 +1,99 @@
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - User's change description (free text or file path).
+- **Fallback**: if no project context exists (no `project-context.md`), proceed as "context-light" (skip layer compliance checks).
+
+### Step 2: Classify Complexity
+- **What**: determine the change tier based on scope signals in the user's description.
+- **How**: apply the classification table below. Walk signals top-to-bottom; the first match wins.
+
+  | Tier | Criteria | Behavior |
+  |------|----------|----------|
+  | **Trivial** | 1 file, no new concepts, no interface change, ≤10 lines affected | Implement directly, conversation-only |
+  | **Simple** | 1-3 files, no new module, no interface break, existing patterns sufficient | Implement after showing plan, conversation-only |
+  | **Complex** | >3 files, new module, interface break, new dependency, or ambiguous scope | STOP -- recommend `/mvt-analyze` or `/mvt-design` |
+
+  Scope signals (heuristic):
+
+  | Signal | Suggests |
+  |--------|----------|
+  | Mentions specific file/symbol | Trivial/Simple |
+  | "add a field/property/column" | Simple |
+  | "change label/text/color" | Trivial |
+  | "new API/endpoint/module" | Complex |
+  | "refactor/redesign/migrate" | Complex |
+  | "integration with X" | Complex |
+  | Affects >1 module (per `project-context.md`) | Complex |
+  | Introduces new dependency | Complex |
+
+- **Branches**:
+
+  | Condition | Action |
+  |-----------|--------|
+  | Classified as Trivial or Simple | Proceed to Step 3 |
+  | Classified as Complex | STOP; recommend `/mvt-analyze` or `/mvt-design` |
+  | Ambiguous (could be Simple or Complex) | Ask user to confirm scope before proceeding |
+
+### Step 3: Locate Target
+- **What**: resolve the exact file(s) and symbol(s) to change.
+- **How**:
+  1. Parse the change description for file paths, class/function/variable names, or module references.
+  2. Resolve each reference using Glob/Grep against the project tree.
+  3. Verify each target: exists on disk (for modifications) or parent path exists (for new files).
+  4. If a target cannot be uniquely resolved, ask the user for clarification before continuing.
+  5. Cross-reference `project-context.md` layer rules (if available) -- flag any change that would violate layer constraints.
+- **Output of this step**: a target list (`path | action | one-line intent`).
+
+### Step 4: Plan the Change
+- **What**: produce an ordered file list before writing any code.
+- **How**:
+  1. For each target from Step 3, decide: `create | modify | delete`, and write a one-line intent.
+  2. Topologically order by dependency if multiple files are involved.
+- **Branches**:
+
+  | Condition | Action |
+  |-----------|--------|
+  | Trivial tier | Proceed silently (change is small and reversible) |
+  | Simple tier | Show the plan to the user as a preview; wait for confirmation before proceeding |
+  | Plan exceeds 3 files | Escalate to Complex -- STOP, recommend standard workflow |
+  | Plan introduces an unplanned module | Escalate to Complex -- STOP, recommend standard workflow |
+
+### Step 5: Implement
+- **What**: write/modify the planned files.
+- **How**:
+  1. Apply changes one file at a time, in the order determined by Step 4.
+  2. Follow `coding-standards.md` if available; match surrounding code style otherwise.
+  3. Respect module/layer rules from `project-context.md`. Forbidden imports must NOT appear.
+  4. Add error handling at system boundaries only (HTTP, DB, external API, file IO, message bus). Do NOT add try/catch around internal calls.
+  5. Inline comments only for non-obvious algorithmic choices or deliberate workarounds with a reason.
+  6. Do NOT introduce abstractions, helpers, or feature flags beyond what the task requires.
+
+### Step 6: Quick Verify
+- **What**: light-weight verification before reporting completion.
+- **How**:
+  1. If a type-checker is configured for the project (`tsc`, `mypy`, `cargo check`, etc.), run it on changed files only. Surface failures.
+  2. If existing tests cover the changed code, suggest the test command but do not auto-run unless user explicitly approved.
+  3. For frontend/UI changes, note that user should verify in browser; do NOT claim "tested" based on type-check alone.
+
+### Step 7: Summarize in Conversation
+- **What**: present the result without writing any artifact file.
+- **How**: output a brief summary containing:
+  - Files touched: `path | action`
+  - Verification status: type-check result, test suggestion
+- **No artifact is written. No document is generated.** This is a conversation-only skill.
+
+### Step 8: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Change description is vague ("improve performance") | STOP -- ask for specifics; cannot classify without concrete scope |
+| Target file doesn't exist | Ask whether it is a new file or a wrong path; do not silently create |
+| Implementation reveals the change is actually Complex | STOP -- revert partial changes, recommend `/mvt-analyze` |
+| Active change is in the middle of `/mvt-implement` | Warn about potential conflicts; ask user to confirm before proceeding |
+| No `active_change` and change is Simple | Proceed without creating an `active_change`; conversation-only result |
+| Change touches a file also being modified in an active plan | Surface the conflict; user must resolve outside this skill |
+| User wants to save progress notes | Direct them to the standard workflow (`/mvt-analyze` -> `/mvt-design` -> `/mvt-implement`) which produces artifacts |

package/sources/skills/mvt-quick-dev/manifest.yaml

@@ -0,0 +1,69 @@
+name: mvt-quick-dev
+output: .claude/skills/mvt-quick-dev/SKILL.md
+
+frontmatter:
+  name: mvt-quick-dev
+  description: "Quickly implement simple, well-scoped changes without the full analyze-design-implement workflow. This skill should be used when the change is small (1-3 files), architecturally neutral, and clearly specified — such as adding a field, fixing a label, adjusting config, or making a targeted enhancement."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Quick Dev
+
+      ## Purpose
+
+      Implement simple, well-scoped changes quickly, bypassing the full workflow. For changes that are small (1-3 files), architecturally neutral, and clearly specified. Produces no artifacts — results are conversation-only.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Developer
+      role_desc: "an Implementation Specialist"
+      decision_rules:
+        - rule: "Change is Trivial (1 file, ≤10 lines) -> Implement directly, conversation-only"
+        - rule: "Change is Simple (1-3 files, no module break) -> Implement, show plan first, conversation-only"
+        - rule: "Change is Complex -> STOP, recommend /mvt-analyze or /mvt-design"
+        - rule: "Ambiguous scope -> Ask user to confirm before proceeding"
+        - rule: "Implementation reveals unexpected complexity -> Revert and escalate"
+        - rule: "Existing tests cover changed code -> Suggest running them"
+      boundaries:
+        - scope: "analyze complex requirements"
+          skill: "/mvt-analyze"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "review code"
+          skill: "/mvt-review"
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - ".ai-agents/knowledge/project/_generated/project-context.md -- Module/layer map (optional)"
+        - ".ai-agents/knowledge/principle/coding-standards.md -- Coding standards (optional)"
+        - "Target source files (load based on change description)"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - type: inline
+    content: |
+      ### Shortcut Operation Rules
+      - Can execute at any time without checking workflow prerequisites
+      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase)
+      - Do NOT create an `active_change` if one doesn't already exist
+      - Do NOT write any artifact or document — results are conversation-only
+      - Do NOT interact with plan.yaml in any way — this skill is plan-independent
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-quick-dev

package/sources/skills/mvt-refactor/business.md

@@ -1,33 +1,104 @@
-## Execution Flow
-
-### Step 1: Analyze Current Code
-- Read target files
-- Understand current behavior
-- Classify refactoring type from the types table
-- Identify refactoring opportunities
-
-### Step 2: Risk Assessment
-- Assess risk level based on refactoring type
-- Identify all callers/dependents of the target code
-- Estimate impact scope (files and modules affected)
-- Check for existing tests covering the target code
-
-### Step 3: Plan Refactoring
-- Define refactoring goals
-- Identify incremental steps
-- Ensure behavior preservation strategy
-
-### Step 4: Execute Refactoring
-- Apply changes incrementally
-- Verify behavior at each step
-
-### Step 5: Verify Behavior Preservation
-- If tests exist -> Suggest running them
-- If no tests -> Describe how to verify behavior is unchanged
-- Confirm no regressions in dependent code
-
-### Step 6: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `session.last_command: "/mvt-refactor"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-   - Do NOT update `progress` (shortcut operation)
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - User-specified target (file path, symbol name, module, or "the code I just wrote").
+- **Recommended**:
+  - Existing tests covering the target (search by file path, by symbol name, and by sibling test files).
+  - `git status` / `git diff` -- to know what is already modified before refactoring.
+- **Fallback**: if no target was specified, ask the user. Do not refactor speculatively.
+
+### Step 2: Locate and Understand Target
+- **What**: produce a precise list of files and line ranges that constitute the refactoring target, plus a one-paragraph statement of what the code currently does.
+- **How**:
+  1. Resolve the target: glob/grep for the named symbol or path.
+  2. List every caller / dependent: grep for the symbol's exported name across the project (and across packages if it is exported beyond the module).
+  3. State the current behavior in plain language; include any non-obvious side effects or invariants you can see in the code.
+- **Output of this step**: a target table (`file | range | role`) and a "current behavior" paragraph; both are shown to user before continuing.
+
+### Step 3: Classify Refactoring Type
+- **What**: pick the smallest type that covers the requested change. Use the Refactoring Types table above for risk levels.
+- **How**: assign one primary type per refactoring task. Multiple types in one run are allowed but each must be tracked separately in the artifact.
+- If the request requires `Change Interface/API` AND the symbol is exported beyond the project (public API, library entry point, IPC boundary): STOP -- this is no longer a refactoring task; recommend `/mvt-design`.
+
+### Step 4: Risk Assessment
+- **What**: assign a final risk score and decide whether explicit confirmation is needed.
+- **How**: combine refactoring type and impact factors.
+
+  | Factor | +risk |
+  |--------|-------|
+  | Touches > 10 files | +1 |
+  | Touches a public/exported symbol | +1 |
+  | No existing tests on the target | +1 |
+  | Target is in a critical path (auth, payments, persistence boundary, public API) | +1 |
+  | User has uncommitted changes overlapping the target | +1 |
+
+- Final risk = type's base level + factors:
+  - Low + 0..1 -> proceed silently in Step 7.
+  - Medium OR Low + 2 -> require explicit confirmation in Step 6.
+  - High OR (Medium + 2) -> require explicit confirmation AND a behavior-preservation strategy from Step 5.
+
+### Step 5: Choose Behavior-Preservation Strategy
+- **What**: pick a verification path BEFORE editing.
+- **How**: choose the row that matches your test reality.
+
+  | Test reality | Strategy |
+  |--------------|----------|
+  | Comprehensive tests cover the target | Run them once before changes (capture baseline), once after each step, and once at the end |
+  | Some tests exist, gaps known | Do the refactor in incremental steps; after each step, run available tests; for gaps, add a single characterization test BEFORE refactoring (capture current behavior, even if quirky) |
+  | No tests exist | Choose ONE: (a) write a minimal characterization test first, OR (b) for Low-risk refactors only, use mechanical refactoring (rename, extract) where the editor / language tooling guarantees behavior. Never attempt High-risk refactors with zero tests |
+
+- Document the chosen strategy in the artifact regardless of risk level.
+
+### Step 6: Confirm with User (when required)
+- **Trigger**: per the Step 4 thresholds, or any High-risk type.
+- **Format**: present a single screen with:
+  - Target summary (Step 2's table, condensed to file count + symbol).
+  - Refactoring type and risk level.
+  - Number of callers and a list of the top 5 affected files.
+  - Behavior-preservation strategy (Step 5).
+  - One yes/no prompt: `Proceed with this refactor? (y / n / show-plan)`.
+
+### Step 7: Plan and Execute Incrementally
+- **What**: apply the change in the smallest reversible steps.
+- **How**:
+  1. Break the refactor into ordered sub-steps (e.g., Rename: 1) update declaration, 2) update callers, 3) update tests, 4) update docs).
+  2. After each sub-step:
+     - Compile / type-check the affected files.
+     - If a test command was identified in Step 5, run it (or surface it for user to run if running tests is not allowed in this environment).
+     - On failure: revert the sub-step, surface the cause, do NOT continue.
+  3. Do not interleave behavior changes (bug fixes, feature toggles) with the refactor. If you spot one, note it for follow-up; do not silently include it.
+  4. Do not modify code outside the planned target unless required for compilation/type correctness; record any such "incidental" edits.
+
+### Step 8: Verify Behavior Preservation
+- **What**: prove (within the chosen strategy) that observable behavior is unchanged.
+- **How**:
+  - With tests: all pre-existing tests pass; new characterization tests pass; assert pass count is unchanged or increased.
+  - Without tests: list the call sites you visually verified, plus the manual behavior checks you recommend the user run.
+- If anything regresses: revert the most recent sub-step, surface the regression, return to Step 7. Do not declare success.
+
+### Step 9: Write Refactor Notes
+- **Path**: `.ai-agents/workspace/artifacts/{change-id}/refactor-notes.md` if `active_change` exists; otherwise inline summary in conversation only (shortcut mode).
+- **Required content**:
+  - `Target` -- file/symbol list, current-behavior paragraph.
+  - `Refactoring Type` and final risk level.
+  - `Behavior-Preservation Strategy` -- chosen row + tests touched / written.
+  - `Steps Applied` -- ordered sub-steps with one-line outcome each.
+  - `Incidental Edits` -- any unplanned files touched, with reason.
+  - `Verification Result` -- tests run, pass/fail counts; or manual checks recommended.
+  - `Follow-ups` -- deferred behavior changes spotted during refactoring.
+
+### Step 10: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Target spans multiple repos / submodules | STOP -- out of scope; recommend a coordinated change rather than a single refactor |
+| Refactor uncovers a real bug | Pause refactor, document the bug, recommend `/mvt-fix` -- do NOT fix during the refactor |
+| Refactor target is dead code | Confirm with user before deleting; offer alternative of marking deprecated first |
+| Symbol is referenced via reflection / dynamic dispatch / string lookup | Increase risk by +2; require strategy 5(a) (characterization test) before proceeding |
+| User has uncommitted changes overlapping the target | Show diff, recommend committing/stashing first, ask for explicit confirmation if user wants to proceed anyway |
+| Type/test failures persist after revert | Surface a clear summary; suggest user re-run the original test baseline to detect a pre-existing failure unrelated to the refactor |
+| User aborts at Step 6 | Do not modify any file; report "no changes" |
+| Active change is mid-implementation (not yet `done`) | Warn that refactoring during implementation can confuse review/test phases; require explicit confirmation |

package/sources/skills/mvt-refactor/manifest.yaml

@@ -1,101 +1,86 @@
-name: mvt-refactor
-output: .claude/skills/mvt-refactor/SKILL.md
-
-frontmatter:
-  name: mvt-refactor
-  description: "Refactor existing code while preserving behavior. Supports extract, rename, move, decompose, and other refactoring types. Use when user wants to improve code structure without changing functionality."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Refactor
-
-      ## Purpose
-
-      Refactor existing code while preserving observable behavior. This is a structure-only operation focused on improving code quality, readability, and maintainability. This is a shortcut operation that can run at any time.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Developer
-      role_desc: "an Implementation Specialist"
-      decision_rules:
-        - rule: "Refactoring target specified -> Analyze and plan the refactoring"
-        - rule: "No target specified -> Ask user what to refactor"
-        - rule: "Risk level is High -> Warn user and require explicit confirmation"
-        - rule: "Tests exist for target code -> Recommend running them after refactoring"
-        - rule: "No tests exist -> Describe how to verify behavior is unchanged"
-        - rule: "Change requires new module not in design -> Flag for Architect"
-      boundaries:
-        - scope: "re-analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "evaluate architecture"
-          skill: "/mvt-design"
-        - scope: "review own code"
-          skill: "/mvt-review"
-
-  - type: inline
-    content: |
-      ### Constraints
-      - Do NOT change observable behavior -- refactoring is structure-only
-      - Do NOT introduce new features during refactoring
-      - Do NOT modify unrelated code outside the refactoring scope
-
-      ## Refactoring Types
-
-      | Type | Description | Risk Level |
-      |------|-------------|------------|
-      | Extract Method/Class | Pull logic into new method or class | Low |
-      | Rename | Rename symbols for clarity | Low |
-      | Move | Relocate code to appropriate module/layer | Medium |
-      | Decompose Conditional | Simplify complex if/switch logic | Medium |
-      | Replace Inheritance with Composition | Change class hierarchy | High |
-      | Change Interface/API | Modify public contracts | High |
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - ".ai-agents/knowledge/patterns/{pattern.active}/ -- Active architecture pattern knowledge"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Project coding standards"
-        - "Related source files to be refactored"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: inline
-    content: |
-      ### Step 3: Pre-flight Checks
-      - No blocking checks required (shortcut operation).
-
-      ### Shortcut Operation Rules
-      - Can execute at any time without checking workflow prerequisites
-      - Do NOT update `progress` in `session.yaml` after completion
-      - Only update `session.last_command` and `recent_actions`
-
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/refactor-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/refactor-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the refactoring results.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      next_primary: mvt-review
-      next_primary_desc: "Verify refactoring changes"
-      next_alternatives:
-        - skill: mvt-test
-          when: "Run tests to confirm behavior preservation"
+name: mvt-refactor
+output: .claude/skills/mvt-refactor/SKILL.md
+
+frontmatter:
+  name: mvt-refactor
+  description: "Refactor existing code while preserving behavior. This skill should be used when user wants to improve code structure, rename symbols, extract methods or classes, or reorganize code without changing functionality."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Refactor
+
+      ## Purpose
+
+      Refactor existing code while preserving observable behavior. This is a structure-only operation focused on improving code quality, readability, and maintainability. This is a shortcut operation that can run at any time.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Developer
+      role_desc: "an Implementation Specialist"
+      decision_rules:
+        - rule: "Refactoring target specified -> Analyze and plan the refactoring"
+        - rule: "No target specified -> Prompt user for refactoring target"
+        - rule: "Risk level is High -> Warn user and require explicit confirmation"
+        - rule: "Tests exist for target code -> Recommend running them after refactoring"
+        - rule: "No tests exist -> Describe how to verify behavior is unchanged"
+        - rule: "Change requires new module not in design -> Flag for Architect"
+      boundaries:
+        - scope: "re-analyze requirements"
+          skill: "/mvt-analyze"
+        - scope: "evaluate architecture"
+          skill: "/mvt-design"
+        - scope: "review own code"
+          skill: "/mvt-review"
+
+  - type: inline
+    content: |
+      ### Constraints
+      - Do NOT change observable behavior -- refactoring is structure-only
+      - Do NOT introduce new features during refactoring
+      - Do NOT modify unrelated code outside the refactoring scope
+
+      ## Refactoring Types
+
+      | Type | Risk Level | Examples |
+      |------|------------|----------|
+      | Rename | Low | Variable, function, file rename |
+      | Extract Method/Class | Low | Pull repeated logic into a helper |
+      | Inline | Low | Eliminate a thin wrapper |
+      | Move | Medium | Relocate code to appropriate module/layer |
+      | Decompose Conditional | Medium | Simplify complex if/switch logic |
+      | Replace Inheritance with Composition | High | Class-hierarchy redesign |
+      | Change Interface/API | High | Modify public contracts |
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - "Related source files to be refactored"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - type: inline
+    content: |
+      ### Step 3: Pre-flight Checks
+      - No blocking checks required (shortcut operation).
+
+      ### Shortcut Operation Rules
+      - Can execute at any time without checking workflow prerequisites
+
+  - type: file
+    source: ./business.md
+
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-refactor

package/sources/skills/mvt-resume/business.md

@@ -0,0 +1,137 @@
+## Execution Flow
+
+### Step 1: Read Session State
+
+Extract from the already-loaded session context:
+- `active_change` -- the current change-id (if any), its phase, plan_path, has_plan
+- `recent_changes` -- list of changes with active plans
+- `skill_history` -- last 10 entries (skill name, timestamp, status, change_id)
+- `recent_actions` -- last 5 entries (what was done, when, outcome)
+- `last_command` and `last_skill` -- most recent invocation
+
+If session.yaml is missing or empty, jump to Step 6 with the "no session" branch.
+
+### Step 1.5: Discover Pending Plans
+
+Scan for in-progress plans using two sources:
+
+1. **Index path**: For each entry in `recent_changes[]`, read its `plan_path` if the file exists.
+2. **Fallback scan**: Glob `.ai-agents/workspace/artifacts/*/plan.yaml`, read any files not already covered by (1).
+
+For each found plan.yaml, read and filter:
+- Include only plans where `plan.status == "in_progress"`.
+- Capture: `change_id`, `title`, task progress (`done_count / total_count`), `updated_at`.
+- Sort candidates by `updated_at` descending.
+
+### Step 1.6: Select Target Change
+
+| Candidates | Behavior |
+|------------|----------|
+| 0          | Skip to Step 2 — use legacy `active_change` / `skill_history` flow (no plan context). |
+| 1          | Auto-select. Print: "Found one active plan: **{title}** ({progress}). Resuming." |
+| ≥2         | **Pause and prompt**. Display candidate table and wait for user input. |
+
+**Candidate table format** (≥2 candidates):
+
+```
+Found {N} active plans. Select which to resume:
+
+| # | change-id | title | progress | last_updated |
+|---|-----------|-------|----------|--------------|
+| 1 | {id}      | {t}   | {d}/{n}  | {relative}   |
+| ...
+
+Enter a number, a change-id, or "none" to skip plan context:
+```
+
+**Explicit argument override**: If the user invoked `/mvt-resume {change-id}`, use that change-id directly — skip the table, locate and load its plan.yaml (error if not found or not in_progress).
+
+After selection, set `selected_change_id` for use in subsequent steps. If "none" or 0 candidates, `selected_change_id = null`.
+
+### Step 2: Inspect Recent Artifacts
+
+If `selected_change_id` is set:
+- List files under `.ai-agents/workspace/artifacts/{selected_change_id}/`, sorted by mtime descending
+- Exclude `plan.yaml` from the artifact list (it gets its own section)
+- Take the top 5
+
+Else if `active_change.id` is set (no-plan fallback):
+- List files under `.ai-agents/workspace/artifacts/{active_change.id}/`, sorted by mtime descending
+- Take the top 5
+
+Otherwise:
+- List all files under `.ai-agents/workspace/artifacts/` (recursive), sorted by mtime descending
+- Take the top 5
+
+For each artifact, capture: file path, mtime, size (in tokens estimate = chars / 4), and the change-id it belongs to.
+
+### Step 3: Determine Resume Point
+
+**Plan-aware path** (when `selected_change_id` has a valid plan.yaml):
+
+Read the plan's `current_task`. The resume point = that task. Next-step recommendation = the task's `skill_hint` (or infer from task title if skill_hint is absent).
+
+Also filter `skill_history` to entries matching `change_id == selected_change_id` (entries with empty change_id are excluded from this filtered view).
+
+**Legacy path** (no plan):
+
+Pick the **resume point** by precedence:
+
+| Condition | Resume point | Phase label |
+|-----------|--------------|-------------|
+| `active_change` is set with non-empty `phase` | `{active_change.phase}` | from session |
+| `active_change` is set without phase | inferred from last skill in history | inferred |
+| `skill_history[0]` exists | last skill | last skill |
+| Nothing | `none` | new project |
+
+Map skill -> next-step recommendation:
+
+| Last skill | Suggested next |
+|-----------|----------------|
+| mvt-init | mvt-analyze-code (if has code) or mvt-analyze (if requirements available) |
+| mvt-analyze | mvt-design |
+| mvt-analyze-code | mvt-analyze (if requirements pending) or mvt-design |
+| mvt-design | mvt-plan-dev (if change is large) or mvt-implement |
+| mvt-implement | mvt-review |
+| mvt-review | mvt-fix (if findings) or mvt-test |
+| mvt-fix | mvt-review (re-review) or mvt-test |
+| mvt-test | mvt-cleanup or next change |
+| mvt-cleanup | new change via mvt-analyze |
+| (other) | mvt-status |
+
+### Step 4: Load Plan Progress (plan-aware path only)
+
+If `selected_change_id` has a plan, generate the **Plan Progress** section:
+
+- Read all tasks from plan.yaml.
+- Build a compact status table: `| # | id | title | status | skill_hint |`
+- Highlight `current_task` row (prefix with `>>` or bold).
+- Count summary: `Done: {d}, In Progress: {ip}, Pending: {p}, Blocked: {b}, Skipped: {s}`
+
+And the **Current Task Detail** section:
+
+- `title`
+- `acceptance` criteria (bulleted list)
+- `depends_on` with status of each dependency (all should be `done`)
+- `notes` (if non-empty)
+- `skill_hint` -> recommendation
+
+### Step 5: Generate Resume Report
+
+Render via the `resume-output.md` template. Sections to fill:
+
+1. **Active Task** -- name, change-id, phase, started_at (from active_change or selected plan)
+2. **Plan Progress** -- (only when plan exists) task table + counts + current task detail
+3. **Recent Skill History** -- last 5 entries from skill_history (filtered to selected change if applicable)
+4. **Recent Artifacts** -- the top 5 artifacts collected in Step 2 (path, mtime, size)
+5. **Resume Point** -- a one-paragraph natural-language summary of "where we are"
+6. **Recommended Next Step** -- the mapped next skill from Step 3, with justification
+
+### Step 6: Edge Cases
+
+- **No session**: report "No session found. Run `/mvt-init` to start a project."
+- **No active_change AND no history AND no plans**: report "No active task. Suggested entry points: `/mvt-init`, `/mvt-analyze`, `/mvt-status`."
+- **active_change set but referenced artifacts missing**: warn "Artifact directory `{path}` not found -- task state may be stale. Verify with `/mvt-status` or run `/mvt-cleanup`."
+- **Last skill ended in failure** (skill_history entry status=failed): surface the failure summary first, suggest retry of that skill rather than advancing.
+- **Plan exists but plan.yaml is invalid** (parse error or schema violation): warn "plan.yaml is corrupted or invalid. Run `/mvt-plan-dev` to regenerate, or `/mvt-status` to inspect."
+- **Stale task warning**: If plan's `current_task` has status `in_progress` but the plan's `updated_at` is more than 5 days old, append a notice: "Current task has been in_progress for {N} days without updates. Consider running `/mvt-update-plan` to refresh status."