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

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

@@ -0,0 +1,71 @@
+name: mvt-resume
+output: .claude/skills/mvt-resume/SKILL.md
+
+frontmatter:
+  name: mvt-resume
+  description: "Resume an in-progress development task in a new conversation. Reads session.yaml (active_change, skill_history, recent_actions) and recent artifacts to reconstruct context. Does not read git state."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Resume
+
+      ## Purpose
+
+      Reconstruct an in-progress development task in a fresh conversation by replaying state from `session.yaml`, recent artifacts, and plan.yaml (if one exists). When multiple plans are in-flight, prompt the user to select which change to resume. Use this skill at the start of a new conversation to pick up exactly where the last session left off.
+
+      ## Arguments
+
+      | Argument | Required | Description |
+      |----------|----------|-------------|
+      | `{change-id}` | No | Directly resume a specific change (skips candidate selection). Error if not found or not in_progress. |
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - rule: "Multiple in_progress plans found -> Pause and display candidate table, wait for user selection"
+        - rule: "Exactly one in_progress plan found -> Auto-select it and proceed"
+        - rule: "No plans found BUT active_change is set -> Fall back to legacy skill_history-based resume"
+        - rule: "active_change is empty AND skill_history is empty AND no plans -> Recommend `/mvt-init` or `/mvt-status`"
+        - rule: "Plan exists and has current_task -> Use current_task's skill_hint as next-step recommendation"
+        - rule: "Plan's current_task has been in_progress for >5 days -> Surface stale warning"
+        - rule: "Last skill failed or was interrupted -> Surface the failure context, suggest retry"
+      boundaries:
+        - scope: "read git state (branch, diff, commits)"
+          skill: "(Out of scope -- this skill is session-state only)"
+        - scope: "modify any files"
+          skill: "(Read-only)"
+        - scope: "run analyses or tests"
+          skill: "(Use the recommended next skill)"
+
+  - 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."
+
+  - type: file
+    source: ./business.md
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-resume

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

@@ -1,49 +1,112 @@
-## Execution Flow
-
-### Step 1: Identify Review Target
-- Latest implementation files from current change
-- Files specified by user
-- Files in current change artifacts
-
-### Step 2: Load Context
-- Read target files
-- Read project-context for architecture expectations
-- Load review checklist for active pattern (if available)
-
-### Step 3: Analyze Code
-- Check architecture compliance (layer assignments, dependencies)
-- Check code quality (functions small/focused, naming, duplication)
-- Check error handling
-- Check edge cases
-- Check readability
-- If `--aspect` specified -> Focus on that aspect
-
-### Step 4: Categorize Issues
-Classify each finding by severity:
-
-| Level | Description | Action Required |
-|-------|-------------|-----------------|
-| **Critical** | Bugs, security issues, breaks functionality | Must fix before merge |
-| **Warning** | Code quality issues, potential bugs | Should fix |
-| **Suggestion** | Improvements, best practices | Nice to have |
-
-### Step 5: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `progress.review: done`
-   - Set `session.last_command: "/mvt-review"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-2. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/review.md`
-
-## Review Checklist
-
-### Architecture Compliance
-- [ ] Follows established architecture pattern
-- [ ] Correct layer assignment
-- [ ] Proper dependency direction
-- [ ] Module boundaries respected
-
-### Code Quality
-- [ ] Functions are small and focused
-- [ ] Naming is clear and consistent
-- [ ] No code duplication
-- [ ] Proper error handling
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - The set of files to review (see Step 2 for resolution).
+- **Fallback**:
+  - If `design.md`/`implementation.md` are missing, downgrade to "code-only review": skip the design-compliance checks (Step 4 row group A) and note the limitation in the artifact.
+  - If `project-context.md` is missing, skip layer-compliance checks and note the limitation.
+
+### Step 2: Resolve Review Target
+- **What**: produce a definitive file list to review.
+- **How**: pick the FIRST source that yields a non-empty list.
+
+  | Source | Condition |
+  |--------|-----------|
+  | User-provided file paths | User passed paths/globs as arguments |
+  | `--aspect` filter | User specified an aspect; intersect aspect-relevant files with the active change's `Change Tracking` |
+  | `implementation.md` -> `Files Touched` | Active change has implementation artifact |
+  | `git diff --name-only main...HEAD` | Inside a feature branch |
+  | `git diff --name-only HEAD~1` | Last-commit fallback |
+
+- If the resolved list is empty, STOP and ask the user to specify the target.
+- If the list exceeds ~30 files, ask the user to scope down OR confirm a high-level (per-module) review depth.
+
+### Step 3: Determine Review Depth
+- **Default**: full review across all axes (Step 4).
+- `--aspect <name>`: narrow to a single axis. Supported aspects: `architecture`, `quality`, `errors`, `edge-cases`, `security`, `naming`, `tests`. Other aspects -> ask user to clarify.
+- For files >300 lines, do a structural pass first (interfaces, exports, key paths) before line-level review; do not attempt line-by-line on huge files.
+
+### Step 4: Run Review Checks
+- **What**: produce findings, each tagged with severity, location, and a concrete remedy.
+- **How**: walk the checklist below. Skip any group whose inputs were missing per Step 1 fallback notes.
+
+  **Group A -- Design / Layer Compliance** (requires design.md OR project-context.md)
+  - Each file is in the module/layer assigned by design or project-context.
+  - Dependency direction respects layer rules (no upward imports, no forbidden cross-module reaches).
+  - Public interfaces match `Key Interfaces` from design.
+  - Implementation `Deviations from Design` are documented; undocumented deviations are findings.
+
+  **Group B -- Code Quality**
+  - Functions are small and focused; flag functions > ~50 lines or with > ~3 nested control levels.
+  - Naming is clear, consistent with `naming-conventions.md`, and matches surrounding code.
+  - No duplication: same logic appearing >= 3 times warrants extraction.
+  - No premature abstraction: a single-use helper / interface / wrapper is a finding.
+  - No dead code, unused imports, commented-out blocks left behind.
+
+  **Group C -- Error Handling**
+  - Error handling appears only at system boundaries (HTTP, DB, external API, file IO, queue).
+  - Interior try/catch must have an explicit reason in a one-line comment, otherwise findable.
+  - No swallowed errors (catch without rethrow / log / explicit recovery).
+  - Error types are specific where the language supports it (no bare `catch Exception` without rethrow).
+
+  **Group D -- Edge Cases**
+  - Boundary inputs handled: empty / null / max length / negative / zero / unicode.
+  - Concurrency: shared state, async ordering, idempotency where required by design.
+  - Resource lifecycle: opened resources are closed on all paths.
+  - Off-by-one: loop bounds, slice indices, pagination cursors.
+
+  **Group E -- Tests** (if test files are in scope)
+  - Each business rule from `project-context.md` has at least one test case.
+  - Tests assert behavior, not implementation details.
+  - No `skip` / `only` / commented-out tests left in.
+  - Test names describe the scenario, not the function name.
+
+  **Group F -- Security** (if user requirements mention auth/data sensitivity OR `--aspect security`)
+  - No secrets in code or test fixtures.
+  - Input validation at every external boundary.
+  - Auth/authz checks present on every protected endpoint or operation.
+  - SQL/NoSQL/HTML rendered through parameterized / escaped APIs.
+
+### Step 5: Categorize and De-duplicate Findings
+- **Severity**: assign each finding using the table below.
+
+  | Level | Definition | Examples |
+  |-------|------------|----------|
+  | **Critical** | Bug, security flaw, broken contract, data loss risk, layer violation that breaks isolation | Swallowed exception in payment path; missing auth on protected endpoint; forbidden cross-layer import |
+  | **Warning** | Likely problem or significant quality issue: not a bug today, but high-risk or maintainability hazard | Function 200 lines; duplicated logic 3x; missing tests for a documented business rule |
+  | **Suggestion** | Improvement, polish, taste preference | Variable name could be clearer; could split a small helper; minor docstring gap |
+
+- Merge duplicate findings (same root cause appearing in multiple files) into one entry with a list of locations.
+- Each finding must include: file, line range, severity, observation, recommendation.
+
+### Step 6: Write Artifact
+- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/review.md` if `active_change` exists; else `.ai-agents/workspace/artifacts/_ad-hoc-review-{YYYY-MM-DD-HHMM}/review.md`.
+- **Template**: `.ai-agents/skills/_templates/review-output.md` (custom override at `_templates/custom/...` takes precedence).
+- **Required content** (mapped to template headings):
+  - `Review Scope` -- file list, depth, aspect filter, fallbacks applied (e.g., "design.md missing -> Group A skipped").
+  - `Summary` -- counts per severity + one-paragraph overall verdict (Approve / Approve with comments / Request changes / Block).
+  - `Critical Findings` -- one entry per finding.
+  - `Warnings`.
+  - `Suggestions`.
+  - `Skipped Checks` -- groups skipped because inputs were missing, with reason.
+  - `Recommended Next Skill` -- e.g., `/mvt-fix` for Critical, `/mvt-test` if Group E gaps, `/mvt-refactor` if Group B is dominant.
+
+### Step 7: Verdict Rule
+- Critical > 0 -> verdict is `Request changes`. Suggest `/mvt-fix`.
+- Critical = 0, Warnings > 5 -> verdict is `Approve with comments`.
+- Critical = 0, Warnings <= 5, Suggestions only -> verdict is `Approve`.
+- Code-only review (design.md missing) -> verdict cannot be higher than `Approve with comments` (call it out explicitly).
+
+### Step 8: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| Review target is generated code (build output, lockfile, vendored dep) | Skip with a one-line note in artifact; do not flag findings |
+| All Group A inputs missing | Run as code-only review; cap verdict at `Approve with comments` |
+| User asked for review but there are zero changes | STOP, report "no diff to review", do not write artifact |
+| Findings in the same file conflict (e.g., quality says "extract", architecture says "do not introduce a new module") | Defer to architecture; record the tension in `Suggestions` |
+| Implementation explicitly documents a deviation from design (in `Deviations from Design`) | Treat as accepted -- flag only if the deviation is itself problematic |
+| Reviewer finds bugs requiring discussion before fix | Mark Critical, but do NOT auto-invoke `/mvt-fix`; leave the call to the user |

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

@@ -1,106 +1,87 @@
-name: mvt-review
-output: .claude/skills/mvt-review/SKILL.md
-
-frontmatter:
-  name: mvt-review
-  description: "Perform code review for quality, standards compliance, and best practices. Identifies issues by severity and suggests improvements. Use when user wants code reviewed or quality checked."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Review
-
-      ## Purpose
-
-      Review code for quality, standards compliance, and best practices. Identify issues by severity, suggest improvements, and ensure architecture compliance. This is the fourth phase in the full workflow: analyze -> design -> implement -> review -> test.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Reviewer
-      role_desc: "a Code Quality Guardian"
-      decision_rules:
-        - rule: "Critical issue found (security, data loss, crash) -> Mark as CRITICAL, require fix before merge"
-        - rule: "Architecture violation found -> Flag for Architect, suggest `/mvt-design`"
-        - rule: "Minor style issue -> Note as suggestion, don't block"
-        - rule: "Subjective preference -> Mark as \"non-blocking\" optional improvement"
-        - rule: "Good code pattern found -> Highlight positively"
-        - rule: "Bug found -> Document with reproduction steps, suggest `/mvt-fix`"
-        - rule: "Insufficient test coverage -> Recommend specific scenarios, suggest `/mvt-test`"
-      boundaries:
-        - scope: "fix code directly"
-          skill: "/mvt-fix"
-        - scope: "make architecture decisions"
-          skill: "/mvt-design"
-        - scope: "modify source code"
-          skill: "(This is a read-only review)"
-
-  - type: inline
-    content: |
-      ## Aspect Options
-
-      | Aspect | Focus Areas |
-      |--------|-------------|
-      | `architecture` | Pattern compliance, module boundaries, dependency direction |
-      | `security` | Input validation, injection prevention, authentication |
-      | `performance` | N+1 queries, memory leaks, caching |
-      | `style` | Naming conventions, formatting, documentation |
-
-      Usage: `/mvt-review` or `/mvt-review --aspect {type}`
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - ".ai-agents/knowledge/core/review-principles.md -- Universal review principles"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Project coding standards"
-        - ".ai-agents/knowledge/patterns/{pattern.active}/review-checklist.md -- Pattern-specific checklist"
-
-  - 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: "no code to review"
-          level: "WARN"
-          message: 'No code to review. Run `/mvt-implement` first or specify files.'
-        - order: "3"
-          field: "pattern.active"
-          level: "WARN"
-          message: 'Architecture pattern not set. Suggest `/mvt-init`." (allow user to proceed)'
-
-  - 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/review-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/review-output.md`, use the custom version instead.
-
-      Fill the template placeholders with the review results.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      next_primary: mvt-fix
-      next_primary_desc: "Address critical issues"
-      next_alternatives:
-        - skill: mvt-test
-          when: "Add missing tests"
+name: mvt-review
+output: .claude/skills/mvt-review/SKILL.md
+
+frontmatter:
+  name: mvt-review
+  description: "Perform code review for quality, standards compliance, and best practices. This skill should be used when user wants code reviewed, quality checked, or to identify issues before merging."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Review
+
+      ## Purpose
+
+      Review code for quality, standards compliance, and best practices. Identify issues by severity, suggest improvements, and ensure architecture compliance.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Reviewer
+      role_desc: "a Code Quality Guardian"
+      decision_rules:
+        - rule: "Critical issue found (security, data loss, crash) -> Mark as CRITICAL, require fix before merge"
+        - rule: "Layer violation found -> Flag for Architect, suggest `/mvt-design`"
+        - rule: "Minor style issue -> Note as suggestion, don't block"
+        - rule: "Subjective preference -> Mark as \"non-blocking\" optional improvement"
+        - rule: "Good code pattern found -> Highlight positively"
+        - rule: "Bug found -> Document with reproduction steps, suggest `/mvt-fix`"
+        - rule: "Insufficient test coverage -> Recommend specific scenarios, suggest `/mvt-test`"
+      boundaries:
+        - scope: "fix code directly"
+          skill: "/mvt-fix"
+        - scope: "make architecture decisions"
+          skill: "/mvt-design"
+        - scope: "modify source code"
+          skill: "(This is a read-only review)"
+
+  - type: inline
+    content: |
+      ## Aspect Options
+
+      | Aspect | Focus Areas |
+      |--------|-------------|
+      | `architecture` | Layer compliance, module boundaries, dependency direction |
+      | `security` | Input validation, injection prevention, authentication |
+      | `performance` | N+1 queries, memory leaks, caching |
+      | `style` | Naming conventions, formatting, documentation |
+
+      Usage: `/mvt-review` or `/mvt-review --aspect {type}`
+
+  - 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: "no code to review"
+          level: "WARN"
+          message: "No code to review. Run `/mvt-implement` first or specify files."
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## Artifact Structure
+      Read the document structure template from: `.ai-agents/skills/_templates/review-output.md`
+      If a custom version exists at `.ai-agents/skills/_templates/custom/review-output.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on review results.
+      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/review.md`
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-review

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

@@ -1,24 +1,71 @@
-## Execution Flow
-
-### Step 1: Load State
-- Read `session.yaml` for progress, active change, recent actions
-- Read `project-context.yaml` for project info, tech stack, architecture
-
-### Step 2: Determine Current Phase
-- Check `progress` fields (analyze, design, implement, review, test)
-- Identify which phases are `done`, `pending`, or `in-progress`
-- Determine the current active phase
-
-### Step 3: Build Workflow Visualization
-- Generate Mermaid flowchart showing phase progression
-- Color-code phases: green (done), yellow (current), gray (pending)
-
-### Step 4: Compile Status Report
-- Project info summary
-- Progress table with phase status
-- Active change details (if any)
-- Recent actions history
-
-### Step 5: Suggest Next Step
-- Based on current progress, recommend the logical next command
-- If all phases done -> Suggest `/mvt-cleanup` or starting a new feature
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Recommended**:
+  - `.ai-agents/knowledge/project/_generated/project-context.md` -- semantic context (only checked for existence here, not parsed).
+- **Fallback / robustness**:
+  - If a YAML file is missing, mark its section as `(unavailable)` in the report and continue. Do not abort the whole skill.
+  - If a YAML file fails to parse, surface a one-line error with the file path and skip the affected section. Do not attempt automatic repair.
+  - If `session.yaml` exists but is empty (zero keys), treat as `not initialized` -> recommend `/mvt-init`.
+
+### Step 2: Build Activity Timeline
+- **What**: produce the most-recent-first list of skill_history entries with derived metadata.
+- **How**:
+  1. Read `skill_history` from `session.yaml`.
+  2. For each entry, attach: relative time (e.g., "2h ago"), `change_id` (if present), and the originating skill name.
+  3. Limit to the last 10 entries for the rendered table; keep full count separately for the summary line.
+
+### Step 3: Discover All Plans (Multi-Change Dashboard)
+- **What**: produce the canonical plan list across the workspace.
+- **How**:
+  1. Iterate `recent_changes[]` from `session.yaml`. For each entry with a `plan_path`, attempt to read the plan file.
+  2. Glob `.ai-agents/workspace/artifacts/*/plan.yaml` to find any plans not registered in `recent_changes` (mark them `unindexed`).
+  3. For each plan, extract: `change_id`, `title`, `status`, `current_task`, task progress (`done/total`), `updated_at`, `skill_hint` (from current task if present).
+  4. If a plan file is present but malformed, include a row with `(corrupt)` in the status column and mark the file path; do not abort.
+- **Branches**:
+
+  | Condition | Action |
+  |-----------|--------|
+  | No plans found anywhere | Skip the Changes Overview section entirely; render only legacy `active_change` summary |
+  | One plan found | Render Changes Overview with one row |
+  | Multiple plans found | Render Changes Overview sorted: `in_progress` desc by `updated_at` first, then `done` desc by `updated_at`, then `abandoned` last |
+  | Any plan over the cap (more than ~12 rows) | Show top 10 rows; print a `+N older changes hidden -- see artifacts/` line |
+
+### Step 4: Build the Status Report
+- Render in this order, omitting any section whose inputs were unavailable:
+
+  1. **Header** -- one-line summary: project name (from `project-context.yaml`), framework version, last synced timestamp.
+  2. **Projects** -- table: name | type | tech stack (truncated). Cap at 10 rows; collapse the rest into `+N more`.
+  3. **Semantic Context** -- one line: `project-context.md present` / `missing -- run /mvt-analyze-code`.
+  4. **Active Change** -- if `active_change` exists: id, title, current phase, start time. Else: `none`.
+  5. **Changes Overview** -- table from Step 3 (skip if no plans). Render with these columns:
+
+     | change-id | title | status | progress | current_task | last_updated |
+     |-----------|-------|--------|----------|--------------|--------------|
+  6. **Skill History** -- last 5 rows of the timeline from Step 2.
+  7. **Recent Actions** -- compact list (max 5).
+
+- Hard cap: total rendered output should not exceed ~120 lines. If it would, truncate Skill History and Recent Actions first; never truncate the active change or Changes Overview header rows.
+
+### Step 5: Suggest Next Step
+- Resolution order (first match wins):
+  1. `active_change` has a plan in `in_progress`, `current_task` is set -> suggest the task's `skill_hint` (or, if missing, recommend `/mvt-update-plan` to set `current_task`).
+  2. `active_change` exists but no plan -> infer next workflow phase from `skill_history` (last completed phase determines next).
+  3. No `active_change`, but `project-context.md` is missing -> suggest `/mvt-analyze-code`.
+  4. No `active_change`, no missing context -> suggest `/mvt-analyze` to start a new feature OR `/mvt-help` to browse the catalog.
+- The suggestion must be a single line: skill command + one-clause reason.
+
+### Step 6: (session update handled by shared section)
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `session.yaml` missing entirely | Render a minimal report (Projects section if available) and recommend `/mvt-init` |
+| `session.yaml` corrupt (parse error) | Surface error with file path, render Projects only, recommend `/mvt-sync-context` |
+| `recent_changes[]` references a `plan_path` that no longer exists | Include in Changes Overview with `(missing)` marker; do not delete the index entry from this skill |
+| Plan file's `current_task` references a task id not in `tasks[]` | Render `current_task` as `(invalid: <id>)`; do not attempt to fix |
+| Plan file's `status` is not one of the known values | Render the raw value verbatim; flag in skip-checks of the report |
+| Both `recent_changes[]` and the artifact glob find the same plan | Deduplicate by `change_id`; prefer the indexed entry's metadata |
+| Multiple `in_progress` plans | All rendered in Changes Overview; Step 5's suggestion picks the most recently updated; mention the count in the suggestion line |
+| Workspace contains zero projects | Render header only with a single suggestion: `/mvt-init` |