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

package/sources/defaults/session.yaml

@@ -1,23 +1,31 @@
-# Workspace Session State
-# Simplified session state — only fields LLM actually needs
-
-session:
-  initialized_at: ""
-  last_command: ""
-
-# Current active change (created by #analyze)
-active_change:
-  id: ""
-  title: ""
-  created_at: ""
-
-# Workflow progress (simplified: pending | done)
-progress:
-  analyze: pending
-  design: pending
-  implement: pending
-  review: pending
-  test: pending
-
-# Recent actions (append-only, keep max 3)
-recent_actions: []
+# Workspace Session State
+# Supports flexible workflows -- no longer bound to a fixed pipeline
+
+session:
+  initialized_at: ""
+  last_command: ""
+
+# Current active change (id/title/created_at set by /mvt-analyze;
+# plan_path/has_plan set by /mvt-plan-dev once a plan is generated)
+active_change:
+  id: ""
+  title: ""
+  created_at: ""
+  plan_path: ""
+  has_plan: false
+
+# Recent changes with active plans (max 5, owned by /mvt-plan-dev and /mvt-update-plan)
+# Each entry: { id, title, plan_path, last_updated }
+# Status is the responsibility of plan.yaml (read on demand by /mvt-resume).
+recent_changes: []
+
+# Skill execution history (append-only, max 10)
+# Records which skills have been executed, replacing the old progress field
+skill_history: []
+  # - command: "/mvt-analyze"
+  #   completed_at: "2026-05-23T14:30:00"
+  #   summary: "Analyzed user authentication requirements"
+  #   change_id: ""   # set when work belongs to an active change
+
+# Recent actions (append-only, max 5)
+recent_actions: []

package/sources/knowledge/core/manifest.yaml

@@ -1,47 +1,6 @@
-id: "core"
-type: "core"
-name: "Core Knowledge"
-version: "1.0"
-description: "Actionable review principles for code quality"
-
-token_estimate:
-  total: 800
-  breakdown:
-    - file: review-principles.md
-      tokens: 800
-      load_priority: 1
-      summary: "Naming, SRP, dependency direction, error handling, duplication, state, testing checklist"
-
-loading_strategy:
-  level_1_overview:
-    description: "Read manifest only for summary"
-    tokens: 100
-    use_case: "Check available knowledge"
-
-  level_2_full:
-    description: "Load complete knowledge files"
-    tokens: 800
-    use_case: "Complete principles reference"
-
-loading:
-  priority: 1
-  auto_load: true
+id: core
+type: shared
 
 files:
-  - path: "review-principles.md"
-    description: "Actionable code review checklist: naming, SRP, dependencies, errors, duplication, state, testing"
-    required: true
-    tokens: 800
-
-attributes:
-  checklist: []
-
-scenarios:
-  - name: "Code review"
-    files: ["review-principles.md"]
-
-  - name: "Refactoring guidance"
-    files: ["review-principles.md"]
-
-  - name: "Architecture design"
-    files: ["review-principles.md"]
+  # User-added entries (origin: user) are appended by /mvt-manage-context.
+  # `mvtt update` preserves them and only rewrites origin: framework entries.

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

@@ -1,5 +1,11 @@
-### Step 2: Load Config & Apply Preferences (Config Foundation)
-Read `.ai-agents/config.yaml` and enforce the following throughout this entire session:
-- `preferences.language` → Use this language for ALL output (responses, artifact content, comments)
-- `preferences.output.no_emojis` → If true, never use emojis
-- `preferences.output.data_format` → Use this format for data sections in artifacts
+### Step 3: 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.
+
+**Other preferences**:
+- `preferences.output.no_emojis` → If true, never use emojis
+- `preferences.output.data_format` → Use this format for data sections in artifacts
+- `preferences.context_routing.relevance_threshold` → Used by `/mvt-manage-context add` for AI routing (default 70 if missing)

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

