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

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

@@ -10,9 +10,9 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
 
 **In scope (user-actionable):**
 - Index: `.ai-agents/workspace/project-context.yaml`.
-- Semantic context: `.ai-agents/knowledge/project/_generated/project-context.md`.
-- Shared knowledge: every entry in `registry.yaml > knowledge.shared`. For the `core` entry, scan only files marked as user-origin per `core/manifest.yaml` (or whose path begins with `user/`); skip files under `core/_framework/`.
-- Per-skill knowledge: every entry in `registry.yaml > skills.*.knowledge`, grouped by skill.
+- Semantic context: `.ai-agents/knowledge/project/_generated/project-context.md` (always the flat path, regardless of project count).
+- Shared knowledge: every entry in `registry.yaml > knowledge._all` and `knowledge.{projectName}` (map-aware -- traverse ALL project keys in the knowledge map). For the `core` entry, scan only files marked as user-origin per `core/manifest.yaml` (or whose path begins with `user/`); skip files under `core/_framework/`.
+- Per-skill knowledge: every entry in `registry.yaml > skills.*.knowledge._all` and `skills.*.knowledge.{projectName}` (map-aware -- traverse ALL project keys for each skill), grouped by skill.
 - Artifacts: all files under `.ai-agents/workspace/artifacts/` recursively. **Exclude the `_archived/` subdirectory** — it contains completed changes archived by `/mvt-cleanup` and should not count toward the active workspace token budget.
 
 **Out of scope (do NOT scan):**
@@ -21,13 +21,19 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
 - `.ai-agents/config.yaml`, `.ai-agents/workspace/session.yaml`, `.ai-agents/registry.yaml` -- small, required, and addressed via `/mvt-config` or `/mvt-manage-context`, not here.
 
 ### Step 3: Estimate Token Consumption
-- **What**: produce a per-file tokens estimate and per-category subtotals.
+- **What**: produce a per-file tokens estimate and per-category subtotals, with **per-project breakdown**.
 - **How**:
   1. For each in-scope file: tokens ~= `characters / 4`.
   2. Group by category: `Index`, `Semantic Context`, `Shared Knowledge`, `Per-Skill Knowledge`, `Artifacts`.
   3. For Shared Knowledge, compute total once -- this is per-skill overhead (loaded by every skill invocation).
   4. For Per-Skill Knowledge, compute totals per skill so users can see which skill is heaviest.
   5. Identify the Top 5 largest single files across the whole in-scope set.
+  6. **Per-project breakdown**: for multi-project workspaces, also compute token costs per project:
+     - `knowledge._all` = shared across all projects
+     - `knowledge.{projectName}` = project-specific overhead
+     - `skills.*.knowledge.{projectName}` = per-skill per-project overhead
+     Display as a separate table: `project | knowledge tokens | per-skill tokens | total`.
+  7. **Global summary**: total tokens across all projects + `_all` overhead loaded every time.
 
 ### Step 4: Apply Thresholds and Health Status
 - **What**: assign each file/category a status of `healthy | borderline | oversized`.
@@ -70,8 +76,9 @@ This skill measures only files the **user** can reduce or relocate. Framework-fi
   2. **Per-Category Breakdown** -- table: `category | files | tokens | status`.
   3. **Top 5 Largest Files** -- table: `path | tokens | category | status`.
   4. **Per-Skill Knowledge Cost** -- table: `skill | tokens` (sorted desc); include shared knowledge as a separate row labeled `(shared, loaded every time)`.
-  5. **Recommendations** -- numbered list from Step 5; if empty, render the healthy line.
-  6. **Excluded Scope Note** -- one paragraph reminding the user that framework files (`_framework/`, `mvt-*/SKILL.md`, `config.yaml`, `session.yaml`, `registry.yaml`) were not measured here.
+  5. **Per-Project Token Accounting** -- table: `project | knowledge tokens | per-skill tokens | total` (only for multi-project workspaces; for single-project, omit this section).
+  6. **Recommendations** -- numbered list from Step 5; if empty, render the healthy line.
+  7. **Excluded Scope Note** -- one paragraph reminding the user that framework files (`_framework/`, `mvt-*/SKILL.md`, `config.yaml`, `session.yaml`, `registry.yaml`) were not measured here.
 - The report is conversation output; this skill does NOT write any artifact.
 
 ## Edge Cases & Errors

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

