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

package/sources/skills/mvt-create-skill/business.md

@@ -26,8 +26,8 @@ The `name` and `description` in YAML frontmatter determine when Claude will use
 
 ### Step 1: Load Inputs
 - **Recommended**:
-  - One existing skill manifest under `sources/skills/<existing>/manifest.yaml` (or `.ai-agents/skills/<existing>/`) as a structural reference.
-  - `sources/sections/` -- the catalog of shared sections this new skill can reuse (role-header, activation-load-context, activation-load-config, output-language-constraint, activation-preflight, session-update, footer-next-steps).
+  - One existing skill's SKILL.md under `.claude/skills/<existing>/SKILL.md` as a structural reference (to extract shared section patterns like Activation Protocol, State Update, Next Steps).
+  - `.ai-agents/registry.yaml` -- to check for name collisions and understand skill categories.
 
 ### Step 2: Understand Usage with Concrete Examples
 Skip only when usage patterns are already crystal clear.
@@ -67,12 +67,12 @@ If the user is unsure on any field, propose a default and ask for confirmation r
   | Knowledge | (declared in registry) | Loaded via Activation Protocol; share across skills or manage via `/mvt-manage-context` | `knowledge/principle/coding-standards/` |
   | Output template | `_templates/` | Persisted document that needs a stable structure | `_templates/{name}-output.md` |
 
-- **Reuse vs new**: before declaring a new shared resource, grep `sources/sections/` and existing knowledge entries -- prefer reusing what is already there.
+- **Reuse vs new**: before declaring a new shared resource, check existing skills' SKILL.md files and knowledge entries -- prefer reusing patterns that already exist.
 - **Output of this step**: a checklist `(name | category | purpose | path)` shown to user.
 
 ### Step 5: Design the Skill
 - **What**: produce a one-page outline before generating any file.
-- **How**: load an existing skill (e.g., `sources/skills/mvt-analyze/manifest.yaml`) as a structural reference, then fill in:
+- **How**: load an existing skill's SKILL.md (e.g., `.claude/skills/mvt-fix/SKILL.md`) as a structural reference, then fill in:
 
   | Aspect | Decision |
   |--------|----------|
@@ -85,19 +85,20 @@ If the user is unsure on any field, propose a default and ask for confirmation r
   | Output | What gets written to disk (artifact path + template) OR pure conversation output |
 
 ### Step 6: Generate Skill Files
-1. Create source directory: `sources/skills/{name}/` (or `.claude/skills/{name}/` if working directly in an installed workspace).
-2. Generate `manifest.yaml` using the standard structure (see Generated Manifest Structure below). The manifest MUST reuse shared sections wherever applicable; do not inline content that already exists as a shared section.
-3. Generate `business.md` containing the Execution Flow. Follow the **standard skeleton** used across all MVTT skills:
+1. Create skill directory: `.claude/skills/{name}/`.
+2. Generate a complete `SKILL.md` file (see Generated SKILL.md Structure below). This file must be fully self-contained — there is no assembler or build step to resolve shared section references. All content must be inlined directly into the SKILL.md.
+3. For standard sections (Activation Protocol, Load Config, Language Constraint, Pre-flight, State Update, Next Steps), copy them verbatim from this document's own SKILL.md and substitute only the skill-specific values (role, decision rules, boundaries, pre-flight checks, next-skill suggestions). Do NOT paraphrase standard sections — copy character-for-character to ensure consistency.
+4. For skill-specific sections (frontmatter, Purpose, Execution Flow, Edge Cases & Errors), generate fresh content following the skeleton below.
    - `## Execution Flow`
    - `### Step 1: Load Inputs` -- list required and recommended files, plus fallback rules.
    - Skill-specific main steps (1-5 of them), each with **What / How / Branches** sub-structure when there is real branching.
    - `### Step N: User Confirmation` -- only when destructive or non-obvious; describe trigger conditions.
    - `### Step N+1: Write Artifacts` -- only when the skill persists files; specify path, template, required content.
-   - Final session update step (delegated to shared section).
+   - Final session update step.
    - `## Edge Cases & Errors` table with at least 3 rows.
-4. If an output template was decided in Step 4, create `_templates/{name}-output.md` with **headings only** (this is a document structure, not a conversation reply template).
-5. If scripts / references / assets are needed, create them in the skill directory.
-6. SKILL.md word budget: aim for the assembled body to be under ~5k words. Push reference material to `references/`.
+5. If an output template was decided in Step 4, create `.ai-agents/skills/_templates/{name}-output.md` with **headings only** (this is a document structure, not a conversation reply template). If a custom version directory exists at `_templates/custom/`, note that users can override there.
+6. If scripts / references / assets are needed, create them under the skill directory.
+7. SKILL.md word budget: aim for the body to be under ~5k words. Push reference material to `references/`.
 
 ### Step 7: Register in Registry (MANDATORY)
 Append the skill entry to `.ai-agents/registry.yaml` > `skills` section:
