@uoyo/mvtt 2.0.0-beta.4 → 2.0.0

package/sources/scripts/session-update.js

@@ -23,7 +23,12 @@
  *     [--set-change-status <status>] \
  *     [--no-change] \
  *     [--set-synced] \
- *     [--truncate-history <n>]
+ *     [--truncate-history <n>] \
+ *     [--new-epic <title> --epic-id <id>] \
+ *     [--set-epic-path <path>] \
+ *     [--set-epic-status <status>] \
+ *     [--close-epic] \
+ *     [--epic-id <id>]   (with --new-change, links sub-change to epic)
  *
  * Output:
  *   Success (exit 0): {"ok":true}
@@ -48,6 +53,10 @@ const ERRORS = {
   SESSION_WRITE_FAILED: (detail) => `Failed to write session.yaml: ${detail}`,
   CONFIG_LIMIT_INVALID: (key, val, min, max, fallback) =>
     `Warning: config history_limits.${key} value "${val}" is invalid (must be integer ${min}-${max}). Using default ${fallback}.`,
+  EPIC_ID_REQUIRED: () => "--new-epic requires --epic-id",
+  CLOSE_NEW_EPIC_CONFLICT: () => "--close-epic and --new-epic are mutually exclusive",
+  NO_ACTIVE_EPIC: (flag) => `${flag} requires an active epic (active_epic.id is empty)`,
+  EPIC_ID_ORPHAN: () => "--epic-id (for sub-change) requires --new-change",
 };
 
 // ── Defaults ────────────────────────────────────────────────────────────────
@@ -124,6 +133,12 @@ function validate(args) {
   if (!args.skill) return ERRORS.MISSING_SKILL();
   if (!args.summary) return ERRORS.MISSING_SUMMARY();
   if (args["new-change"] && !args["change-id"]) return ERRORS.CHANGE_ID_REQUIRED();
+
+  // Epic combo validation (§9.1.1, ADR-10)
+  if (args["new-epic"] && !args["epic-id"]) return ERRORS.EPIC_ID_REQUIRED();
+  if (args["close-epic"] && args["new-epic"]) return ERRORS.CLOSE_NEW_EPIC_CONFLICT();
+  if (args["epic-id"] && !args["new-change"] && !args["new-epic"]) return ERRORS.EPIC_ID_ORPHAN();
+
   return null;
 }
 
@@ -197,6 +212,7 @@ function main() {
         plan_path: session.active_change.plan_path || "",
         status: "active",
         updated_at: now,
+        epic_id: session.active_change.epic_id || "",
       };
       if (existingIdx >= 0) {
         session.changes[existingIdx] = snapshotEntry;
@@ -215,6 +231,7 @@ function main() {
     session.active_change.title = args["new-change"];
     session.active_change.created_at = now;
     session.active_change.plan_path = "";
+    session.active_change.epic_id = args["epic-id"] || "";
   }
 
   // --set-initialized
@@ -252,6 +269,7 @@ function main() {
       plan_path: ac.plan_path || "",
       status: "active",
       updated_at: now,
+      epic_id: ac.epic_id || "",
     };
     if (existingIdx >= 0) {
       session.changes[existingIdx] = entry;
@@ -281,6 +299,7 @@ function main() {
         plan_path: ac.plan_path || "",
         status: "done",
         updated_at: now,
+        epic_id: ac.epic_id || "",
       };
       if (existingIdx >= 0) {
         session.changes[existingIdx] = entry;
@@ -300,6 +319,7 @@ function main() {
       title: "",
       created_at: "",
       plan_path: "",
+      epic_id: "",
     };
   }
 
@@ -329,11 +349,91 @@ function main() {
     }
   }
 
+  // ── Epic flags ──────────────────────────────────────────────────────────
+
+  // --new-epic: auto-snapshot old active_epic, then set new one
+  if (args["new-epic"]) {
+    session.active_epic = session.active_epic || {};
+
+    // Auto-snapshot: if there's an existing active_epic with an id, upsert into epics[]
+    if (session.active_epic.id) {
+      session.epics = session.epics || [];
+      const existingIdx = session.epics.findIndex(
+        (e) => e.id === session.active_epic.id
+      );
+      const snapshotEntry = {
+        id: session.active_epic.id,
+        title: session.active_epic.title || "",
+        epic_path: session.active_epic.epic_path || "",
+        status: "active",
+        updated_at: now,
+      };
+      if (existingIdx >= 0) {
+        session.epics[existingIdx] = snapshotEntry;
+      } else {
+        session.epics.push(snapshotEntry);
+      }
+    }
+
+    // Set new active_epic
+    session.active_epic.id = args["epic-id"];
+    session.active_epic.title = args["new-epic"];
+    session.active_epic.created_at = now;
+    session.active_epic.epic_path = "";
+  }
+
+  // --set-epic-path: set active_epic.epic_path
+  if (args["set-epic-path"]) {
+    session.active_epic = session.active_epic || {};
+    if (!session.active_epic.id && !args["new-epic"]) {
+      process.stderr.write(ERRORS.NO_ACTIVE_EPIC("--set-epic-path") + "\n");
+      process.exit(1);
+    }
+    session.active_epic.epic_path = args["set-epic-path"];
+  }
+
+  // --set-epic-status: update matching epics[] entry status
+  if (args["set-epic-status"]) {
+    session.active_epic = session.active_epic || {};
+    if (!session.active_epic.id && !args["new-epic"]) {
+      process.stderr.write(ERRORS.NO_ACTIVE_EPIC("--set-epic-status") + "\n");
+      process.exit(1);
+    }
+    session.epics = session.epics || [];
+    const epicIdx = session.epics.findIndex(
+      (e) => e.id === session.active_epic.id
+    );
+    if (epicIdx >= 0) {
+      session.epics[epicIdx].status = args["set-epic-status"];
+      session.epics[epicIdx].updated_at = now;
+    }
+  }
+
+  // --close-epic: set matching epics[] entry to done, clear active_epic
+  if (args["close-epic"]) {
+    session.epics = session.epics || [];
+    session.active_epic = session.active_epic || {};
+    const aeId = session.active_epic.id;
+    if (aeId) {
+      const epicIdx = session.epics.findIndex((e) => e.id === aeId);
+      if (epicIdx >= 0) {
+        session.epics[epicIdx].status = "done";
+        session.epics[epicIdx].updated_at = now;
+      }
+    }
+    session.active_epic = {
+      id: "",
+      title: "",
+      created_at: "",
+      epic_path: "",
+    };
+  }
+
   // ── Write back atomically ─────────────────────────────────────────────
   const tmpPath = sessionPath + ".tmp";
 
   try {
-    writeFileSync(tmpPath, stringifyYaml(session), "utf-8");
+    writeFileSync(tmpPath, stringifyYaml(session, { lineWidth: 200 }), "utf-8");
     renameSync(tmpPath, sessionPath);
   } catch (e) {
     try {

package/sources/sections/activation-load-config.md

@@ -1,9 +1,9 @@
-### Step 3: Load Config & Apply Preferences (Config Foundation)
+### Step 4: Load Config & Apply Preferences (Config Foundation)
 Read `.ai-agents/config.yaml` and enforce the following throughout this entire session:
 
 **Language**:
-- `preferences.interaction_language` → Use for everything spoken to the user (chat, prompts, tables); NOT for files written to disk.
-- `preferences.document_output_language` → See **Output Language Constraint** section below for the full rules governing files written to disk.
+- `preferences.interaction_language` → Language for everything spoken to the user (chat, prompts, tables); NOT for files written to disk. See the **Language Constraint** section below for the full, non-negotiable rules.
+- `preferences.document_output_language` → Language for files written to disk. See the **Language Constraint** section below for the full rules.
 
 **Other preferences**:
 - `preferences.output.no_emojis` → If true, never use emojis

package/sources/sections/activation-load-context.md

@@ -1,8 +1,7 @@
 ## Activation Protocol
 
-### Step 1: Load Context (Context Foundation)
-Load the following files as foundational context:
-- `.ai-agents/workspace/session.yaml` -- Current workflow state
+### Step 1: Load Context
+Load these files as foundational context:
 - `.ai-agents/workspace/project-context.yaml` -- Project index (structural info)
 - `.ai-agents/registry.yaml` -- Available skills registry and knowledge declarations
 {{?extended_context}}
@@ -13,18 +12,48 @@ Extended context for this skill:
 - {{.}}
 {{/extended_context}}
 
-### Step 2: Load Knowledge
+### Step 2: Resolve Project Scope (PS)
 
-Read `.ai-agents/registry.yaml` and load every file referenced under:
-- `knowledge.shared` (loaded by all skills)
-- `skills.<current-skill>.knowledge` (this skill's specific knowledge, if present)
+Read `project-context.yaml > projects[]`.
 
-For each entry, resolve files relative to `.ai-agents/{source}`:
-- If the entry lists `files: [...]`, load those files.
-- If the entry lists `files_from_manifest: true`, read `{source}/manifest.yaml` and load every `files[]` entry where `auto_load: true`.
+**Single project** (`projects.length == 1`): Set PS = [sole project name]. Skip remaining PS steps.
 
-Skip any path that does not exist.
+**Multi-project** (`projects.length > 1`):
+**Mode A -- Plan-driven** (active plan exists and skill operates on plan tasks):
+1. **Plan signal**: PS = current task's `project` array from plan's `current_tasks`. Drop stale project names (not in `projects[]`), fall through.
+2. **Path match**: Match current working paths against `projects[].path` and `source_paths`.
+3. **Prompt**: If still unresolved, list candidates and ask user. Never silently load all projects.
 
-### Archived Artifacts Convention
+**Mode B -- Non-plan** (no active plan or ad-hoc changes):
+Defer PS to execution: identify change target, match against `projects[].path` and `source_paths`, load project-specific knowledge on demand (Step 3).
 
-The directory `.ai-agents/workspace/artifacts/_archived/` contains change-id directories that have been archived by `/mvt-cleanup`. All skills that scan `artifacts/` MUST exclude `_archived/` from their scan scope unless explicitly inspecting archived content.
+### Step 3: Load Knowledge
+
+Registry uses project-keyed maps; `_all` is a reserved key (all projects). Applies to both top-level `knowledge` and `skills.<name>.knowledge`.
+
+**Knowledge Loading Protocol**:
+For each knowledge entry in the registry, follow these steps:
+1. **Read the `source` field** from the registry entry (e.g., `knowledge/project/_generated/`).
+2. **Construct the base directory**: join `.ai-agents/` with the `source` value → `.ai-agents/{source_value}/`.
+3. **Load files**:
+   - `files: [a.md, b.md]` → load `.ai-agents/{source_value}/a.md`, `.ai-agents/{source_value}/b.md`.
+   - `files_from_manifest: true` → read `.ai-agents/{source_value}/manifest.yaml`, load entries with `auto_load: true`.
+4. **Skip non-existent paths** silently (do not error or warn).
+
+**Worked example**:
+Given this registry entry:
+```yaml
+- id: project-context
+  source: knowledge/project/_generated/
+  files:
+    - project-context.md
+```
+Resolution: `.ai-agents/` + `knowledge/project/_generated/` + `project-context.md` = `.ai-agents/knowledge/project/_generated/project-context.md`
+
+**Anti-pattern -- DO NOT**:
+- Guess or hardcode base directories (e.g., `.ai-agents/workspace/`).
+- Assume a default path structure. The `source` field value is the authoritative path component.
+
+**At activation** (both modes): load `knowledge._all` + `skills.<current-skill>.knowledge._all`.
+**Mode A** (additionally): for each P in PS, load `knowledge[P]` + `skills.<current-skill>.knowledge[P]`.
+**Mode B** (during execution): on demand, load `knowledge[P]` + `skills.<current-skill>.knowledge[P]` for identified project(s).

package/sources/sections/activation-preflight.md

@@ -1,4 +1,4 @@
-### Step 4: Pre-flight Checks
+### Step 5: Pre-flight Checks
 
 For each check below, if the condition holds, perform the action implied by its **Level**:
 

package/sources/sections/footer-next-steps.md

@@ -1,6 +1,7 @@
 ## Suggested Next Steps
 
 Recommend 2-3 relevant next skills based on the skill just completed (`{{current_skill}}`) and the current project state.
+**Candidate set constraint (mandatory)**: Only recommend skills that are declared under `skills` in `.ai-agents/registry.yaml`.
 {{#conditional_suggestions}}
 
 ### Conditional Recommendations
@@ -21,11 +22,11 @@ Match the current state to one of the conditions below. If none match, use `defa
 
 ### Resolution order
 
-Infer 2-3 suggestions from:
+Infer 2-3 suggestions, choosing **only** from the skills declared under `skills` in `registry.yaml`:
 - `history` in `session.yaml`
 - `category` and `description` of each skill in `registry.yaml`
 - The current `active_change` state (if in progress)
-- The `depends_on` relationships between skills
+- The standard workflow order (analyze → design → implement → review → test)
 {{/conditional_suggestions}}
 
 ### Format

package/sources/sections/language-constraint.md

@@ -0,0 +1,26 @@
+## Language Constraint (Mandatory)
+
+This constraint governs the language of **everything** this skill produces. It has two independent scopes — interactive output (what you say to the user) and persisted document output (what you write to disk). Both are NON-NEGOTIABLE and override any other language signals.
+
+### Interactive Output (spoken to the user)
+
+All interactive output — chat replies, questions, prompts, status lines, tables, and summaries shown in the conversation — MUST be written in the language specified by `preferences.interaction_language` from config.yaml.
+
+**Rules**:
+- This applies to EVERY message in the conversation, not just the first — re-assert it on every turn, including long sessions.
+- Do NOT mirror the language of: the user's prompt, the source code or its comments, this skill's own English body, file contents you just read, or tool output. None of these are language signals.
+- If the user writes to you in a different language, still reply in the configured `interaction_language` (unless they explicitly ask you to switch).
+- If `interaction_language` is not set, fall back to `en-US`.
+- This constraint is NON-NEGOTIABLE and overrides any other language signals.
+
+### Persisted Document Output (files written to disk)
+
+All persisted document output (files written to disk) MUST be written in the language specified by `preferences.document_output_language` from config.yaml.
+
+**Scope**: artifact files, generated reports, plans, and any markdown written to disk.
+
+**Rules**:
+- Section headings defined in templates may remain in their original language, but all generated **content** MUST use the configured language
+- If `document_output_language` is not set, fall back to `interaction_language`
+- Do NOT infer output language from template headings, user prompt language, or source code comments
+- This constraint is NON-NEGOTIABLE and overrides any other language signals

package/sources/sections/output-format-constraint.md

@@ -1,14 +1,14 @@
-## Output Format Constraint (Mandatory)
-
-All persisted document output (markdown written to disk) MUST follow the formatting rules below. These rules govern *how* content is rendered, independent of the language it is written in.
-**Scope**: artifact files, generated reports, plans, design documents, and any markdown written to disk. These rules do NOT apply to conversational output in the chat.
-
-**Rules**:
-- **Diagrams**: Express flowcharts, architecture, sequence, and structure diagrams as fenced `mermaid` code blocks. Do NOT draw diagrams with ASCII art (boxes made of `+`, `-`, `|`, arrows like `-->` outside mermaid, etc.).
-- **Tables**: Render tabular data as Markdown tables (`| col | col |`). Do NOT simulate tables with space- or tab-aligned text.
-- **Code**: Place code, commands, and config snippets in fenced code blocks with a language tag (e.g. ```` ```ts ````, ```` ```bash ````, ```` ```yaml ````). Do NOT leave code in bare or untagged fences.
-- **Headings**: Use the Markdown heading hierarchy (`#` -> `##` -> `###`) without skipping levels. Do NOT use bold text as a substitute for a heading.
-
-**Notes**:
-- If a diagram genuinely cannot be expressed in mermaid (e.g. a precise spatial/pixel layout), state that explicitly and prefer a Markdown table or prose description over ASCII art.
-- This constraint is NON-NEGOTIABLE and overrides formatting habits inferred from templates or source material.
+## Output Format Constraint (Mandatory)
+
+All persisted document output (markdown written to disk) MUST follow the formatting rules below. These rules govern *how* content is rendered, independent of the language it is written in.
+**Scope**: artifact files, generated reports, plans, design documents, and any markdown written to disk. These rules do NOT apply to conversational output in the chat.
+
+**Rules**:
+- **Diagrams**: Express flowcharts, architecture, sequence, and structure diagrams as fenced `mermaid` code blocks. Do NOT draw diagrams with ASCII art (boxes made of `+`, `-`, `|`, arrows like `-->` outside mermaid, etc.).
+- **Tables**: Render tabular data as Markdown tables (`| col | col |`). Do NOT simulate tables with space- or tab-aligned text.
+- **Code**: Place code, commands, and config snippets in fenced code blocks with a language tag (e.g. ```` ```ts ````, ```` ```bash ````, ```` ```yaml ````). Do NOT leave code in bare or untagged fences.
+- **Headings**: Use the Markdown heading hierarchy (`#` -> `##` -> `###`) without skipping levels. Do NOT use bold text as a substitute for a heading.
+
+**Notes**:
+- If a diagram genuinely cannot be expressed in mermaid (e.g. a precise spatial/pixel layout), state that explicitly and prefer a Markdown table or prose description over ASCII art.
+- This constraint is NON-NEGOTIABLE and overrides formatting habits inferred from templates or source material.

package/sources/sections/project-context-profile.md

@@ -1,29 +1,29 @@
-## Document Profile: project-context.md
-
-Before writing to `project-context.md`, understand what this document IS and IS NOT.
-
-### Identity
-`project-context.md` is the project's **long-term semantic ground truth** -- a self-contained knowledge base consumed by AI skills to make decisions. It is NOT a copy of design documents, NOT a changelog, NOT an ADR index.
-
-### Audience
-The readers are AI skill instances (implementer, designer, tester, reviewer), NOT humans reading for reference. They use this document to make **binary decisions** (is this import legal? does this test cover this rule?) -- not to trace design rationale.
-
-### Content Quality Standards
-Every piece of content written into `project-context.md` must satisfy ALL of the following:
-
-1. **Self-contained**: understandable without consulting any external document, artifact, or ADR.
-2. **Actionable**: usable by an AI skill to make a yes/no decision or produce a concrete output (e.g., a test case).
-3. **Atomic**: each item is independently meaningful -- not a fragment of a larger argument that only makes sense in its source document.
-4. **Lean**: the token budget for this document is <= 4000 (healthy threshold). Content that does not directly serve a decision should be excluded.
-5. **Stable**: only persist knowledge with long-term reference value. Transient state (change metadata, in-progress decisions, temporary workarounds) belongs in session.yaml or artifacts.
-
-### Governing Principle (What Does NOT Belong)
-**If a reader must consult an external document to understand an entry, that entry -- or its reference marker -- does not belong here.**
-
-Strip any cross-reference marker (pointers to ADRs, design-document section numbers, internal rule labels, etc.). Remove only the *reference marker*, NEVER the *substantive content* it annotates.
-
-- ✅ `idempotency key or exists-or-skip semantics (ADR-06, §12.4)` → `idempotency key or exists-or-skip semantics`
-- ✅ `B-1: resume() degrades to rebuild on protocol error` → `resume() degrades to rebuild on protocol error`
-- ❌ `Subscriber Idempotency Contract` -- this is the term itself, keep it.
-
-> This profile applies ONLY when the target document is `project-context.md`. Other knowledge files (principle/, project/, core/user/, etc.) are not governed by it.
+## Document Profile: project-context.md
+
+Before writing to `project-context.md`, understand what this document IS and IS NOT.
+
+### Identity
+`project-context.md` is the project's **long-term semantic ground truth** -- a self-contained knowledge base consumed by AI skills to make decisions. It is NOT a copy of design documents, NOT a changelog, NOT an ADR index.
+
+### Audience
+The readers are AI skill instances (implementer, designer, tester, reviewer), NOT humans reading for reference. They use this document to make **binary decisions** (is this import legal? does this test cover this rule?) -- not to trace design rationale.
+
+### Content Quality Standards
+Every piece of content written into `project-context.md` must satisfy ALL of the following:
+
+1. **Self-contained**: understandable without consulting any external document, artifact, or ADR.
+2. **Actionable**: usable by an AI skill to make a yes/no decision or produce a concrete output (e.g., a test case).
+3. **Atomic**: each item is independently meaningful -- not a fragment of a larger argument that only makes sense in its source document.
+4. **Lean**: the token budget for this document is <= 4000 (healthy threshold). Content that does not directly serve a decision should be excluded.
+5. **Stable**: only persist knowledge with long-term reference value. Transient state (change metadata, in-progress decisions, temporary workarounds) belongs in session.yaml or artifacts.
+
+### Governing Principle (What Does NOT Belong)
+**If a reader must consult an external document to understand an entry, that entry -- or its reference marker -- does not belong here.**
+
+Strip any cross-reference marker (pointers to ADRs, design-document section numbers, internal rule labels, etc.). Remove only the *reference marker*, NEVER the *substantive content* it annotates.
+
+- ✅ `idempotency key or exists-or-skip semantics (ADR-06, §12.4)` → `idempotency key or exists-or-skip semantics`
+- ✅ `B-1: resume() degrades to rebuild on protocol error` → `resume() degrades to rebuild on protocol error`
+- ❌ `Subscriber Idempotency Contract` -- this is the term itself, keep it.
+
+> This profile applies ONLY when the target document is `project-context.md`. Other knowledge files (principle/, project/, core/user/, etc.) are not governed by it.

package/sources/sections/session-update.md

@@ -9,7 +9,7 @@ This skill is read-only and does NOT modify `.ai-agents/workspace/session.yaml`.
 After completing the skill's main task, run the session update script **exactly once** with the following arguments:
 
 ```bash
-node .ai-agents/scripts/session-update.cjs --skill <skill_command_name> --summary "<concise one-line summary>"{{#update_active_change}} --new-change "<active_change.title>" --change-id <active_change.id>{{/update_active_change}}{{#set_plan_path}} --set-plan-path ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"{{/set_plan_path}}{{#update_change}} --update-change{{/update_change}}{{#close_change}} --close-change{{/close_change}}{{#set_change_status}} --set-change-status <status>{{/set_change_status}}{{#no_change}} --no-change{{/no_change}}{{#set_synced}} --set-synced{{/set_synced}}{{#truncate_history}} --truncate-history <count>{{/truncate_history}}{{#update_initialized_at}} --set-initialized{{/update_initialized_at}}
+node .ai-agents/scripts/session-update.cjs --skill <skill_command_name> --summary "<concise one-line summary>"{{#update_active_change}} --new-change "<active_change.title>" --change-id <active_change.id>{{#link_subchange_to_epic}} --epic-id <active_epic.id>{{/link_subchange_to_epic}}{{/update_active_change}}{{#set_plan_path}} --set-plan-path ".ai-agents/workspace/artifacts/{active_change.id}/plan.yaml"{{/set_plan_path}}{{#update_change}} --update-change{{/update_change}}{{#close_change}} --close-change{{/close_change}}{{#set_change_status}} --set-change-status <status>{{/set_change_status}}{{#new_epic}} --new-epic "<epic_title>" --epic-id <epic_id>{{/new_epic}}{{#set_epic_path}} --set-epic-path <epic_path>{{/set_epic_path}}{{#set_epic_status}} --set-epic-status <status>{{/set_epic_status}}{{#close_epic}} --close-epic{{/close_epic}}{{#no_change}} --no-change{{/no_change}}{{#set_synced}} --set-synced{{/set_synced}}{{#truncate_history}} --truncate-history <count>{{/truncate_history}}{{#update_initialized_at}} --set-initialized{{/update_initialized_at}}
 
 ```
 
@@ -49,6 +49,22 @@ If the script exits with code 0, the state update was applied successfully; ther
 {{#update_initialized_at}}
 | `--set-initialized` | Flag only, no value. Set when this skill initializes the project for the first time. | — |
 {{/update_initialized_at}}
+{{#new_epic}}
+| `--new-epic` | The title of the new epic being created (same value written to `active_epic.title`) | `"ecommerce platform"` |
+| `--epic-id` | The unique identifier of the new epic. Required when using `--new-epic`. Format: `epic-{YYYYMMDD}-{slug}`. | `"epic-20260608-ecommerce-platform"` |
+{{/new_epic}}
+{{#set_epic_path}}
+| `--set-epic-path` | The path to the written `epic.yaml` file. Sets `active_epic.epic_path`. | `".ai-agents/workspace/artifacts/epic-20260608-ecommerce-platform/epic.yaml"` |
+{{/set_epic_path}}
+{{#set_epic_status}}
+| `--set-epic-status` | The status to set on the `epics[]` entry matching `active_epic.id`. Values: `in_progress`, `done`, `abandoned`. | `done` |
+{{/set_epic_status}}
+{{#close_epic}}
+| `--close-epic` | Flag only, no value. Snapshots `active_epic` into `epics[]` with `status: done`, then clears all `active_epic` fields. | — |
+{{/close_epic}}
+{{#link_subchange_to_epic}}
+| `--epic-id` (with `--new-change`) | The parent epic id that this new sub-change belongs to. Only valid when used together with `--new-change`. | `"epic-20260608-ecommerce-platform"` |
+{{/link_subchange_to_epic}}
 
 {{#update_active_change}}
 ### Parameter semantics
@@ -56,6 +72,9 @@ If the script exits with code 0, the state update was applied successfully; ther
 | Argument | When to use | Effect on `session.yaml` |
 |----------|-------------|--------------------------|
 | `--new-change` + `--change-id` | Skill creates or identifies a new change | Sets `active_change.id`, `.title`, `.created_at`. Auto-snapshots old `active_change` into `changes[]` if non-empty. Requires both arguments together. |
+{{#link_subchange_to_epic}}
+| `--epic-id` (with `--new-change`) | Skill creates a new sub-change inside an existing epic (epic-child mode) | Writes `active_change.epic_id` so the new sub-change is linked to the parent epic. Only valid when used together with `--new-change`. |
+{{/link_subchange_to_epic}}
 {{#set_plan_path}}
 | `--set-plan-path` | Skill creates a new `plan.yaml` for the active change | Sets `active_change.plan_path`. Must be used together with `--update-change`. |
 {{/set_plan_path}}
@@ -68,6 +87,15 @@ If the script exits with code 0, the state update was applied successfully; ther
 {{#set_change_status}}
 | `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
 {{/set_change_status}}
+{{#set_epic_path}}
+| `--set-epic-path` | Skill writes or moves the `epic.yaml` file (e.g., after `/mvt-decompose` writes the artifacts) | Sets `active_epic.epic_path`. |
+{{/set_epic_path}}
+{{#set_epic_status}}
+| `--set-epic-status` | Skill marks the active epic as `done` or `abandoned` (rarely used directly — `epic-update.cjs` usually drives this) | Sets `status` on the `epics[]` entry whose `id` matches `active_epic.id`. |
+{{/set_epic_status}}
+{{#close_epic}}
+| `--close-epic` | Skill closes the active epic (e.g., after archiving a completed epic) | Snapshots `active_epic` into `epics[]` with `status: done`, then clears all `active_epic` fields. |
+{{/close_epic}}
 {{#no_change}}
 | `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
 {{/no_change}}
@@ -86,6 +114,9 @@ If the script exits with code 0, the state update was applied successfully; ther
 
 | Argument | When to use | Effect on `session.yaml` |
 |----------|-------------|--------------------------|
+{{#new_epic}}
+| `--new-epic` + `--epic-id` | Skill creates a new epic (e.g., `/mvt-decompose`) | Sets `active_epic.{id,title,created_at}`. Auto-snapshots old `active_epic` into `epics[]` if non-empty. Requires both arguments together. |
+{{/new_epic}}
 {{#update_change}}
 | `--update-change` | Skill modifies a plan (i.e., after `plan.yaml` is updated) | Upserts current `active_change` into `changes[]` (with `status: active`), sets `updated_at`, sorts ascending, truncates to configured limit. |
 {{/update_change}}
@@ -95,6 +126,15 @@ If the script exits with code 0, the state update was applied successfully; ther
 {{#set_change_status}}
 | `--set-change-status` | Explicitly mark a change as `done` or `abandoned` | Sets `status` on the `changes[]` entry whose `id` matches `active_change.id`. |
 {{/set_change_status}}
+{{#set_epic_path}}
+| `--set-epic-path` | Skill writes or moves the `epic.yaml` file (e.g., after `/mvt-decompose` writes the artifacts) | Sets `active_epic.epic_path`. |
+{{/set_epic_path}}
+{{#set_epic_status}}
+| `--set-epic-status` | Skill marks the active epic as `done` or `abandoned` (rarely used directly — `epic-update.cjs` usually drives this) | Sets `status` on the `epics[]` entry whose `id` matches `active_epic.id`. |
+{{/set_epic_status}}
+{{#close_epic}}
+| `--close-epic` | Skill closes the active epic (e.g., after archiving a completed epic) | Snapshots `active_epic` into `epics[]` with `status: done`, then clears all `active_epic` fields. |
+{{/close_epic}}
 {{#no_change}}
 | `--no-change` | Skill should not be associated with any change | Forces `history[].change_id` to empty string, skipping the `active_change.id` fallback. |
 {{/no_change}}

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

@@ -1,3 +1,15 @@
+## Epic-Child Mode (Pre-check)
+
+**When**: `active_epic.id` is non-empty AND `active_change.id` is empty.
+
+In this state the user is starting a new sub-change within an existing epic. Read `epic.yaml` via `active_epic.epic_path` and determine the scenario:
+
+| Scenario | User message | Handling |
+|----------|-------------|----------|
+| A | Empty | Auto-use `current_change` child's scope from `epic.yaml` as the requirement input. Proceed to Step 3. |
+| B | Supplements current child | Merge user message with `current_change` child's scope. Proceed to Step 3. |
+| C | Points to different child | Locate target in `children[]`. If `depends_on` has unfinished prerequisites → warn and ask to confirm forced reorder (y/n). If deps satisfied → confirm switch (y/n). On confirmed reorder: call `epic-update.cjs --epic <epic_path> --switch-active <target_id>`. If target not in `children[]` → offer to treat as independent change (exit epic-child mode) or `--add-child`. |
+
 ## Execution Flow
 
 ### Step 1: Load Requirements
@@ -10,7 +22,33 @@
 - Extract business rules and constraints
 - Note assumptions made
 
-### Step 3: Assess Complexity (Quick Path Detection)
+### Step 3: Assess Scale (Epic Detection)
+- **What**: evaluate whether the input is an epic-scale requirement that should be decomposed into multiple sub-changes via `/mvt-decompose`.
+- **Signals**:
+
+  | Signal type | Signal | Example |
+  |-------------|--------|---------|
+  | Strong | Whole system / platform scope | "Build an e-commerce system" |
+  | Strong | Input is a multi-feature design manual | "Implement based on this design manual" |
+  | Strong | Multiple independent deliverable capability domains | Auth + Catalog + Cart + Payment |
+  | Weak (corroboration only) | Multiple actors with multiple independent main flows | -- |
+  | Weak (corroboration only) | No single cohesive acceptance criterion | -- |
+
+- **Trigger**: any strong signal, OR (strong + 2+ weak). Weak signals alone never trigger.
+
+- **Branches**:
+
+  | Condition | Action |
+  |-----------|--------|
+  | Epic detection hits | Ask: "This looks like an epic-level requirement (multiple independent capability domains). Use `/mvt-decompose` to decompose it first? (y / n / show-signals)" |
+  | `y` | Do NOT write `analysis.md`. Guide to `/mvt-decompose`. |
+  | `n` | Continue standard analysis (Steps 4-7). Cheap reversal path. |
+  | `show-signals` | Display matched signals, re-prompt. |
+  | Epic misses | Fall through to Step 4 (Quick Path Detection). |
+
+- **Epic-child mode note**: When operating in epic-child mode (scenarios A or B from the pre-check), Step 3 should treat the selected child scope as the intended change boundary. Do not re-route to `/mvt-decompose` unless the user explicitly expands the request beyond that child or the scope is clearly still epic-scale (e.g., the child scope itself contains multiple independent capability domains that were not part of the original decomposition rationale).
+
+### Step 4: Assess Complexity (Quick Path Detection)
 - **What**: evaluate whether this requirement qualifies as a simple change suitable for the quick development path via `/mvt-quick-dev`.
 - **How**: check each criterion in the table below. ALL criteria must pass for the quick path to be offered.
 
@@ -40,30 +78,30 @@
     - Scope: ✗ touches auth middleware, user model, login UI, OAuth callback handler, config (5+ files)
     - No new concepts: ✗ introduces external IdP and OAuth callback contract
     - No integration concerns: ✗ new external dependency (Google IdP)
-    → Proceed with standard analysis flow (Steps 4-6).
+    → Proceed with standard analysis flow (Steps 5-7).
 
 - **Branches**:
 
   | Condition | Action |
   |-----------|--------|
   | ALL criteria pass | Ask user: "This appears to be a simple change (1-3 files, no architectural impact). Use /mvt-quick-dev for faster execution? (y / n / show-criteria)" |
-  | ANY criterion fails | Proceed with standard analysis flow (Steps 4-6) |
+  | ANY criterion fails | Proceed with standard analysis flow (Steps 5-7) |
   | Ambiguous (2-3 criteria unclear) | Proceed with standard analysis; do NOT offer quick path |
 
 - **On user choice**:
   - "y" -- Do NOT write an analysis artifact. Summarize the requirement understanding in conversation and recommend `/mvt-quick-dev` directly. Set `active_change` if one doesn't exist, so `/mvt-quick-dev` can reference the current work context.
-  - "n" -- Continue with full analysis flow (Steps 4-6).
+  - "n" -- Continue with full analysis flow (Steps 5-7).
   - "show-criteria" -- Display the assessment results (pass/fail per criterion), then re-prompt with y/n.
 
-### Step 4: Detect Ambiguities
+### Step 5: Detect Ambiguities
 - Check for unclear requirements
 - Check for missing information
 - Check for conflicting requirements
 
-### Step 5: Generate Clarification Questions
+### Step 6: Generate Clarification Questions
 - If ambiguities found -> List each with specific question, prioritized by impact
 - If no ambiguities -> Skip this step
 
-### Step 6: Update Workspace
-1. Generate change-id: `{YYYYMMDD}-{slug}` format (e.g., `20260425-user-authentication`)
+### Step 7: Update Workspace
+1. Generate change-id: `{YYYYMMDD}-{slug}` format (e.g., `20260425-user-authentication`). Slug constraints: lowercase ASCII, kebab-case, `[a-z0-9-]+`, 1-4 words.
 2. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/analysis.md`

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

@@ -42,7 +42,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
@@ -76,6 +76,7 @@ sections:
     params:
       current_skill: mvt-analyze
       update_active_change: true
+      link_subchange_to_epic: true
 
   - type: shared
     source: sections/footer-next-steps.md
@@ -83,7 +84,10 @@ sections:
       current_skill: mvt-analyze
       conditional_suggestions:
         conditions:
-          - condition: "user chose quick path in Step 2.5"
+          - condition: "epic-scale detected in Step 3 (Epic Detection) and user chose y"
+            primary: "mvt-decompose"
+            primary_desc: "Decompose this epic-scale requirement into sub-changes"
+          - condition: "user chose quick path in Step 4 (Quick Path Detection)"
             primary: "mvt-quick-dev"
             primary_desc: "Implement this simple change quickly"
           - condition: "default"