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

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

@@ -1,32 +1,91 @@
-## Execution Flow
-
-### Step 1: Load Design Context
-- Read architecture design from artifacts
-- Read module structure from `project-context.yaml`
-- Read coding standards if available
-- Identify files to create or modify
-
-### Step 2: Plan Implementation
-- Map design components to file structure
-- Define implementation order (dependencies first)
-- Identify shared utilities or base classes needed
-
-### Step 3: Implement Code
-- Follow architecture module boundaries
-- Use interfaces defined in design
-- Apply coding standards
-- Add error handling at system boundaries
-- Include inline comments for complex logic only
-
-### Step 4: Verify Design Compliance
-- Check each file against its designated module/layer
-- Verify dependency direction (no layer violations)
-- Confirm interface contracts are satisfied
-
-### Step 5: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `progress.implement: done`
-   - Set `session.last_command: "/mvt-implement"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-2. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/implementation.md`
-3. Write the actual code files to the project
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - The actual source files referenced in the design's `File Structure` and `Change Tracking` sections.
+- **Fallback**:
+  - If `design.md` is missing, surface a WARN and ask the user whether to (a) run `/mvt-design` first or (b) proceed using their conversational description as the design (mark artifact with "Source: conversation only").
+  - If `coding-standards.md` is missing, fall back to language/framework defaults inferred from `project-context.yaml`.
+
+### Step 2: Plan the Implementation
+- **What**: produce an ordered file list with the smallest possible commit boundary per group.
+- **How**:
+  1. Take `Change Tracking` from `design.md` as the source of truth for which files are in scope.
+  2. Topologically order files by dependency: domain entities -> repositories/adapters -> use-case/services -> controllers/UI.
+  3. Group consecutive files that share a single conceptual change into one commit boundary.
+  4. For each file, decide: `create | modify | delete`, and write a one-line intent.
+- **Plan-aware behavior**: if `plan.yaml` is present, restrict scope to the files implied by `current_task` (cross-reference `plan.tasks[*].artifacts.files`); do NOT silently expand into other tasks.
+- **Output of this step**: an in-conversation list shown to user as a preview, with no write yet.
+
+### Step 3: Confirm Scope (when needed)
+- **Confirm before writing if any are true**:
+  - The plan touches > 5 files.
+  - The plan introduces a new public API (exported symbol, HTTP endpoint, CLI flag).
+  - The plan deletes existing code (delete count > 0).
+  - The plan deviates from `design.md` (e.g., adds files not in `Change Tracking` or skips files listed there).
+- **Otherwise**: proceed silently.
+- **On deviation from design**: explain the deviation reason in one line; if the deviation is structural (new module, layer change, interface break), STOP and recommend re-running `/mvt-design`.
+
+### Step 4: Implement Code
+- **What**: write/modify the planned files, one commit-group at a time.
+- **How**:
+  1. For each commit-group: write all files, then move on. Do not interleave groups.
+  2. Follow `coding-standards.md`. Match the surrounding code style if standards are silent.
+  3. Respect module/layer rules from `project-context.md`. Forbidden imports must NOT appear; use the abstractions defined in `design.md`'s `Key Interfaces`.
+  4. Add error handling at system boundaries only (HTTP, DB, external API, file IO, message bus). Do NOT add try/catch around internal calls "just in case".
+  5. Inline comments only for: non-obvious algorithmic choices, deliberate workarounds with a reason, interface contracts not expressible in code. Never narrate WHAT the code does.
+  6. Do NOT introduce abstractions, helpers, or feature flags beyond what the task requires.
+
+### Step 5: Verify Design Compliance
+- **What**: confirm the implementation matches the design before writing the artifact.
+- **How**: run the checks below. Each is either Auto (mechanical / scriptable / type-checker) or Manual (read the design + diff).
+
+  | Check | Mode | Action on failure |
+  |-------|------|-------------------|
+  | Files touched == Change Tracking ± deviation noted | Auto (compare lists) | Update artifact's deviation log OR revert extras |
+  | Each file lives in the module/layer assigned by `Module Design` | Auto (path match against design table) | Move file or mark deliberate exception with rationale |
+  | Public interfaces match `Key Interfaces` (signatures, endpoints) | Auto (grep for declarations) | Adjust to match OR raise as deliberate change requiring `/mvt-design` re-run |
+  | Forbidden cross-layer imports absent | Auto (grep import paths against `project-context.md` rules) | BLOCK -- must fix before artifact write |
+  | Error handling lives only at boundaries listed in design | Manual (read code) | Refactor or document why an interior catch was needed |
+  | No new external deps not listed in `design.md` ADRs | Auto (diff package manifests) | Either remove or add an ADR via `/mvt-design` |
+
+- **On any BLOCK failure**: stop, fix, re-run Step 5. Do not proceed to Step 6.
+
+### Step 6: Run Quick Self-Check
+- **What**: light-weight verification before handing off to `/mvt-review` or `/mvt-test`.
+- **How**:
+  1. If a type-checker is configured for the project (`tsc`, `mypy`, `cargo check`, etc.), run it on changed files only. Surface failures.
+  2. If a fast-running test target exists for the affected module, suggest the command but do not auto-run unless user explicitly approved.
+  3. UI/frontend changes: per project rules, ask user to verify in browser; do NOT claim "tested" if you only ran type-check.
+
+### Step 7: Write Artifact
+- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/implementation.md`.
+- **Template**: `.ai-agents/skills/_templates/implement-output.md` (custom override at `_templates/custom/...` takes precedence).
+- **Required content** (mapped to template headings):
+  - `Implementation Summary` -- one paragraph: what was built, scope.
+  - `Files Touched` -- table: path | create/modify/delete | one-line intent.
+  - `Design Compliance` -- summary of Step 5 checks (passed / deviated, with reasons).
+  - `Deviations from Design` -- empty list is acceptable; otherwise list each deviation with rationale.
+  - `Self-Check Results` -- type-check status, suggested test commands (Step 6).
+  - `Open TODOs` -- anything deferred for `/mvt-review`, `/mvt-test`, or follow-up changes.
+- The actual source code goes to the project tree; the artifact is a record, not the code itself.
+
+### Step 8: Plan-Aware Progress Hint (if applicable)
+- If `plan.yaml` exists and a single `current_task` covers this implementation, suggest the user run `/mvt-update-plan <task-id> done` (or `blocked` with reason).
+- Do NOT modify `plan.yaml` directly from this skill; it is owned by `/mvt-update-plan`.
+- Do NOT modify `recent_changes` directly; it is owned by `/mvt-plan-dev` / `/mvt-update-plan`.
+
+### Step 9: (session update handled by shared section)
+- Standard `skill_history` entry must include `change_id`. All other state mutations are delegated.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `design.md` missing | WARN, ask user; if they proceed, mark artifact "Source: conversation only" and skip Step 5 design-match checks |
+| Implementation reveals the design is infeasible | STOP at Step 4, document the blocker in conversation, recommend `/mvt-design` re-run -- do not silently improvise an alternative |
+| Type-checker fails on pre-existing errors unrelated to the change | Note in artifact, do not attempt blanket fixes outside scope |
+| User aborts at Step 3 confirmation | Do not write any source files or artifact |
+| File listed in `Change Tracking` no longer exists in the working tree | Surface, ask user whether design is stale or file was deleted in a parallel change |
+| Implementation must touch a file outside the active project (other repo / submodule) | STOP -- this is out of scope for `/mvt-implement`; surface and ask user to plan it as a separate change |
+| Plan task is `blocked` or `done` already | Refuse to implement that task; ask user to pick another `current_task` or run `/mvt-update-plan` |

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-implement/SKILL.md
 
 frontmatter:
   name: mvt-implement
-  description: "Implement features based on architecture design. Writes production code following established patterns and design blueprints. Use when user wants to implement a feature or write code."
+  description: "Implement features based on architecture design. This skill should be used when user wants to implement a feature, write production code, or translate design blueprints into working code."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Write production code based on architecture designs. Follow established patterns, module boundaries, and coding standards. This is the third phase in the full workflow: analyze -> design -> implement -> review -> test.
+      Write production code based on architecture designs. Follow established module boundaries, layer constraints, and coding standards.
 
   - type: shared
     source: sections/role-header.md
@@ -36,15 +36,13 @@ sections:
 
   - type: shared
     source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - ".ai-agents/knowledge/patterns/{pattern.active}/ -- Active architecture pattern knowledge"
-        - ".ai-agents/knowledge/principle/coding-standards.md -- Project coding standards"
-        - ".ai-agents/workspace/artifacts/{active_change.id}/ -- Analysis and design artifacts"
 
   - type: shared
     source: sections/activation-load-config.md
 
+  - type: shared
+    source: sections/output-language-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -52,45 +50,31 @@ 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"
+          field: "modules in project-context.md"
           level: "WARN"
-          message: 'Architecture pattern not set. Suggest `/mvt-init`." (allow user to proceed)'
-        - order: "4"
-          field: "modules in architecture"
-          level: "WARN"
-          message: 'No architecture defined. Run `/mvt-design` first." (allow user to proceed)'
-
-  - type: inline
-    content: |
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
+          message: "No architecture defined. Run `/mvt-design` 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/implement-output.md`
-
+      ## Artifact Structure
+      Read the document structure template from: `.ai-agents/skills/_templates/implement-output.md`
       If a custom version exists at `.ai-agents/skills/_templates/custom/implement-output.md`, use the custom version instead.
+      The template defines section headings only. Generate content for each section based on implementation results.
+      Write the artifact to: `.ai-agents/workspace/artifacts/{change-id}/implementation.md`
 
-      Fill the template placeholders with the implementation 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: "Review the implementation"
-      next_alternatives:
-        - skill: mvt-test
-          when: "Write tests for the implementation"
+      current_skill: mvt-implement

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

@@ -1,49 +1,164 @@
-## Execution Flow
-
-### Step 1: Project Discovery
-- Scan project root for:
-  - Package managers (package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, etc.)
-  - Framework config files (.eslintrc, tsconfig.json, vite.config, etc.)
-  - Source directories (src/, lib/, app/, etc.)
-  - Test directories (tests/, __tests__/, spec/, etc.)
-
-### Step 2: Tech Stack Detection
-- Identify primary language
-- Identify frameworks and libraries
-- Identify build tools
-- Identify test framework
-
-### Step 3: Architecture Pattern Suggestion
-- Analyze directory structure against known patterns
-- Compare with available patterns in `.ai-agents/knowledge/patterns/`
-- Rank pattern matches by confidence
-- Present recommendation with alternatives
-
-Available patterns:
-1. `ddd` -- Domain-Driven Design
-2. `clean-architecture` -- Layer separation with dependency inversion
-3. `frontend-react` -- React/Next.js frontend
-4. `generic` -- Simple projects without specific architecture
-
-### Step 4: User Confirmation
-- Present detected info and suggested pattern
-- Wait for user to confirm or select alternative
-- Options: `yes` (accept), pattern name (select different), `analyze` (create custom), `none` (skip)
-
-### Step 5: Update Workspace
-1. Write `.ai-agents/workspace/project-context.yaml`:
-   - Set `project.name`, `project.type`, `project.root`
-   - Set `tech_stack` (language, framework, build_tool, test_framework)
-   - Set `architecture.pattern` if selected
-2. Write `.ai-agents/workspace/session.yaml`:
-   - Set `session.initialized_at` to current timestamp
-   - Set `session.last_command: "/mvt-init"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-3. Write `.ai-agents/config.yaml`:
-   - Set `pattern.active` to selected pattern
-
-### Step 6 (--deep only): Extended Analysis
-- Map module structure (directories -> modules)
-- Identify key entities and services
-- Map dependency relationships
-- Generate architecture overview diagram
+## Execution Flow
+
+### Step 1: Project Discovery
+
+Scan the project root systematically to identify all projects and their structure.
+
+#### 1.1 Root-level file scan (priority order)
+
+Check for these files in order of detection priority:
+
+| Priority | File | Indicates |
+|----------|------|-----------|
+| 1 | `package.json` | Node.js / JavaScript / TypeScript |
+| 2 | `requirements.txt` / `pyproject.toml` / `setup.py` | Python |
+| 3 | `go.mod` | Go |
+| 4 | `Cargo.toml` | Rust |
+| 5 | `pom.xml` / `build.gradle` | Java / JVM |
+| 6 | `*.sln` / `*.csproj` | .NET |
+| 7 | `Gemfile` | Ruby |
+| 8 | `mix.exs` | Elixir |
+
+If **multiple** package managers are detected at root level → flag as **monorepo candidate** and identify primary vs secondary languages.
+
+If **no** package manager is detected → check for:
+- Source directories (`src/`, `lib/`, `app/`) → infer language from file extensions
+- Any code files at all → minimal detection
+- Empty directory → warn user: "This appears to be an empty project. Initialize with minimal config?"
+
+#### 1.2 Multi-project detection
+
+After root-level scan, check for sub-projects:
+
+| Indicator | Pattern | Example |
+|-----------|---------|---------|
+| Monorepo tools | `packages/`, `apps/`, `libs/`, `services/` | Turborepo, Nx, Lerna |
+| Workspace config | `workspaces` in `package.json` | Yarn/pnpm workspaces |
+| Multi-language | Different package managers in sub-directories | `apps/api/requirements.txt` + `apps/web/package.json` |
+| Service-oriented | `services/` or `cmd/` with independent configs | Microservices |
+| Independent sub-dirs | Multiple directories each with own package file | Multi-project repo |
+
+For each detected sub-project:
+1. Identify its root path (relative to repo root)
+2. Repeat Step 1.1 scan within that path
+3. Assign a unique `name` based on directory name or package name
+
+If no sub-projects detected → single project with `name="default"`, `path="."`
+
+#### 1.3 Directory structure scan
+
+- Source directories: `src/`, `lib/`, `app/`, `cmd/`, `internal/`, `pkg/`
+- Test directories: `tests/`, `__tests__/`, `spec/`, `test/`, `*_test/`
+- Config directories: `config/`, `configs/`, `.config/`
+- Framework-specific: `.eslintrc*`, `tsconfig.json`, `vite.config.*`, `next.config.*`, `Dockerfile`, `docker-compose.*`
+
+### Step 2: Tech Stack Detection
+
+For each detected project, determine:
+
+- **Primary language**: The language with the most files / deepest structure
+- **Secondary languages**: Other detected languages (if any)
+- **Framework**: Extract from package.json dependencies, requirements.txt, go.mod, etc.
+- **Build tool**: webpack, vite, rollup, cargo, maven, gradle, etc.
+- **Test framework**: jest, pytest, go test, JUnit, etc.
+
+### Step 3: Project Type Inference
+
+Based on detected files and structure, infer the project type for each project:
+
+| Signal | Inferred Type |
+|--------|---------------|
+| React / Vue / Angular / Next.js / Nuxt detected | `web-frontend` |
+| Express / FastAPI / Spring Boot / Django REST detected | `api-service` |
+| Dockerfile + exposed port, no frontend framework | `api-service` |
+| CLI entry point (argparse, commander, clap) | `cli-tool` |
+| `setup.py` / `pyproject.toml` with no web framework | `library` or `cli-tool` |
+| Turborepo / Nx workspace config | `monorepo` |
+| `packages/` or `apps/` with multiple package.json | `monorepo` |
+| Airflow / Prefect / dbt detected | `data-pipeline` |
+| Mobile framework (React Native, Flutter) | `mobile-app` |
+| No clear signals | `generic` |
+
+If uncertain between two types → prompt for user confirmation.
+
+### Step 4: User Confirmation
+
+Present the full detection summary:
+
+For each project:
+- Name, path, type
+- Tech stack (language, framework, build tool, test framework)
+
+Wait for user to confirm or adjust:
+- `yes` -- Accept all
+- Provide corrections -- User specifies which fields to change
+- `add` -- Add a project that was not auto-detected
+- `remove` -- Remove a project from the list
+
+### Step 5: Write Artifacts
+
+#### 5.1 Pre-write checks
+
+For each target file, check if it already exists:
+- If exists → compare proposed content with existing content
+- If differences found → show diff and confirm overwrite with user
+- If user declines → preserve existing file, skip that artifact
+
+#### 5.2 Write files
+
+1. Write `.ai-agents/workspace/project-context.yaml` with lean index schema:
+   ```yaml
+   projects:
+     - name: "{project_name}"
+       path: "{relative_path}"
+       type: "{project_type}"
+       tech_stack:
+         primary_language: "{language}"
+         secondary_languages: [{...}]
+         framework: "{framework}"
+         build_tool: "{build_tool}"
+         test_framework: "{test_framework}"
+   ```
+   For multi-project repos, include one entry per detected project.
+
+#### 5.3 Post-write validation
+
+After writing all files, validate:
+- `project-context.yaml` is valid YAML with `projects[]` containing at least one entry
+- Each project entry has required fields: `name`, `path`, `type`, `tech_stack.primary_language`
+- `session.yaml` is structurally intact and contains: `session`, `active_change` (with `plan_path` / `has_plan`), `recent_changes` (array), `skill_history`, `recent_actions`
+
+If any validation fails → report the specific error and offer to retry or skip.
+
+### Step 6: Refresh Mode Handling (--refresh only)
+
+When `--refresh` is specified:
+
+1. **Preserve** the following from existing files:
+   - `session.yaml` > `skill_history` and `recent_actions`
+   - `project-context.yaml` > any user-added custom fields (fields not in the standard schema)
+   - `config.yaml` > `preferences` section
+
+2. **Update** only auto-detectable fields:
+   - `tech_stack` (re-scan and update)
+   - `type` (re-infer)
+
+3. **Diff and confirm**: Show a summary of what will change vs what will be preserved. Ask for confirmation before writing.
+
+4. **Old format migration**: If existing `project-context.yaml` uses old format (has top-level `project`, `requirements`, `architecture`, `environment` keys):
+   - Wrap `project.*` as `projects[0]` with `name="default"`, `path="."`
+   - Discard `requirements`, `architecture` sections -- suggest running `/mvt-analyze-code` to regenerate
+   - Discard `environment` section
+   - Discard any `pattern` related fields
+
+### Step 7: Determine Project State (drives next-step recommendation)
+
+After Step 5 writes are committed, classify the project state to select the appropriate next_suggestions branch from registry.yaml:
+
+| Condition | Detection logic |
+|-----------|-----------------|
+| `has_existing_code` | Step 1 detected at least one source file (any language) under recognized source directories (`src/`, `lib/`, `app/`, `cmd/`, `internal/`, `pkg/`) OR a package manager file at root |
+| `empty_project` | Step 1 found no source files AND no package manager file (truly empty or docs-only repo) -- the recommended next step is `/mvt-manage-context` to manually capture context |
+| `default` | Neither condition matched (rare -- fallback path) |
+
+Pass the resolved condition to the output template so the suggested next steps section renders the matching branch from `registry.yaml > skills.mvt-init.next_suggestions.conditional[]`.

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

@@ -3,7 +3,7 @@ output: .claude/skills/mvt-init/SKILL.md
 
 frontmatter:
   name: mvt-init
-  description: "Initialize or refresh a project with comprehensive analysis. Detects tech stack, suggests architecture patterns, and sets up workspace state. Use when starting a new project or refreshing an existing one."
+  description: "Initialize or refresh a project by scanning its structure, detecting tech stack, and inferring project type. This skill should be used when starting a new project, re-initializing after structural changes, or setting up the MVTT workspace."
 
 sections:
   - type: inline
@@ -12,7 +12,7 @@ sections:
 
       ## Purpose
 
-      Initialize a project by scanning its structure, detecting the tech stack, suggesting an architecture pattern, and setting up the workspace state files. This is the entry point for the MVTT framework.
+      Initialize a project by scanning its structure, detecting tech stack, inferring project type, and writing the lean project index. This is the entry point for the MVTT framework.
 
   - type: shared
     source: sections/role-header.md
@@ -24,9 +24,14 @@ sections:
         - rule: "If `session.yaml` shows `initialized_at: \"\"` -> This is a fresh init"
         - rule: "If `session.yaml` shows existing data -> This is a refresh (preserve existing state)"
         - rule: "If no project files found -> Warn user this may be an empty project"