@@ -127,16 +128,16 @@ Walk this checklist; any failed item must be fixed before declaring success.
 
 | Check | Pass criterion |
 |-------|----------------|
-| Frontmatter present | `name` and `description` exist in the manifest's `frontmatter:` block |
+| Frontmatter present | `name` and `description` exist in SKILL.md YAML frontmatter |
 | Description quality | Third-person, includes what + when, distinguishes from neighbors |
 | Writing style | Imperative/infinitive throughout; no "you" / "your" |
 | Naming uniqueness | No collision with another entry in `registry.yaml` |
 | `custom: true` | Set in registry entry |
+| Standard sections present | SKILL.md contains Role, Activation Protocol, Execution Flow, Edge Cases & Errors, State Update, Suggested Next Steps |
 | Knowledge files exist | Every file referenced in `knowledge:` resolves on disk |
 | Template path correct | If `template:` set, file exists at that path; the template is headings-only |
-| Word budget | Assembled SKILL.md body under ~5k words (run a quick `wc` if available) |
-| Standard skeleton | business.md contains Load Inputs, main steps with branches, Edge Cases & Errors |
-| Build green | If running inside the framework repo, `npm run build` succeeds |
+| Word budget | SKILL.md body under ~5k words (use any available word-count method, e.g., editor statistics) |
+| Standard skeleton | Execution Flow contains Load Inputs, main steps with branches, Edge Cases & Errors |
 
 Show the user how to invoke: `/{name}`.
 
@@ -147,78 +148,85 @@ Tell the user the iteration loop:
 3. Decide whether to update SKILL.md, add a `references/` file, add a knowledge entry, or split into a new skill.
 4. Re-run `/mvt-create-skill` to refine, or edit the source files directly and rebuild.
 
-### Step 10: (session update handled by shared section)
+### Step 10: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
 
 | Case | Handling |
 |------|----------|
 | Skill name collides with an existing registry entry | STOP at Step 3; ask user to rename; do not generate any file |
-| User wants the skill to mutate `session.yaml` fields beyond `skill_history` | Surface that ownership rules forbid this (e.g., `recent_changes` is owned by `/mvt-plan-dev`/`/mvt-update-plan`); recommend redesign |
+| User wants the skill to mutate `session.yaml` fields beyond `history` | Surface that ownership rules forbid this (e.g., `changes` is owned by `/mvt-plan-dev`/`/mvt-update-plan`); recommend redesign |
 | Output template is requested but the skill is conversation-only (no persisted file) | Refuse to create a template; explain that templates are for document structure, not conversation replies |
-| User asks to skip the registry registration step | Refuse; an unregistered skill is invisible to `/mvt-help`, `/mvt-status`, and the assembler. Registration is non-negotiable |
+| User asks to skip the registry registration step | Refuse; an unregistered skill is invisible to `/mvt-help`, `/mvt-status`, and `/mvt-resume`. Registration is non-negotiable |
 | Skill duplicates an existing skill's responsibility | Surface the overlap (cite the existing skill's description); propose merging or sub-classing as a variant rather than creating a duplicate |
 | User provides a non-third-person description ("Use this skill when you need...") | Rewrite to third-person before saving; show the rewrite for confirmation |
-| Generated manifest references a shared section that does not exist | Abort with the missing section path; do NOT invent a new section silently -- recommend creating it via a separate change |
+| Generated SKILL.md is missing a standard section (e.g., State Update, Next Steps) | Abort generation; inform user which section is missing; read an existing SKILL.md for the correct structure |
 | `registry.yaml` parse fails after append | Restore from a pre-append backup; surface the error; do not leave the registry corrupt |
 
-## Generated Manifest Structure
+## Generated SKILL.md Structure
 
