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

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

@@ -1,93 +1,101 @@
-name: mvt-init
-output: .claude/skills/mvt-init/SKILL.md
-
-frontmatter:
-  name: mvt-init
-  description: "Initialize or refresh a project with comprehensive analysis. Detects tech stack, suggests architecture patterns, and sets up workspace state. Use when starting a new project or refreshing an existing one."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Init
-
-      ## Purpose
-
-      Initialize a project by scanning its structure, detecting the tech stack, suggesting an architecture pattern, and setting up the workspace state files. This is the entry point for the MVTT framework.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Conductor
-      role_desc: "a Workflow Coordinator"
-      decision_rules:
-        - rule: "If user intent is unclear -> Ask a clarifying question before proceeding"
-        - rule: "If `session.yaml` shows `initialized_at: \"\"` -> This is a fresh init"
-        - rule: "If `session.yaml` shows existing data -> This is a refresh (preserve existing state)"
-        - rule: "If no project files found -> Warn user this may be an empty project"
-      boundaries:
-        - scope: "analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "design architecture"
-          skill: "/mvt-design"
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
-
-  - type: inline
-    content: |
-      ## Variants
-
-      | Variant | Description |
-      |---------|-------------|
-      | `/mvt-init` | Standard initialization (balanced scan) |
-      | `/mvt-init --light` | Quick scan, minimal analysis |
-      | `/mvt-init --deep` | Exhaustive scan, comprehensive analysis |
-      | `/mvt-init --refresh` | Re-scan existing project, preserve workspace state |
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - "Scan project root for config files (package.json, requirements.txt, pom.xml, etc.)"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/activation-preflight.md
-    params:
-      checks:
-        - order: "1"
-          field: "session and project-context both empty"
-          level: "INFO"
-          message: "This is a first-time init, proceed normally."
-
-  - type: inline
-    content: |
-      ### 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/init-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/init-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the initialization results.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      next_primary: mvt-analyze
-      next_primary_desc: "Start analyzing requirements"
-      always_show:
-        - skill: mvt-status
-          desc: "View project status"
-        - skill: mvt-config
-          desc: "Adjust configuration settings"
+name: mvt-init
+output: .claude/skills/mvt-init/SKILL.md
+
+frontmatter:
+  name: mvt-init
+  description: "Initialize or refresh a project by scanning its structure, detecting tech stack, and inferring project type. This skill should be used when starting a new project, re-initializing after structural changes, or setting up the MVTT workspace."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Init
+
+      ## Purpose
+
+      Initialize a project by scanning its structure, detecting tech stack, inferring project type, and writing the lean project index. This is the entry point for the MVTT framework.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - rule: "If user intent is unclear -> Ask a clarifying question before proceeding"
+        - rule: "If `session.yaml` shows `initialized_at: \"\"` -> This is a fresh init"
+        - rule: "If `session.yaml` shows existing data -> This is a refresh (preserve existing state)"
+        - rule: "If no project files found -> Warn user this may be an empty project"
+        - rule: "If multiple languages detected -> Flag as monorepo candidate, identify primary language"
+        - rule: "If project type is ambiguous -> Prompt for confirmation between top candidates"
+        - rule: "If existing workspace files found on refresh -> Show diff and confirm before overwrite"
+      boundaries:
+        - scope: "analyze requirements"
+          skill: "/mvt-analyze"
+        - scope: "analyze existing code"
+          skill: "/mvt-analyze-code"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "write implementation code"
+          skill: "/mvt-implement"
+
+  - type: inline
+    content: |
+      ## Variants
+
+      | Variant | Description |
+      |---------|-------------|
+      | `/mvt-init` | Standard initialization (scan + detect + write index) |
+      | `/mvt-init --refresh` | Re-scan existing project -- preserve user state, update auto-detectable fields, show diff before writing |
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - "Scan project root for config files (package.json, requirements.txt, pom.xml, etc.)"
+        - "Scan project root for directory structure (src/, lib/, app/, tests/, etc.)"
+
+  - 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 and project-context both empty"
+          level: "INFO"
+          message: "This is a first-time init, proceed normally."
+
+  - type: file
+    source: ./business.md
+
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      update_initialized_at: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-init
+      conditional_suggestions:
+        conditions:
+          - condition: "has_existing_code"
+            primary: mvt-analyze-code
+            primary_desc: "Reverse-analyze existing codebase to generate project-context.md"
+          - condition: "empty_project"
+            primary: mvt-manage-context
+            primary_desc: "Manually add project context, requirements, or team conventions"
+          - condition: "default"
+            primary: mvt-analyze
+            primary_desc: "Start analyzing requirements"
+        alternatives:
+          - skill: mvt-manage-context
+            desc: "Manually add team conventions or domain knowledge"
+          - skill: mvt-analyze
+            desc: "Start from a requirements document"
+          - skill: mvt-status
+            desc: "Inspect current project status"

