@uoyo/mvtt 2.0.0-beta.4 → 2.0.0

package/sources/skills/mvt-analyze-code/business.md

@@ -2,17 +2,15 @@
 
 ### Step 1: Determine Analysis Target
 
-Identify which project(s) to analyze:
+Identify which project(s) to analyze using interactive routing:
 
-| Variant | Target |
-|---------|--------|
-| `/mvt-analyze-code` | Analyze the first project in `project-context.yaml` (or the only one) |
-| `/mvt-analyze-code --all` | Analyze all projects listed in `project-context.yaml` |
-| `/mvt-analyze-code {name}` | Analyze the project matching the given name |
-
-For each target project:
-1. Read its `path` from `project-context.yaml`
-2. Use `path` as the source directory for analysis
+1. Read `project-context.yaml > projects[]` to get the list of registered projects.
+2. **Single project** (only one entry): automatically select it — no prompt needed.
+3. **Multiple projects**: present an interactive selection menu:
+   - List each project by `name` with its `path`
+   - Include an option to **analyze all projects**
+   - Wait for user selection before proceeding
+4. For each selected project, read its `path` and use it as the source directory for analysis.
 
 ### Step 2: Load Template
 
@@ -72,11 +70,14 @@ Identify public interfaces:
    - Fill each template section with analysis results
    - If a section has no relevant content, include the heading with "(No relevant content detected)"
 
-2. Write the output to `.ai-agents/knowledge/project/_generated/project-context.md`:
-   - If analyzing a single project, write that project's section
-   - If analyzing multiple projects (`--all`), write all sections separated by `---`
-   - If the file already exists, merge with existing content:
-     - Replace sections for re-analyzed projects
-     - Preserve sections for projects NOT in this analysis run
+2. Write the output to `.ai-agents/knowledge/project/_generated/project-context.md` (always the flat path, regardless of project count).
+   - **Single-project**: write the full document.
+   - **Multi-project**: use `# Project: {name}` as the top-level heading to separate each project's content sections within the single file.
+
+3. If the output file already exists:
+   - **Single-project**: replace the whole file.
+   - **Multi-project**: replace only the `# Project: {name}` section(s) for re-analyzed projects; preserve sections for projects NOT in this analysis run.
+
+4. **Populate `source_paths`** in `project-context.yaml`: after analyzing each project, update the matching project entry's `source_paths` array with the detected source directories (e.g., `["src/", "test/"]`). This overwrites the empty default set by `/mvt-init`.
 
-3. Do NOT update `project-context.yaml` -- it is the lean index, managed by `/mvt-init` and `/mvt-sync-context` only
+5. Do NOT update other fields in `project-context.yaml` -- only `source_paths` is touched by this skill.

package/sources/skills/mvt-analyze-code/manifest.yaml

@@ -37,13 +37,10 @@ sections:
 
   - type: inline
     content: |
-      ## Variants
+      ## Invocation
 
-      | Variant | Description |
-      |---------|-------------|
-      | `/mvt-analyze-code` | Analyze the first (or only) project |
-      | `/mvt-analyze-code --all` | Analyze all projects in the workspace |
-      | `/mvt-analyze-code {name}` | Analyze a specific project by name |
+      `/mvt-analyze-code` — single entry point, no arguments or flags.
+      When multiple projects exist, the skill interactively prompts the user to select the target(s).
 
   - type: shared
     source: sections/activation-load-context.md
@@ -57,7 +54,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md

package/sources/skills/mvt-bug-detect/manifest.yaml

@@ -44,6 +44,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - type: inline
     content: |
       ## Operation Mode: Shortcut

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,10 +40,8 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
+  - type: shared
+    source: sections/language-constraint.md
 
   - 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

@@ -52,7 +52,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md

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

@@ -56,19 +56,19 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/language-constraint.md
+
   - 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 +79,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
@@ -224,9 +212,9 @@ Copy the following sections verbatim from this document (the assembled SKILL.md
 |---------|----------------------|-----------------|
 | Activation Protocol | `## Activation Protocol` | Add `extended_context` entries if the skill needs additional context sources; otherwise copy as-is |
 | Load Config | Load Config step within Activation Protocol | Copy as-is |
-| Output Language Constraint | Output Language Constraint step within Activation Protocol | Copy as-is |
+| Language Constraint | 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

@@ -48,16 +48,11 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md
 
-  - type: inline
-    content: |
-      ### Step 4: Pre-flight Checks
-      - No blocking checks required.
-
   - 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/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

@@ -53,7 +53,7 @@ sections:
     source: sections/activation-load-config.md
 
   - type: shared
-    source: sections/output-language-constraint.md
+    source: sections/language-constraint.md
 
   - type: shared
     source: sections/output-format-constraint.md