-```yaml
-name: {name}
-output: .claude/skills/{name}/SKILL.md
-
-frontmatter:
-  name: {name}
-  description: "{third-person description with trigger keywords}"
-
-sections:
-  - type: inline
-    content: |
-      # {Title}
-
-      ## Purpose
-
-      {concise purpose statement}
-
-  - type: shared
-    source: sections/role-header.md
-    params:
-      role: {Agent Role}
-      role_desc: "{role description}"
-      decision_rules:
-        {generated rules}
-      boundaries:
-        {generated boundaries}
-
-  - type: shared
-    source: sections/activation-load-context.md
-    params:
-      extended_context:
-        {if needed, list additional context sources}
-
-  - 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:
-        {if needed, list preflight checks}
-
-  - type: file
-    source: ./business.md
-
-  - type: shared
-    source: sections/session-update.md
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      current_skill: {name}
+The generated SKILL.md consists of two parts: **skill-specific sections** (generated fresh) and **standard sections** (copied from this document with skill-specific values replaced).
+
+### Skill-specific sections (generate fresh)
+
+```markdown
+---
+name: '{name}'
+description: '{third-person description with trigger keywords}'
+---
+
+# {Title}
+
+## Purpose
+
+{concise purpose statement}
+
+## Role
+
+You are the **{Agent Role}** -- {role description}.
+
+### Decision Rules
+{generated rules, one per line, verb-first}
+
+### Boundaries
+- Do NOT {scope} (use `/{skill}` instead)
+{repeat for each boundary}
+
+## Execution Flow
+
+### Step 1: Load Inputs
+{required and recommended inputs, plus fallback rules}
+
+{skill-specific steps 2-N}
+
+### Step N: User Confirmation
+{only when destructive or non-obvious; describe trigger conditions}
+
+### Step N+1: Write Artifacts
+{only when the skill persists files; specify path, template, required content}
+{if shortcut/conversation-only: "No artifact -- results are conversation-only."}
+
+{final session update step if not shortcut, or shortcut operation rules}
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+{at least 3 rows}
 ```
 
-Note: State Update and Suggested Next Steps are handled by shared sections (`sections/session-update.md` and `sections/footer-next-steps.md`) and must be referenced from the manifest, not duplicated as inline content.
+### Standard sections (copy from this document)
+
+Copy the following sections verbatim from this document (the assembled SKILL.md you are currently reading), replacing only the skill-specific values indicated:
+
+| Section | Source in this document | What to replace |
+|---------|----------------------|-----------------|
+| Activation Protocol | `## Activation Protocol` | Add `extended_context` entries if the skill needs additional context sources; otherwise copy as-is |
+| Load Config | Load Config step within Activation Protocol | Copy as-is |
+| Output Language Constraint | Output Language Constraint step within Activation Protocol | Copy as-is |
+| Pre-flight Checks | Pre-flight Checks step within Activation Protocol | Replace `checks` table with skill-specific checks; if none required, use a single INFO row |
+| State Update | `## State Update` | Replace `/{name}` with the new skill's command; include `active_change` conditional block only if the skill creates changes; include `Shortcut Operation Rules` only if category is `shortcut` |
+| Suggested Next Steps | `## Suggested Next Steps` | Replace `current_skill` with the new skill name; replace conditional suggestions with skill-appropriate ones |
+
+**Important**: Do NOT paraphrase or rewrite the standard sections. Copy them character-for-character from this document and only substitute the skill-specific values. This ensures consistency across all MVTT skills.

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

@@ -1,95 +1,107 @@
-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`
-      - **Manifest**: Generated with shared sections
-      - **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/session-update.md
-
-  - type: shared
-    source: sections/footer-next-steps.md
-    params:
-      current_skill: mvt-create-skill
+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: "generate skills that deviate from MVTT SKILL.md standard structure"
+          skill: "the standard structure as documented"
+        - scope: "use arbitrary prefixes without validating naming conventions"
+          skill: "`mvt-` or a project-specific prefix like `app-`, `proj-`"
+        - scope: "create skills without registering in registry.yaml"
+          skill: "`custom: true` in registry.yaml"
+        - scope: "write vague or first-person descriptions"
+          skill: "third-person with effective trigger keywords"
+        - scope: "exceed ~5k words in SKILL.md body"
+          skill: "references/ for detailed content"
+
+  - 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 4: 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/session-update.md
+    params:
+      current_skill: mvt-create-skill
+
+  - type: shared
+    source: sections/footer-next-steps.md
+    params:
+      current_skill: mvt-create-skill
+      conditional_suggestions:
+        conditions:
+          - condition: "skill created successfully"
+            primary: mvt-help
+            primary_desc: "Verify the new skill appears in the catalog"
+          - condition: "skill needs knowledge entries"
+            primary: mvt-manage-context
+            primary_desc: "Add knowledge files for the new skill"
+          - condition: "skill needs testing with real tasks"
+            primary: mvt-status
+            primary_desc: "Check project state before testing the skill"

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

@@ -82,8 +82,7 @@
 - **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.
+- **Path and template**: as defined in the **Artifact Structure** section below.
 - **Required sections** (filled per template headings, but content must include):
   - `Overview` -- the problem statement (Step 2).
   - `Architecture Decision Records` -- every ADR from Step 6.
@@ -99,10 +98,8 @@
 - 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.
+### Step 10: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors