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

package/sources/skills/mvt-create-skill/manifest.yaml

@@ -1,79 +1,91 @@
-name: mvt-create-skill
-output: .claude/skills/mvt-create-skill/SKILL.md
-
-frontmatter:
-  name: mvt-create-skill
-  description: "Create custom MVTT skills through interactive guided workflow. Use when user wants to create a new skill, extend the framework with custom functionality, or build project-specific automation."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Custom Skill
-
-      ## Purpose
-
-      Guide users through designing and creating custom MVTT-compliant skills. Generates properly structured SKILL.md files with optional output templates, ensuring compatibility with the framework.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: Conductor
-      role_desc: "a Workflow Coordinator"
-      decision_rules:
-        - rule: "User provides skill name -> Validate and proceed with design"
-        - rule: "Name conflicts with existing skill -> Warn and ask for alternative"
-        - rule: "Skill needs output template -> Create template in `_templates/` and update manifest"
-        - rule: "Skill needs state updates -> Include session.yaml update rules"
-      boundaries:
-        - scope: "Generated skills must follow MVTT SKILL.md standard structure"
-          skill: "(constraint)"
-        - scope: "Skill names may use `mvt-` prefix or a project-specific prefix (e.g., `app-`, `proj-`)"
-          skill: "(constraint)"
-        - scope: "All custom skills MUST be registered in `registry.yaml` with `custom: true`"
-          skill: "(to prevent overwrite during framework updates)"
-        - scope: "Description field must contain effective trigger keywords"
-          skill: "(constraint)"
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        - "Load one existing SKILL.md as structural reference (e.g., `.claude/skills/mvt-status/SKILL.md`)"
-        - ".ai-agents/registry.yaml -- Registered skills list"
-
-  - type: shared
-    source: sections/activation-load-config.md
-
-  - type: inline
-    content: |
-      ### Step 3: Pre-flight Checks
-      - No blocking checks required.
-
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## Output Format
-
-      No external template -- output is the generated skill file itself plus a creation summary:
-
-      ```markdown
-      ## Custom Skill Created
-
-      - **Skill**: `/{name}`
-      - **Location**: `.claude/skills/{name}/SKILL.md`
-      - **Registry**: `registry.yaml` (custom: true)
-      - **Template**: {created/none}
-      - **Category**: {category}
-
-      You can now use `/{name}` to invoke your new skill.
-
-      ---
-      **Suggested Next Steps**:
-      - Test your new skill by running `/{name}`
-      - `/mvt-help` -- View updated skills list
-      ```
+name: mvt-create-skill
+output: .claude/skills/mvt-create-skill/SKILL.md
+
+frontmatter:
+  name: mvt-create-skill
+  description: "Create custom MVTT skills through interactive guided workflow. This skill should be used when user wants to create a new skill, extend the framework with custom functionality, or build project-specific automation."
+
+sections:
+  - type: inline
+    content: |
+      # MVT Create Skill
+
+      ## Purpose
+
+      Guide users through designing and creating custom MVTT-compliant skills. Follows a structured process: understand use cases, plan reusable resources, design the skill, generate files, and validate. Generates properly structured SKILL.md files with optional bundled resources (scripts, references, assets), manifest.yaml, and registry entries -- ensuring compatibility with the MVTT framework.
+
+  - type: shared
+    source: sections/role-header.md
+    params:
+      role: Conductor
+      role_desc: "a Workflow Coordinator"
+      decision_rules:
+        - rule: "User provides skill name -> Validate and proceed with design"
+        - rule: "Name conflicts with existing skill -> Warn and ask for alternative"
+        - rule: "Skill needs output template -> Create template in `_templates/` and update manifest"
+        - rule: "Skill needs state updates -> Include session.yaml update rules"
+        - rule: "Skill needs bundled resources -> Plan scripts/references/assets in Step 3"
+        - rule: "Usage patterns unclear -> Ask for concrete examples before proceeding"
+      boundaries:
+        - scope: "Generated skills must follow MVTT SKILL.md standard structure"
+          skill: "(constraint)"
+        - scope: "Skill names may use `mvt-` prefix or a project-specific prefix (e.g., `app-`, `proj-`)"
+          skill: "(constraint)"
+        - scope: "All custom skills MUST be registered in `registry.yaml` with `custom: true`"
+          skill: "(to prevent overwrite during framework updates)"
+        - scope: "Description field must use third-person with effective trigger keywords"
+          skill: "(constraint)"
+        - scope: "SKILL.md body target <5k words; move detailed content to references/"
+          skill: "(progressive disclosure)"
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - "Load one existing SKILL.md as structural reference (e.g., `.claude/skills/mvt-status/SKILL.md`)"
+
+  - type: shared
+    source: sections/activation-load-config.md
+
+  - type: shared
+    source: sections/output-language-constraint.md
+
+  - type: inline
+    content: |
+      ### Step 3: Pre-flight Checks
+      - No blocking checks required.
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## Output Format
+
+      No external template -- output is the generated skill files plus a creation summary:
+
+      ```markdown
+      ## Custom Skill Created
+
+      - **Skill**: `/{name}`
+      - **Agent**: {agent role}
+      - **Location**: `.claude/skills/{name}/SKILL.md`
+      - **Registry**: `registry.yaml` (custom: true)
+      - **Template**: {created/none}
+      - **Resources**: {scripts/references/assets listing, or none}
+      - **Knowledge**: {per-skill entries / shared only}
+      - **Context Budget**: SKILL.md body ~{N} words
+
+      Use `/{name}` to invoke the new skill.
+
+      ### Iteration
+      1. Use `/{name}` on real tasks
+      2. Notice struggles or inefficiencies
+      3. Update SKILL.md or bundled resources as needed
+      4. Use `/mvt-create-skill` to refine, or edit skill files directly
+      ```
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-create-skill

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