package/sources/skills/mvt-manage-context/business.md

@@ -0,0 +1,175 @@
+## Execution Flow
+
+### Step 1: Parse Subcommand
+
+Detect the subcommand from the invocation:
+
+| Invocation | Subcommand |
+|------------|-----------|
+| `/mvt-manage-context` | interactive menu (prompt user to pick add / remove / move / rename / list) |
+| `/mvt-manage-context add` | add |
+| `/mvt-manage-context remove [id]` | remove |
+| `/mvt-manage-context move [id]` | move |
+| `/mvt-manage-context rename [id]` | rename |
+| `/mvt-manage-context list` | list |
+
+For interactive menu, present the five options and wait for user choice, then enter that flow.
+
+### Step 2: Subcommand Routing
+
+Switch to the matching section below.
+
+---
+
+## Subcommand: add
+
+### 2.1 Collect content
+Prompt user for the knowledge content. Accept either:
+- Pasted text -> save to a new file
+- Path to an existing file -> import in place
+
+### 2.2 Detect knowledge type
+Classify the content into one of:
+- `principle` -- coding standards, naming conventions, review rules, team policies
+- `project` -- domain knowledge, business rules, API specs, integration notes
+- `core/user` -- universal principles the user wants applied to **every** skill (rare; explicit opt-in)
+
+The skill should suggest a type based on content keywords; the user confirms or overrides.
+
+### 2.3 AI Routing -- Score every skill
+
+1. Read `.ai-agents/registry.yaml` > `skills.*` -- collect every skill's `name` and `description`.
+2. For each skill, score relevance to the content on a 0-100 scale:
+   - 90-100: directly aligned (e.g., review rules + `mvt-review`)
+   - 70-89: strongly relevant
+   - 50-69: tangentially relevant
+   - 0-49: weak match
+3. Read `.ai-agents/config.yaml` > `preferences.context_routing.relevance_threshold` (default 70 if missing).
+4. Display **all** skills sorted by score descending. Do not truncate -- the user sees the full list with scores.
+   - Skills at or above threshold: pre-checked, shown with `[High]` / `[Med]` markers (or stars in emoji mode).
+   - Skills below threshold: collapsed under an "expand" prompt; not pre-checked.
+
+### 2.4 Accept user input
+Accept any of:
+- `Enter` (empty input) -- confirm pre-checked selection
+- Comma-separated indices (e.g. `1,3,5`) -- custom skill selection
+- `s` -- promote to **shared** (write to `registry.yaml > knowledge.shared`)
+- `c` -- promote to **core** (write to `.ai-agents/knowledge/core/user/{filename}` + append entry to `core/manifest.yaml` with `origin: user`)
+- `n` -- **none** (file-only; not auto-loaded)
+- `m` -- **manual** mode (display the full skill list including below-threshold for direct picking)
+- `expand` -- show below-threshold skills inline
+
+### 2.5 Resolve target path
+
+| User choice | File destination | Registry / manifest update |
+|------------|-----------------|----------------------------|
+| Per-skill (any subset) | `.ai-agents/knowledge/{type}/{filename}` (`type` = `principle` or `project`) | For each chosen skill: append entry to `registry.yaml > skills.{name}.knowledge[]` with `type: static`, `source: knowledge/{type}/`, `files: [{filename}]` |
+| `s` (shared) | `.ai-agents/knowledge/{type}/{filename}` | Append to `registry.yaml > knowledge.shared[]` with the same `type: static` shape |
+| `c` (core) | `.ai-agents/knowledge/core/user/{filename}` | Append to `core/manifest.yaml > files[]` with `path: user/{filename}`, `origin: user`, `auto_load: true` |
+| `n` (none) | `.ai-agents/knowledge/{type}/{filename}` | No registry/manifest change |
+
+If the user chose multiple bindings (e.g., shared + per-skill review), apply each rule.
+
+### 2.6 Write atomically
+1. Write the knowledge file.
+2. Update `registry.yaml` (and/or `core/manifest.yaml`) with all references.
+3. If any write fails, roll back: delete the new file, revert the registry/manifest edits.
+
+### 2.7 Report
+Use the `add / move / rename` output format from the manifest. Show:
+- The routing decision table (skill, score, bound or not)
+- The files modified
+- Token impact estimate (sum of file size / 4)
+
+---
+
+## Subcommand: remove
+
+### 3.1 Identify target
+- If `[id]` was provided: jump to 3.2
+- Otherwise: list all knowledge entries with their IDs and locations (same format as `list`), prompt user to pick one
+
+### 3.2 Confirm deletion
+Show the entry's file path, all binding references (shared / per-skill / core), and ask user to confirm.
+
+### 3.3 Drop references
+- `registry.yaml > knowledge.shared[]` -- remove entries whose path matches
+- `registry.yaml > skills.*.knowledge[]` -- remove every per-skill entry whose path matches
+- `core/manifest.yaml > files[]` -- if the file lives under `core/user/`, remove the matching entry
+
+### 3.4 Delete file
+Delete the physical file. If multiple entries pointed to the same file, only delete after all references are cleared.
+
+### 3.5 Report
+Use the `remove` output format. Show every reference dropped.
+
+---
+
+## Subcommand: move
+
+### 4.1 Identify source
+- If `[id]` was provided: jump to 4.2
+- Otherwise: prompt user to pick from `list` output
+
+### 4.2 Show current binding
+Display where the entry is currently bound (shared / per-skill / core / none).
+
+### 4.3 Prompt for new binding
+Use the same UI as `add` step 2.4 (Enter / indices / `s` / `c` / `n`).
+
+### 4.4 Apply changes
+- Update registry / manifest references atomically:
+  - Remove old references that no longer apply
+  - Add new references for newly chosen bindings
+- If the new binding requires the file to live in a different directory (e.g., promoting a `principle/` file to `core/user/`):
+  - Move the physical file
+  - Update the `path` field in every retained reference to match
+
+### 4.5 Report
+Use the `add / move / rename` output format. Highlight which references moved.
+
+---
+
+## Subcommand: rename
+
+### 5.1 Identify source
+Same as `move` step 4.1.
+
+### 5.2 Prompt for new id
+- Validate uniqueness against existing entries (under the same binding scope)
+- Validate filename safety (no path separators, no leading dots)
+
+### 5.3 Apply changes
+- Rename the physical file (`old/path/old-id.md` -> `old/path/new-id.md`)
+- Update every retained reference in `registry.yaml` and `core/manifest.yaml` to point to the new path
+
+### 5.4 Report
+Use the `add / move / rename` output format.
+
+---
+
+## Subcommand: list
+
+### 6.1 Read sources
+- `.ai-agents/registry.yaml` > `knowledge.shared[]` and `skills.*.knowledge[]`
+- `.ai-agents/knowledge/core/manifest.yaml` > `files[]`
+- Walk `.ai-agents/knowledge/{principle,project}/` for files not referenced anywhere (Unbound)
+
+### 6.2 Group and render
+Use the `list` output format. Each row should answer: where is the file, and which skills load it?
+
+For Per-Skill rows, list every skill that binds to the file (a single file can be bound to multiple skills).
+
+### 6.3 Health hints
+At the bottom of the list, optionally surface:
+- "N file(s) present but unbound -- consider `/mvt-manage-context move` or `/mvt-manage-context remove`"
+- "Total token cost (auto-loaded): ~X tokens" -- approximate
+
+---
+
+## Cross-cutting rules
+
+- **Atomicity**: file system writes and registry/manifest writes must succeed together. On partial failure, restore the previous state.
+- **No edits to framework files**: never write to `.ai-agents/knowledge/core/_framework/`. If user content would land there by accident, redirect to `core/user/`.
+- **Backups**: before mutating `registry.yaml` or `core/manifest.yaml`, copy them to `.ai-agents/.backup/{filename}-{timestamp}.yaml`.
+- **Idempotency**: re-running the same `add` (same content + same bindings) should detect the existing entry and offer "skip / overwrite / cancel" rather than silently duplicating.

