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

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

@@ -1,91 +1,90 @@
-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
+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 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"
+      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
+    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

@@ -1,69 +1,84 @@
-name: mvt-quick-dev
-output: .claude/skills/mvt-quick-dev/SKILL.md
-
-frontmatter:
-  name: mvt-quick-dev
-  description: "Quickly implement simple, well-scoped changes without the full analyze-design-implement workflow. This skill should be used when the change is small (1-3 files), architecturally neutral, and clearly specified — such as adding a field, fixing a label, adjusting config, or making a targeted enhancement."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Quick Dev
-
-      ## Purpose
-
-      Implement simple, well-scoped changes quickly, bypassing the full workflow. For changes that are small (1-3 files), architecturally neutral, and clearly specified. Produces no artifacts — results are conversation-only.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Developer
-      role_desc: "an Implementation Specialist"
-      decision_rules:
-        - rule: "Change is Trivial (1 file, ≤10 lines) -> Implement directly, conversation-only"
-        - rule: "Change is Simple (1-3 files, no module break) -> Implement, show plan first, conversation-only"
-        - rule: "Change is Complex -> STOP, recommend /mvt-analyze or /mvt-design"
-        - rule: "Ambiguous scope -> Ask user to confirm before proceeding"
-        - rule: "Implementation reveals unexpected complexity -> Revert and escalate"
-        - rule: "Existing tests cover changed code -> Suggest running them"
-      boundaries:
-        - scope: "analyze complex requirements"
-          skill: "/mvt-analyze"
-        - scope: "design architecture"
-          skill: "/mvt-design"
-        - scope: "review code"
-          skill: "/mvt-review"
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - ".ai-agents/knowledge/project/_generated/project-context.md -- Module/layer map (optional)"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Coding standards (optional)"
-        - "Target source files (load based on change description)"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: shared
-    source: sections/output-language-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
-
-  - type: file
-    source: ./business.md
-
-  - type: shared
-    source: sections/session-update.md
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      current_skill: mvt-quick-dev
+name: mvt-quick-dev
+output: .claude/skills/mvt-quick-dev/SKILL.md
+
+frontmatter:
+  name: mvt-quick-dev
+  description: "Quickly implement simple, well-scoped changes without the full analyze-design-implement workflow. This skill should be used when the change is small (1-3 files), architecturally neutral, and clearly specified — such as adding a field, fixing a label, adjusting config, or making a targeted enhancement."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Quick Dev
+
+      ## Purpose
+
+      Implement simple, well-scoped changes quickly, bypassing the full workflow. For changes that are small (1-3 files), architecturally neutral, and clearly specified. Produces no artifacts — results are conversation-only.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Developer
+      role_desc: "an Implementation Specialist"
+      decision_rules:
+        - rule: "Change is Trivial (1 file, ≤10 lines) -> Implement directly, conversation-only"
+        - rule: "Change is Simple (1-3 files, no module break) -> Implement, show plan first, conversation-only"
+        - rule: "Change is Complex -> STOP, recommend /mvt-analyze or /mvt-design"
+        - rule: "Ambiguous scope -> Ask user to confirm before proceeding"
+        - rule: "Implementation reveals unexpected complexity -> Revert and escalate"
+        - rule: "Existing tests cover changed code -> Suggest running them"
+      boundaries:
+        - scope: "analyze complex requirements"
+          skill: "/mvt-analyze"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "review code"
+          skill: "/mvt-review"
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - ".ai-agents/knowledge/project/_generated/project-context.md -- Module/layer map (optional)"
+        - ".ai-agents/knowledge/principle/coding-standards.md -- Coding standards (optional)"
+        - "Target source files (load based on change description)"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - 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 (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