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

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-design/SKILL.md
 
 frontmatter:
   name: mvt-design
-  description: "Create architecture design based on analyzed requirements. Applies architectural patterns, defines module structure, and creates technical blueprints. Use when user wants to design system architecture."
+  description: "Create architecture design based on analyzed requirements. This skill should be used when user wants to design system architecture, define module structure, or create technical blueprints for implementation."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Design system architecture based on analyzed requirements. Apply architectural patterns and create technical blueprints that guide implementation. This is the second phase in the full workflow: analyze -> design -> implement -> review -> test.
+      Design system architecture based on analyzed requirements. Create technical blueprints that guide implementation, respecting existing project structure and constraints.
 
   - type: shared
     source: sections/role-header.md
@@ -20,12 +20,12 @@ sections:
       role: Architect
       role_desc: "a System Architecture Expert"
       decision_rules:
-        - rule: "Multiple valid patterns exist -> Present top 2-3 options with pros/cons table, recommend one"
+        - rule: "Multiple valid approaches exist -> Present top 2-3 options with pros/cons table, recommend one"
         - rule: "Trade-off affects performance vs maintainability -> Document as ADR, state the trade-off"
         - rule: "User asks for technology choice -> Evaluate against: requirements fit, team familiarity, maintenance cost"
         - rule: "Design needs breaking change -> Highlight impact scope, list affected files, propose migration"
         - rule: "Requirements are ambiguous -> Stop and ask clarification before designing"
-        - rule: "Pattern conflicts with project structure -> Report conflict, suggest pattern change via `/mvt-config`"
+        - rule: "Layer constraint violation in design -> Flag and suggest alternative that respects existing boundaries"
       boundaries:
         - scope: "write implementation code"
           skill: "/mvt-implement"
@@ -47,13 +47,14 @@ sections:
     source: sections/activation-load-context.md
     params:
       extended_context:
-        - ".ai-agents/knowledge/patterns/{pattern.active}/ -- Active architecture pattern knowledge"
-        - ".ai-agents/knowledge/core/ -- Core knowledge files"
         - ".ai-agents/workspace/artifacts/{active_change.id}/analysis.md -- Analysis from previous phase"
 
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/output-language-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -61,45 +62,35 @@ sections:
         - order: "1"
           field: "session.initialized_at"
           level: "BLOCK"
-          message: 'Session not initialized. Run `/mvt-init` first.'
+          message: "Session not initialized. Run `/mvt-init` first."
         - order: "2"
-          field: "project.name"
+          field: "projects[] in project-context.yaml"
           level: "BLOCK"
-          message: 'Project not initialized. Run `/mvt-init` first.'
+          message: "Project not initialized. Run `/mvt-init` first."
         - order: "3"
-          field: "pattern.active"
-          level: "BLOCK"
-          message: 'Architecture pattern required. Run `/mvt-init` to detect and set the pattern.'
+          field: "project-context.md"
+          level: "WARN"
+          message: "No project-context.md found. Run `/mvt-analyze-code` for better design context. (allow user to proceed)"
         - order: "4"
-          field: "requirements in project-context"
+          field: "requirements in project-context.md"
           level: "WARN"
-          message: 'No requirements found. Run `/mvt-analyze` first." (allow user to proceed)'
-
-  - type: inline
-    content: |
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
+          message: "No requirements found. Run `/mvt-analyze` first. (allow user to proceed)"
 
   - type: file
     source: ./business.md
 
   - type: inline
     content: |
-      ## Output Format
-
-      Read and use the output template from: `.ai-agents/skills/_templates/design-output.md`
-
+      ## Artifact Structure
+      Read the document structure template from: `.ai-agents/skills/_templates/design-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/design-output.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on design results.
+      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/design.md`
 
-      Fill the template placeholders with the design results.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
-      next_primary: mvt-implement
-      next_primary_desc: "Start implementing this design"
-      always_show:
-        - skill: mvt-status
-          desc: "Check current workflow progress"
+      current_skill: mvt-design

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

@@ -1,28 +1,103 @@
-## 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: Load Inputs
+- **Required**:
+  - User-provided bug description (free text, possibly with stack trace, error message, or reproduction steps).
+- **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.
+- **Fallback**: if none of the above exists, proceed using the bug description alone and note "context-light fix" in the final fix notes.
+
+### Step 2: Reproduce & Localize
+- **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
+- **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
+- **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.
+
+  | 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
+- 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.
+  - `Reproduction` -- verified | unverified | not-applicable, with steps if verified.
+  - `Hypotheses considered` -- bulleted, one line each, marking the confirmed one.
+  - `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

@@ -3,7 +3,7 @@ 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."
+  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
@@ -42,6 +42,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/output-language-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -55,32 +58,15 @@ sections:
     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.
+      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase)
 
   - 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/session-update.md
 
   - 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"
+      current_skill: mvt-fix

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

@@ -3,7 +3,7 @@ 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."
+  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
@@ -12,7 +12,7 @@ sections:
 
       ## 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.
+      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
 
@@ -24,14 +24,14 @@ sections:
   - 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.
 
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
   - type: file
     source: ./business.md
 
@@ -46,7 +46,7 @@ sections:
 
       ### Current Status
       - **Project**: {name} ({initialized/not initialized})
-      - **Current Phase**: {phase}
+      - **Last Skill**: {last command from skill_history}
       - **Recommended Next**: `/mvt-{next}` -- {description}
 
       ### Workflow
@@ -54,8 +54,14 @@ sections:
 
       ### Available Skills
       {Skills tables grouped by category, as defined in Step 3}
-
-      ---
-      **Suggested Next Steps**:
-      - `/mvt-{recommended}` -- {description}
       ```
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      read_only: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-help