@@ -1,34 +1,116 @@
-## Execution Flow
-
-### Step 1: Review Requirements
-- Load requirements from `project-context.yaml`
-- Load analysis artifact if exists
-- Identify key architectural concerns (scalability, security, performance, etc.)
-
-### Step 2: Select Architecture Approach
-- Check active pattern in config
-- Load pattern-specific knowledge
-- If `--plan` flag -> Skip to high-level plan, omit detailed interfaces
-
-### Step 3: Design Module Structure
-- Define modules with responsibilities and layers
-- Define interfaces between modules
-- Establish dependency direction rules
-
-### Step 4: Create Data Flow Design
-- Design request/response flows
-- Define service interactions
-- Create sequence diagrams (Mermaid)
-
-### Step 5: Document Decisions
-- Record Architecture Decision Records (ADRs)
-- Include rationale, alternatives considered, and trade-offs
-
-### Step 6: Update Workspace
-1. Update `.ai-agents/workspace/session.yaml`:
-   - Set `progress.design: done`
-   - Set `session.last_command: "/mvt-design"`
-   - Append one-line summary to `recent_actions` (keep max 3)
-2. Update `.ai-agents/workspace/project-context.yaml`:
-   - Write to `architecture` section (modules, decisions, interfaces)
-3. Write artifact: `.ai-agents/workspace/artifacts/{change-id}/design.md`
+## Execution Flow
+
+### Step 1: Load Inputs
+- **Required**:
+  - Existing design artifacts of related prior changes (`artifacts/*/design.md`) -- to stay consistent.
+- **Fallback**:
+  - If `analysis.md` is missing, surface a WARN and accept the user's free-text intent as the requirement input.
+  - If `project-context.md` is missing, proceed but mark the design as "context-light" and skip the layer-compliance check in Step 4.
+
+### Step 2: Frame the Problem
+- **What**: produce a one-paragraph problem statement plus a list of explicit architectural concerns (3-7 items).
+- **How**:
+  1. From `analysis.md`, lift the goal, actors, and primary use cases.
+  2. Derive concerns by scanning the requirements for: scalability, latency, consistency, security/auth, persistence, observability, deployment, integration with existing modules.
+  3. Drop any concern that is not actually exercised by the requirements -- do not invent NFRs.
+- **Output of this step**: a Concerns Table with columns `concern | source-of-evidence | priority(must/should/nice)`.
+
+### Step 3: Choose Architecture Style
+- **What**: select the smallest viable architecture style for this change. Escalate only when concerns force it.
+- **How**: pick the row that matches the dominant concerns; multiple changes within the same project should normally pick the same style unless requirements force otherwise.
+
+  | Style | Use when | Avoid when |
+  |-------|----------|------------|
+  | Plain CRUD / 3-layer | Single resource flow, no domain rules beyond validation | Complex business invariants, multi-step workflows |
+  | Service-oriented within a module | Multiple use cases sharing entities, transactions across them | Cross-team boundaries, independent deployment needs |
+  | Domain-driven (aggregates, domain services) | Rich business rules, invariants, multiple actors per workflow | Simple read-mostly resources |
+  | Event-driven / async | Long-running flows, decoupled side-effects, retry/back-pressure | Strong synchronous contracts, immediate-consistency reads |
+  | Multi-service / boundary split | Independent scaling or deployment, separate teams | Single team, single deployment pipeline -- DEFER |
+
+- If the requirements suggest "multi-service" but project is currently single-service: STOP and ask user to confirm scope expansion before designing across services.
+
+### Step 4: Design Module Structure
+- **What**: list modules (new and modified), their responsibilities, owned entities, and interfaces.
+- **How**:
+  1. Map each Concern (Step 2) to one owning module.
+  2. For every module, write: name, responsibility (one sentence), owned entities, public interface (function/class signatures or HTTP endpoints), dependencies on other modules.
+  3. Validate dependency direction against `project-context.md` layer rules (e.g., domain -> infra forbidden). If violation found, redesign or flag it as an explicit ADR (Step 6).
+  4. Use the existing module names from `project-context.md` whenever possible -- introduce a new module only when no existing one fits.
+- **Branches**:
+
+  | Condition | Action |
+  |-----------|--------|
+  | Layer-compliance check passes | Proceed |
+  | Single layer violation, fix is local | Adjust module placement, document in change tracking |
+  | Systemic violation (style mismatch with existing project) | STOP, raise ADR (Step 6) and ask user to confirm direction before continuing |
+
+### Step 5: Define Data Flow
+- **What**: for each primary use case, produce a sequence of module interactions.
+- **How**:
+  1. For each use case (from Step 2 / analysis.md), list the trigger, the modules involved, the call order, and the persistence/event boundaries.
+  2. Render as a Mermaid `sequenceDiagram` if there are >= 3 participants OR there are async/event hops; otherwise a numbered list is fine.
+  3. Mark transactional boundaries explicitly (`-- transaction begin/end`).
+  4. Identify error paths for each flow: what happens if step N fails? Document fallback behavior (retry, compensating action, user-visible error).
+
+### Step 6: Document Decisions (ADRs)
+- **What**: capture every non-obvious choice as an Architecture Decision Record.
+- **How**: write one ADR per decision with these fields:
+
+  | Field | Required content |
+  |-------|------------------|
+  | Title | Short imperative ("Use event sourcing for orders") |
+  | Status | proposed / accepted / superseded |
+  | Context | What concerns + constraints forced this decision (cite Step 2/3) |
+  | Decision | The chosen option, stated unambiguously |
+  | Alternatives | At least 1 rejected option, with the rejection reason |
+  | Consequences | Positive and negative impacts; which downstream skills/modules pay the cost |
+
+- Decisions that MUST be ADRs (do not skip):
+  - Choice of architecture style (Step 3) when more than one row was viable.
+  - Any layer-rule violation accepted as a deliberate exception.
+  - Introduction of a new external dependency (DB, queue, library category).
+  - Breaking change to an existing public interface.
+
+### Step 7: User Confirmation Before Write
+- **When to confirm before writing the artifact**:
+  - Step 3 escalated to multi-service.
+  - Step 4 raised a systemic layer violation.
+  - Step 6 contains any ADR with `status: proposed` for a breaking change.
+  - The design adds a new external dependency.
+- **When to write silently**:
+  - Single-module addition that fits existing layers, no ADR escalations, no breaking change.
+- **Confirmation format**: present a one-screen summary -- style chosen, modules added/changed, ADRs requiring review, a single yes/no prompt. Do not dump the full artifact.
+
+### Step 8: Write Artifact
+- **Path**: `.ai-agents/workspace/artifacts/{active_change.id}/design.md`.
+- **Template**: `.ai-agents/skills/_templates/design-output.md`; if `_templates/custom/design-output.md` exists, use the custom version.
+- **Required sections** (filled per template headings, but content must include):
+  - `Overview` -- the problem statement (Step 2).
+  - `Architecture Decision Records` -- every ADR from Step 6.
+  - `Module Design` -- table of modules from Step 4.
+  - `Key Interfaces` -- explicit signatures/endpoints.
+  - `Data Flow` -- sequences from Step 5, including error paths.
+  - `File Structure` -- mapping of modules to file/directory paths in this repo.
+  - `Implementation Guidelines` -- ordering hints for `/mvt-implement` and `/mvt-plan-dev`.
+  - `Change Tracking` -- list of files expected to be created/modified/deleted.
+- Do NOT modify `project-context.yaml` or `project-context.md` here.
+
+### Step 9: Suggest Plan Decomposition
+- If `Change Tracking` lists more than ~5 files OR Module Design adds more than 1 new module OR ADRs include any breaking change, recommend `/mvt-plan-dev` as the next step.
+- Otherwise recommend `/mvt-implement` directly.
+
+### Step 10: (session update handled by shared section)
+
+## Variants
+- `/mvt-design --plan` flag: skip Step 5 (data flow detail) and Step 6 (full ADR fields). In `--plan` mode, ADRs collapse to a one-line `decision: <text>`. Step 8 still writes `design.md` but with the abbreviated content. The output is a high-level plan, not an implementation-ready blueprint -- mark the artifact with a top-line `Mode: plan` indicator.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| `analysis.md` missing entirely | Proceed with user's free-text intent; mark artifact with "Source: conversation only"; recommend `/mvt-analyze` as a follow-up |
+| Requirements are mutually contradictory | STOP at Step 2; surface contradictions; do not invent a resolution |
+| User wants to skip ADRs ("just write the design") | Refuse silently-skipping; produce minimal one-line ADRs (Step 6 abbreviated form) but never zero |
+| Design directly contradicts an existing accepted ADR | Treat as superseding; new ADR must reference and `supersedes:` the old one |
+| `--plan` mode but request is actually small (1 file) | Downgrade to a 5-line summary in chat, do NOT write `design.md` |
+| User aborts at Step 7 confirmation | Do not write artifact; keep a conversation-only summary |

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

