@uoyo/mvtt 2.0.0-beta.0 → 2.0.0-beta.2

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

@@ -1,28 +1,132 @@
-## Execution Flow
-
-### Step 1: Understand the Issue
-- Parse user description of the bug
-- Identify affected files and modules
-- Reproduce or confirm the issue
-
-### Step 2: Root Cause Analysis
-- Generate hypotheses for the bug cause
-- Examine relevant code for each hypothesis
-- Test each hypothesis against the evidence
-- Identify the confirmed root cause
-
-### Step 3: Plan the Fix
-- Determine the minimal change required
-- Check for side effects on related code
-- Verify the fix won't break existing behavior
-
-### Step 4: Apply the Fix
-- Make the targeted code change
-- Verify fix addresses the root cause
-- Document what was changed and why
-
-### Step 5: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `session.last_command: "/mvt-fix"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-   - Do NOT update `progress` (shortcut operation)
+## Execution Flow
+
+### Step 1: Resolve Input Source
+- Determine the diagnosis source by checking in priority order:
+
+  | Priority | Source | Condition | What to Load |
+  |----------|--------|-----------|--------------|
+  | 1 | Review artifact | `review.md` exists in active change artifacts | Critical + Warning findings as fix targets |
+  | 2 | Bug detection result | `/mvt-bug-detect` was executed in the current conversation | Root cause, affected files, severity, reproduction status from conversation history |
+  | 3 | Direct user input | User provided bug description in conversation | Bug description text |
+
+- **1a. Review artifact (mvt-review output)**
+  - Read `.ai-agents/workspace/artifacts/{active_change.id}/review.md`
+  - Extract Critical + Warning findings as fix targets. For each finding: file, line range, observation, recommendation serve as pre-verified diagnosis.
+  - If multiple Critical findings exist, ask user which to address first.
+  - Skip Steps 2-4, proceed directly to Step 5.
+
+- **1b. Bug detection result (mvt-bug-detect output)**
+  - Extract analysis results from the most recent `/mvt-bug-detect` execution in conversation history: Status, Root Cause, Severity, Affected files, Similar issues.
+  - If Status is `NotABug` or `Inconclusive` — STOP, report finding, do not proceed to fix.
+  - Skip Steps 2-4, proceed directly to Step 5 with extracted context.
+
+- **1c. Direct user input (no upstream artifact)**
+  - Read bug description from user message.
+  - Execute Steps 2-4 for self-contained diagnosis.
+
+- **Fallback**: If no source yields content, ask user to describe the bug or run `/mvt-bug-detect` first.
+- **Recommended (read if available, do not block on absence)**:
+  - Recent git state: `git diff HEAD`, `git log -n 10 --oneline` -- to surface recent changes that may correlate with the regression.
+
+### Step 2: Reproduce & Localize (only for source 1c)
+**Skip this step if Step 1 resolved to source 1a (review artifact) or 1b (bug detection).**
+- **What**: confirm the bug is reproducible (or, if not reproducible, mark it explicitly as "report-only") and identify the smallest set of files that contain the suspected fault.
+- **How**:
+  1. Extract concrete signals from the bug description: error message text, stack trace frames, file paths, function/class names, input data.
+  2. For each signal, locate matching code (Grep / Glob).
+  3. Build a candidate file list with one-line justification per file.
+  4. If reproduction steps are provided, attempt to reproduce (run command, write minimal repro snippet) before forming hypotheses.
+- **Branches**:
+
+  | Condition | Action |
+  |-----------|--------|
+  | Reproducible locally | Capture observed vs expected, proceed to Step 3 |
+  | Not reproducible, signals are concrete (stack trace + paths) | Continue with static analysis only, mark "unverified repro" in fix notes |
+  | Not reproducible, signals are vague | STOP -- ask user for: minimal repro, exact error, environment, last-known-good version |
+
+### Step 3: Generate Hypotheses (only for source 1c)
+**Skip this step if Step 1 resolved to source 1a or 1b.**
+- **What**: produce 1-5 candidate root causes, each with a falsifiable check.
+- **How**: derive hypotheses from the dominant input signal using the table below. Combine sources when multiple are available.
+
+  | Dominant signal | Hypothesis sources |
+  |-----------------|--------------------|
+  | Stack trace | Top frame in user code, recently changed code in any frame, null/undefined origin, type mismatch at boundary |
+  | Error message | Exact-string search in repo, typed exception class hierarchy, library docs for that error |
+  | Recent git diff | Files changed in last N commits intersecting with localized files (Step 2), commit messages mentioning related modules |
+  | Behavioral description (no error) | Module boundary mismatches, off-by-one / null-handling, async/race, state leakage, configuration drift |
+
+- Each hypothesis must be written as: `<claim> -- evidence: <pointer> -- check: <how to verify>`.
+
+### Step 4: Verify Root Cause (only for source 1c)
+**Skip this step if Step 1 resolved to source 1a or 1b.**
+- **What**: reduce the hypothesis set to one confirmed root cause.
+- **How**:
+  1. For each hypothesis, run its check (read code, add tracing, run a focused script). Cheapest check first.
+  2. Eliminate hypotheses that fail their checks.
+  3. STOP and report if all hypotheses are eliminated -- do not invent new ones silently; ask the user for more information.
+- **Branches**:
+
+  | Result | Action |
+  |--------|--------|
+  | Exactly one hypothesis confirmed | Record as root cause, proceed to Step 5 |
+  | Multiple hypotheses still plausible | Pick the cheapest fix that addresses ALL of them, OR ask user to prioritize |
+  | Zero hypotheses survive | STOP, surface findings, request more info from user |
+
+### Step 5: Plan the Fix
+- **What**: decide the change scope and minimum-risk patch shape.
+- **How**: classify the fix using the table below. Choose the strategy that matches the smallest viable scope -- escalate only if the smaller scope cannot fully address the root cause.
+- For source 1a (review.md): each Critical/Warning finding maps to a fix; classify individually.
+- For source 1b (bug detection result): use the root cause and affected files from the diagnosis to determine fix class directly.
+- For source 1c: classify based on self-contained diagnosis from Steps 2-4.
+
+  | Fix class | Indicator | Strategy |
+  |-----------|-----------|----------|
+  | One-liner | Typo, off-by-one, missing null check, wrong constant | Apply directly, minimal review |
+  | Single-file | Logic localized to one module, no public API change | Apply, list affected callers in fix notes |
+  | Multi-module | Touches >1 module or shared utility | List impacted modules, read each call site before editing, group by commit if possible |
+  | Cross-architecture | Requires layering change, new dependency, or interface redesign | STOP -- recommend `/mvt-design` (or `/mvt-refactor` if behavior is preserved); do NOT implement here |
+
+- Identify regression risk: which existing tests cover this code? If none, decide whether to add a regression test in Step 7.
+
+### Step 6: User Confirmation
+- **When to confirm before applying**:
+  - Multi-module class or above.
+  - The fix changes a public/exported symbol or a configuration default.
+  - The reproduction was unverified (Step 2).
+  - The fix deletes existing behavior (not just adjusts it).
+- **When to apply silently**:
+  - One-liner / single-file class AND fix is purely additive or correctional AND reproduction was verified.
+- **Confirmation prompt format**: present `Root cause: ...`, `Proposed change: <files + summary>`, `Risk: <regression scope>`, then ask `Apply? (y / n / show-diff)`.
+
+### Step 7: Apply the Fix
+- For source 1a (review.md): apply fixes per finding; re-run the review's relevant checks (not reproduction) to confirm each fix addresses its finding.
+- Make the targeted code change.
+- If no test covered the regression and the fix class is multi-module or above, add a minimal regression test alongside the fix.
+- Re-run the original repro (if any) to confirm resolution.
+- If repro still fails -> revert, return to Step 3 with the new evidence.
+
+### Step 8: Write Fix Notes
+- **Path**: `.ai-agents/workspace/artifacts/{change-id}/fix-notes.md` if an `active_change` exists; otherwise inline in the conversation only (no artifact -- shortcut operation).
+- **Structure** (each section is a single paragraph or list):
+  - `Symptom` -- what the user saw / reported.
+  - `Input Source` -- "Review artifact" | "Bug detection result" | "Direct user input".
+  - `Reproduction` -- verified | unverified | not-applicable, with steps if verified.
+  - `Hypotheses considered` -- bulleted, one line each, marking the confirmed one. (Skip if source 1a or 1b provided a pre-verified root cause.)
+  - `Root cause` -- one paragraph.
+  - `Patch summary` -- files touched + one-line per file.
+  - `Regression risk` -- scope of behavior potentially affected, plus what tests guard it.
+  - `Follow-ups` -- TODOs, deferred refactors, related issues.
+
+### Step 9: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Bug is intermittent / racy | Mark reproduction as "flaky", state confidence level explicitly, prefer adding instrumentation over speculative fix |
+| Fix would require breaking a downstream API | STOP -- escalate to `/mvt-design` or `/mvt-refactor`; do not silently break contracts |
+| Root cause is in a third-party dependency | Document the upstream issue, apply a minimal local workaround clearly labeled as temporary |
+| User aborts at Step 6 | Do not write fix notes; record the diagnosis as a comment in the conversation only |
+| Fix relies on changes the user has uncommitted in another branch | Surface the conflict before editing; do not overwrite |
+| `active_change` is missing entirely | Apply fix without writing artifact (shortcut mode), summarize result in conversation |

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

