@uoyo/mvtt 2.0.0 → 2.2.0

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

@@ -1,57 +1,62 @@
 ## Execution Flow
 
+`/mvt-config` takes no arguments. Every invocation opens the Interactive Menu (Step 2); all actions -- viewing settings, editing a key, and guided setup -- are reached from there. There is no `set` / `show` / `wizard` / `reset` invocation form.
+
 ### Step 1: Load Inputs
+- **Required**:
+  - `.ai-agents/config.yaml` -- the configuration to inspect and edit.
 - **Recommended**:
-  - `.ai-agents/knowledge/core/manifest.yaml` -- only when computing token estimates for shared knowledge view.
+  - `.ai-agents/knowledge/core/manifest.yaml` -- only when computing token estimates for the shared knowledge view.
 - **Fallback**: if `config.yaml` is missing, surface the error and recommend `mvtt install` or `/mvt-init`. Do not silently create a fresh config from this skill.
 
-### Step 2: Dispatch by Mode
-- **What**: pick the operating mode from the user's invocation.
-- **How**:
-
-  | Invocation | Mode | Go to |
-  |------------|------|-------|
-  | `/mvt-config` (no args) | Interactive Menu | Step 3 |
-  | `/mvt-config show` | Show All | Step 4 |
-  | `/mvt-config set {key} {value}` | Direct Set | Step 5 |
-  | `/mvt-config wizard` | Guided Wizard | Step 6 |
-  | `/mvt-config reset` | Reset | Step 7 |
-  | Anything else | Refuse, print Variants table, stop | -- |
-
-### Step 3: Interactive Menu
-1. Read current `config.yaml` and render a numbered menu grouped by category (User Preferences, Knowledge Settings, etc.) with current values inline.
-2. Wait for user to select a category number (or `q` to quit).
-3. Show the category detail view: keys with current values, type, default, allowed values.
-4. Let user pick a key to edit; reuse Step 5 (Direct Set) sub-flow for validation, preview, confirmation, write.
-5. After write, return to the top-level menu until user quits.
-6. No write happens unless the Step 5 sub-flow confirms.
-
-### Step 4: Show All
+### Step 2: Interactive Menu (entry point)
+1. Read current `config.yaml`.
+2. Render the top-level menu with these actions:
+
+   | # | Action | Goes to |
+   |---|--------|---------|
+   | 1 | View all settings | Step 3 |
+   | 2 | Edit a setting | Step 4 |
+   | 3 | Guided setup (walk through common settings) | Step 5 |
+   | `q` | Quit | -- exit, no write |
+
+3. Wait for the user's selection. Re-render the menu after any action completes, until the user quits.
+4. On an unrecognized selection, re-print the menu and prompt again. Do not exit.
+5. No write happens unless the user confirms -- either in the Edit sub-flow (Step 4) or at the Guided-setup summary (Step 5).
+
+### Step 3: View All
 - Print every key with `current value | type | default`. Mark values that differ from default with a `*`.
-- Print the Configuration Keys reference table (provided in shared section above) below the values, for context.
-- No write.
+- Print the Configuration Keys reference table (provided in the shared section above) below the values, for context.
+- No write. Return to the top-level menu (Step 2).
 
-### Step 5: Direct Set (`set {key} {value}`)
-1. **Validate key exists**:
-   - The key must match one of the rows in the Configuration Keys table. If not, print "Unknown key: <name>", list available keys, exit without writing.
+### Step 4: Edit a Setting
+1. Render a numbered list of editable keys grouped by category (User Preferences, etc.) with current values inline.
+2. Wait for the user to select a key (or `b` to go back to the top-level menu).
+3. Show the key detail: current value, type, default, allowed values.
+4. Run the **Edit sub-flow** (below) for the selected key.
+5. After the sub-flow completes (write or cancel), return to the editable-key list, then to the top-level menu.
+
+#### Edit sub-flow (validate -> preview -> confirm -> write)
+Used by Step 4 and by each stage of Step 5.
+
+1. **Validate key exists**: the key must match one of the rows in the Configuration Keys table. If not, report it and return without writing.
 2. **Validate value type and constraints**:
 
    | Type | Validation |
    |------|------------|