@@ -1,105 +1,96 @@
-name: mvt-design
-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."
-
-sections:
-  - type: inline
-    content: |
-      # MVT Design
-
-      ## 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.
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      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: "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`"
-      boundaries:
-        - scope: "write implementation code"
-          skill: "/mvt-implement"
-        - scope: "re-analyze requirements"
-          skill: "/mvt-analyze"
-        - scope: "review code"
-          skill: "/mvt-review"
-
-  - type: inline
-    content: |
-      ## Variants
-
-      | Variant | Description |
-      |---------|-------------|
-      | `/mvt-design` | Full architecture design |
-      | `/mvt-design --plan` | High-level implementation plan only |
-
-  - type: shared
-    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/activation-preflight.md
-    params:
-      checks:
-        - order: "1"
-          field: "session.initialized_at"
-          level: "BLOCK"
-          message: 'Session not initialized. Run `/mvt-init` first.'
-        - order: "2"
-          field: "project.name"
-          level: "BLOCK"
-          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.'
-        - order: "4"
-          field: "requirements in project-context"
-          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.
-
-  - type: file
-    source: ./business.md
-
-  - type: inline
-    content: |
-      ## Output Format
-
-      Read and use the output 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.
-
-      Fill the template placeholders with the design results.
-
-      Every response MUST end with a Suggested Next Steps section.
-
-  - 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"
+name: mvt-design
+output: .claude/skills/mvt-design/SKILL.md
+
+frontmatter:
+  name: mvt-design
+  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
+    content: |
+      # MVT Design
+
+      ## Purpose
+
+      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
+    params:
+      role: Architect
+      role_desc: "a System Architecture Expert"
+      decision_rules:
+        - 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: "Layer constraint violation in design -> Flag and suggest alternative that respects existing boundaries"
+      boundaries:
+        - scope: "write implementation code"
+          skill: "/mvt-implement"
+        - scope: "re-analyze requirements"
+          skill: "/mvt-analyze"
+        - scope: "review code"
+          skill: "/mvt-review"
+
+  - type: inline
+    content: |
+      ## Variants
+
+      | Variant | Description |
+      |---------|-------------|
+      | `/mvt-design` | Full architecture design |
+      | `/mvt-design --plan` | High-level implementation plan only |
+
+  - type: shared
+    source: sections/activation-load-context.md
+    params:
+      extended_context:
+        - ".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:
+      checks:
+        - order: "1"
+          field: "session.initialized_at"
+          level: "BLOCK"
+          message: "Session not initialized. Run `/mvt-init` first."
+        - order: "2"
+          field: "projects[] in project-context.yaml"
+          level: "BLOCK"
+          message: "Project not initialized. Run `/mvt-init` first."
+        - order: "3"
+          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.md"
+          level: "WARN"
+          message: "No requirements found. Run `/mvt-analyze` first. (allow user to proceed)"
+
+  - type: file
+    source: ./business.md
+
+  - type: inline
+    content: |
+      ## 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`
+
+  - type: shared
+    source: sections/session-update.md
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-design