@@ -1,86 +1,85 @@
-name: mvt-fix
-output: .claude/skills/mvt-fix/SKILL.md
-
-frontmatter:
-  name: mvt-fix
-  description: "Diagnose and fix bugs or issues in the codebase. Performs root cause analysis and applies targeted fixes. Use when user reports a bug, error, or wants to fix an issue."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Fix
-
-      ## Purpose
-
-      Diagnose bugs and issues, perform root cause analysis, and apply targeted fixes. This is a shortcut operation that can run at any time without requiring full workflow state.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Developer
-      role_desc: "an Implementation Specialist"
-      decision_rules:
-        - rule: "Bug description provided -> Analyze the issue, propose fix, apply after user confirms"
-        - rule: "Error message provided -> Trace to root cause, fix the source not the symptom"
-        - rule: "Multiple possible causes -> List hypotheses with evidence, verify each"
-        - rule: "Fix requires architecture change -> Stop and suggest `/mvt-design`"
-        - rule: "Fix affects other modules -> Document impact scope before applying"
-      boundaries:
-        - scope: "re-analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "evaluate architecture"
-          skill: "/mvt-design"
-        - scope: "review own fix"
-          skill: "/mvt-review"
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - "Related source files only (load based on bug description)"
-
-  - type: shared
-    source: sections/activation-load-config.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.'
-
-  - type: inline
-    content: |
-      ### Shortcut Operation Rules
-      - Can execute at any time without checking workflow prerequisites
-      - Do NOT update `progress` in `session.yaml` after completion
-      - Only update `session.last_command` and `recent_actions`
-
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/fix-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/fix-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the fix results.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      next_primary: mvt-review
-      next_primary_desc: "Verify the fix"
-      next_alternatives:
-        - skill: mvt-test
-          when: "Add regression tests"
+name: mvt-fix
+output: .claude/skills/mvt-fix/SKILL.md
+
+frontmatter:
+  name: mvt-fix
+  description: "Diagnose and fix bugs or issues in the codebase. This skill should be used when user reports a bug, encounters an error, or wants to diagnose and resolve an issue."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Fix
+
+      ## Purpose
+
+      Diagnose bugs and issues, perform root cause analysis, and apply targeted fixes. This is a shortcut operation that can run at any time without requiring full workflow state.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Developer
+      role_desc: "an Implementation Specialist"
+      decision_rules:
+        - rule: "Bug description provided -> Analyze the issue, propose fix, apply after user confirms"
+        - rule: "Error message provided -> Trace to root cause, fix the source not the symptom"
+        - rule: "Multiple possible causes -> List hypotheses with evidence, verify each"
+        - rule: "Fix requires architecture change -> Stop and suggest `/mvt-design`"
+        - rule: "Fix affects other modules -> Document impact scope before applying"
+      boundaries:
+        - scope: "re-analyze requirements"
+          skill: "/mvt-analyze"
+        - scope: "evaluate architecture"
+          skill: "/mvt-design"
+        - scope: "review own fix"
+          skill: "/mvt-review"
+        - scope: "diagnose bugs without fixing"
+          skill: "/mvt-bug-detect"
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - "Related source files only (load based on bug description)"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - type: shared
+    source: sections/activation-preflight.md
+    params:
+      checks:
+        - order: "1"
+          field: "session.initialized_at"
+          level: "WARN"
+          message: 'Session not initialized. Run `/mvt-init` first.'
+
+  - type: inline
+    content: |
+      ### Shortcut Operation Rules
+      - Can execute at any time without checking workflow prerequisites
+      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase)
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-fix
+      conditional_suggestions:
+        conditions:
+          - condition: "fix applied, root cause had wide impact"
+            primary: "mvt-review"
+            primary_desc: "Review the fix for side effects"
+          - condition: "fix applied, needs test coverage"
+            primary: "mvt-test"
+            primary_desc: "Add regression tests"
+          - condition: "bug too complex for targeted fix"
+            primary: "mvt-design"
+            primary_desc: "Design architectural solution"

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