@@ -40,11 +40,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
-
   - type: file
     source: ./business.md
 

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

@@ -7,7 +7,7 @@
 
 For each `changes[]` entry with `status: done`:
 1. Compare `session.last_synced_at` with the change's `updated_at`.
-2. If `last_synced_at` is empty OR `last_synced_at` < `updated_at`, mark the change as **⚠️ unsynced**.
+2. If `last_synced_at` is empty OR `last_synced_at` < `updated_at`, mark the change as **WARNING: unsynced**.
 3. Collect all unsynced change-ids into a warning list for display in Step 6.
 
 This check ensures `/mvt-sync-context` has processed a change's knowledge before cleanup archives it. Once archived, the original artifact files (`analysis.md`, `design.md`, `implementation.md`) are no longer accessible to sync-context.
@@ -31,6 +31,8 @@ This check ensures `/mvt-sync-context` has processed a change's knowledge before
   | Source | Rule | Proposed action |
   |--------|------|-----------------|
   | `changes[]` entry with `status: done` AND any task in plan is older than the active change's start | Summarize: generate a `summary.md` from the change's artifacts, then move the **entire** `artifacts/{id}/` directory (including `summary.md`) to `artifacts/_archived/{id}/` |
+  | `changes[]` entry with `status: done` AND `epic_id` non-empty AND parent epic status is NOT `done` | **Epic integrity warning**: mark the candidate as `epic-unsafe` -- archiving a sub-change whose parent epic is still in-progress may leave the epic in an inconsistent state. Default to `n` (skip) in the cleanup plan. User may override to force-archive. |
+  | Artifact directory under `artifacts/` whose id starts with `epic-` AND contains `epic.yaml` with `status: done` | **Batch archive candidate**: mark for batch suggestion in Step 7 -- read `epic.yaml.children[]` for child change-ids to offer as batch archive options alongside the epic |
   | Change-id directory marked `unindexed` | List for user review (do NOT auto-archive -- could be in-flight work the user just hasn't registered) |
   | `history` entries beyond the most recent N (from `config.yaml > preferences.history_limits.history`, default 20) | Truncate via `session-update.cjs --truncate-history <N>` |
   | Directory `knowledge/patterns/` exists | Flag for deletion (legacy pattern data; no replacement) |
@@ -55,7 +57,7 @@ This check ensures `/mvt-sync-context` has processed a change's knowledge before
   - `summarize` action (collapses multi-file content).
   - `archive` action (moves entire change-id directory into `artifacts/_archived/`).
 - If the Step 2 warning list is non-empty, prepend it to the confirmation prompt:
-  > ⚠️ The following changes have NOT been synced by `/mvt-sync-context`. Archiving them will permanently lose their knowledge for aggregation:
+  > WARNING: The following changes have NOT been synced by `/mvt-sync-context`. Archiving them will permanently lose their knowledge for aggregation:
   > - {change-id}: {title}
   > Options: `y` = archive anyway, `n` = cancel, `sync-first` = abort and run `/mvt-sync-context` first, `show-details` = per-file breakdown.
 - If no unsynced warnings, use the standard prompt: `Apply cleanup plan? (y / n / show-details)`. `show-details` prints the per-file actions, then re-asks.
@@ -67,6 +69,16 @@ This check ensures `/mvt-sync-context` has processed a change's knowledge before
 - **How**:
   1. **Summarize action**: read the full set of files in the change-id directory; produce a `summary.md` with: title, change-id, status, key decisions (list each ADR/decision title), final outcomes, list of original files. Write `summary.md` into the change-id directory, then move the **entire** `artifacts/{id}/` directory to `artifacts/_archived/{id}/` (summary.md travels with it).
   2. **Archive action** (no summarize): move the **entire** `artifacts/{id}/` directory to `artifacts/_archived/{id}/`. No internal path restructuring needed.
+  2a. **Batch archive action** (epic with children): when archiving a completed epic (the change-id is an epic directory containing `epic.yaml` with `status: done`), read `epic.yaml.children` and present the user with three options before proceeding:
+
+       | Option | Description |
+       |--------|-------------|
+       | Epic only | Archive only the epic directory (leave child change directories in place) |
+       | All children | Archive the epic directory AND move all child change directories (`artifacts/{child_id}/`) to `artifacts/_archived/{child_id}/` |
+       | Selective | User picks which children to include alongside the epic |
+
+     Per ADR-8: archive = abandon references; no post-archive `epic_id` integrity maintenance. Child changes that are also `status: done` are eligible for batch archiving; in-progress or pending children are excluded with a note.
+
   3. **Delete action**: remove only the items explicitly marked for deletion in the confirmed plan; never recurse beyond what was listed.
   4. **Stale history truncation**: call `session-update.cjs --truncate-history <N>` where N is from `config.yaml > preferences.history_limits.history` (default 20).
   5. All file mutations atomic where possible (write-temp + rename, copy-then-delete for moves).
@@ -104,3 +116,6 @@ Apply the State Update rules defined in the **State Update** section below.
 | File targeted for action no longer exists (concurrent removal) | Skip with a note; do not error out the whole run |
 | Unindexed change-id directory contains only `plan.yaml` | List as review-only; suggest user runs `/mvt-update-plan` or registers it via `/mvt-plan-dev` instead of cleaning |
 | `session.yaml.bak` present from a previous failed run | Overwrite during Step 7 collapse (only the most recent backup is useful) |
+| Change with `epic_id` is a cleanup candidate but parent epic is still `in_progress` | Mark as `epic-unsafe`; default to skip. User may override to force-archive. Warn: "This change belongs to in-progress epic '{title}'. Archiving it separately may leave the epic in an inconsistent state." |
+| Epic directory marked for batch archive but `epic.yaml` is missing or unreadable | Skip batch suggestion; treat as a regular archive candidate |
+| Batch archive includes a child that is still `in_progress` | Exclude that child from the batch with a note: "Child {id} is in_progress and cannot be archived." |

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

@@ -54,6 +54,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:

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

@@ -38,10 +38,10 @@
 
    | Type | Validation |
    |------|------------|
-   | `enum` | Value MUST be in the allowed list. Reject with the allowed list shown. For `language` enums (`en-US`, `zh-CN`), reject other locale strings -- ask user to pick from the allowed list (do not fuzzy-match) |
+   | `enum` | Value MUST be in the allowed list. Reject with the allowed list shown. For `language` enums (`en-US` = English, `zh-CN` = 简体中文), reject other locale strings -- ask user to pick from the allowed list (do not fuzzy-match) |
    | `bool` | Accept exactly `true` / `false` (case-insensitive). Reject `yes`/`1`/`y` |
    | `int` | Parse as integer; check range when range is documented (e.g., `relevance_threshold` must be 0-100) |
-   | `list` | Parse as comma-separated tokens; for `knowledge.shared`, every token must be a registered knowledge id |
+   | `list` | Parse as comma-separated tokens; for knowledge map entries (`_all` and project keys), every token must be a registered knowledge id |
 
 3. **Preview**: render `key: <current> -> <new>` on a single line.
 4. **Confirm**: prompt `Apply this change? (y/n)`. Skip the prompt only if invocation included an explicit non-interactive flag (none currently exists, so always prompt).
@@ -72,10 +72,10 @@
 4. Backup current `config.yaml` to `config.yaml.bak` before writing.
 5. Write defaults atomically.
 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.
+- Do NOT reset knowledge map entries (`_all`, project keys) 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.
 
 ## 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.
+- **View**: list global knowledge ids from `registry.yaml > knowledge._all` and project-specific ids from `knowledge.{projectName}`, 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.
 
 ## Edge Cases & Errors
@@ -89,5 +89,5 @@
 | User aborts mid-wizard | No partial write; the temp values are discarded |
 | `.bak` from previous reset already exists | Overwrite (only the most recent backup is useful) |
 | Concurrent edit detected (mtime changed during preview->write) | Abort write, surface a message, ask user to re-run |
-| `set knowledge.shared <list>` includes unknown id | Reject with the list of valid ids from `registry.yaml` |
+| `set knowledge._all <list>` (or project key) includes unknown id | Reject with the list of valid ids from `registry.yaml` |
 | `reset` invoked but `config.yaml` already matches defaults | Report "nothing to reset", do not write |

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

@@ -58,17 +58,14 @@ sections:
 
   - type: inline
     content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required (config is always accessible)
-
       ## Configuration Keys
 
       ### User Preferences
 
       | Key | Type | Default | Description |
       |-----|------|---------|-------------|
-      | `preferences.interaction_language` | enum | `en-US` | Language for interactive output: chat replies, prompts, tables (en-US, zh-CN) |
-      | `preferences.document_output_language` | enum | `en-US` | Language for persisted documents: artifacts, project-context.md (falls back to interaction_language) |
+      | `preferences.interaction_language` | enum | `en-US` | Language for interactive output: chat replies, prompts, tables. Values: `en-US` (English), `zh-CN` (简体中文) |
+      | `preferences.document_output_language` | enum | `en-US` | Language for persisted documents: artifacts, project-context.md (falls back to interaction_language). Values: `en-US` (English), `zh-CN` (简体中文) |
       | `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) |
@@ -79,7 +76,7 @@ sections:
 
       | Key | Type | Default | Description |
       |-----|------|---------|-------------|
-      | `knowledge.shared` | list | `[core, project-context]` | Shared knowledge entries in registry.yaml, loaded by all skills |
+      | `knowledge._all` | list | `[core, project-context]` | Global knowledge entries in registry.yaml under `_all` key, loaded by all skills across all projects |
 
   - type: file
     source: ./business.md

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

@@ -50,7 +50,6 @@ Collect core metadata. Each field has an explicit constraint -- do not accept va
 | Purpose | One sentence | Will become the SKILL.md `## Purpose` section |
 | Category | One of: `workflow`, `shortcut`, `project`, `utility` | Drives how `/mvt-help` groups it |
 | Description | Third-person, includes what + when + how it differs | Will become the frontmatter `description` |
-| Dependencies | List of skill names that must run first, OR `none` | Becomes `depends_on` in registry |
 | Variants (optional) | List of flag/sub-mode entries | Becomes the Variants table |
 
 If the user is unsure on any field, propose a default and ask for confirmation rather than leaving it blank.
@@ -68,7 +67,7 @@ If the user is unsure on any field, propose a default and ask for confirmation r
   | Output template | `_templates/` | Persisted document that needs a stable structure | `_templates/{name}-output.md` |
 
 - **Reuse vs new**: before declaring a new shared resource, check existing skills' SKILL.md files and knowledge entries -- prefer reusing patterns that already exist.
-- **Output of this step**: a checklist `(name | category | purpose | path)` shown to user.
+- **Output of this step**: a checklist `(name | purpose | path)` shown to user.
 
 ### Step 5: Design the Skill
 - **What**: produce a one-page outline before generating any file.
@@ -105,22 +104,11 @@ Append the skill entry to `.ai-agents/registry.yaml` > `skills` section:
 
 ```yaml
   {name}:
-    agent: {agent}
     description: "{third-person description with trigger keywords}"
-    path: .claude/skills/{name}/SKILL.md
-    template: {template_path_or_null}
-    category: {category}
-    depends_on: {dependencies_or_omitted}
     custom: true
-    knowledge:
-      {entries_or_empty_list}
-    next_suggestions:
-      primary: {suggested_next_skill}
-      primary_desc: "{when to use the next skill}"
 ```
 
 - The `custom: true` field is **required** for user-created skills; without it, framework updates will overwrite the entry.
-- If the skill has no specific knowledge needs, set `knowledge: []` or omit the key entirely.
 - Validate the YAML still parses after the append; if not, abort and surface the parse error.
 
 ### Step 8: Validation
@@ -226,7 +214,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` | 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` if the user opted for shortcut semantics during Step 5 design |
 | 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

@@ -50,10 +50,8 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
+  - type: shared
+    source: sections/output-format-constraint.md
 
   - type: file
     source: ./business.md

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

@@ -0,0 +1,94 @@
+## Execution Flow
+
+### Step 1: Load Requirements
+- If file path provided as argument -> Read that file
+- Otherwise -> Use requirements text from user message
+
+### Step 2: Lightweight Sanity Gate
+- **What**: verify the input warrants epic-scale decomposition
+- **How**: check whether the input is clearly a single-file or single-module change
+
+  | Signal | Verdict |
+  |--------|---------|
+  | Input describes 1 feature touching 1-3 files | Too small for epic |
+  | Input describes a cohesive system with 2+ independent capability domains | Epic-scale |
+  | Ambiguous | Ask user: decompose or redirect to `/mvt-analyze`? |
+
+- **Branches**:
+
+  | Condition | Action |
+  |-----------|--------|
+  | Clearly epic-scale | Continue to Step 3 |
+  | Clearly too small | Suggest: "This looks like a standard change. Use `/mvt-analyze` instead? (y/n)" |
+  | Ambiguous | Offer choice: "Decompose as epic (2-8 children) or analyze as single change?" |
+
+### Step 3: Epic Analysis
+- Extract the **vision**: one-sentence summary of the overall goal
+- Define **scope and out-of-scope**: what the epic delivers vs. explicitly excludes
+- Identify **cross-cutting concerns**: themes spanning multiple children (auth, logging, error handling, data migration)
+- Identify **actors and stakeholders**
+
+### Step 4: Decompose into 2-8 Sub-changes
+- **What**: break the epic into right-sized children, each suitable for one analyze-design-plan-implement cycle
+- **Sizing rule**: each child should produce one deliverable capability slice, implementable in 3-10 plan tasks
+- **For each child**, define:
+  - `change_id`: `{YYYYMMDD}-{slug}` format. Slug constraints: lowercase ASCII, kebab-case, `[a-z0-9-]+`, 1-4 words (e.g., `user-auth`, `catalog-search`)
+  - `title`: concise name
+  - `scope`: description of what this child delivers
+  - `depends_on`: list of `change_id` values this child depends on (empty for root children)
+  - `project`: project hint array. For single-project workspaces: use the sole project name from `project-context.yaml > projects[].name` (e.g., `["mvtt"]` in this workspace; do NOT hardcode `["default"]`). For multi-project workspaces: must match a project name from `project-context.yaml > projects[].name`; if uncertain, ask the user rather than guessing.
+- **DAG constraints**:
+  - Dependencies must form a DAG (no cycles)
+  - Dependencies reference existing `change_id` values only
+  - Prefer shallow depth (wide parallelism) over deep chains
+- **Validation**: if > 8 children needed, WARN and suggest narrowing the epic scope. If < 2 children, suggest using `/mvt-analyze` directly.
+
+### Step 5: Preview and Confirm
+- **What**: show the decomposition result to the user before writing any files.
+- **How**: display the following inline (conversation-only, no disk write yet):
+  1. **Child story table**: the same table that will appear in `epic.md`
+  2. **Dependency diagram**: Mermaid flowchart of child dependencies
+  3. **Suggested starting child**: "Start with: `{first_child_title}` (`{first_child_id}`)"
+- **Wait for user confirmation**: ask "Proceed with this decomposition? (y/n)". Default to **y** if the user does not respond.
+- **On decline or revision request**: do NOT write any files. Revise the decomposition based on user feedback and re-present, or abort if the user chooses to cancel.
+- **On confirmation**: proceed to Step 6.
+
+### Step 6: Write Artifacts
+Write two artifacts using the `decompose-output` template for `epic.md`:
+
+1. **epic.md** (narrative) -- `.ai-agents/workspace/artifacts/{epic_id}/epic.md`
+   - Uses the `decompose-output` template.
+   - **Child Stories**: Markdown table mirroring `epic.yaml.children[]`
+
+     | # | Child | Scope | Status | Depends On |
+     |---|-------|-------|--------|------------|
+
+   - **Dependency Map**: Mermaid flowchart showing child dependencies
+
+2. **epic.yaml** (structured) -- `.ai-agents/workspace/artifacts/{epic_id}/epic.yaml`
+   - Follows the schema defined in Artifact Structure
+   - Set first child `status: active`, all others `status: pending`
+   - Set `current_change` to the first child's `change_id`
+
+**Self-validation checklist** (verify before writing):
+- [ ] All `change_id` values are unique
+- [ ] All `depends_on` references exist in `children[]`
+- [ ] No cycles in the dependency graph
+- [ ] Exactly one child has `status: active`
+- [ ] `current_change` matches the active child's `change_id`
+- [ ] Each child has non-empty `title` and `scope`
+
+**Optional safety net**: after writing, call `epic-update.cjs --validate` to verify:
+```bash
+node .ai-agents/scripts/epic-update.cjs --validate .ai-agents/workspace/artifacts/{epic_id}/epic.yaml
+```
+
+### Step 7: Update Session
+Run the session update command (see State Update section) to:
+1. Create a new `active_epic` in session.yaml
+2. Set the `epic_path` to the written `epic.yaml`
+
+### Step 8: Output
+Display to the user:
+1. **Write confirmation**: "Epic created: `{epic_id}` at `{epic_path}`"
+2. **Suggested next step**: "Run `/mvt-analyze` to start the first child: `{first_child_title}` (`{first_child_id}`)"

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

@@ -0,0 +1,121 @@
+name: mvt-decompose
+output: .claude/skills/mvt-decompose/SKILL.md
+
+frontmatter:
+  name: mvt-decompose
+  description: "Decompose epic-scale requirements into right-sized sub-changes with DAG dependencies. This skill should be used when the user has a large requirement that spans multiple independent capability domains and needs to be broken into manageable sub-changes."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Decompose
+
+      ## Purpose
+
+      Decompose epic-scale requirements into 2-8 right-sized sub-changes with explicit DAG dependencies, producing `epic.yaml` (structured) and `epic.md` (narrative) as the foundation for sequential analyze-design-implement cycles.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Strategist
+      role_desc: "an Epic Decomposition Strategist"
+      decision_rules:
+        - rule: "Epic-scale input -> Decompose into 2-8 sub-changes with DAG"
+        - rule: "Input too small for epic -> Redirect to /mvt-analyze"
+        - rule: "> 8 children needed -> Warn and suggest scope narrowing"
+        - rule: "Ambiguous boundaries -> Ask user to clarify before decomposing"
+      boundaries:
+        - scope: "implement code"
+          skill: "/mvt-implement"
+        - scope: "design architecture"
+          skill: "/mvt-design"
+        - scope: "analyze non-epic requirements"
+          skill: "/mvt-analyze"
+
+  - 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: shared
+    source: sections/output-format-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: "projects[] in project-context.yaml"
+          level: "WARN"
+          message: 'Project not initialized. Run `/mvt-init` first.'
+        - order: "3"
+          field: "active_change.id"
+          level: "WARN"
+          message: 'An active change already exists. Decomposing will create a new epic alongside it. Continue? (y/n)'
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## Artifact Structure
+
+      **epic.md** (narrative):
+      Read the document structure template from: `.ai-agents/skills/_templates/decompose-output.md`
+      If a custom version exists at `.ai-agents/skills/_templates/custom/decompose-output.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on decomposition results.
+      Write to: `.ai-agents/workspace/artifacts/{epic_id}/epic.md`
+
+      **epic.yaml** (structured):
+      Write to: `.ai-agents/workspace/artifacts/{epic_id}/epic.yaml`
+      Schema:
+      ```yaml
+      version: 1
+      epic_id: "{epic_id}"
+      title: "{epic_title}"
+      created_at: "{ISO timestamp}"
+      updated_at: "{ISO timestamp}"
+      status: in_progress
+      vision: >
+        {epic vision summary}
+      current_change: "{first_active_child_id}"
+      children:
+        - change_id: "{YYYYMMDD}-{slug}"
+          title: "{child title}"
+          scope: >
+            {child scope description}
+          status: active       # first child: active, rest: pending
+          depends_on: []       # DAG dependencies
+          project: ["<project-name>"] # use the sole project name from project-context.yaml > projects[].name
+          completed_at: null
+      ```
+
+      **epic-id format**: `epic-{YYYYMMDD}-{slug}` (e.g., `epic-20260608-ecommerce-platform`)
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      current_skill: mvt-decompose
+      new_epic: true
+      set_epic_path: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-decompose
+      conditional_suggestions:
+        conditions:
+          - condition: "decomposition complete"
+            primary: "mvt-analyze"
+            primary_desc: "Start analyzing the first (active) sub-change"
+          - condition: "default"
+            primary: "mvt-analyze"
+            primary_desc: "Begin the analyze-design-implement cycle for the current child"

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

@@ -55,6 +55,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:

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

@@ -87,9 +87,24 @@
   | Multi-module | Touches >1 module or shared utility | List impacted modules, read each call site before editing, group by commit if possible |
   | Cross-architecture | Requires layering change, new dependency, or interface redesign | STOP -- recommend `/mvt-design` (or `/mvt-refactor` if behavior is preserved); do NOT implement here |
 
-- Identify regression risk: which existing tests cover this code? If none, decide whether to add a regression test in Step 7.
+- Identify regression risk: which existing tests cover this code? If none, decide whether to add a regression test in Step 8.
 
-### Step 6: User Confirmation
+### Step 6: Identify Project Scope and Load Project-Specific Knowledge
+
+This step applies only when the workspace has multiple projects (`projects.length > 1` in `project-context.yaml`). In single-project workspaces, all relevant knowledge was loaded at activation; skip this step entirely.
+
+- **Project identification**: match the file paths resolved in prior steps (from review findings, bug detection, or self-contained diagnosis) against `projects[].path` and `projects[].source_paths`:
+  - A file whose path starts with a project's `path` prefix belongs to that project.
+  - A file under a project's `source_paths` entry also belongs to that project.
+  - Collect the set of unique project names from all matched files. This is the **active project scope** for this invocation.
+- **On-demand knowledge loading**: for each project P in the active project scope, read `.ai-agents/registry.yaml` and load:
+  1. Every entry under `knowledge.{P}` -- load each entry's referenced files (resolve relative to `.ai-agents/{source}`).
+  2. Every entry under `skills.mvt-fix.knowledge.{P}` -- load each entry's referenced files.
+  3. Skip any key absent from the registry (no project-specific knowledge is valid; do not warn).
+- **Multi-project scenario**: if affected files span multiple projects, load each project's knowledge sequentially. The skill operates with the union of all loaded project-specific knowledge plus the `_all` knowledge already loaded at activation.
+- **Unmatched files**: if a file path does not match any project's `path` or `source_paths`, surface a note and treat it as belonging to the first project in `projects[]` (fallback). This may indicate a configuration gap in `project-context.yaml`.
+
+### Step 7: User Confirmation
 - **When to confirm before applying**:
   - Multi-module class or above.
   - The fix changes a public/exported symbol or a configuration default.
@@ -99,14 +114,14 @@
   - One-liner / single-file class AND fix is purely additive or correctional AND reproduction was verified.
 - **Confirmation prompt format**: present `Root cause: ...`, `Proposed change: <files + summary>`, `Risk: <regression scope>`, then ask `Apply? (y / n / show-diff)`.
 
-### Step 7: Apply the Fix
+### Step 8: Apply the Fix
 - For source 1a (review.md): apply fixes per finding; re-run the review's relevant checks (not reproduction) to confirm each fix addresses its finding.
 - Make the targeted code change.
 - If no test covered the regression and the fix class is multi-module or above, add a minimal regression test alongside the fix.
 - Re-run the original repro (if any) to confirm resolution.
 - If repro still fails -> revert, return to Step 3 with the new evidence.
 
-### Step 8: Write Fix Notes
+### Step 9: Write Fix Notes
 - **Path**: `.ai-agents/workspace/artifacts/{change-id}/fix-notes.md` if an `active_change` exists; otherwise inline in the conversation only (no artifact -- shortcut operation).
 - **Structure** (each section is a single paragraph or list):
   - `Symptom` -- what the user saw / reported.
@@ -118,7 +133,7 @@
   - `Regression risk` -- scope of behavior potentially affected, plus what tests guard it.
   - `Follow-ups` -- TODOs, deferred refactors, related issues.
 
-### Step 9: State Update
+### Step 10: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
@@ -128,6 +143,6 @@ Apply the State Update rules defined in the **State Update** section below.
 | Bug is intermittent / racy | Mark reproduction as "flaky", state confidence level explicitly, prefer adding instrumentation over speculative fix |
 | Fix would require breaking a downstream API | STOP -- escalate to `/mvt-design` or `/mvt-refactor`; do not silently break contracts |
 | Root cause is in a third-party dependency | Document the upstream issue, apply a minimal local workaround clearly labeled as temporary |
-| User aborts at Step 6 | Do not write fix notes; record the diagnosis as a comment in the conversation only |
+| User aborts at Step 7 | Do not write fix notes; record the diagnosis as a comment in the conversation only |
 | Fix relies on changes the user has uncommitted in another branch | Surface the conflict before editing; do not overwrite |
 | `active_change` is missing entirely | Apply fix without writing artifact (shortcut mode), summarize result in conversation |

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

@@ -47,6 +47,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -61,7 +64,7 @@ sections:
       ## 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).
+      - Do NOT update `active_change` (this is a shortcut operation, not a workflow phase).
 
   - type: file
     source: ./business.md

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

@@ -11,8 +11,9 @@
 
   | Condition | Recommendation |
   |-----------|---------------|
-  | `session.yaml` missing or `initialized_at` empty | `/mvt-init` -- Initialize the project |
+  | `.ai-agents/workspace/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 |
+  | `active_epic.id` non-empty AND `active_change.id` empty (epic-pending) | `/mvt-analyze` -- Start the next sub-change in the epic |
   | 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 |
@@ -25,14 +26,11 @@
 
 ### Step 3: Display Skills Catalog
 Read `registry.yaml` > `skills` section.
-Group skills by `category` field and display as tables:
-- `workflow` -> "Workflow Skills (sequential phases)"
-- `shortcut` -> "Shortcut Skills (anytime, no prerequisites)"
-- `project` -> "Project Management Skills"
-- `utility` -> "Utility Skills"
+Display all skills as a single flat table (no grouping; the section comment headers in `registry.yaml` already group them by role for human readers):
+- Header row: `Skill | Description`
 
 For each skill, show: `/{skill-name}` | `description` field from registry.
-Sort within each group by declaration order in registry.
+Sort by declaration order in registry.
 
 ### Step 4: Show Workflow Diagram
 Display the standard workflow with current position highlighted:
@@ -45,6 +43,9 @@ flowchart LR
     E --> F[review] --> G[test]
 
     C -.->|simple change| Q[quick-dev]
+    C -.->|epic scale| DC[decompose]
+    DC --> C2[analyze<br/>epic-child]
+    C2 --> D
 ```
 
 Color-code based on current progress: green (done), yellow (current/recommended), gray (pending). The "current" node is whichever skill the Step 2 table recommended; "done" is determined by the same evidence the Step 2 table consumed.
@@ -56,7 +57,7 @@ Color-code based on current progress: green (done), yellow (current/recommended)
   | Question pattern | Response |
   |------------------|----------|
   | "What should I do next?" / no specific question | Repeat the Step 2 recommendation in one line, followed by a one-clause reason citing the matched condition |
-  | "What does `/mvt-X` do?" / asks about a specific skill | Read the skill's metadata from `registry.yaml`, show: name, description, category, dependencies, knowledge entries (if any), template (if any). If the skill has a `path`, mention "see SKILL.md for the full procedure" -- do NOT inline the full SKILL.md content (too large) |
+  | "What does `/mvt-X` do?" / asks about a specific skill | Read the skill's metadata from `registry.yaml`, show: name, description, knowledge entries (if any), template (if any). Mention "see the skill's SKILL.md for the full procedure" -- do NOT inline the full SKILL.md content (too large) |
   | "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 |
 
@@ -69,4 +70,5 @@ Color-code based on current progress: green (done), yellow (current/recommended)
 | `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` |
+| Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> [decompose (epic) -> analyze (epic-child)] -> design -> [plan-dev] -> implement -> review -> test` |
+| Epic-pending state (`active_epic` non-empty, `active_change` empty) | Step 2's recommendation is `/mvt-analyze` to start the next sub-change; the decompose path is shown in the workflow diagram |

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

@@ -24,11 +24,6 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
-
   - type: file
     source: ./business.md