@@ -1,11 +1,26 @@
-## Activation Protocol
-
-### Step 1: Load Context (Context Foundation)
-Load the following files as foundational context:
-- `.ai-agents/workspace/session.yaml` -- Current workflow state
-- `.ai-agents/workspace/project-context.yaml` -- Project domain data
-
-Extended context for this skill:
-{{#extended_context}}
-- {{.}}
-{{/extended_context}}
+## Activation Protocol
+
+### Step 1: Load Context (Context Foundation)
+Load the following files as foundational context:
+- `.ai-agents/workspace/session.yaml` -- Current workflow state
+- `.ai-agents/workspace/project-context.yaml` -- Project index (structural info)
+- `.ai-agents/registry.yaml` -- Available skills registry and knowledge declarations
+{{?extended_context}}
+
+Extended context for this skill:
+{{/extended_context}}
+{{#extended_context}}
+- {{.}}
+{{/extended_context}}
+
+### Step 2: Load Knowledge
+
+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)
+
+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`.
+
+Skip any path that does not exist.

package/sources/sections/activation-preflight.md

@@ -1,4 +1,14 @@
-### Step 3: Pre-flight Checks
-{{#checks}}
-{{order}}. If `{{field}}` is empty → {{level}}: "{{message}}"
-{{/checks}}
+### Step 4: Pre-flight Checks
+
+For each check below, if the condition holds, perform the action implied by its **Level**:
+
+- **WARN** -- emit the message, then ask "Continue anyway? (y/n)". Default to **y** if the user does not respond.
+- **BLOCK** -- emit the message and stop. Do not proceed until the prerequisite is satisfied.
+- **REQUIRED** -- same as BLOCK; the prerequisite is mandatory.
+- **INFO** -- emit the message and proceed; no confirmation needed.
+
+| # | Condition | Level | Message |
+|---|-----------|-------|---------|
+{{#checks}}
+| {{order}} | `{{field}}` is empty | {{level}} | {{message}} |
+{{/checks}}

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

@@ -1,9 +1,35 @@
-## Suggested Next Steps
-After completion, suggest:
-- `/{{next_primary}}` -- {{next_primary_desc}}
-{{#next_alternatives}}
-- `/{{skill}}` -- {{when}}
-{{/next_alternatives}}
-{{#always_show}}
-- `/{{skill}}` -- {{desc}}
-{{/always_show}}
+## Suggested Next Steps
+
+Recommend 2-3 relevant next skills based on the skill just completed (`{{current_skill}}`) and the current project state.
+{{#conditional_suggestions}}
+
+### Conditional Recommendations
+
+Match the current state to one of the conditions below. If none match, use `default`.
+
+{{#conditions}}
+- **`{{condition}}`** → `/{{primary}}` -- {{primary_desc}}
+{{#alternatives}}
+  - Or `/{{skill}}` -- {{desc}}
+{{/alternatives}}
+{{/conditions}}
+{{#alternatives}}
+- `/{{skill}}` -- {{desc}}
+{{/alternatives}}
+{{/conditional_suggestions}}
+{{^conditional_suggestions}}
+
+### Resolution order
+
+Infer 2-3 suggestions from:
+- `skill_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
+{{/conditional_suggestions}}
+
+### Format
+
+- `/{skill_name}` -- {when to use this skill, tailored to the current context}
+
+Do not suggest the skill that was just completed. Prioritize skills that logically follow from the work done.

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

@@ -0,0 +1,11 @@
+## Output Language Constraint (Mandatory)
+
+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/role-header.md

@@ -1,13 +1,13 @@
-## Role
-
-You are the **{{role}}** -- {{role_desc}}.
-
-### Decision Rules
-{{#decision_rules}}
-- {{rule}}
-{{/decision_rules}}
-
-### Boundaries
-{{#boundaries}}
-- Do NOT {{scope}} -> Suggest `{{skill}}`
-{{/boundaries}}
+## Role
+
+You are the **{{role}}** -- {{role_desc}}.
+
+### Decision Rules
+{{#decision_rules}}
+- {{rule}}
+{{/decision_rules}}
+
+### Boundaries
+{{#boundaries}}
+- Do NOT {{scope}} (use `{{skill}}` instead)
+{{/boundaries}}

package/sources/sections/session-update.md

@@ -0,0 +1,47 @@
+{{?read_only}}
+## State Update
+
+This skill is read-only and does NOT modify `.ai-agents/workspace/session.yaml`. No state mutation, no `skill_history` append, no `recent_actions` append.
+{{/read_only}}
+{{^read_only}}
+## State Update (Required)
+
+After execution, update `.ai-agents/workspace/session.yaml` with the following fields.
+
+### Mandatory (every skill must set)
+
+- `session.last_command`: Set to the current skill command (e.g., `"/mvt-analyze"`)
+- `skill_history`: Append entry:
+  ```yaml
+  - command: "/{skill-name}"
+    completed_at: "{current timestamp ISO 8601}"
+    summary: "{one-line summary of what was accomplished}"
+    change_id: "{active_change.id if set, otherwise empty string}"
+  ```
+  Keep max 10 entries. If exceeds, drop the oldest. The `change_id` field enables `/mvt-resume` to filter history per change when multiple changes are in flight.
+- `recent_actions`: Append one-line summary with format:
+  `[{YYYY-MM-DD HH:MM}] /{command}: {one-line summary}`
+  Keep max 5 entries. If exceeds, drop the oldest.
+{{#update_active_change}}
+
+### Conditional (set only when applicable)
+
+- `active_change.id`: Set when this skill creates a new change
+- `active_change.title`: Set when this skill creates a new change
+- `active_change.created_at`: Set when this skill creates a new change
+{{/update_active_change}}
+{{#update_initialized_at}}
+
+### Conditional (set only when applicable)
+
+- `session.initialized_at`: Set to current timestamp when this skill initializes the project
+{{/update_initialized_at}}
+
+### Forbidden
+
+- Do NOT update fields not listed above
+- Do NOT overwrite `active_change` unless this skill creates a new change
+- Do NOT modify `skill_history` entries other than appending a new one
+- Do NOT modify `recent_changes` -- it is owned by `/mvt-plan-dev` and `/mvt-update-plan`
+- Do NOT modify `active_change.plan_path` or `active_change.has_plan` -- these are owned by `/mvt-plan-dev`
+{{/read_only}}

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

@@ -1,33 +1,69 @@
-## Execution Flow
-
-### Step 1: Load Requirements
-- If file path provided as argument -> Read that file
-- If requirements exist in `.ai-agents/workspace/requirements/` -> List files, ask user to select
-- Otherwise -> Use requirements text from user message
-
-### Step 2: Extract Information
-- Identify features and functionality
-- Identify actors and stakeholders
-- Extract business rules and constraints
-- Note assumptions made
-
-### Step 3: Detect Ambiguities
-- Check for unclear requirements
-- Check for missing information
-- Check for conflicting requirements
-
-### Step 4: Generate Clarification Questions
-- If ambiguities found -> List each with specific question, prioritized by impact
-- If no ambiguities -> Skip this step
-
-### Step 5: Update Workspace
-1. Generate change-id: `{YYYYMMDD}-{slug}` format (e.g., `20260425-user-authentication`)
-2. Update `.ai-agents/workspace/session.yaml`:
-   - Set `active_change.id` and `active_change.title`
-   - Set `active_change.created_at`
-   - Set `progress.analyze: done`
-   - Set `session.last_command: "/mvt-analyze"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-3. Update `.ai-agents/workspace/project-context.yaml`:
-   - Write to `requirements` section (features, actors, business_rules, clarifications)
-4. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/analysis.md`
+## Execution Flow
+
+### Step 1: Load Requirements
+- If file path provided as argument -> Read that file
+- Otherwise -> Use requirements text from user message
+
+### Step 2: Extract Information
+- Identify features and functionality
+- Identify actors and stakeholders
+- Extract business rules and constraints
+- Note assumptions made
+
+### Step 3: 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.
+
+  | Criterion | Pass condition |
+  |-----------|----------------|
+  | Scope | Affects ≤ 3 files (estimate from the requirement's mention of modules/features) |
+  | No new concepts | No new domain entities, no new API contracts, no new module boundaries |
+  | No architectural impact | No ADR needed; fits existing module/layer structure |
+  | Clear specification | No ambiguities detected in Step 2 (or all ambiguities resolved by user confirmation) |
+  | No integration concerns | No new external dependencies, no cross-service changes, no async/event flows |
+  | Single actor | Only one user role or system actor involved |
+
+- **Worked Examples**:
+
+  - **Example 1 (PASS — offer quick path)**
+    > "Increase the password reset email expiration from 30 minutes to 2 hours."
+    - Scope: 1 config file ✓
+    - No new concepts ✓ (existing flow)
+    - No architectural impact ✓
+    - Clear specification ✓
+    - No integration concerns ✓
+    - Single actor ✓
+    → Offer `/mvt-quick-dev`.
+
+  - **Example 2 (FAIL — proceed with standard analysis)**
+    > "Add SSO login via Google for our user portal."
+    - 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).
+
+- **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) |
+  | 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).
+  - "show-criteria" -- Display the assessment results (pass/fail per criterion), then re-prompt with y/n.
+
+### Step 4: Detect Ambiguities
+- Check for unclear requirements
+- Check for missing information
+- Check for conflicting requirements
+
+### Step 5: 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`)
+2. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/analysis.md`

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

@@ -1,89 +1,90 @@
-name: mvt-analyze
-output: .claude/skills/mvt-analyze/SKILL.md
-
-frontmatter:
-  name: mvt-analyze
-  description: "Analyze requirements documents and extract domain concepts. Use when user wants to analyze requirements, extract features, or start the analysis phase of development workflow."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Analyze
-
-      ## Purpose
-
-      Analyze requirements and extract domain concepts as the foundation for architecture design and implementation. This is the first phase in the full workflow: analyze -> design -> implement -> review -> test.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Analyst
-      role_desc: "a Requirements Analysis Expert"
-      decision_rules:
-        - rule: "Clear requirements -> Proceed with structured analysis"
-        - rule: "Ambiguities found -> Stop and ask clarification first"
-        - rule: "Multiple interpretations -> List all, ask user to choose"
-        - rule: "Conflicts detected -> Highlight explicitly, ask for resolution"
-        - rule: "Vague requirements -> Request specific examples"
-      boundaries:
-        - scope: "make architecture decisions"
-          skill: "/mvt-design"
-        - scope: "recommend technologies"
-          skill: "/mvt-design"
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - ".ai-agents/workspace/requirements/ -- Existing requirements files (if exists)"
-
-  - 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.'
-        - order: "2"
-          field: "project.name"
-          level: "WARN"
-          message: 'Project not initialized. Run `/mvt-init` first.'
-        - order: "3"
-          field: "pattern.active"
-          level: "Continue"
-          message: "analysis does not require pattern, but add warning and suggest `/mvt-init`."
-
-  - type: inline
-    content: |
-      ### 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/analyze-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/analyze-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the analysis results.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      next_primary: mvt-design
-      next_primary_desc: "Create architecture design based on this analysis"
-      always_show:
-        - skill: mvt-status
-          desc: "Check current workflow progress"
+name: mvt-analyze
+output: .claude/skills/mvt-analyze/SKILL.md
+
+frontmatter:
+  name: mvt-analyze
+  description: "Analyze requirements documents and extract domain concepts. This skill should be used when user wants to analyze requirements, extract features and business rules, or start the analysis phase of a development workflow."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Analyze
+
+      ## Purpose
+
+      Analyze requirements and extract domain concepts as the foundation for architecture design and implementation.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Analyst
+      role_desc: "a Requirements Analysis Expert"
+      decision_rules:
+        - rule: "Clear requirements -> Proceed with structured analysis"
+        - rule: "Ambiguities found -> Stop and ask clarification first"
+        - rule: "Multiple interpretations -> List all, prompt for selection"
+        - rule: "Conflicts detected -> Highlight explicitly, ask for resolution"
+        - rule: "Vague requirements -> Request specific examples"
+      boundaries:
+        - scope: "make architecture decisions"
+          skill: "/mvt-design"
+        - scope: "recommend technologies"
+          skill: "/mvt-design"
+        - scope: "write implementation code"
+          skill: "/mvt-implement"
+        - scope: "directly implement simple changes"
+          skill: "/mvt-quick-dev"
+
+  - 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: shared
+    source: sections/activation-preflight.md
+    params:
+      checks:
+        - order: "1"
+          field: "session.initialized_at"
+          level: "WARN"
+          message: 'Session not initialized. Run `/mvt-init` first.'
+        - order: "2"
+          field: "projects[] in project-context.yaml"
+          level: "WARN"
+          message: 'Project not initialized. Run `/mvt-init` first.'
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## Artifact Structure
+      Read the document structure template from: `.ai-agents/skills/_templates/analyze-output.md`
+      If a custom version exists at `.ai-agents/skills/_templates/custom/analyze-output.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on analysis results.
+      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/analysis.md`
+
+  - type: shared
+    source: sections/session-update.md
+    params:
+      update_active_change: true
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-analyze
+      conditional_suggestions:
+        conditions:
+          - condition: "user chose quick path in Step 2.5"
+            primary: "mvt-quick-dev"
+            primary_desc: "Implement this simple change quickly"
+          - condition: "default"
+            primary: "mvt-design"
+            primary_desc: "Design architecture based on analysis"
+            alternatives:
+              - skill: "mvt-analyze-code"
+                desc: "Generate code context for better design"