@@ -1,70 +1,74 @@
-## Execution Flow
-
-### Step 1: Load Current State
-- Read session.yaml: check initialization, active change, phase progress
-- Read project-context.yaml: check project info completeness
-- Read config.yaml: check pattern.active
-
-### Step 2: Assess User Position
-Determine where the user is in the workflow and what to recommend:
-
-| Condition | Recommendation |
-|-----------|---------------|
-| Not initialized | `/mvt-init` -- Initialize the project |
-| Initialized, no requirements | `/mvt-analyze` -- Analyze requirements |
-| Requirements exist, no architecture | `/mvt-design` -- Design architecture |
-| Architecture exists, not implemented | `/mvt-implement` -- Implement the design |
-| Implemented, not reviewed | `/mvt-review` -- Review the code |
-| Reviewed, not tested | `/mvt-test` -- Write tests |
-| All phases complete | `/mvt-cleanup` or start new feature |
-
-### Step 3: Display Skills Catalog
-Show all available skills grouped by category:
-
-**Workflow Skills** (sequential phases):
-| Skill | Description |
-|-------|-------------|
-| `/mvt-analyze` | Analyze requirements and extract domain concepts |
-| `/mvt-analyze-code` | Reverse-analyze existing code to generate context |
-| `/mvt-design` | Create architecture design based on requirements |
-| `/mvt-implement` | Implement features based on architecture design |
-| `/mvt-review` | Code review for quality and standards compliance |
-| `/mvt-test` | Generate tests to validate implementations |
-
-**Shortcut Skills** (anytime, no prerequisites):
-| Skill | Description |
-|-------|-------------|
-| `/mvt-fix` | Diagnose and fix bugs or issues |
-| `/mvt-refactor` | Refactor code while preserving behavior |
-
-**Project Management Skills**:
-| Skill | Description |
-|-------|-------------|
-| `/mvt-init` | Initialize or refresh project setup |
-| `/mvt-status` | Show current project and workflow status |
-| `/mvt-config` | Manage framework configuration |
-| `/mvt-sync-context` | Synchronize context with code changes |
-| `/mvt-cleanup` | Clean up workspace artifacts |
-
-**Utility Skills**:
-| Skill | Description |
-|-------|-------------|
-| `/mvt-help` | Show this help information |
-| `/mvt-create-skill` | Create custom MVTT skills through guided workflow |
-| `/mvt-add-context` | Interactively add or update project context |
-| `/mvt-check-context` | Analyze context token load and optimization |
-| `/mvt-template` | View, customize, and manage output templates |
-
-### Step 4: Show Workflow Diagram
-Display the standard workflow with current position highlighted:
-
-```mermaid
-flowchart LR
-    A[analyze] --> B[design] --> C[implement] --> D[review] --> E[test]
-```
-
-Color-code based on current progress: green (done), yellow (current/recommended), gray (pending).
-
-### Step 5: Respond to User Questions
-- If user asks about a specific skill -> Provide usage details for that skill
-- If user asks "what should I do next" -> Give contextual recommendation based on Step 2
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Recommended**:
+  - `.ai-agents/knowledge/project/_generated/project-context.md` -- existence check only, to detect whether semantic context has been generated.
+- **Fallback**: any missing optional file is treated as "feature absent" for assessment purposes; do not abort. If `registry.yaml` itself is missing, surface the error and recommend `mvtt install`.
+
+### Step 2: Assess User Position
+- **What**: pick exactly one recommended next skill based on the current workspace state.
+- **How**: walk the table top-to-bottom; the first row whose condition holds wins.
+
+  | Condition | Recommendation |
+  |-----------|---------------|
+  | `session.yaml` missing or `initialized_at` empty | `/mvt-init` -- Initialize the project |
+  | Initialized AND `project-context.md` does not exist | `/mvt-analyze-code` -- Analyze existing code |
+  | No requirements (no `analysis.md` for active change AND no completed `/mvt-analyze` in `skill_history`) | `/mvt-analyze` -- Analyze requirements |
+  | No requirements, but user describes a simple change directly | `/mvt-quick-dev` -- Implement a simple change quickly |
+  | Requirements present, no `design.md` | `/mvt-design` -- Design architecture |
+  | `design.md` exists, change is large (Change Tracking lists > 5 files OR ADR includes breaking change OR > 1 new module) | `/mvt-plan-dev` -- Decompose into tracked plan |
+  | `design.md` (or `plan.yaml`) ready, no `implementation.md` | `/mvt-implement` -- Implement the design |
+  | `implementation.md` exists, no `review.md` | `/mvt-review` -- Review the code |
+  | `review.md` exists with no Critical findings, no `test-design.md` | `/mvt-test` -- Write tests |
+  | `review.md` has Critical findings | `/mvt-fix` -- Fix critical issues before continuing |
+  | All of the above complete | `/mvt-cleanup` -- Tidy artifacts, OR start a new feature with `/mvt-analyze` |
+
+### Step 3: Display Skills Catalog
+Read `registry.yaml` > `skills` section.
+Group skills by `category` field and display as tables:
+- `workflow` -> "Workflow Skills (sequential phases)"
+- `shortcut` -> "Shortcut Skills (anytime, no prerequisites)"
+- `project` -> "Project Management Skills"
+- `utility` -> "Utility Skills"
+
+For each skill, show: `/{skill-name}` | `description` field from registry.
+Sort within each group by declaration order in registry.
+
+### Step 4: Show Workflow Diagram
+Display the standard workflow with current position highlighted:
+
+```mermaid
+flowchart LR
+    A[init] --> B[analyze-code] --> C[analyze] --> D[design] --> D2[plan-dev]
+    D --> E[implement]
+    D2 --> E
+    E --> F[review] --> G[test]
+
+    C -.->|simple change| Q[quick-dev]
+```
+
+Color-code based on current progress: green (done), yellow (current/recommended), gray (pending). The "current" node is whichever skill the Step 2 table recommended; "done" is determined by the same evidence the Step 2 table consumed.
+
+### Step 5: Respond to User Questions
+- **What**: handle the user's free-form question after the catalog is rendered.
+- **How**:
+
+  | Question pattern | Response |
+  |------------------|----------|
+  | "What should I do next?" / no specific question | Repeat the Step 2 recommendation in one line, followed by a one-clause reason citing the matched condition |
+  | "What does `/mvt-X` do?" / asks about a specific skill | Read the skill's metadata from `registry.yaml`, show: name, description, category, dependencies, knowledge entries (if any), template (if any). If the skill has a `path`, mention "see SKILL.md for the full procedure" -- do NOT inline the full SKILL.md content (too large) |
+  | "Compare `/mvt-X` and `/mvt-Y`" | Pull descriptions from registry; if both are workflow skills, mention their relative position in the diagram |
+  | Asks about something not in registry | Reply: "No skill matches that. Available skills: see catalog above." Do not invent skills |
+
+### Step 6: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `registry.yaml` missing | STOP at Step 1; recommend `mvtt install`; show no catalog |
+| `session.yaml` missing | Render catalog (Step 3) and diagram (Step 4) without the "current position" highlight; Step 2 recommends `/mvt-init` |
+| `recent_changes[]` references a `plan_path` that no longer exists | Ignore for help purposes; do not warn -- `/mvt-status` is the right place for that |
+| User invokes `/mvt-help` while inside an active change with Critical review findings | Step 2's recommendation is `/mvt-fix`; surface this prominently above the catalog |
+| User asks about a custom skill (registry entry with `custom: true`) | Treat identically to built-ins; the only difference is showing `custom: true` in the metadata view |
+| Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> design -> [plan-dev] -> implement -> review -> test` |

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

@@ -1,61 +1,67 @@
-name: mvt-help
-output: .claude/skills/mvt-help/SKILL.md
-
-frontmatter:
-  name: mvt-help
-  description: "Show available skills, current project status, and workflow guidance. Use when user is new to MVTT, wants to know what commands are available, or needs guidance on what to do next."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Help
-
-      ## Purpose
-
-      Help users navigate the MVTT framework by showing available skills, current project status, and contextual guidance on what to do next. This is the entry point for new users and a quick reference for experienced ones.
-
-      ## Role
-
-      You are the **Conductor** -- a Workflow Coordinator.
-
-  - type: shared
-    source: sections/activation-load-context.md
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: inline
-    content: |
-      ### Step 3: Pre-flight Checks
-      - No blocking checks required.
-
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## Output Format
-
-      Output is generated inline (no external template). Structure:
-
-      ```markdown
-      ## MVT Help
-
-      ### Current Status
-      - **Project**: {name} ({initialized/not initialized})
-      - **Current Phase**: {phase}
-      - **Recommended Next**: `/mvt-{next}` -- {description}
-
-      ### Workflow
-      {Mermaid flowchart with current position highlighted}
-
-      ### Available Skills
-      {Skills tables grouped by category, as defined in Step 3}
-
-      ---
-      **Suggested Next Steps**:
-      - `/mvt-{recommended}` -- {description}
-      ```
+name: mvt-help
+output: .claude/skills/mvt-help/SKILL.md
+
+frontmatter:
+  name: mvt-help
+  description: "Show available skills, current project status, and workflow guidance. This skill should be used when user is new to MVTT, wants to discover available commands, or needs guidance on what to do next."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Help
+
+      ## Purpose
+
+      Navigate the MVTT framework by showing available skills, current project status, and contextual guidance on what to do next. Entry point for new users and quick reference for experienced ones.
+
+      ## Role
+
+      You are the **Conductor** -- a Workflow Coordinator.
+
+  - type: shared
+    source: sections/activation-load-context.md
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - type: inline
+    content: |
+      ### Step 3: Pre-flight Checks
+      - No blocking checks required.
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## Output Format
+
+      Output is generated inline (no external template). Structure:
+
+      ```markdown
+      ## MVT Help
+
+      ### Current Status
+      - **Project**: {name} ({initialized/not initialized})
+      - **Last Skill**: {last command from skill_history}
+      - **Recommended Next**: `/mvt-{next}` -- {description}
+
+      ### Workflow
+      {Mermaid flowchart with current position highlighted}
+
+      ### Available Skills
+      {Skills tables grouped by category, as defined in Step 3}
+      ```
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-help