package/sources/skills/mvt-manage-context/manifest.yaml

@@ -0,0 +1,123 @@
+name: mvt-manage-context
+output: .claude/skills/mvt-manage-context/SKILL.md
+
+frontmatter:
+  name: mvt-manage-context
+  description: "Unified entry point for managing knowledge and registry. Supports subcommands: add (with AI routing), remove, move, rename, list. Use this skill instead of mvt-add-context."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Manage Context
+
+      ## Purpose
+
+      Unified CRUD entry point for project context and knowledge entries. Handles add (with AI-driven skill routing), remove, move, rename, and list operations across `project-context.yaml`, `project-context.md`, `knowledge/principle/`, `knowledge/project/`, `knowledge/core/user/`, and the corresponding `registry.yaml` / `core/manifest.yaml` references.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Knowledge Curator"
+      decision_rules:
+        - rule: "User invokes without subcommand -> Show interactive menu of operations"
+        - rule: "Add a knowledge file -> Run AI routing, suggest skill bindings, write file + update registry/manifest atomically"
+        - rule: "Remove a knowledge entry -> Drop both the file and every registry/manifest reference, show diff"
+        - rule: "Move binding (per-skill <-> shared <-> core) -> Update references and (if path changes) physically move the file"
+        - rule: "Rename a knowledge id -> Update file path + every registry/manifest reference in lockstep"
+        - rule: "List request -> Group entries by binding type and show which skills load each"
+        - rule: "AI routing produces no candidate above threshold -> Recommend `none` (file-only) or prompt user to broaden scope"
+      boundaries:
+        - scope: "analyze code automatically"
+          skill: "/mvt-sync-context or /mvt-analyze-code"
+        - scope: "make architecture decisions"
+          skill: "/mvt-design"
+        - scope: "write implementation code"
+          skill: "/mvt-implement"
+        - scope: "edit framework knowledge under core/_framework/"
+          skill: "(Read-only -- framework files are not user-editable)"
+
+  - 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: inline
+    content: |
+      ### Step 3: Pre-flight Checks
+      - No blocking checks required.
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## Output Format
+
+      No external template -- output is inline. Format depends on subcommand:
+
+      ### add / move / rename
+      ```markdown
+      ## Knowledge Updated
+
+      ### Operation: {add | move | rename}
+
+      ### Routing Decision
+      | Skill | Score | Bound? |
+      |-------|-------|--------|
+      | mvt-review | 92 | Yes |
+      | mvt-test | 85 | Yes |
+      | mvt-implement | 60 | No (below threshold) |
+
+      ### Files Modified
+      - `.ai-agents/knowledge/{path}` -- {created | moved | renamed}
+      - `.ai-agents/registry.yaml` -- {entries added/removed}
+      - `.ai-agents/knowledge/core/manifest.yaml` -- {entry added/removed} (if applicable)
+      ```
+
+      ### remove
+      ```markdown
+      ## Knowledge Removed
+
+      ### Removed entry: `{id}`
+      - File: `.ai-agents/knowledge/{path}` (deleted)
+      - References dropped from:
+        - `registry.yaml > knowledge.shared` (if applicable)
+        - `registry.yaml > skills.{name}.knowledge` x N (if applicable)
+        - `core/manifest.yaml > files[]` (if applicable)
+      ```
+
+      ### list
+      ```markdown
+      ## Knowledge Inventory
+
+      ### Shared (all skills)
+      | id | path | type |
+      |----|------|------|
+
+      ### Per-Skill
+      | id | path | bound to |
+      |----|------|----------|
+
+      ### Core (user contributions)
+      | id | path | auto_load |
+      |----|------|-----------|
+
+      ### Unbound (file present but not auto-loaded)
+      | id | path |
+      |----|------|
+      ```
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-manage-context

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

