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

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

@@ -60,6 +60,7 @@
   | 3 | `preferences.output.no_emojis` | Default `true` |
   | 4 | `preferences.output.data_format` | Default `yaml`; allowed: `yaml`, `json` |
   | 5 | `preferences.context_routing.relevance_threshold` | Default `70`; allowed: 0-100 |
+  | 6 | `preferences.history_limits.*` | Show each limit with current value; accept new int or Enter to keep |
 
 - After all stages, render a Summary Preview table: `key | from | to`, then a single confirmation prompt to apply ALL changes atomically.
 - If the user aborts at the summary, discard all in-progress values; do not write anything.
@@ -73,8 +74,6 @@
 6. Report the keys that changed.
 - Do NOT reset `knowledge.shared` to defaults if the user has added entries via `/mvt-manage-context` -- preserve user-added knowledge ids; only reset preferences. Surface this exception in the diff.
 
-### Step 8: (session update handled by shared section)
-
 ## Knowledge Inspection (sub-flow used by Interactive Menu and Show All)
 - **View**: list shared knowledge ids from `registry.yaml > knowledge.shared`, then per-skill knowledge ids grouped by skill (`registry.yaml > skills.*.knowledge`). Show token estimates from each entry's manifest if available.
 - **Modify**: this skill does NOT mutate knowledge settings; defer to `/mvt-manage-context`. Print the suggested command (`/mvt-manage-context move`, `/mvt-manage-context add`, etc.) instead of doing the work here.

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

@@ -56,12 +56,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required (config is always accessible)
 
       ## Configuration Keys
@@ -75,6 +72,8 @@ sections:
       | `preferences.output.no_emojis` | bool | `true` | Disable emojis in output |
       | `preferences.output.data_format` | enum | `yaml` | Data output format (yaml, json) |
       | `preferences.context_routing.relevance_threshold` | int | `70` | AI routing threshold for `/mvt-manage-context add` (0-100) |
+      | `preferences.history_limits.history` | int | `20` | Max history entries (1-100) |
+      | `preferences.history_limits.changes` | int | `20` | Max changes entries (1-100) |
 
       ### Knowledge Settings
 
@@ -94,3 +93,11 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-config
+      conditional_suggestions:
+        conditions:
+          - condition: "configuration updated"
+            primary: mvt-status
+            primary_desc: "Check project status with new settings"
+          - condition: "language changed"
+            primary: mvt-help
+            primary_desc: "Verify output in the new language"

package/sources/skills/mvt-create-skill/business.md

@@ -27,7 +27,7 @@ The `name` and `description` in YAML frontmatter determine when Claude will use
 ### Step 1: Load Inputs
 - **Recommended**:
   - One existing skill's SKILL.md under `.claude/skills/<existing>/SKILL.md` as a structural reference (to extract shared section patterns like Activation Protocol, State Update, Next Steps).
-  - `registry.yaml` -- to check for name collisions and understand skill categories.
+  - `.ai-agents/registry.yaml` -- to check for name collisions and understand skill categories.
 
 ### Step 2: Understand Usage with Concrete Examples
 Skip only when usage patterns are already crystal clear.
@@ -136,7 +136,7 @@ Walk this checklist; any failed item must be fixed before declaring success.
 | Standard sections present | SKILL.md contains Role, Activation Protocol, Execution Flow, Edge Cases & Errors, State Update, Suggested Next Steps |
 | Knowledge files exist | Every file referenced in `knowledge:` resolves on disk |
 | Template path correct | If `template:` set, file exists at that path; the template is headings-only |
-| Word budget | SKILL.md body under ~5k words (run a quick `wc` if available) |
+| Word budget | SKILL.md body under ~5k words (use any available word-count method, e.g., editor statistics) |
 | Standard skeleton | Execution Flow contains Load Inputs, main steps with branches, Edge Cases & Errors |
 
 Show the user how to invoke: `/{name}`.