-   | `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) |
+   | `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 the 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 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).
+4. **Confirm**: prompt `Apply this change? (y/n)`. On `n`, discard and return.
 5. **Write atomically**:
    - Read the current file, mutate only the targeted key, preserve all other content and formatting (do NOT rewrite the whole file from a template -- the user may have comments).
    - Write to a temp file in the same directory, then rename. On any error, do not touch the original.
 6. Report the new value and a one-line "what this affects" hint (e.g., "applies to subsequent skill invocations").
 
-### Step 6: Guided Wizard
-- Walk the user through these stages in order. Each stage uses the Step 5 validation rules. Defer the actual write to the end.
+### Step 5: Guided Setup
+- Selected from the top-level menu. Walk the user through these stages in order. Each stage uses the Edit sub-flow's validation rules. Defer the actual write to the end.
 
   | Stage | Key | Notes |
   |-------|-----|-------|
@@ -61,20 +66,13 @@
   | 4 | `preferences.output.data_format` | Default `yaml`; allowed: `yaml`, `json` |
   | 5 | `preferences.context_routing.relevance_threshold` | Default `70`; allowed: 0-100 |
   | 6 | `preferences.history_limits.*` | Show each limit with current value; accept new int or Enter to keep |
+  | 7 | `preferences.planning.granularity` | Default `medium`; allowed: `coarse`, `medium`, `fine` |
 
 - After all stages, render a Summary Preview table: `key | from | to`, then a single confirmation prompt to apply ALL changes atomically.
 - If the user aborts at the summary, discard all in-progress values; do not write anything.
+- After applying (or aborting), return to the top-level menu (Step 2).
 
-### Step 7: Reset
-1. Build the diff between current `config.yaml` and framework defaults: list every key that will revert.
-2. Render the diff as `key | current | will-become-default`.
-3. Require explicit confirmation: `Reset all settings to defaults? (y/n)`.
-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 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)
+## Knowledge Inspection (sub-flow used by View All and Edit a Setting)
 - **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.
 
@@ -84,10 +82,8 @@
 |------|----------|
 | `config.yaml` missing | STOP; recommend `mvtt install` or `/mvt-init` |
 | `config.yaml` exists but unparseable YAML | Surface error with line number; refuse to write; recommend manual fix or `mvtt install --refresh` |
-| User runs `set` with a deprecated key (`preferences.language`) | Print migration hint: `Run mvtt update --migrate-config` to split into the two language fields. Do not mutate the deprecated key |
-| Wizard stage receives an empty value | Treat as "accept default for this stage", continue |
-| 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) |
+| Editing a deprecated key (`preferences.language`) | Print migration hint: `Run mvtt update --migrate-config` to split into the two language fields. Do not mutate the deprecated key |
+| Guided-setup stage receives an empty value | Treat as "accept default for this stage", continue |
+| User aborts mid guided-setup | No partial write; the temp values are discarded |
 | Concurrent edit detected (mtime changed during preview->write) | Abort write, surface a message, ask user to re-run |
