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

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

@@ -4,13 +4,15 @@
 
 Collect everything that should inform the plan:
 
-1. Any extra context the user supplies in the current message.
+1. The analysis artifact at `.ai-agents/workspace/artifacts/{active_change.id}/` (if any).
+2. The design artifact (if `/mvt-design` was run for this change).
+3. Any extra context the user supplies in the current message.
 
 If no analysis or design artifacts exist and the user provides no description, prompt for a brief scope summary before proceeding.
 
 ### Step 2: Detect Regeneration
 
-If `active_change.has_plan == true` AND `.ai-agents/workspace/artifacts/{active_change.id}/plan.yaml` already exists:
+If `active_change.plan_path is non-empty` AND `.ai-agents/workspace/artifacts/{active_change.id}/plan.yaml` already exists:
 
 - Read the existing plan.
 - Show a summary (task count, status counts, current_task).
@@ -26,13 +28,58 @@ Decompose the change with the following constraints. These constraints are AI-fr
 | Count | Aim for 3–10 tasks at the top level. If the change clearly needs more, stop and propose phasing into multiple plans (one per phase). |
 | Single responsibility | Each task should map to one focused skill invocation (e.g., one `/mvt-implement` for one feature slice). |
 | Independently verifiable | Each task must have at least one acceptance criterion that a human or test can check. |
-| Explicit dependencies | If task B requires output from task A, list `A` in B's `depends_on`. Avoid hidden ordering. |
+| Explicit dependencies | If task B requires output from task A, list `A` in B's `depends_on`. Avoid hidden ordering. Tasks that can run in parallel should have no dependency between them. |
 | No cycles | Dependency graph must be a DAG. Validation will reject cycles. |
-| Skill hint | Set `skill_hint` to the skill that will most likely execute the task (`mvt-implement`, `mvt-test`, `mvt-fix`, `mvt-review`, etc.). |
+| Skill hint | Set `skill_hint` to the skill best suited to execute the task (without `/` prefix): `mvt-implement`, `mvt-test`, `mvt-fix`, `mvt-design`, `mvt-review`, `mvt-refactor`, etc. |
 
 ### Step 4: Assemble plan.yaml
 
-Build the plan object following `docs/plan-yaml-schema.md`:
+Build the plan object following the schema below. Here is a minimal reference sample showing the exact YAML shape to emit:
+
+```yaml
+version: 1
+change_id: "20260531-feature-name"
+title: "Feature Name"
+created_at: "2026-05-31T11:30:00"
+updated_at: "2026-05-31T11:30:00"
+status: in_progress
+current_task: "t1-foundation-layer"
+
+tasks:
+  - id: "t1-foundation-layer"
+    title: "Foundation types and interfaces"
+    status: in_progress
+    completed_at: null
+    depends_on: []
+    skill_hint: mvt-implement
+    artifacts:
+      files:
+        - "src/core/types.ts"
+        - "src/core/interfaces.ts"
+    notes: >
+      Define the data contract and shared interfaces.
+      Referenced by ADR-2 in the design artifact.
+    acceptance:
+      - "All new types compile without errors"
+      - "tsc clean; existing tests pass"
+
+  - id: "t2-core-logic"
+    title: "Core business logic implementation"
+    status: pending
+    completed_at: null
+    depends_on: ["t1-foundation-layer"]
+    skill_hint: mvt-implement
+    artifacts: null
+    notes: >
+      Implement the main processing pipeline using types from t1.
+      Must handle partial failures gracefully per design spec.
+    acceptance:
+      - "Pipeline processes valid input end-to-end"
+      - "Partial failures return error object without crashing"
+      - "tsc clean; existing tests pass"
+```
+
+#### Top-level fields
 
 - `version: 1`
 - `change_id`: copy from `active_change.id`
@@ -40,19 +87,42 @@ Build the plan object following `docs/plan-yaml-schema.md`:
 - `created_at`: current ISO 8601 timestamp
 - `updated_at`: same as `created_at` initially
 - `status: in_progress`
-- `current_task`: the id of the first task that has `depends_on: []` and `status: pending` (or `in_progress` if you mark one as actively in progress)
-- `tasks[]`: as decomposed above. Initial task statuses:
-  - First task → `in_progress`
-  - All other tasks → `pending`
+- `current_task`: the `id` of the first executable task (a task with `depends_on: []`), set to `in_progress`
+
+#### Task fields
+
+For each task, populate:
+
+- **`id`**: format `t{n}-{kebab-slug}` (e.g., `t1-backend-types`, `t3-dev-panel-ui`). The sequence number reflects natural execution order; keep the slug to 2–5 words.
+- **`title`**: one-line descriptive title.
+- **`status`**: first executable task → `in_progress`; all others → `pending`.
+- **`completed_at`**: `null` for all tasks on initial creation (set by `/mvt-update-plan` when marking `done`).
+- **`depends_on`**: array of task ids. Empty array `[]` means no dependencies.
+- **`skill_hint`**: the skill name (without `/`) that will execute this task.
+- **`artifacts`**: structured object. On initial plan creation, set to `null` or pre-populate with planned target files if known:
+  ```yaml
+  artifacts:
+    files:
+      - "src/path/to/expected-file.ts"
+  ```
+- **`notes`**: multiline string (use YAML `>` or `|` scalar) containing implementation context — scope description, constraints, references to design decisions or ADRs, key technical considerations. This is the primary guidance that `/mvt-implement` or other skills read when executing the task. Write enough detail that the executing skill can proceed without re-reading the full analysis/design. Keep to 3–8 lines.
+- **`acceptance`**: array of strings. Each entry is a single verifiable assertion. Write criteria that are:
+  - **Specific**: "getDiagnostic() returns `{ listening, port, sseClientConnected }`" not "method works correctly"
+  - **Testable**: can be checked by a human review, a compiler (`tsc clean`), or an automated test
+  - **Independent**: each criterion stands alone; avoid "see above"
+  - Always include at least one build/type-check criterion (e.g., `"tsc clean; existing tests pass"`) for implementation tasks
 
 ### Step 5: Validate
 
-Before writing, validate the assembled YAML against the schema:
+Before writing, validate the assembled YAML:
 
-- Unique task ids
-- All `depends_on` references resolve
-- No dependency cycles
-- `current_task` references a task with status `pending` or `in_progress`
+1. **Unique IDs** — no two tasks share the same `id`
+2. **Valid references** — every `depends_on` entry references an existing task `id`
+3. **No cycles** — the dependency graph is a DAG
+4. **current_task validity** — references a task with status `pending` or `in_progress`
+5. **Acceptance required** — every task has at least one acceptance criterion
+6. **Single in_progress** — at most one task has status `in_progress`
+7. **completed_at consistency** — must be `null` for all non-done tasks
 
 If validation fails, revise the plan and re-validate (do NOT write a broken plan).
 
@@ -64,12 +134,23 @@ If a previous `plan.yaml` exists and the user chose regeneration in Step 2, over
 
 ### Step 7: Update Session State
 
-Apply the standard State Update rules (see shared section above) AND the plan-dev-specific updates:
-
-- `active_change.plan_path` -> the new file path
-- `active_change.has_plan` -> `true`
-- `recent_changes[]` -> upsert an entry for this change (refresh `last_updated`)
+Apply the standard State Update rules (see State Update section below).
 
 ### Step 8: Output
 
-Render the result via the plan-dev output template, including a tabular summary of all tasks with their initial status and the `current_task` highlight. Surface the schema location so users know how to read or hand-edit it later.
+Render an inline summary (no external template). Structure:
+
+```markdown
+## Development Plan: {title}
+
+**Change**: `{change_id}`
+**Tasks**: {total_count} | **Status**: {status}
+
+### Task Breakdown
+
+| # | id | title | status | skill | depends_on |
+|---|----|----|--------|-------|------------|
+| 1 | {id} | {title} | {status} | {skill_hint} | {deps_or_"—"} |
+| ... |
+
+```

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

@@ -20,8 +20,8 @@ sections:
       role: Architect
       role_desc: "a Development Planner"
       decision_rules:
-        - rule: "active_change is set AND has_plan is false -> Generate a fresh plan.yaml"
-        - rule: "active_change is set AND has_plan is true -> Confirm before regenerating; default to /mvt-update-plan"
+        - rule: "active_change is set AND plan_path is empty -> Generate a fresh plan.yaml"
+        - rule: "active_change is set AND plan_path is non-empty -> Confirm before regenerating; default to /mvt-update-plan"
         - rule: "Tasks would exceed 10 -> Stop, propose phasing the change into multiple plans"
         - rule: "Dependencies form a cycle -> Reject and ask the user to resolve"
         - rule: "active_change is empty -> Stop and request /mvt-analyze first"