@@ -148,14 +148,15 @@ Tell the user the iteration loop:
 3. Decide whether to update SKILL.md, add a `references/` file, add a knowledge entry, or split into a new skill.
 4. Re-run `/mvt-create-skill` to refine, or edit the source files directly and rebuild.
 
-### 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
 
 | Case | Handling |
 |------|----------|
 | Skill name collides with an existing registry entry | STOP at Step 3; ask user to rename; do not generate any file |
-| User wants the skill to mutate `session.yaml` fields beyond `skill_history` | Surface that ownership rules forbid this (e.g., `recent_changes` is owned by `/mvt-plan-dev`/`/mvt-update-plan`); recommend redesign |
+| User wants the skill to mutate `session.yaml` fields beyond `history` | Surface that ownership rules forbid this (e.g., `changes` is owned by `/mvt-plan-dev`/`/mvt-update-plan`); recommend redesign |
 | Output template is requested but the skill is conversation-only (no persisted file) | Refuse to create a template; explain that templates are for document structure, not conversation replies |
 | User asks to skip the registry registration step | Refuse; an unregistered skill is invisible to `/mvt-help`, `/mvt-status`, and `/mvt-resume`. Registration is non-negotiable |
 | Skill duplicates an existing skill's responsibility | Surface the overlap (cite the existing skill's description); propose merging or sub-classing as a variant rather than creating a duplicate |