-| `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 |
+| User asks to edit `knowledge._all` or any knowledge map key | Refuse and route to `/mvt-manage-context`; this skill inspects knowledge settings but does not mutate them |

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

@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Manage MVTT framework configuration interactively. Provide guided setup, direct key-value setting, and a setup wizard for common configurations.
+      Manage MVTT framework configuration through an interactive menu: view all settings, edit an individual key, or run a guided setup for common configurations.
 
   - type: shared
     source: sections/role-header.md
@@ -20,13 +20,12 @@ sections:
       role: Conductor
       role_desc: "a Workflow Coordinator"
       decision_rules:
-        - rule: "No arguments -> Show interactive configuration menu"
-        - rule: "`show` argument -> Display all current settings"
-        - rule: "`set {key} {value}` -> Validate and apply the specific setting"
-        - rule: "`wizard` argument -> Start guided setup flow"
-        - rule: "`reset` argument -> Reset all settings to defaults after confirmation"
-        - rule: "Invalid key -> Show available keys and exit"
-        - rule: "Invalid value type -> Show expected type and exit"
+        - rule: "Any invocation -> Open the interactive configuration menu (this skill takes no arguments)"
+        - rule: "Menu: View all settings -> Display every key with current value, type, default"
+        - rule: "Menu: Edit a setting -> Pick a key, validate, preview, confirm, write"
+        - rule: "Menu: Guided setup -> Walk common settings in order, apply atomically at the end"
+        - rule: "Invalid key -> Show available keys and return to the menu"
+        - rule: "Invalid value type -> Show expected type and re-prompt"
       boundaries:
         - scope: "analyze requirements"
           skill: "/mvt-analyze"
@@ -37,25 +36,22 @@ sections:
 
   - type: inline
     content: |
-      ## Variants
+      ## Usage
 
-      | Variant | Description |
-      |---------|-------------|
-      | `/mvt-config` | Show interactive configuration menu |
-      | `/mvt-config show` | Display all current settings |
-      | `/mvt-config set {key} {value}` | Set a specific configuration value |
-      | `/mvt-config wizard` | Start guided setup wizard |
-      | `/mvt-config reset` | Reset all settings to defaults |
+      `/mvt-config` takes no arguments. It always opens an interactive menu; all actions are reached from there.
+
+      | Menu action | Description |
+      |-------------|-------------|
+      | View all settings | Display every configuration key with its current value, type, and default |
+      | Edit a setting | Pick a key, then validate, preview, confirm, and write the change |
+      | Guided setup | Walk through common settings in order and apply them atomically |
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
       extended_context:
         - ".ai-agents/config.yaml -- Current configuration (this skill's primary target)"
 
-  - type: shared
-    source: sections/activation-load-config.md
-
   - type: shared
     source: sections/language-constraint.md
 
@@ -72,14 +68,14 @@ sections:
       | `preferences.output.no_emojis` | bool | `true` | Disable emojis in output |
       | `preferences.output.data_format` | enum | `yaml` | Data output format (yaml, json) |
       | `preferences.context_routing.relevance_threshold` | int | `70` | AI routing threshold for `/mvt-manage-context add` (0-100) |
-      | `preferences.history_limits.history` | int | `20` | Max history entries (1-100) |
-      | `preferences.history_limits.changes` | int | `20` | Max changes entries (1-100) |
+      | `preferences.history_limits.history` | int | `10` | Max history entries (1-100) |
+      | `preferences.history_limits.changes` | int | `10` | Max changes entries (1-100) |
+      | `preferences.context_thresholds.*` | map | built-in thresholds | Optional context health thresholds read by `/mvt-check-context`; omitted keys use built-in defaults |
+      | `preferences.planning.granularity` | enum | `medium` | Task decomposition granularity for `/mvt-plan-dev`. Qualitative AI guidance, not hard limits. Values: `coarse` (fewer, larger tasks), `medium` (balanced), `fine` (more, smaller tasks) |
 
       ### Knowledge Settings
 
-      | Key | Type | Default | Description |
-      |-----|------|---------|-------------|
-      | `knowledge._all` | list | `[core, project-context]` | Global knowledge entries in registry.yaml under `_all` key, loaded by all skills across all projects |
+      Knowledge routing is managed by `/mvt-manage-context`, not by `/mvt-config`. Requests to change `knowledge.*` keys must be refused and routed there.
 
   - type: file
     source: ./business.md

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

@@ -45,7 +45,7 @@ Collect core metadata. Each field has an explicit constraint -- do not accept va
 
 | Field | Constraint | Notes |
 |-------|------------|-------|
-| Name | Lowercase, kebab-case, no spaces. Prefix `mvt-` for framework skills; project-specific prefixes (e.g., `app-`, `proj-`) are also acceptable | Reject if conflicts with an existing entry in `registry.yaml` |
+| Name | Lowercase, kebab-case, no spaces, must match `^[a-z][a-z0-9-]*$`. Prefix `mvt-` for framework skills; project-specific prefixes (e.g., `app-`, `proj-`) are also acceptable | Reject if invalid or if it conflicts with an existing entry in `registry.yaml` |
 | Agent role | One of: `conductor`, `analyst`, `architect`, `developer`, `reviewer`, `tester` | Maps the skill to an existing role family |
 | Purpose | One sentence | Will become the SKILL.md `## Purpose` section |
 | Category | One of: `workflow`, `shortcut`, `project`, `utility` | Drives how `/mvt-help` groups it |