@@ -0,0 +1,75 @@
+## Execution Flow
+
+### Step 1: Gather Source Material
+
+Collect everything that should inform the plan:
+
+1. 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:
+
+- Read the existing plan.
+- Show a summary (task count, status counts, current_task).
+- Ask: "A plan already exists. Choose: (1) regenerate from scratch (existing tasks discarded), (2) cancel and use `/mvt-update-plan` to evolve it, (3) abort."
+- Only continue with generation on choice (1).
+
+### Step 3: Decompose Into Tasks
+
+Decompose the change with the following constraints. These constraints are AI-friendly granularity rules — too coarse leaves a task uncompletable in a single skill invocation; too fine turns the plan into noise.
+
+| Rule | Detail |
+|------|--------|
+| 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. |
+| 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.). |
+
+### Step 4: Assemble plan.yaml
+
+Build the plan object following `docs/plan-yaml-schema.md`:
+
+- `version: 1`
+- `change_id`: copy from `active_change.id`
+- `title`: copy from `active_change.title`
+- `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`
+
+### Step 5: Validate
+
+Before writing, validate the assembled YAML against the schema:
+
+- Unique task ids
+- All `depends_on` references resolve
+- No dependency cycles
+- `current_task` references a task with status `pending` or `in_progress`
+
+If validation fails, revise the plan and re-validate (do NOT write a broken plan).
+
+### Step 6: Write plan.yaml
+
+Write to `.ai-agents/workspace/artifacts/{active_change.id}/plan.yaml`. If the artifacts directory does not exist, create it.
+
+If a previous `plan.yaml` exists and the user chose regeneration in Step 2, overwrite it. Otherwise, this is a fresh write.
+
+### 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`)
+
+### 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.

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