@@ -225,7 +226,7 @@ Copy the following sections verbatim from this document (the assembled SKILL.md
 | Load Config | Load Config step within Activation Protocol | Copy as-is |
 | Output Language Constraint | Output Language Constraint step within Activation Protocol | Copy as-is |
 | Pre-flight Checks | Pre-flight Checks step within Activation Protocol | Replace `checks` table with skill-specific checks; if none required, use a single INFO row |
-| State Update | `## State Update (Required)` | Replace `/{name}` with the new skill's command; include `active_change` conditional block only if the skill creates changes; include `Shortcut Operation Rules` only if category is `shortcut` |
+| State Update | `## State Update` | Replace `/{name}` with the new skill's command; include `active_change` conditional block only if the skill creates changes; include `Shortcut Operation Rules` only if category is `shortcut` |
 | Suggested Next Steps | `## Suggested Next Steps` | Replace `current_skill` with the new skill name; replace conditional suggestions with skill-appropriate ones |
 
 **Important**: Do NOT paraphrase or rewrite the standard sections. Copy them character-for-character from this document and only substitute the skill-specific values. This ensures consistency across all MVTT skills.

package/sources/skills/mvt-create-skill/manifest.yaml

@@ -27,16 +27,16 @@ sections:
         - rule: "Skill needs bundled resources -> Plan scripts/references/assets in Step 3"
         - rule: "Usage patterns unclear -> Ask for concrete examples before proceeding"
       boundaries:
-        - scope: "Generated skills must follow MVTT SKILL.md standard structure"
-          skill: "(constraint)"
-        - scope: "Skill names may use `mvt-` prefix or a project-specific prefix (e.g., `app-`, `proj-`)"
-          skill: "(constraint)"
-        - scope: "All custom skills MUST be registered in `registry.yaml` with `custom: true`"
-          skill: "(to prevent overwrite during framework updates)"
-        - scope: "Description field must use third-person with effective trigger keywords"
-          skill: "(constraint)"
-        - scope: "SKILL.md body target <5k words; move detailed content to references/"
-          skill: "(progressive disclosure)"
+        - scope: "generate skills that deviate from MVTT SKILL.md standard structure"
+          skill: "the standard structure as documented"
+        - scope: "use arbitrary prefixes without validating naming conventions"
+          skill: "`mvt-` or a project-specific prefix like `app-`, `proj-`"
+        - scope: "create skills without registering in registry.yaml"
+          skill: "`custom: true` in registry.yaml"
+        - scope: "write vague or first-person descriptions"
+          skill: "third-person with effective trigger keywords"
+        - scope: "exceed ~5k words in SKILL.md body"
+          skill: "references/ for detailed content"
 
   - type: shared
     source: sections/activation-load-context.md
@@ -52,7 +52,7 @@ sections:
 
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -85,7 +85,23 @@ sections:
       4. Use `/mvt-create-skill` to refine, or edit skill files directly
       ```
 
+  - type: shared
+    source: sections/session-update.md
+    params:
+      current_skill: mvt-create-skill
+
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-create-skill
+      conditional_suggestions:
+        conditions:
+          - condition: "skill created successfully"
+            primary: mvt-help
+            primary_desc: "Verify the new skill appears in the catalog"
+          - condition: "skill needs knowledge entries"
+            primary: mvt-manage-context
+            primary_desc: "Add knowledge files for the new skill"
+          - condition: "skill needs testing with real tasks"
+            primary: mvt-status
+            primary_desc: "Check project state before testing the skill"

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

@@ -82,8 +82,7 @@
 - **Confirmation format**: present a one-screen summary -- style chosen, modules added/changed, ADRs requiring review, a single yes/no prompt. Do not dump the full artifact.
 
 ### Step 8: Write Artifact
-- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/design.md`.
-- **Template**: `.ai-agents/skills/_templates/design-output.md`; if `_templates/custom/design-output.md` exists, use the custom version.
+- **Path and template**: as defined in the **Artifact Structure** section below.
 - **Required sections** (filled per template headings, but content must include):
   - `Overview` -- the problem statement (Step 2).
   - `Architecture Decision Records` -- every ADR from Step 6.
@@ -99,10 +98,8 @@
 - If `Change Tracking` lists more than ~5 files OR Module Design adds more than 1 new module OR ADRs include any breaking change, recommend `/mvt-plan-dev` as the next step.
 - Otherwise recommend `/mvt-implement` directly.
 
-### Step 10: (session update handled by shared section)
-
-## Variants
-- `/mvt-design --plan` flag: skip Step 5 (data flow detail) and Step 6 (full ADR fields). In `--plan` mode, ADRs collapse to a one-line `decision: <text>`. Step 8 still writes `design.md` but with the abbreviated content. The output is a high-level plan, not an implementation-ready blueprint -- mark the artifact with a top-line `Mode: plan` indicator.
+### Step 10: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
 

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

@@ -41,7 +41,7 @@ sections:
       | Variant | Description |
       |---------|-------------|
       | `/mvt-design` | Full architecture design |
-      | `/mvt-design --plan` | High-level implementation plan only |
+      | `/mvt-design --plan` | High-level implementation plan only: skip Step 5 (data flow detail) and Step 6 (full ADR fields). ADRs collapse to one-line `decision: <text>`. Step 8 writes `design.md` with abbreviated content and a top-line `Mode: plan` indicator. If the request is actually small (1 file), downgrade to a 5-line summary in chat and do NOT write `design.md`. |
 
   - type: shared
     source: sections/activation-load-context.md
@@ -89,8 +89,21 @@ sections:
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-design
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-design
+      conditional_suggestions:
+        conditions:
+          - condition: "design complete, change tracking lists >5 files or >1 new module"
+            primary: mvt-plan-dev
+            primary_desc: "Create a structured implementation plan"
+          - condition: "design complete, small scope"
+            primary: mvt-implement
+            primary_desc: "Implement the designed architecture"
+          - condition: "design has proposed ADRs needing stakeholder review"
+            primary: mvt-review
+            primary_desc: "Review the design decisions"

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

@@ -118,7 +118,8 @@
   - `Regression risk` -- scope of behavior potentially affected, plus what tests guard it.
   - `Follow-ups` -- TODOs, deferred refactors, related issues.
 
-### Step 9: (session update handled by shared section)
+### Step 9: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
 

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

@@ -58,15 +58,18 @@ sections:
 
   - 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)
+      ## Operation Mode: Shortcut
+
+      This skill operates as a shortcut — it can execute at any time without checking workflow prerequisites.
+      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase).
 
   - type: file
     source: ./business.md
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-fix
 
   - type: shared
     source: sections/footer-next-steps.md

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