@@ -77,7 +77,7 @@ If the user is unsure on any field, propose a default and ask for confirmation r
   |--------|----------|
   | Input parameters | What does the skill need from the user / workspace? |
   | Execution mode | Interactive / automated / hybrid |
-  | Pre-flight checks | List, with severity (BLOCK / WARN); defer to `activation-preflight.md` shared section |
+  | Pre-flight checks | List, with severity (BLOCK / WARN); these populate the Pre-flight part of the Activation Protocol copied into the generated SKILL.md |
   | Decision rules (in role-header) | 3-7 imperative rules covering the major branches |
   | Boundaries | What is in-scope vs delegated to other skills |
   | Execution Flow steps | Bulleted titles only (full content comes in Step 6) |
@@ -86,7 +86,7 @@ If the user is unsure on any field, propose a default and ask for confirmation r
 ### Step 6: Generate Skill Files
 1. Create skill directory: `.claude/skills/{name}/`.
 2. Generate a complete `SKILL.md` file (see Generated SKILL.md Structure below). This file must be fully self-contained — there is no assembler or build step to resolve shared section references. All content must be inlined directly into the SKILL.md.
-3. For standard sections (Activation Protocol, Load Config, Language Constraint, Pre-flight, State Update, Next Steps), copy them verbatim from this document's own SKILL.md and substitute only the skill-specific values (role, decision rules, boundaries, pre-flight checks, next-skill suggestions). Do NOT paraphrase standard sections — copy character-for-character to ensure consistency.
+3. For standard sections (Activation Protocol, Language Constraint, Output Format Constraint, State Update, Next Steps), read the existing shared section files under `.ai-agents/sections/` or the corresponding installed skill section and substitute only the skill-specific values (role, decision rules, boundaries, pre-flight checks, next-skill suggestions). Do NOT reproduce these sections from memory; use the checked-in source text as the canonical template.
 4. For skill-specific sections (frontmatter, Purpose, Execution Flow, Edge Cases & Errors), generate fresh content following the skeleton below.
    - `## Execution Flow`
    - `### Step 1: Load Inputs` -- list required and recommended files, plus fallback rules.
@@ -100,16 +100,21 @@ If the user is unsure on any field, propose a default and ask for confirmation r
 7. SKILL.md word budget: aim for the body to be under ~5k words. Push reference material to `references/`.
 
 ### Step 7: Register in Registry (MANDATORY)
-Append the skill entry to `.ai-agents/registry.yaml` > `skills` section:
+Create a pre-write backup of `.ai-agents/registry.yaml`, then add the skill entry to `.ai-agents/registry.yaml` > `skills` section using structured YAML serialization (not hand-written string concatenation):
 
 ```yaml
   {name}:
     description: "{third-person description with trigger keywords}"
     custom: true
+    template: "_templates/{name}-output.md"   # include ONLY if an output template was created in Step 6; omit this key otherwise
 ```
 
+- If an output template was created in Step 6, set `template:` to its path so `/mvt-template` can discover it; otherwise omit the key entirely.
 - The `custom: true` field is **required** for user-created skills; without it, framework updates will overwrite the entry.
-- Validate the YAML still parses after the append; if not, abort and surface the parse error.
+- Refuse to overwrite an existing skill key.
+- Escape `description` through the YAML serializer; never interpolate raw user text into YAML.
+- Validate the YAML still parses after the write; if not, restore the backup and surface the parse error.
+- Post-write, assert the skills entry count increased by exactly 1 and no existing sibling skill entry changed.
 
 ### Step 8: Validation
 Walk this checklist; any failed item must be fixed before declaring success.