@@ -0,0 +1,91 @@
+name: mvt-plan-dev
+output: .claude/skills/mvt-plan-dev/SKILL.md
+
+frontmatter:
+  name: mvt-plan-dev
+  description: "Generate a structured development plan (plan.yaml) for a large change. This skill should be used when a change is too big for a single implement pass and needs to be tracked across multiple sessions with task-level granularity."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Plan Dev
+
+      ## Purpose
+
+      Decompose a large change into a structured `plan.yaml` so progress can survive across conversations. Each task carries status, dependencies, acceptance criteria, and a recommended skill, enabling `/mvt-resume` to land precisely on the next executable task in a future session.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      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: "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"
+      boundaries:
+        - scope: "create or modify the active change itself"
+          skill: "/mvt-analyze"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "advance task status after completion"
+          skill: "/mvt-update-plan"
+        - scope: "implement code"
+          skill: "/mvt-implement"
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - ".ai-agents/workspace/artifacts/{active_change.id}/ -- Existing analysis/design artifacts for this change"
+        - ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml -- Existing plan, if any (regeneration mode)"
+
+  - 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.id"
+          level: "BLOCK"
+          message: 'No active change. Run `/mvt-analyze` to create one before planning.'
+
+  - type: file
+    source: ./business.md
+
+
+  - 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).
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-plan-dev