@@ -13,7 +13,7 @@
   |-----------|---------------|
   | `session.yaml` missing or `initialized_at` empty | `/mvt-init` -- Initialize the project |
   | Initialized AND `project-context.md` does not exist | `/mvt-analyze-code` -- Analyze existing code |
-  | No requirements (no `analysis.md` for active change AND no completed `/mvt-analyze` in `skill_history`) | `/mvt-analyze` -- Analyze requirements |
+  | No requirements (no `analysis.md` for active change AND no completed `/mvt-analyze` in `history`) | `/mvt-analyze` -- Analyze requirements |
   | No requirements, but user describes a simple change directly | `/mvt-quick-dev` -- Implement a simple change quickly |
   | Requirements present, no `design.md` | `/mvt-design` -- Design architecture |
   | `design.md` exists, change is large (Change Tracking lists > 5 files OR ADR includes breaking change OR > 1 new module) | `/mvt-plan-dev` -- Decompose into tracked plan |
@@ -60,15 +60,13 @@ Color-code based on current progress: green (done), yellow (current/recommended)
   | "Compare `/mvt-X` and `/mvt-Y`" | Pull descriptions from registry; if both are workflow skills, mention their relative position in the diagram |
   | Asks about something not in registry | Reply: "No skill matches that. Available skills: see catalog above." Do not invent skills |
 
-### Step 6: (session update handled by shared section)
-
 ## Edge Cases & Errors
 
 | Case | Handling |
 |------|----------|
 | `registry.yaml` missing | STOP at Step 1; recommend `mvtt install`; show no catalog |
 | `session.yaml` missing | Render catalog (Step 3) and diagram (Step 4) without the "current position" highlight; Step 2 recommends `/mvt-init` |
-| `recent_changes[]` references a `plan_path` that no longer exists | Ignore for help purposes; do not warn -- `/mvt-status` is the right place for that |
+| `changes[]` references a `plan_path` that no longer exists | Ignore for help purposes; do not warn -- `/mvt-status` is the right place for that |
 | User invokes `/mvt-help` while inside an active change with Critical review findings | Step 2's recommendation is `/mvt-fix`; surface this prominently above the catalog |
 | User asks about a custom skill (registry entry with `custom: true`) | Treat identically to built-ins; the only difference is showing `custom: true` in the metadata view |
 | Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> design -> [plan-dev] -> implement -> review -> test` |

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

@@ -24,12 +24,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -46,7 +43,7 @@ sections:
 
       ### Current Status
       - **Project**: {name} ({initialized/not initialized})
-      - **Last Skill**: {last command from skill_history}
+      - **Last Skill**: {last command from history}
       - **Recommended Next**: `/mvt-{next}` -- {description}
 
       ### Workflow
@@ -65,3 +62,14 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-help
+      conditional_suggestions:
+        conditions:
+          - condition: "project not initialized"
+            primary: mvt-init
+            primary_desc: "Initialize the project"
+          - condition: "project initialized, no active change"
+            primary: mvt-analyze
+            primary_desc: "Start analyzing requirements for a new feature"
+          - condition: "active change in progress"
+            primary: mvt-resume
+            primary_desc: "Resume work on the active change"

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

@@ -59,8 +59,7 @@
   3. UI/frontend changes: per project rules, ask user to verify in browser; do NOT claim "tested" if you only ran type-check.
 
 ### Step 7: Write Artifact
-- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/implementation.md`.
-- **Template**: `.ai-agents/skills/_templates/implement-output.md` (custom override at `_templates/custom/...` takes precedence).
+- **Path and template**: as defined in the **Artifact Structure** section below.
 - **Required content** (mapped to template headings):
   - `Implementation Summary` -- one paragraph: what was built, scope.
   - `Files Touched` -- table: path | create/modify/delete | one-line intent.
@@ -73,10 +72,10 @@
 ### Step 8: Plan-Aware Progress Hint (if applicable)
 - If `plan.yaml` exists and a single `current_task` covers this implementation, suggest the user run `/mvt-update-plan <task-id> done` (or `blocked` with reason).
 - Do NOT modify `plan.yaml` directly from this skill; it is owned by `/mvt-update-plan`.
-- Do NOT modify `recent_changes` directly; it is owned by `/mvt-plan-dev` / `/mvt-update-plan`.
+- Do NOT modify `changes` directly; it is owned by `/mvt-plan-dev` / `/mvt-update-plan`.
 
-### Step 9: (session update handled by shared section)
-- Standard `skill_history` entry must include `change_id`. All other state mutations are delegated.
+### Step 9: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
 

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

@@ -73,8 +73,21 @@ sections:
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-implement
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-implement
+      conditional_suggestions:
+        conditions:
+          - condition: "implementation complete, no tests written yet"
+            primary: mvt-test
+            primary_desc: "Generate tests for the implementation"
+          - condition: "implementation deviates from design"
+            primary: mvt-review
+            primary_desc: "Review code for design compliance"
+          - condition: "plan exists with remaining tasks"
+            primary: mvt-update-plan
+            primary_desc: "Mark current task done and advance to next"

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

@@ -126,7 +126,7 @@ For each target file, check if it already exists:
 After writing all files, validate:
 - `project-context.yaml` is valid YAML with `projects[]` containing at least one entry
 - Each project entry has required fields: `name`, `path`, `type`, `tech_stack.primary_language`
-- `session.yaml` is structurally intact and contains: `session`, `active_change` (with `plan_path` / `has_plan`), `recent_changes` (array), `skill_history`, `recent_actions`
+- `session.yaml` is structurally intact and contains: `session` (with `initialized_at`, `last_synced_at`), `active_change` (with `plan_path`), `changes` (array), `history`
 
 If any validation fails → report the specific error and offer to retry or skip.
 
@@ -135,7 +135,7 @@ If any validation fails → report the specific error and offer to retry or skip
 When `--refresh` is specified:
 
 1. **Preserve** the following from existing files:
-   - `session.yaml` > `skill_history` and `recent_actions`
+   - `session.yaml` > `history`
    - `project-context.yaml` > any user-added custom fields (fields not in the standard schema)
    - `config.yaml` > `preferences` section
 

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

@@ -75,6 +75,7 @@ sections:
   - type: shared
     source: sections/session-update.md
     params:
+      current_skill: mvt-init
       update_initialized_at: true
 
   - type: shared

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

@@ -173,3 +173,14 @@ At the bottom of the list, optionally surface:
 - **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.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| File path points outside `.ai-agents/knowledge/` | Reject with error: knowledge files must reside under the managed directory tree |
+| `registry.yaml` or `core/manifest.yaml` is malformed (parse error) | Abort the operation; print the parse error; suggest manual fix or restore from `.ai-agents/.backup/` |
+| User attempts to `remove` a core framework file (`core/_framework/*`) | Refuse: framework files are read-only and managed by the installer |
+| `add` target file already exists on disk but has no registry entry | Offer "register existing / overwrite / cancel" instead of blindly writing |
+| `move` destination binding already has an entry with the same id | Prompt for rename or cancel; do not silently overwrite |
+| Disk write fails mid-operation (permission denied, disk full) | Roll back all registry/manifest changes using the backup copies; report partial failure |

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

@@ -34,8 +34,8 @@ sections:
           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)"
+        - scope: "edit framework knowledge under core/_framework/ (framework files are read-only)"
+          skill: "(constraint)"
 
   - type: shared
     source: sections/activation-load-context.md
@@ -48,7 +48,7 @@ sections:
 
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -121,3 +121,14 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-manage-context
+      conditional_suggestions:
+        conditions:
+          - condition: "knowledge added or moved"
+            primary: mvt-check-context
+            primary_desc: "Verify context health after the change"
+          - condition: "knowledge removed"
+            primary: mvt-check-context
+            primary_desc: "Confirm token savings"
+          - condition: "large knowledge files detected"
+            primary: mvt-cleanup
+            primary_desc: "Clean up workspace to reduce context load"

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_"—"} |
+| ... |
+
+```