@@ -150,7 +155,7 @@ Apply the State Update rules defined in the **State Update** section below.
 | Skill duplicates an existing skill's responsibility | Surface the overlap (cite the existing skill's description); propose merging or sub-classing as a variant rather than creating a duplicate |
 | User provides a non-third-person description ("Use this skill when you need...") | Rewrite to third-person before saving; show the rewrite for confirmation |
 | Generated SKILL.md is missing a standard section (e.g., State Update, Next Steps) | Abort generation; inform user which section is missing; read an existing SKILL.md for the correct structure |
-| `registry.yaml` parse fails after append | Restore from a pre-append backup; surface the error; do not leave the registry corrupt |
+| `registry.yaml` parse fails after write | Restore from the pre-write backup; surface the error; do not leave the registry corrupt |
 
 ## Generated SKILL.md Structure
 
@@ -210,11 +215,10 @@ Copy the following sections verbatim from this document (the assembled SKILL.md
 
 | Section | Source in this document | What to replace |
 |---------|----------------------|-----------------|
-| 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 |
-| 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 |
+| Activation Protocol | `## Activation Protocol` (the whole Load + Resolve block) | Copy the entire block as-is. The block already covers context loading, project scope, knowledge, config preferences, and pre-flight. Adjust only two skill-specific parts: under Load, the Extended Context entries (add the files/directives this skill needs, or drop the Extended Context bullet if none); under Resolve > Pre-flight, the checks table (skill-specific checks, or a single INFO row if none required) |
+| Language Constraint | `## Language Constraint` | Copy as-is (separate section, not part of Activation Protocol) |
+| Output Format Constraint | `## Output Format Constraint` | Copy as-is (separate section); include only if the skill writes persisted markdown |
 | 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.
+**Important**: Do NOT paraphrase or rewrite the standard sections. Load them from the checked-in shared section sources or a selected installed exemplar and only substitute the skill-specific values. This ensures consistency across all MVTT skills.

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

@@ -28,25 +28,22 @@ sections:
         - rule: "Usage patterns unclear -> Ask for concrete examples before proceeding"
       boundaries:
         - scope: "generate skills that deviate from MVTT SKILL.md standard structure"
-          skill: "the standard structure as documented"
+          guidance: "follow the standard structure as documented"
         - scope: "use arbitrary prefixes without validating naming conventions"
-          skill: "`mvt-` or a project-specific prefix like `app-`, `proj-`"
+          guidance: "use `mvt-` or a project-specific prefix like `app-`, `proj-`"
         - scope: "create skills without registering in registry.yaml"
-          skill: "`custom: true` in registry.yaml"
+          guidance: "register with `custom: true` in registry.yaml"
         - scope: "write vague or first-person descriptions"
-          skill: "third-person with effective trigger keywords"
+          guidance: "write third-person with effective trigger keywords"
         - scope: "exceed ~5k words in SKILL.md body"
-          skill: "references/ for detailed content"
+          guidance: "push detailed content to references/"
 
   - type: shared
-    source: sections/activation-load-context.md
+    source: sections/activation-protocol.md
     params:
       extended_context:
         - "Load one existing SKILL.md as structural reference (e.g., `.claude/skills/mvt-status/SKILL.md`)"
 
-  - type: shared
-    source: sections/activation-load-config.md
-
   - type: shared
     source: sections/language-constraint.md
 

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

@@ -54,16 +54,13 @@
 - **On confirmation**: proceed to Step 6.
 
 ### Step 6: Write Artifacts
-Write two artifacts using the `decompose-output` template for `epic.md`:
+Write two artifacts:
 
-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 |
-     |---|-------|-------|--------|------------|
+Before writing, derive `epic_id` and check whether `.ai-agents/workspace/artifacts/{epic_id}/` already exists. If it exists, do NOT overwrite it; warn the user and ask for a disambiguating slug, then re-run the preview from Step 5 with the new id.
 
-   - **Dependency Map**: Mermaid flowchart showing child dependencies
+1. **epic.md** (narrative) -- `.ai-agents/workspace/artifacts/{epic_id}/epic.md`
+   - Uses the `decompose-output` template. Follow the HTML comments in the template for what each section should contain (including the Child Stories table format and the Dependency Map mermaid flowchart); strip comments from the final artifact.
+  - **Required coverage**: cover only content that is applicable to this decomposition. Preserve enough information for the user to understand the epic vision, boundaries, cross-cutting concerns, child stories, dependencies, and unresolved questions. Do not create empty or artificial sections just because an item is named here; if the template omits or renames a section, place applicable content in the closest relevant section.
 
 2. **epic.yaml** (structured) -- `.ai-agents/workspace/artifacts/{epic_id}/epic.yaml`
    - Follows the schema defined in Artifact Structure
@@ -72,17 +69,32 @@ Write two artifacts using the `decompose-output` template for `epic.md`:
 
 **Self-validation checklist** (verify before writing):
 - [ ] All `change_id` values are unique
+- [ ] `.ai-agents/workspace/artifacts/{epic_id}/` does not already exist
 - [ ] 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:
+**Optional safety net**: after writing, validate the epic using the Epic Update Script command below:
 ```bash
 node .ai-agents/scripts/epic-update.cjs --validate .ai-agents/workspace/artifacts/{epic_id}/epic.yaml
 ```
 
+If the epic needs children added later (e.g. a missed sub-change discovered during analysis), use `--add-child`:
+```bash
+node .ai-agents/scripts/epic-update.cjs --epic .ai-agents/workspace/artifacts/{epic_id}/epic.yaml \
+  --add-child <new_child_id> --child-title "<title>" --child-scope "<scope>"
+```
+
+To advance the epic after a child change completes, use `--complete-child`:
+```bash
+node .ai-agents/scripts/epic-update.cjs --epic .ai-agents/workspace/artifacts/{epic_id}/epic.yaml \
+  --complete-child <completed_child_id>
+```
+
+For post-write epic mutations, use the rendered `epic-update.cjs` commands. Do NOT hand-edit `epic.yaml`, advance `current_change`, or read `.cjs`/`.js` source.
+
 ### Step 7: Update Session
 Run the session update command (see State Update section) to:
 1. Create a new `active_epic` in session.yaml

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

@@ -33,33 +33,31 @@ sections:
           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
+    source: sections/activation-protocol.md
     params:
+      activation_reads:
+        - session.yaml
+      has_preflight: true
       checks:
         - order: "1"
           field: "session.initialized_at"
           level: "WARN"
-          message: 'Session not initialized. Run `/mvt-init` first.'
+          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.'
+          message: "Project not initialized. Run `/mvt-init` first."
         - order: "3"
           field: "active_change.id"
+          condition: "active_change.id is non-empty"
           level: "WARN"
-          message: 'An active change already exists. Decomposing will create a new epic alongside it. Continue? (y/n)'
+          message: "An active change already exists. Decomposing will create a new epic alongside it. Continue? (y/n)"
+
+  - type: shared
+    source: sections/language-constraint.md
+
+  - type: shared
+    source: sections/output-format-constraint.md
 
   - type: file
     source: ./business.md
@@ -71,7 +69,7 @@ sections:
       **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.
+      The template defines section structure and guidance comments. Generate applicable content based on decomposition results.
       Write to: `.ai-agents/workspace/artifacts/{epic_id}/epic.md`
 
       **epic.yaml** (structured):

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

@@ -5,7 +5,7 @@
   - Existing design artifacts of related prior changes (`artifacts/*/design.md`) -- to stay consistent.
 - **Fallback**:
   - If `analysis.md` is missing, surface a WARN and accept the user's free-text intent as the requirement input.
-  - If `project-context.md` is missing, proceed but mark the design as "context-light" and skip the layer-compliance check in Step 4.
+  - If `project-context.md` is missing, proceed but mark the design as "context-light" and skip the layer-compliance check in Step 3.
 
 ### Step 2: Frame the Problem
 - **What**: produce a one-paragraph problem statement plus a list of explicit architectural concerns (3-7 items).
@@ -15,36 +15,35 @@
   3. Drop any concern that is not actually exercised by the requirements -- do not invent NFRs.
 - **Output of this step**: a Concerns Table with columns `concern | source-of-evidence | priority(must/should/nice)`.
 
-### Step 3: Choose Architecture Style
-- **What**: select the smallest viable architecture style for this change. Escalate only when concerns force it.
-- **How**: pick the row that matches the dominant concerns; multiple changes within the same project should normally pick the same style unless requirements force otherwise.
-
-  | Style | Use when | Avoid when |
-  |-------|----------|------------|
-  | Plain CRUD / 3-layer | Single resource flow, no domain rules beyond validation | Complex business invariants, multi-step workflows |
-  | Service-oriented within a module | Multiple use cases sharing entities, transactions across them | Cross-team boundaries, independent deployment needs |
-  | Domain-driven (aggregates, domain services) | Rich business rules, invariants, multiple actors per workflow | Simple read-mostly resources |
-  | Event-driven / async | Long-running flows, decoupled side-effects, retry/back-pressure | Strong synchronous contracts, immediate-consistency reads |
-  | Multi-service / boundary split | Independent scaling or deployment, separate teams | Single team, single deployment pipeline -- DEFER |
-
-- If the requirements suggest "multi-service" but project is currently single-service: STOP and ask user to confirm scope expansion before designing across services.
-
-### Step 4: Design Module Structure
+### Step 3: Design Module Structure
 - **What**: list modules (new and modified), their responsibilities, owned entities, and interfaces.
 - **How**:
-  1. Map each Concern (Step 2) to one owning module.
-  2. For every module, write: name, responsibility (one sentence), owned entities, public interface (function/class signatures or HTTP endpoints), dependencies on other modules.
-  3. Validate dependency direction against `project-context.md` layer rules (e.g., domain -> infra forbidden). If violation found, redesign or flag it as an explicit ADR (Step 6).
-  4. Use the existing module names from `project-context.md` whenever possible -- introduce a new module only when no existing one fits.
+  1. Follow existing project architecture first: `project-context.md`, accepted ADRs, framework constraints, and domain rules override the examples below.
+  2. Start simple. Add a boundary, abstraction, async flow, dependency, or new module only when a must/should concern requires it.
+  3. For each must/should Concern (Step 2), choose the smallest response that satisfies it. Use the table as examples, not a closed list; if no row fits, derive a response from the concern itself.
+
+     | Concern signal (example) | Smallest architectural response | Module consequence |
+     |---------------------------|----------------------------------|--------------------|
+     | Simple data lifecycle | CRUD-oriented service/repository shape | Resource module with validation and persistence boundary |
+     | Rich business invariant | Domain model or aggregate boundary | Entity or aggregate module owns invariant enforcement |
+     | Shared multi-step workflow | Application service or use-case coordinator | Workflow module coordinates existing modules |
+     | Async side effect or retry need | Event handler or queue boundary | Producer/consumer or handler module; mark event boundary |
+     | Independent deployment, scaling, or team ownership | Service boundary candidate | STOP if it implies a new deployable service, runtime, or cross-service contract |
+
+  4. Output the concern mapping as `concern | response | owning module | boundary impact`.
+  5. For every module, write: name, responsibility (one sentence), owned entities, public interface (function/class signatures or HTTP endpoints), dependencies on other modules.
+  6. Reuse existing module names from `project-context.md` whenever possible. Add a new module only when no existing module fits.
+  7. Validate dependency direction against `project-context.md` layer rules (e.g., domain -> infra forbidden). If violation found, redesign or flag it as an explicit ADR (Step 5).
 - **Branches**:
 
   | Condition | Action |
   |-----------|--------|
   | Layer-compliance check passes | Proceed |
   | Single layer violation, fix is local | Adjust module placement, document in change tracking |
-  | Systemic violation (style mismatch with existing project) | STOP, raise ADR (Step 6) and ask user to confirm direction before continuing |
+  | Architectural response implies a new deployable service, runtime, or cross-service contract | STOP, ask user to confirm scope expansion before designing across boundaries |
+  | Systemic violation (mismatch with existing project architecture) | STOP, raise ADR (Step 5) and ask user to confirm direction before continuing |
 
-### Step 5: Define Data Flow
+### Step 4: Define Data Flow
 - **What**: for each primary use case, produce a sequence of module interactions.
 - **How**:
   1. For each use case (from Step 2 / analysis.md), list the trigger, the modules involved, the call order, and the persistence/event boundaries.
@@ -52,7 +51,7 @@
   3. Mark transactional boundaries explicitly (`-- transaction begin/end`).
   4. Identify error paths for each flow: what happens if step N fails? Document fallback behavior (retry, compensating action, user-visible error).
 
-### Step 6: Document Decisions (ADRs)
+### Step 5: Document Decisions (ADRs)
 - **What**: capture every non-obvious choice as an Architecture Decision Record.
 - **How**: write one ADR per decision with these fields:
 
@@ -66,39 +65,31 @@
   | Consequences | Positive and negative impacts; which downstream skills/modules pay the cost |
 
 - Decisions that MUST be ADRs (do not skip):
-  - Choice of architecture style (Step 3) when more than one row was viable.
+  - Any architectural response that changes module boundaries, deployment/runtime boundaries, persistence boundaries, async/event boundaries, or public contracts.
   - Any layer-rule violation accepted as a deliberate exception.
   - Introduction of a new external dependency (DB, queue, library category).
   - Breaking change to an existing public interface.
 
-### Step 7: User Confirmation Before Write
+### Step 6: User Confirmation Before Write
 - **When to confirm before writing the artifact**:
-  - Step 3 escalated to multi-service.
-  - Step 4 raised a systemic layer violation.
-  - Step 6 contains any ADR with `status: proposed` for a breaking change.
+  - Step 3 identified a new deployable service, runtime, or cross-service contract.
+  - Step 3 raised a systemic layer violation.
+  - Step 5 contains any ADR with `status: proposed` for a breaking change.
   - The design adds a new external dependency.
 - **When to write silently**:
   - Single-module addition that fits existing layers, no ADR escalations, no breaking change.
-- **Confirmation format**: present a one-screen summary -- style chosen, modules added/changed, ADRs requiring review, a single yes/no prompt. Do not dump the full artifact.
-
-### Step 8: Write Artifact
-- **Path and template**: as defined in the **Artifact Structure** section below.
-- **Required sections** (filled per template headings, but content must include):
-  - `Overview` -- the problem statement (Step 2).
-  - `Architecture Decision Records` -- every ADR from Step 6.
-  - `Module Design` -- table of modules from Step 4.
-  - `Key Interfaces` -- explicit signatures/endpoints.
-  - `Data Flow` -- sequences from Step 5, including error paths.
-  - `File Structure` -- mapping of modules to file/directory paths in this repo.
-  - `Implementation Guidelines` -- ordering hints for `/mvt-implement` and `/mvt-plan-dev`.
-  - `Change Tracking` -- list of files expected to be created/modified/deleted.
+- **Confirmation format**: present a one-screen summary -- module boundary changes, deployment/runtime boundary changes, ADRs requiring review, external dependencies, and a single yes/no prompt. Do not dump the full artifact.
+
+### Step 7: Write Artifact
+- **Path and template**: as defined in the **Artifact Structure** section below. Follow the HTML comments in the template for what each section should contain; strip comments from the final artifact.
+- **Required coverage**: cover only content that is applicable to this design. Preserve enough information for downstream skills to understand the problem, decisions made, module/interface/data-flow impacts, expected file changes, and implementation guidance. Do not create empty or artificial sections just because an item is named here; if the template omits or renames a section, place applicable content in the closest relevant section.
 - Do NOT modify `project-context.yaml` or `project-context.md` here.
 
-### Step 9: Suggest Plan Decomposition
-- If `Change Tracking` lists more than ~5 files OR Module Design adds more than 1 new module OR ADRs include any breaking change, recommend `/mvt-plan-dev` as the next step.
+### Step 8: Suggest Plan Decomposition
+- If `Change Tracking` lists more than 5 files OR Module Design adds more than 1 new module OR ADRs include any breaking change, recommend `/mvt-plan-dev` as the next step.
 - Otherwise recommend `/mvt-implement` directly.
 
-### Step 10: State Update
+### Step 9: State Update
 Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors