@uoyo/mvtt 2.0.0-beta.1 → 2.0.0-beta.3

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

@@ -1,86 +1,104 @@
-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
+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 4: Pre-flight Checks
+      - No blocking checks required (shortcut operation).
+
+  - type: inline
+    content: |
+      ## Operation Mode: Shortcut
+
+      This skill operates as a shortcut — it can execute at any time without checking workflow prerequisites.
+      - Do NOT update `active_change` fields.
+      - Write a `history` entry only (via State Update).
+
+  - type: file
+    source: ./business.md
+
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      current_skill: mvt-refactor
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-refactor
+      conditional_suggestions:
+        conditions:
+          - condition: "refactoring complete, tests exist"
+            primary: mvt-test
+            primary_desc: "Run tests to verify behavior is preserved"
+          - condition: "refactoring complete, no tests exist"
+            primary: mvt-review
+            primary_desc: "Review the refactored code"
+          - condition: "refactoring revealed design issues"
+            primary: mvt-design
+            primary_desc: "Redesign the affected module"

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

@@ -3,31 +3,29 @@
 ### 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
+- `active_change` -- the current change-id (if any), plan_path
+- `changes` -- list of changes with active plans
+- `history` -- last 20 entries (skill name, timestamp, change_id)
 
-If session.yaml is missing or empty, jump to Step 6 with the "no session" branch.
+If session.yaml is missing or empty, jump to Step 8 with the "no session" branch.
 
-### Step 1.5: Discover Pending Plans
+### Step 2: 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).
+1. **Index path**: For each entry in `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). **Skip any paths under `artifacts/_archived/`** — those are completed changes archived by `/mvt-cleanup` and should not appear as resume candidates.
 
 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
+### Step 3: Select Target Change
 
 | Candidates | Behavior |
 |------------|----------|
-| 0          | Skip to Step 2 — use legacy `active_change` / `skill_history` flow (no plan context). |
+| 0          | Jump to Step 8 with the "no plans" edge case — report no active plans and suggest `/mvt-plan-dev` or `/mvt-analyze`. |
 | 1          | Auto-select. Print: "Found one active plan: **{title}** ({progress}). Resuming." |
 | ≥2         | **Pause and prompt**. Display candidate table and wait for user input. |
 
@@ -36,9 +34,9 @@ For each found plan.yaml, read and filter:
 ```
 Found {N} active plans. Select which to resume:
 
-| # | change-id | title | progress | last_updated |
-|---|-----------|-------|----------|--------------|
-| 1 | {id}      | {t}   | {d}/{n}  | {relative}   |
+| # | change-id | title | progress | updated_at |
+|---|-----------|-------|----------|------------|
+| 1 | {id}      | {t}   | {d}/{n}  | {relative} |
 | ...
 
 Enter a number, a change-id, or "none" to skip plan context:
@@ -46,62 +44,25 @@ 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`.
+After selection, set `selected_change_id` for use in subsequent steps.
 
-### Step 2: Inspect Recent Artifacts
+### Step 4: Inspect Recent Artifacts
 
-If `selected_change_id` is set:
-- List files under `.ai-agents/workspace/artifacts/{selected_change_id}/`, sorted by mtime descending
+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):
+### Step 5: Determine Resume Point
 
 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 |
+Also filter `history` to entries matching `change_id == selected_change_id` (entries with empty change_id are excluded from this filtered view).
 
-### Step 4: Load Plan Progress (plan-aware path only)
+### Step 6: Load Plan Progress
 
-If `selected_change_id` has a plan, generate the **Plan Progress** section:
+Generate the **Plan Progress** section:
 
 - Read all tasks from plan.yaml.
 - Build a compact status table: `| # | id | title | status | skill_hint |`
@@ -116,22 +77,21 @@ And the **Current Task Detail** section:
 - `notes` (if non-empty)
 - `skill_hint` -> recommendation
 