+        - rule: "If multiple languages detected -> Flag as monorepo candidate, identify primary language"
+        - rule: "If project type is ambiguous -> Prompt for confirmation between top candidates"
+        - rule: "If existing workspace files found on refresh -> Show diff and confirm before overwrite"
       boundaries:
         - scope: "analyze requirements"
           skill: "/mvt-analyze"
+        - scope: "analyze existing code"
+          skill: "/mvt-analyze-code"
         - scope: "design architecture"
           skill: "/mvt-design"
         - scope: "write implementation code"
@@ -38,20 +43,22 @@ sections:
 
       | Variant | Description |
       |---------|-------------|
-      | `/mvt-init` | Standard initialization (balanced scan) |
-      | `/mvt-init --light` | Quick scan, minimal analysis |
-      | `/mvt-init --deep` | Exhaustive scan, comprehensive analysis |
-      | `/mvt-init --refresh` | Re-scan existing project, preserve workspace state |
+      | `/mvt-init` | Standard initialization (scan + detect + write index) |
+      | `/mvt-init --refresh` | Re-scan existing project -- preserve user state, update auto-detectable fields, show diff before writing |
 
   - type: shared
     source: sections/activation-load-context.md
     params:
       extended_context:
         - "Scan project root for config files (package.json, requirements.txt, pom.xml, etc.)"
+        - "Scan project root for directory structure (src/, lib/, app/, tests/, etc.)"
 
   - 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,33 +68,34 @@ sections:
           level: "INFO"
           message: "This is a first-time init, proceed normally."
 
-  - 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/init-output.md`
-
-      If a custom version exists at `.ai-agents/skills/_templates/custom/init-output.md`, use the custom version instead.
 
-      Fill the template placeholders with the initialization results.
-
-      Every response MUST end with a Suggested Next Steps section.
+  - type: shared
+    source: sections/session-update.md
+    params:
+      update_initialized_at: true
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
-      next_primary: mvt-analyze
-      next_primary_desc: "Start analyzing requirements"
-      always_show:
-        - skill: mvt-status
-          desc: "View project status"
-        - skill: mvt-config
-          desc: "Adjust configuration settings"
+      current_skill: mvt-init
+      conditional_suggestions:
+        conditions:
+          - condition: "has_existing_code"
+            primary: mvt-analyze-code
+            primary_desc: "Reverse-analyze existing codebase to generate project-context.md"
+          - condition: "empty_project"
+            primary: mvt-manage-context
+            primary_desc: "Manually add project context, requirements, or team conventions"
+          - condition: "default"
+            primary: mvt-analyze
+            primary_desc: "Start analyzing requirements"
+        alternatives:
+          - skill: mvt-manage-context
+            desc: "Manually add team conventions or domain knowledge"
+          - skill: mvt-analyze
+            desc: "Start from a requirements document"
+          - skill: mvt-status
+            desc: "Inspect current project status"