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

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

@@ -1,49 +1,96 @@
-## Execution Flow
-
-### Step 1: Load Template Inventory
-- Read registry to get all registered templates
-- Scan `custom/` directory for existing custom versions
-- Build status list: default / customized for each template
-
-### Step 2: Display Template List
-Show all templates with their status:
-
-```markdown
-## Output Templates
-
-| # | Template | Skill | Status |
-|---|---------|-------|--------|
-| 1 | analyze-output.md | mvt-analyze | Default |
-| 2 | design-output.md | mvt-design | Customized |
-| ... | ... | ... | ... |
-
-**Actions**: `view {#}`, `customize {#}`, `reset {#}`, `export {#}`
-```
-
-### Step 3: Execute Action (based on user choice)
-
-**View**:
-- Display full template content
-- If custom version exists, show that; otherwise show default
-- Indicate which version is being shown
-
-**Customize**:
-1. Show current default template
-2. Ask user to describe desired modifications
-3. Generate new template based on modifications
-4. Preview the customized template
-5. Save to `custom/{template-name}` after user confirmation
-6. Custom template must retain frontmatter (`id`, `version`, `skill`)
-
-**Reset**:
-1. Confirm user wants to reset to default
-2. Delete the custom version from `custom/`
-3. Confirm reset complete
-
-**Export**:
-- Output template content to user-specified location
-- Or display in a code block for manual copy
-
-### Step 4: Confirmation
-- Show result of the action taken
-- Confirm files modified
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Recommended**:
+  - `.ai-agents/skills/_templates/` -- default templates (read-only from this skill).
+
+### Step 2: Build Template Inventory
+- **What**: produce the canonical list of templates with their status.
+- **How**:
+  1. From `registry.yaml`, collect every `skills.<name>.template` value that is not null.
+  2. For each entry, derive the basename (e.g., `analyze-output.md`).
+  3. For each basename:
+     - `default` exists if the file is present under `.ai-agents/skills/_templates/`.
+     - `custom` exists if the file is present under `.ai-agents/skills/_templates/custom/` with the same basename.
+  4. Status:
+     - `Default` if only default exists.
+     - `Customized` if both exist.
+     - `Orphan-custom` if custom exists but registry has no skill referencing it (surface as a warning).
+     - `Missing` if registry references a basename that has no default file (surface as a warning).
+
+### Step 3: Display Inventory and Wait for Action
+- Render the inventory as a numbered table:
+
+  ```markdown
+  | # | Template | Skill(s) | Status |
+  |---|----------|----------|--------|
+  | 1 | analyze-output.md | mvt-analyze | Default |
+  | 2 | design-output.md | mvt-design | Customized |
+  ```
+
+- Below the table, list available actions: `view {#}`, `customize {#}`, `reset {#}`, `export {#} [path]`.
+- If any `Orphan-custom` or `Missing` rows exist, print a one-line warning above the table.
+- Wait for user input. The `{#}` may be a number or the basename.
+
+### Step 4: Dispatch Action
+
+#### 4a. View
+- **What**: show the active version of the template.
+- **How**:
+  1. If `Customized`, read the custom file. Otherwise read the default.
+  2. Print the file content in a fenced code block, prefixed by a single line: `Showing: <default|custom> -- <path>`.
+  3. No write.
+
+#### 4b. Customize
+- **What**: create or update the custom override; preserve a structure the assembler can still consume.
+- **How** (4-step subflow):
+  1. **Show baseline**: print the current active version (custom if exists, otherwise default).
+  2. **Collect modifications from the user**: ask for one of these explicit input forms (do not improvise):
+     - "replace section `<heading>` with: ..."
+     - "add section `<heading>` after `<existing-heading>`: ..."
+     - "remove section `<heading>`"
+     - "edit frontmatter field `<key>` to `<value>`"
+     - "free-form patch: <unified diff>"
+  3. **Preview**: render the resulting file (full content) and a diff against the baseline. Do NOT write yet.
+  4. **Validate** (mandatory before write):
+     - Frontmatter block (`---\n...\n---`) must be present and parseable.
+     - Required frontmatter keys (`id`, `version`, `skill` if originally present) must be retained.
+     - All Mustache placeholders that were present in the default and that the assembler relies on (`{{...}}`, `{{#...}}`, `{{?...}}`, `{{^...}}`) must still be present unless the user explicitly removed them; warn if removed.
+     - Validation failures -> abort write, surface the failed checks, return to step 2 of this subflow.
+  5. **Confirm and write**: prompt `Save customized template to .ai-agents/skills/_templates/custom/<name>? (y/n)`. On `y`, write atomically (temp + rename). Backup any existing custom file as `<name>.bak` first.
+
+#### 4c. Reset
+- **What**: revert to the default template.
+- **How**:
+  1. If no custom file exists, report "Already default, nothing to reset" and stop.
+  2. Show a one-line summary of what will be deleted (`<path>`, last modified date).
+  3. Require explicit confirmation: `Delete custom override <name>? (y/n)`.
+  4. On `y`, delete the file. Do NOT keep a backup -- user must use git for recovery.
+  5. Report success and the new status (`Default`).
+
+#### 4d. Export
+- **What**: emit the template content to a destination chosen by the user.
+- **How**:
+  1. Determine source: custom version if exists, otherwise default. Print which one is being exported.
+  2. Determine destination using the table:
+
+     | User input | Destination |
+     |------------|-------------|
+     | No path given | Print the content as a fenced code block in chat |
+     | Relative or absolute file path | Write to that path; if file exists, ask for confirmation before overwriting |
+     | Literal string `custom` | Copy default to `.ai-agents/skills/_templates/custom/<name>` (use as starting point for customization) |
+
+  3. Never write outside the project root unless an absolute path was explicitly provided by the user.
+
+### Step 5: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| User selects a `#` that doesn't exist in inventory | Re-display the table, ask again |
+| `customize` validation fails repeatedly | After two failed attempts, suggest user export to a file and edit manually, then re-import via `customize` with `free-form patch` |
+| Custom file exists but registry no longer references the template (`Orphan-custom`) | Allow `view` and `reset`; refuse `customize` (stale target); recommend running `/mvt-init --refresh` or removing the file manually |
+| Default file is missing (`Missing`) | Refuse all actions for that row; suggest reinstall (`mvtt install`) |
+| User aborts at any confirmation prompt | Do not modify any file; report "no changes" |
+| External process modified the file between preview and write | Detect via mtime check just before write; abort and re-run preview |

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-template/SKILL.md
 
 frontmatter:
   name: mvt-template
-  description: "View, customize, and manage output templates for MVTT skills. Use when user wants to see available templates, create custom template versions, reset to defaults, or export templates."
+  description: "View, customize, and manage output templates for MVTT skills. This skill should be used when user wants to inspect available templates, create custom template versions, reset customizations, or export templates."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Provide an interactive tool for viewing, customizing, and managing MVTT output templates. Users can inspect default templates, create custom versions that override defaults, reset customizations, and export templates.
+      View, customize, and manage MVTT output templates. Inspect default templates, create custom versions that override defaults, reset customizations, and export templates.
 
   - type: shared
     source: sections/role-header.md
@@ -36,36 +36,28 @@ sections:
     source: sections/activation-load-context.md
     params:
       extended_context:
-        - ".ai-agents/registry.yaml -- Template registry"
         - "Scan `.ai-agents/skills/_templates/custom/` for existing customizations"
 
   - 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.
 
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
   - type: file
     source: ./business.md
 
-  - type: inline
-    content: |
-      ## Output Format
-
-      No external template -- output is inline based on the action:
-
-      ```markdown
-      ## Template Manager
-
-      {Action-specific content}
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
 
-      ---
-      **Suggested Next Steps**:
-      - `/mvt-template` -- Manage more templates
-      - `/mvt-help` -- View all available skills
-      ```
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-template

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

@@ -1,36 +1,104 @@
-## Execution Flow
-
-### Step 1: Load Context
-- Read implementation files
-- Read project-context for tech stack and test framework
-- Identify test framework conventions
-
-### Step 2: Analyze Test Scenarios
-- Identify happy path scenarios
-- Identify edge cases and boundary conditions
-- Identify error scenarios
-- Identify security test cases (if applicable)
-
-### Step 3: Design Test Cases
-- Create test case table with IDs, scenarios, inputs, expected outputs
-- Define preconditions for each test
-- Prioritize by type (happy path and edge cases first)
-
-### Step 4: Write Test Code
-- Follow project's test framework conventions
-- Write clear, descriptive test names
-- Include setup, action, and assertion sections
-- Use mocks/stubs for external dependencies
-
-### Step 5: Coverage Analysis (with --coverage)
-- Map test cases to requirements
-- Identify coverage gaps
-- Recommend additional tests for missing coverage
-
-### Step 6: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `progress.test: done`
-   - Set `session.last_command: "/mvt-test"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-2. Write test files to the project
-3. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/tests/`
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - The implementation files to test (see Step 2 for resolution).
+- **Recommended**:
+  - Existing tests near the target files -- to follow conventions and avoid duplication.
+- **Fallback**:
+  - If test framework is unspecified in `project-context.yaml`, infer from package manifests (jest/vitest/pytest/junit/...) and ask user to confirm before generating tests.
+  - If `project-context.md` business rules are missing, derive scenarios solely from code and design; mark coverage analysis as "rule-mapping unavailable".
+
+### Step 2: Resolve Test Target
+- **What**: produce the file list under test.
+- **How**: pick the FIRST source that yields a non-empty list.
+
+  | Source | Condition |
+  |--------|-----------|
+  | User-provided feature/file argument (`/mvt-test {feature}`) | Argument present |
+  | `implementation.md` -> `Files Touched` | Active change has implementation artifact |
+  | `git diff --name-only main...HEAD` filtered to source dirs | Inside a feature branch |
+  | Recently modified source files | Last-resort, last 24h mtime |
+
+- For each target file, locate or plan its corresponding test file path using the project's test layout convention (mirror under `tests/`, sibling `*.test.ts`, etc.).
+
+### Step 3: Identify Test Scenarios
+- **What**: produce a Scenario Table covering happy path, edge, negative, and security cases.
+- **How**:
+  1. For each public function / endpoint in scope, list at least: 1 happy path, 1 boundary, 1 invalid input.
+  2. For each business rule from `project-context.md` that this code implements, list at least 1 scenario asserting the rule.
+  3. For each error path declared in `design.md` data flow, list at least 1 scenario.
+  4. Consult the Test Case Types table (provided in shared section above):
+     - Happy Path / Edge / Negative -> always include if applicable.
+     - Security -> include only when requirements mention auth, data sensitivity, or external input boundaries.
+     - Performance -> include only when requirements explicitly state SLAs.
+
+### Step 4: Choose Test Granularity
+- **What**: assign each scenario to unit / integration / E2E.
+- **How**: use the rule below; one scenario maps to one granularity.
+
+  | Granularity | Use when |
+  |-------------|----------|
+  | Unit | Pure logic, single class/function, no IO, deterministic |
+  | Integration | Crosses a system boundary (DB, HTTP, queue, file system); module collaboration without UI |
+  | E2E | User-visible flow that traverses multiple services or includes UI interaction |
+
+- A single scenario should not be tested at multiple granularities unless explicitly required (avoid wasteful duplication).
+- Flag scenarios that need integration but the project lacks an integration test setup -> note in artifact, suggest setup, do not invent a fixture.
+
+### Step 5: Design Test Cases
+- **What**: turn each scenario into a concrete test case row.
+- **How**: each row must include `id | scenario | granularity | preconditions | inputs | actions | expected | rule-traced-to`.
+- Prioritize: every business rule trace must be present; happy paths first, then edges, then negatives, then security/performance.
+- For external dependencies, decide mock/stub/fake per project conventions; document the choice.
+
+### Step 6: Write Test Code
+- **What**: emit test files using project conventions.
+- **How**:
+  1. Match the project's existing test framework, file layout, and naming.
+  2. Test names describe the scenario in business language ("rejects login when password is expired"), not the function name.
+  3. Each test follows arrange / act / assert structure with no hidden setup.
+  4. Use mocks/stubs only at boundaries identified in Step 4; do NOT mock the unit under test.
+  5. Do not modify the production code being tested -- if implementation has a bug, surface it (Step 8) and recommend `/mvt-fix`.
+  6. Avoid `skip` / `only` / commented-out tests in the final output.
+
+### Step 7: Coverage Analysis (only when `--coverage` flag set)
+- **What**: produce a coverage map and gap list.
+- **How**:
+  1. Map each test case (Step 5) back to: a target file/function, and (if available) a business rule from `project-context.md`.
+  2. Identify gaps: target functions with no test, business rules with no test, error paths from `design.md` with no test.
+  3. Read coverage thresholds from `.ai-agents/config.yaml` if present; otherwise default targets: line >= 80%, branch >= 70%, business-rule == 100%.
+  4. Recommend additional test cases for each gap; do not auto-generate them in this run unless user confirms.
+
+### Step 8: Surface Implementation Issues (if any)
+- During scenario design or test writing you may discover the implementation is wrong (failing test reveals a real bug, not a test bug).
+- **Do not** modify production code from this skill.
+- Record each finding with: scenario id, expected vs observed, severity (Critical / Warning), and recommend `/mvt-fix`.
+
+### Step 9: Write Artifact
+- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/tests/test-design.md`.
+- **Template**: `.ai-agents/skills/_templates/test-output.md` (custom override at `_templates/custom/...` takes precedence).
+- **Required content** (mapped to template headings):
+  - `Scope` -- target files, fallbacks applied.
+  - `Test Framework & Layout` -- chosen framework, file layout convention.
+  - `Test Scenarios` -- the Scenario Table from Step 3.
+  - `Test Cases` -- the row-level table from Step 5.
+  - `Granularity Decisions` -- summary from Step 4, including any "needs setup" gaps.
+  - `Coverage Analysis` -- only when `--coverage`; otherwise omit the heading.
+  - `Implementation Issues Found` -- from Step 8; empty list is fine.
+  - `Suggested Run Commands` -- one or two commands the user can copy-paste.
+- The actual test files go to the project tree; the artifact is a record.
+
+### Step 10: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Test framework unsupported by environment (e.g., language has no widely-used framework) | STOP, report, ask user for guidance; do not improvise a custom harness |
+| Implementation files have zero public API (purely internal) | Cap at integration-level scenarios; do not test private symbols |
+| Existing tests for the target are present and conflict with new scenarios | Surface the conflict in `Implementation Issues Found`; do not silently delete or rewrite existing tests |
+| External services required and not mockable (e.g., real LLM call) | Use recorded fixtures if conventional; otherwise mark scenarios as `requires-live-service` and skip code generation |
+| Flaky test detected during writing | Add deterministic seeding/clock; if not possible, mark as `flaky-suspected` and surface in artifact |
+| User asks to "skip edge cases" | Refuse: edge cases are a non-negotiable boundary of this skill; explain and continue |
+| `--coverage` set but coverage tool not configured in project | Generate the gap list from scenarios alone; suggest tool setup; do not invoke a non-existent coverage runner |

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-test/SKILL.md
 
 frontmatter:
   name: mvt-test
-  description: "Generate and design tests to validate implementations. Creates test cases covering happy paths, edge cases, negative scenarios, and security. Use when user wants to write tests or validate code."
+  description: "Generate and design tests to validate implementations. This skill should be used when user wants to write tests, validate code, generate test cases, or analyze test coverage."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Design and write tests to validate implementations against requirements. Ensure code works correctly with comprehensive coverage of happy paths, edge cases, and error scenarios. This is the fifth phase in the full workflow: analyze -> design -> implement -> review -> test.
+      Design and write tests to validate implementations against requirements and business rules. Ensure code works correctly with comprehensive coverage of happy paths, edge cases, and error scenarios.
 
   - type: shared
     source: sections/role-header.md
@@ -49,14 +49,14 @@ sections:
     source: sections/activation-load-context.md
     params:
       extended_context:
-        - ".ai-agents/knowledge/core/review-principles.md -- Code quality principles"
-        - ".ai-agents/knowledge/patterns/{pattern.active}/ -- Active pattern knowledge"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Project coding standards"
         - "Implementation files to be tested"
 
   - 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,21 +64,14 @@ sections:
         - order: "1"
           field: "session.initialized_at"
           level: "WARN"
-          message: 'Session not initialized. Run `/mvt-init` first.'
+          message: "Session not initialized. Run `/mvt-init` first."
         - order: "2"
           field: "no implementation files"
           level: "WARN"
-          message: 'No implementation found. Run `/mvt-implement` first.'
-        - order: "3"
-          field: "pattern.active"
-          level: "WARN"
-          message: 'Architecture pattern not set. Suggest `/mvt-init`." (allow user to proceed)'
+          message: "No implementation found. Run `/mvt-implement` first."
 
   - type: inline
     content: |
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
       ## Test Case Types
 
       | Type | Description | Priority |
@@ -94,18 +87,16 @@ sections:
 
   - type: inline
     content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/test-output.md`
-
+      ## Artifact Structure
+      Read the document structure template from: `.ai-agents/skills/_templates/test-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/test-output.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on test design results.
+      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/tests/test-design.md`
 
-      Fill the template placeholders with the test design results.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
-      next_primary: mvt-fix
-      next_primary_desc: "Run tests with the appropriate command; if tests fail, use this"
+      current_skill: mvt-test

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

@@ -0,0 +1,72 @@
+## Execution Flow
+
+### Step 1: Resolve Target
+
+Required inputs:
+
+- **task_id** -- which task to update
+- **new_status** -- one of: `pending`, `in_progress`, `done`, `blocked`, `skipped`
+- **artifacts** (optional, comma-separated paths) -- files produced or touched
+- **notes** (optional) -- free-form note string
+
+Resolution rules:
+
+- If `task_id` is omitted AND exactly one task currently has status `in_progress` -> default to that task.
+- If `task_id` is omitted AND zero or multiple tasks are in_progress -> ask the user to specify.
+- If the user reply is the natural-language form `done` / `blocked: <reason>` (from a workflow skill's soft-prompt) -> map to:
+  - `done` -> task = plan.current_task, new_status = done
+  - `blocked: <reason>` -> task = plan.current_task, new_status = blocked, notes = `<reason>`
+
+### Step 2: Load and Validate Existing Plan
+
+1. Read `active_change.plan_path` (the file location is fixed by `/mvt-plan-dev`).
+2. Parse YAML; if parse fails or schema is invalid -> stop and report. Do not attempt to repair silently.
+3. Verify the target `task_id` exists in `tasks[]`. If not, list valid ids and stop.
+
+### Step 3: Apply the Update
+
+Mutate the in-memory plan:
+
+1. Find the target task; capture `old_status` for the report.
+2. Set `tasks[i].status = new_status`.
+3. If `artifacts` provided -> append to `tasks[i].artifacts` (de-duplicate).
+4. If `notes` provided -> overwrite `tasks[i].notes`.
+5. Update `plan.updated_at` to current ISO 8601 timestamp.
+
+### Step 4: Recompute current_task
+
+Selection logic, in order:
+
+1. If any task has status `in_progress` AND it is **not** the task we just changed to a terminal status (done/blocked/skipped) -> `current_task` = that task's id.
+2. Otherwise pick the first task (by array order) where:
+   - `status == pending`
+   - All ids in `depends_on` reference tasks with status `done`
+3. If no such task exists AND every task is `done` -> set `plan.status = done`, `current_task = null`.
+4. If no such task exists but some tasks are still `pending` (because their dependencies are not done -- e.g., everything reachable is blocked) -> set `current_task = null`, leave `plan.status = in_progress`. Surface a warning in the output ("All remaining tasks are blocked by dependencies; resolve a blocker before continuing").
+
+If the selected next task is currently `pending` -> promote it to `in_progress` (so the plan accurately reflects the active focus). Skip this promotion if `plan.status` just transitioned to `done`.
+
+### Step 5: Validate and Write
+
+1. Run the plan validator on the mutated structure.
+2. If validation fails -> abort the write, report the validation errors, leave the original file untouched.
+3. Otherwise, write back to `active_change.plan_path`.
+
+### Step 6: Update Session State
+
+Apply the standard State Update rules (see shared section above) AND the update-plan-specific updates:
+
+- Refresh the matching entry in `recent_changes[]`: `last_updated` -> current ISO 8601 timestamp.
+- Do NOT touch `active_change.has_plan` / `active_change.plan_path`.
+
+### Step 7: Output
+
+Emit the Plan Update summary block defined in the Output Format section. Include:
+
+- The task that changed (id, title, old -> new status).
+- A compact table of all tasks with their current status.
+- The new `current_task` (or "(plan complete)" if `plan.status == done`).
+- A one-line "Next" hint:
+  - If a new `current_task` is set -> recommend the skill matching its `skill_hint`.
+  - If plan complete -> recommend `/mvt-cleanup` or starting a new change via `/mvt-analyze`.
+  - If all remaining tasks are blocked -> recommend resolving the blocker (point at the `notes` of the blocked task).

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

@@ -0,0 +1,132 @@
+name: mvt-update-plan
+output: .claude/skills/mvt-update-plan/SKILL.md
+
+frontmatter:
+  name: mvt-update-plan
+  description: "Update a single task in the active change's plan.yaml: change status, attach artifacts, leave notes, and auto-advance current_task. This skill should be used after a workflow skill finishes work that maps to a plan task, or whenever the user wants to mark a task as done, blocked, or skipped."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Update Plan
+
+      ## Purpose
+
+      Apply incremental updates to the active plan.yaml: mark a task done/blocked/skipped, attach the artifacts produced, and let the skill auto-advance `current_task` to the next executable task. AI may invoke this skill on the user's behalf when the user replies to a soft-prompt with `done` / `blocked: <reason>`.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Architect
+      role_desc: "a Development Planner"
+      decision_rules:
+        - rule: "Task id provided AND target status valid -> Apply update, advance current_task, write back"
+        - rule: "Task id missing AND only one task is in_progress -> Default to that task"
+        - rule: "Target status would create an invalid current_task -> Recompute current_task automatically"
+        - rule: "All tasks become done -> Set plan.status = done, current_task = null"
+        - rule: "active_change.has_plan is false -> Stop and suggest /mvt-plan-dev"
+
+      boundaries:
+        - scope: "create new tasks or restructure the plan"
+          skill: "/mvt-plan-dev"
+        - scope: "create or modify the active change itself"
+          skill: "/mvt-analyze"
+        - scope: "implement code"
+          skill: "/mvt-implement"
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - "{active_change.plan_path} -- The plan to update (resolved from session.yaml)"
+
+  - 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.'
+        - order: "2"
+          field: "active_change.has_plan"
+          level: "BLOCK"
+          message: 'No active plan. Run `/mvt-plan-dev` to create one before updating.'
+
+  - type: inline
+    content: |
+      ### Shortcut Operation Rules
+      - Can execute at any time when an active plan exists
+      - Performs surgical edits only -- never overwrites the whole plan structure
+      - Re-validates the resulting plan before writing; aborts on validation failure
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## Output Format
+
+      Render an inline summary (no external template). Structure:
+
+      ```markdown
+      ## Plan Update
+
+      ### Change Applied
+      - **Task**: {task_id} -- {task_title}
+      - **Status**: {old_status} -> {new_status}
+      - **Artifacts attached**: {comma_separated_list_or_"(none)"}
+      - **Notes**: {notes_or_"(unchanged)"}
+
+      ### Plan Progress
+      | # | id | title | status |
+      |---|----|----|--------|
+      | ... |
+
+      Progress: {done_count}/{total_count}
+      Current task: {new_current_task_id_or_"(plan complete)"}
+
+      ### Next
+      {one-line guidance: continue to next task, resolve blocker, or run /mvt-cleanup}
+      ```
+
+      Every response MUST end with a Suggested Next Steps section.
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: inline
+    content: |
+      ### Update-Plan Specific State Updates
+
+      In addition to the mandatory updates above, this skill MUST refresh `recent_changes` for the active change:
+
+      - Find the entry where `id == active_change.id`. If absent, append one (this should be rare; happens when the plan was created out-of-band).
+      - Set `last_updated` to the current ISO 8601 timestamp.
+      - Trim to max 5 entries (drop the oldest by `last_updated` ascending).
+
+      Do NOT modify `active_change.has_plan` or `active_change.plan_path` here -- those are owned by `/mvt-plan-dev`.
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-update-plan
+      conditional_suggestions:
+        conditions:
+          - condition: "plan_done"
+            primary: mvt-cleanup
+            primary_desc: "All tasks complete -- clean up artifacts and prepare to start the next change"
+          - condition: "default"
+            primary: mvt-implement
+            primary_desc: "Continue with the next current_task"
+        alternatives:
+          - skill: mvt-resume
+            desc: "Refresh context after task transitions"
+          - skill: mvt-status
+            desc: "Inspect overall progress across changes"