-### Step 5: Generate Resume Report
+### Step 7: 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)
+1. **Active Task** -- name, change-id, started_at (from selected plan)
+2. **Plan Progress** -- task table + counts + current task detail
+3. **Recent Skill History** -- last 5 entries from history (filtered to selected change if applicable)
+4. **Recent Artifacts** -- the top 5 artifacts collected in Step 4 (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
+6. **Recommended Next Step** -- the mapped next skill from Step 5, with justification
 
-### Step 6: Edge Cases
+### Step 8: 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.
+- **No active plans**: report "No active plans found. Start a new change with `/mvt-analyze` or run `/mvt-status` to check project state."
+- **Selected change but referenced artifacts missing**: warn "Artifact directory `{path}` not found -- task state may be stale. Verify with `/mvt-status` or run `/mvt-cleanup`."
 - **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."

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

@@ -1,71 +1,81 @@
-name: mvt-resume
-output: .claude/skills/mvt-resume/SKILL.md
-
-frontmatter:
-  name: mvt-resume
-  description: "Resume an in-progress development task in a new conversation. Reads session.yaml (active_change, skill_history, recent_actions) and recent artifacts to reconstruct context. Does not read git state."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Resume
-
-      ## Purpose
-
-      Reconstruct an in-progress development task in a fresh conversation by replaying state from `session.yaml`, recent artifacts, and plan.yaml (if one exists). When multiple plans are in-flight, prompt the user to select which change to resume. Use this skill at the start of a new conversation to pick up exactly where the last session left off.
-
-      ## Arguments
-
-      | Argument | Required | Description |
-      |----------|----------|-------------|
-      | `{change-id}` | No | Directly resume a specific change (skips candidate selection). Error if not found or not in_progress. |
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Conductor
-      role_desc: "a Workflow Coordinator"
-      decision_rules:
-        - rule: "Multiple in_progress plans found -> Pause and display candidate table, wait for user selection"
-        - rule: "Exactly one in_progress plan found -> Auto-select it and proceed"
-        - rule: "No plans found BUT active_change is set -> Fall back to legacy skill_history-based resume"
-        - rule: "active_change is empty AND skill_history is empty AND no plans -> Recommend `/mvt-init` or `/mvt-status`"
-        - rule: "Plan exists and has current_task -> Use current_task's skill_hint as next-step recommendation"
-        - rule: "Plan's current_task has been in_progress for >5 days -> Surface stale warning"
-        - rule: "Last skill failed or was interrupted -> Surface the failure context, suggest retry"
-      boundaries:
-        - scope: "read git state (branch, diff, commits)"
-          skill: "(Out of scope -- this skill is session-state only)"
-        - scope: "modify any files"
-          skill: "(Read-only)"
-        - scope: "run analyses or tests"
-          skill: "(Use the recommended next skill)"
-
-  - type: shared
-    source: sections/activation-load-context.md
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/output-language-constraint.md
-
-  - type: shared
-    source: sections/activation-preflight.md
-    params:
-      checks:
-        - order: "1"
-          field: "session.initialized_at"
-          level: "WARN"
-          message: "Session not initialized. Run `/mvt-init` first."
-
-  - type: file
-    source: ./business.md
-
-  - type: shared
-    source: sections/session-update.md
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      current_skill: mvt-resume
+name: mvt-resume
+output: .claude/skills/mvt-resume/SKILL.md
+
+frontmatter:
+  name: mvt-resume
+  description: "Resume an in-progress development task in a new conversation. Reads session.yaml (active_change, history) and recent artifacts to reconstruct context. Does not read git state."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Resume
+
+      ## Purpose
+
+      Reconstruct an in-progress development task in a fresh conversation by replaying state from `session.yaml`, recent artifacts, and plan.yaml (if one exists). When multiple plans are in-flight, prompt the user to select which change to resume. Use this skill at the start of a new conversation to pick up exactly where the last session left off.
+
+      ## Arguments
+
+      | Argument | Required | Description |
+      |----------|----------|-------------|
+      | `{change-id}` | No | Directly resume a specific change (skips candidate selection). Error if not found or not in_progress. |
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - rule: "Multiple in_progress plans found -> Pause and display candidate table, wait for user selection"
+        - rule: "Exactly one in_progress plan found -> Auto-select it and proceed"
+        - rule: "No plans found -> Report no active plans, suggest `/mvt-analyze` or `/mvt-plan-dev`"
+        - rule: "active_change is empty AND history is empty AND no plans -> Recommend `/mvt-init` or `/mvt-status`"
+        - rule: "Plan exists and has current_task -> Use current_task's skill_hint as next-step recommendation"
+        - rule: "Plan's current_task has been in_progress for >5 days -> Surface stale warning"
+        - rule: "Last skill was interrupted -> Surface the context, suggest retry"
+      boundaries:
+        - scope: "read git state (branch, diff, commits)"
+          skill: "(Out of scope -- this skill is session-state only)"
+        - scope: "modify any files"
+          skill: "(Read-only)"
+        - scope: "run analyses or tests"
+          skill: "(Use the recommended next skill)"
+
+  - type: shared
+    source: sections/activation-load-context.md
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/activation-preflight.md
+    params:
+      checks:
+        - order: "1"
+          field: "session.initialized_at"
+          level: "WARN"
+          message: "Session not initialized. Run `/mvt-init` first."
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-resume
+      conditional_suggestions:
+        conditions:
+          - condition: "plan has current_task with skill_hint"
+            primary: mvt-implement
+            primary_desc: "Continue with the next planned task (use skill_hint)"
+          - condition: "no active plans found"
+            primary: mvt-analyze
+            primary_desc: "Start a new feature"
+          - condition: "plan stale (>5 days without updates)"
+            primary: mvt-update-plan
+            primary_desc: "Refresh plan status before continuing"

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

@@ -81,8 +81,7 @@
 - Each finding must include: file, line range, severity, observation, recommendation.
 
 ### Step 6: Write Artifact
-- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/review.md` if `active_change` exists; else `.ai-agents/workspace/artifacts/_ad-hoc-review-{YYYY-MM-DD-HHMM}/review.md`.
-- **Template**: `.ai-agents/skills/_templates/review-output.md` (custom override at `_templates/custom/...` takes precedence).
+- **Path and template**: as defined in the **Artifact Structure** section below. If no `active_change` exists, use `.ai-agents/workspace/artifacts/_ad-hoc-review-{YYYY-MM-DD-HHMM}/review.md`.
 - **Required content** (mapped to template headings):
   - `Review Scope` -- file list, depth, aspect filter, fallbacks applied (e.g., "design.md missing -> Group A skipped").
   - `Summary` -- counts per severity + one-paragraph overall verdict (Approve / Approve with comments / Request changes / Block).
@@ -98,7 +97,8 @@
 - Critical = 0, Warnings <= 5, Suggestions only -> verdict is `Approve`.
 - Code-only review (design.md missing) -> verdict cannot be higher than `Approve with comments` (call it out explicitly).
 
-### Step 8: (session update handled by shared section)
+### Step 8: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors