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

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

@@ -1,111 +1,224 @@
-## Execution Flow
-
-### Step 1: Requirements Gathering
-Ask the user for:
-- **Skill name**: Suggest `mvt-` prefix for consistency, but also accept project-specific prefixes (e.g., `app-`, `proj-`)
-- **Purpose**: What does this skill do?
-- **Category**: workflow / utility / project-specific
-- **Trigger keywords**: What phrases should invoke this skill? (used for `description` field)
-
-### Step 2: Skill Design
-- Load an existing skill file as structural reference
-- Load config.yaml for project configuration context
-- Determine required input parameters
-- Determine execution mode: interactive / automated / hybrid
-- Determine output format needs
-
-### Step 3: Template Decision
-- Does the skill need an output template?
-  - Yes -> Choose: adapt existing template or create new one
-  - No -> Skip template creation
-- Does the skill need context loading beyond session + project-context?
-  - Yes -> Define the file list
-  - No -> Use only basic loading
-
-### Step 4: Generate Skill Files
-1. Create `.claude/skills/{name}/SKILL.md` with standard structure:
-   - YAML frontmatter (`name`, `description`)
-   - Purpose section
-   - Role section (Decision Rules + Boundaries)
-   - Context Loading section
-   - Execution Flow section
-   - State Update section (MANDATORY — see below)
-   - Output Format section
-   - Suggested Next Steps section
-2. If output template needed -> Create `.ai-agents/skills/_templates/{name}-output.md`
-3. Update registry if template was created
-
-### Step 4.5: Register in Registry (MANDATORY)
-Append the new skill entry to `.ai-agents/registry.yaml` > `skills` section:
-```yaml
-  {name}:
-    agent: {agent}
-    path: .claude/skills/{name}/SKILL.md
-    template: {template_path_or_null}
-    category: {category}
-    mode: independent
-    custom: true
-```
-The `custom: true` field is **required** for all user-created skills. It protects the skill from being overwritten during framework updates.
-
-### Step 5: Validation
-- Verify SKILL.md format compliance (frontmatter has `name` + `description`)
-- Confirm no naming conflicts with existing skills
-- Verify `registry.yaml` entry includes `custom: true`
-- Show the user how to invoke: `/{name}`
-
-## Generated Skill Structure
-
-```markdown
----
-name: mvt-{name}
-description: '{trigger keyword description}'
----
-
-# MVT {Name}
-
-## Purpose
-{user-defined purpose}
-
-## Role
-You are the **Conductor** -- a Workflow Coordinator.
-
-### Decision Rules
-{generated based on skill purpose}
-
-### Boundaries
-{standard boundaries}
-
-## Activation Protocol
-
-### Step 1: Load Context (Context Foundation)
-Load the following files as foundational context:
-- `.ai-agents/workspace/session.yaml` -- Current workflow state
-- `.ai-agents/workspace/project-context.yaml` -- Project domain data
-
-### Step 2: Load Config & Apply Preferences (Config Foundation)
-Read `.ai-agents/config.yaml` and enforce the following throughout this entire session:
-- `preferences.language` → Use this language for ALL output
-- `preferences.output.no_emojis` → If true, never use emojis
-- `preferences.output.data_format` → Use this format for data sections
-
-### Step 3: Pre-flight Checks
-{skill-specific checks}
-
-### Step 4: Execute
-Proceed to Execution Flow below.
-
-## Execution Flow
-{generated based on user requirements}
-
-## State Update (Required)
-After execution, update `.ai-agents/workspace/session.yaml`:
-- Set `session.last_command: "/{name}"`
-- Append one-line summary to `recent_actions` (keep max 3)
-
-## Output Format
-{template reference or inline format}
-
-## Suggested Next Steps
-{contextual suggestions}
-```
+## Design Principles
+
+### Progressive Disclosure
+Skills use a three-level loading system to manage context efficiently:
+1. **Metadata (name + description)** -- Always in context (~100 words). Determines when Claude triggers the skill.
+2. **SKILL.md body** -- Loaded when skill triggers. Target <5k words. Keep only essential procedural instructions and workflow guidance.
+3. **Bundled resources** -- Loaded on demand by Claude. Unlimited size.
+
+**Avoid duplication**: information should live in either SKILL.md, `references/`, or knowledge entries -- not in multiple places.
+
+### Writing Style
+Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language ("To accomplish X, do Y" rather than "You should do X"). This maintains consistency and clarity for AI consumption.
+
+### Description Quality
+The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Guidelines:
+- Be specific about what the skill does and when to use it.
+- Use third-person ("This skill should be used when...").
+- Include: what it does + when to trigger + how it differs from similar skills.
+
+| Good | Bad |
+|------|-----|
+| "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." | "Skill creator" |
+| "Analyze requirements documents and extract domain concepts. Use when user provides requirements text or asks to understand project scope." | "Analyze stuff" |
+
+## Execution Flow
+
+### 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).
+
+### Step 2: Understand Usage with Concrete Examples
+Skip only when usage patterns are already crystal clear.
+
+Ask up to 3 of the following (do not ask all at once):
+- "Can you give 1-2 concrete examples of how this skill would be used?"
+- "What would a user say or do that should trigger this skill?"
+- "Are there edge cases or variations in how this skill gets invoked?"
+- "What does success look like? What does the AI produce / write?"
+
+Conclude this step with a short paragraph stating the skill's purpose in one sentence and listing 1-3 representative invocations.
+
+### Step 3: Gather Requirements
+Collect core metadata. Each field has an explicit constraint -- do not accept vague answers.
+
+| Field | Constraint | Notes |
+|-------|------------|-------|
+| Name | Lowercase, kebab-case, no spaces. Prefix `mvt-` for framework skills; project-specific prefixes (e.g., `app-`, `proj-`) are also acceptable | Reject if conflicts with an existing entry in `registry.yaml` |
+| Agent role | One of: `conductor`, `analyst`, `architect`, `developer`, `reviewer`, `tester` | Maps the skill to an existing role family |
+| Purpose | One sentence | Will become the SKILL.md `## Purpose` section |
+| Category | One of: `workflow`, `shortcut`, `project`, `utility` | Drives how `/mvt-help` groups it |
+| Description | Third-person, includes what + when + how it differs | Will become the frontmatter `description` |
+| Dependencies | List of skill names that must run first, OR `none` | Becomes `depends_on` in registry |
+| Variants (optional) | List of flag/sub-mode entries | Becomes the Variants table |
+
+If the user is unsure on any field, propose a default and ask for confirmation rather than leaving it blank.
+
+### Step 4: Plan Reusable Contents
+- **What**: decide which resources (beyond the SKILL.md body) the new skill needs.
+- **How**: for each example from Step 2, ask: "If we executed this from scratch, what reusable resource would have helped?" Map each answer to one of the categories below.
+
+  | Resource | Directory | Use when | Example |
+  |----------|-----------|----------|---------|
+  | Scripts | `scripts/` | Same code rewritten repeatedly OR deterministic reliability needed | `scripts/validate_schema.py` |
+  | References | `references/` | Documentation Claude should read while working (schemas, API docs, policies) | `references/api_spec.md` |
+  | Assets | `assets/` | Files used in the output, not in context (templates, icons, fonts) | `assets/report_template.md` |
+  | 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.
+- **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:
+
+  | Aspect | Decision |
+  |--------|----------|
+  | Input parameters | What does the skill need from the user / workspace? |
+  | Execution mode | Interactive / automated / hybrid |
+  | Pre-flight checks | List, with severity (BLOCK / WARN); defer to `activation-preflight.md` shared section |
+  | Decision rules (in role-header) | 3-7 imperative rules covering the major branches |
+  | Boundaries | What is in-scope vs delegated to other skills |
+  | Execution Flow steps | Bulleted titles only (full content comes in Step 6) |
+  | 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:
+   - `## 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).
+   - `## 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/`.
+
+### Step 7: Register in Registry (MANDATORY)
+Append the skill entry to `.ai-agents/registry.yaml` > `skills` section:
+
+```yaml
+  {name}:
+    agent: {agent}
+    description: "{third-person description with trigger keywords}"
+    path: .claude/skills/{name}/SKILL.md
+    template: {template_path_or_null}
+    category: {category}
+    depends_on: {dependencies_or_omitted}
+    custom: true
+    knowledge:
+      {entries_or_empty_list}
+    next_suggestions:
+      primary: {suggested_next_skill}
+      primary_desc: "{when to use the next skill}"
+```
+
+- The `custom: true` field is **required** for user-created skills; without it, framework updates will overwrite the entry.
+- If the skill has no specific knowledge needs, set `knowledge: []` or omit the key entirely.
+- Validate the YAML still parses after the append; if not, abort and surface the parse error.
+
+### Step 8: Validation
+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 |
+| 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 |
+| 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 |
+
+Show the user how to invoke: `/{name}`.
+
+### Step 9: Iteration Guidance
+Tell the user the iteration loop:
+1. Use `/{name}` on real tasks.
+2. Notice struggles or inefficiencies.
+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)
+
+## 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 |
+| 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 |
+| 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 |
+| `registry.yaml` parse fails after append | Restore from a pre-append backup; surface the error; do not leave the registry corrupt |
+
+## Generated Manifest 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}
+```
+
+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.

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

@@ -3,16 +3,16 @@ 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."
+  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 Custom Skill
+      # MVT Create 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.
+      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
@@ -24,6 +24,8 @@ sections:
         - 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)"
@@ -31,27 +33,28 @@ sections:
           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"
+        - 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`)"
-        - ".ai-agents/registry.yaml -- Registered skills list"
 
   - 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.
 
-      ### Step 4: Execute
-      Proceed to Execution Flow below.
-
   - type: file
     source: ./business.md
 
@@ -59,21 +62,34 @@ sections:
     content: |
       ## Output Format
 
-      No external template -- output is the generated skill file itself plus a creation summary:
+      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}
-      - **Category**: {category}
+      - **Resources**: {scripts/references/assets listing, or none}
+      - **Knowledge**: {per-skill entries / shared only}
+      - **Context Budget**: SKILL.md body ~{N} words
 
-      You can now use `/{name}` to invoke your new skill.
+      Use `/{name}` to invoke the new skill.
 
-      ---
-      **Suggested Next Steps**:
-      - Test your new skill by running `/{name}`
-      - `/mvt-help` -- View updated skills list
+      ### 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

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 |