@@ -48,6 +48,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -67,25 +70,24 @@ sections:
 
   - type: shared
     source: sections/session-update.md
-
-  - type: inline
-    content: |
-      ### Plan-Dev Specific State Updates
-
-      In addition to the mandatory updates above, this skill MUST update:
-
-      - `active_change.plan_path`: Set to `".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"`
-      - `active_change.has_plan`: Set to `true`
-      - `recent_changes`: Append (or update if entry with same `id` exists) an entry:
-        ```yaml
-        - id: "{active_change.id}"
-          title: "{active_change.title}"
-          plan_path: ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"
-          last_updated: "{current timestamp ISO 8601}"
-        ```
-        Keep max 5 entries (drop the oldest by `last_updated` ascending).
+    params:
+      current_skill: mvt-plan-dev
+      update_active_change: true
+      set_plan_path: true
+      update_change: true
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-plan-dev
+      conditional_suggestions:
+        conditions:
+          - condition: "plan created, first task is implementation"
+            primary: mvt-implement
+            primary_desc: "Start implementing the first task"
+          - condition: "plan created, first task is design"
+            primary: mvt-design
+            primary_desc: "Design the architecture for the first task"
+          - condition: "plan created, first task is testing"
+            primary: mvt-test
+            primary_desc: "Write tests for the first task"

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

@@ -84,7 +84,8 @@
   - 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)
+### Step 8: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
 

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

@@ -48,22 +48,40 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-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
+      ## 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 (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
+    params:
+      current_skill: mvt-quick-dev
+      no_change: true
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-quick-dev
+      conditional_suggestions:
+        conditions:
+          - condition: "change applied, tests exist for affected code"
+            primary: mvt-test
+            primary_desc: "Run tests on the changed code"
+          - condition: "change applied, no tests exist"
+            primary: mvt-review
+            primary_desc: "Quick review of the change"
+          - condition: "change was more complex than expected"
+            primary: mvt-analyze
+            primary_desc: "Do a full analysis for this change"

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

@@ -88,7 +88,8 @@
   - `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)
+### Step 10: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
 

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

@@ -65,13 +65,21 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required (shortcut operation).
 
-      ### Shortcut Operation Rules
-      - Can execute at any time without checking workflow prerequisites
+  - 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
@@ -79,8 +87,21 @@ sections:
 
   - 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

@@ -3,7 +3,7 @@ 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."
+  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
@@ -28,11 +28,11 @@ sections:
       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: "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 failed or was interrupted -> Surface the failure context, suggest retry"
+        - 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)"
@@ -47,9 +47,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -64,8 +61,21 @@ sections:
 
   - 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
 

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

@@ -48,12 +48,23 @@ sections:
 
       Usage: `/mvt-review` or `/mvt-review --aspect {type}`
 
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - ".ai-agents/workspace/artifacts/{active_change.id}/analysis.md -- Requirements analysis"
+        - ".ai-agents/workspace/artifacts/{active_change.id}/design.md -- Architecture design"
+        - ".ai-agents/workspace/artifacts/{active_change.id}/implementation.md -- Implementation record"
+
   - type: shared
     source: sections/activation-load-config.md
 
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -63,7 +74,7 @@ sections:
           level: "WARN"
           message: "Session not initialized. Run `/mvt-init` first."
         - order: "2"
-          field: "no code to review"
+          field: "review target (user args, implementation.md, or git diff)"
           level: "WARN"
           message: "No code to review. Run `/mvt-implement` first or specify files."
 
@@ -80,8 +91,21 @@ sections:
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-review
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-review
+      conditional_suggestions:
+        conditions:
+          - condition: "critical issues found"
+            primary: mvt-fix
+            primary_desc: "Fix the critical issues before merge"
+          - condition: "review approved, tests not written"
+            primary: mvt-test
+            primary_desc: "Add test coverage"
+          - condition: "review approved, all checks passed"
+            primary: mvt-update-plan
+            primary_desc: "Mark review task done in the plan"