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

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

@@ -60,6 +60,7 @@
   | 3 | `preferences.output.no_emojis` | Default `true` |
   | 4 | `preferences.output.data_format` | Default `yaml`; allowed: `yaml`, `json` |
   | 5 | `preferences.context_routing.relevance_threshold` | Default `70`; allowed: 0-100 |
+  | 6 | `preferences.history_limits.*` | Show each limit with current value; accept new int or Enter to keep |
 
 - After all stages, render a Summary Preview table: `key | from | to`, then a single confirmation prompt to apply ALL changes atomically.
 - If the user aborts at the summary, discard all in-progress values; do not write anything.
@@ -73,8 +74,6 @@
 6. Report the keys that changed.
 - Do NOT reset `knowledge.shared` to defaults if the user has added entries via `/mvt-manage-context` -- preserve user-added knowledge ids; only reset preferences. Surface this exception in the diff.
 
-### Step 8: (session update handled by shared section)
-
 ## Knowledge Inspection (sub-flow used by Interactive Menu and Show All)
 - **View**: list shared knowledge ids from `registry.yaml > knowledge.shared`, then per-skill knowledge ids grouped by skill (`registry.yaml > skills.*.knowledge`). Show token estimates from each entry's manifest if available.
 - **Modify**: this skill does NOT mutate knowledge settings; defer to `/mvt-manage-context`. Print the suggested command (`/mvt-manage-context move`, `/mvt-manage-context add`, etc.) instead of doing the work here.

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

@@ -56,12 +56,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required (config is always accessible)
 
       ## Configuration Keys
@@ -75,6 +72,8 @@ sections:
       | `preferences.output.no_emojis` | bool | `true` | Disable emojis in output |
       | `preferences.output.data_format` | enum | `yaml` | Data output format (yaml, json) |
       | `preferences.context_routing.relevance_threshold` | int | `70` | AI routing threshold for `/mvt-manage-context add` (0-100) |
+      | `preferences.history_limits.history` | int | `20` | Max history entries (1-100) |
+      | `preferences.history_limits.changes` | int | `20` | Max changes entries (1-100) |
 
       ### Knowledge Settings
 
@@ -94,3 +93,11 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-config
+      conditional_suggestions:
+        conditions:
+          - condition: "configuration updated"
+            primary: mvt-status
+            primary_desc: "Check project status with new settings"
+          - condition: "language changed"
+            primary: mvt-help
+            primary_desc: "Verify output in the new language"

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

@@ -27,7 +27,7 @@ The `name` and `description` in YAML frontmatter determine when Claude will use
 ### Step 1: Load Inputs
 - **Recommended**:
   - 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).
-  - `registry.yaml` -- to check for name collisions and understand skill categories.
+  - `.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.
@@ -136,7 +136,7 @@ Walk this checklist; any failed item must be fixed before declaring success.
 | 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 | SKILL.md body under ~5k words (run a quick `wc` if available) |
+| 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}`.
@@ -148,14 +148,15 @@ 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 `/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 |
@@ -225,7 +226,7 @@ Copy the following sections verbatim from this document (the assembled SKILL.md
 | 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 (Required)` | 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` |
+| 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

@@ -27,16 +27,16 @@ sections:
         - 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)"
+        - 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
@@ -50,9 +50,12 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -85,7 +88,23 @@ sections:
       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
 

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

@@ -41,7 +41,7 @@ sections:
       | Variant | Description |
       |---------|-------------|
       | `/mvt-design` | Full architecture design |
-      | `/mvt-design --plan` | High-level implementation plan only |
+      | `/mvt-design --plan` | High-level implementation plan only: skip Step 5 (data flow detail) and Step 6 (full ADR fields). ADRs collapse to one-line `decision: <text>`. Step 8 writes `design.md` with abbreviated content and a top-line `Mode: plan` indicator. If the request is actually small (1 file), downgrade to a 5-line summary in chat and do NOT write `design.md`. |
 
   - type: shared
     source: sections/activation-load-context.md
@@ -55,6 +55,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -89,8 +92,21 @@ sections:
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-design
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-design
+      conditional_suggestions:
+        conditions:
+          - condition: "design complete, change tracking lists >5 files or >1 new module"
+            primary: mvt-plan-dev
+            primary_desc: "Create a structured implementation plan"
+          - condition: "design complete, small scope"
+            primary: mvt-implement
+            primary_desc: "Implement the designed architecture"
+          - condition: "design has proposed ADRs needing stakeholder review"
+            primary: mvt-review
+            primary_desc: "Review the design decisions"

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

@@ -118,7 +118,8 @@
   - `Regression risk` -- scope of behavior potentially affected, plus what tests guard it.
   - `Follow-ups` -- TODOs, deferred refactors, related issues.
 
-### Step 9: (session update handled by shared section)
+### Step 9: State Update
+Apply the State Update rules defined in the **State Update** section below.
 
 ## Edge Cases & Errors
 

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

@@ -47,6 +47,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -58,15 +61,18 @@ sections:
 
   - type: inline
     content: |
-      ### Shortcut Operation Rules
-      - Can execute at any time without checking workflow prerequisites
-      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase)
+      ## Operation Mode: Shortcut
+
+      This skill operates as a shortcut — it can execute at any time without checking workflow prerequisites.
+      - Do NOT update `progress` (this is a shortcut operation, not a workflow phase).
 
   - type: file
     source: ./business.md
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-fix
 
   - type: shared
     source: sections/footer-next-steps.md

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

@@ -13,7 +13,7 @@
   |-----------|---------------|
   | `session.yaml` missing or `initialized_at` empty | `/mvt-init` -- Initialize the project |
   | Initialized AND `project-context.md` does not exist | `/mvt-analyze-code` -- Analyze existing code |
-  | No requirements (no `analysis.md` for active change AND no completed `/mvt-analyze` in `skill_history`) | `/mvt-analyze` -- Analyze requirements |
+  | No requirements (no `analysis.md` for active change AND no completed `/mvt-analyze` in `history`) | `/mvt-analyze` -- Analyze requirements |
   | No requirements, but user describes a simple change directly | `/mvt-quick-dev` -- Implement a simple change quickly |
   | Requirements present, no `design.md` | `/mvt-design` -- Design architecture |
   | `design.md` exists, change is large (Change Tracking lists > 5 files OR ADR includes breaking change OR > 1 new module) | `/mvt-plan-dev` -- Decompose into tracked plan |
@@ -60,15 +60,13 @@ Color-code based on current progress: green (done), yellow (current/recommended)
   | "Compare `/mvt-X` and `/mvt-Y`" | Pull descriptions from registry; if both are workflow skills, mention their relative position in the diagram |
   | Asks about something not in registry | Reply: "No skill matches that. Available skills: see catalog above." Do not invent skills |
 
-### Step 6: (session update handled by shared section)
-
 ## Edge Cases & Errors
 
 | Case | Handling |
 |------|----------|
 | `registry.yaml` missing | STOP at Step 1; recommend `mvtt install`; show no catalog |
 | `session.yaml` missing | Render catalog (Step 3) and diagram (Step 4) without the "current position" highlight; Step 2 recommends `/mvt-init` |
-| `recent_changes[]` references a `plan_path` that no longer exists | Ignore for help purposes; do not warn -- `/mvt-status` is the right place for that |
+| `changes[]` references a `plan_path` that no longer exists | Ignore for help purposes; do not warn -- `/mvt-status` is the right place for that |
 | User invokes `/mvt-help` while inside an active change with Critical review findings | Step 2's recommendation is `/mvt-fix`; surface this prominently above the catalog |
 | User asks about a custom skill (registry entry with `custom: true`) | Treat identically to built-ins; the only difference is showing `custom: true` in the metadata view |
 | Workflow diagram cannot be rendered (mermaid unsupported in environment) | Fall back to a textual flow: `init -> analyze-code -> analyze -> design -> [plan-dev] -> implement -> review -> test` |

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

@@ -24,12 +24,9 @@ sections:
   - type: shared
     source: sections/activation-load-config.md
 
-  - type: shared
-    source: sections/output-language-constraint.md
-
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -46,7 +43,7 @@ sections:
 
       ### Current Status
       - **Project**: {name} ({initialized/not initialized})
-      - **Last Skill**: {last command from skill_history}
+      - **Last Skill**: {last command from history}
       - **Recommended Next**: `/mvt-{next}` -- {description}
 
       ### Workflow
@@ -65,3 +62,14 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-help
+      conditional_suggestions:
+        conditions:
+          - condition: "project not initialized"
+            primary: mvt-init
+            primary_desc: "Initialize the project"
+          - condition: "project initialized, no active change"
+            primary: mvt-analyze
+            primary_desc: "Start analyzing requirements for a new feature"
+          - condition: "active change in progress"
+            primary: mvt-resume
+            primary_desc: "Resume work on the active change"

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

@@ -14,7 +14,7 @@
   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.
+- **Plan-aware behavior**: if `plan.yaml` is present, treat `current_task`'s `artifacts.files` (cross-reference `plan.tasks[*].artifacts.files`) as a **starting-scope hint, not a hard ceiling**. The source of truth for scope remains `design.md`'s `Change Tracking` (per Step 2.1). When `artifacts.files` is `null` or empty, derive scope entirely from `Change Tracking`. If implementation reveals files beyond this hint are genuinely required, do NOT silently expand — surface them via Step 3 confirmation and never absorb files that clearly belong to a different task.
 - **Output of this step**: an in-conversation list shown to user as a preview, with no write yet.
 
 ### Step 3: Confirm Scope (when needed)
@@ -23,6 +23,7 @@
   - 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).
+  - The plan touches files beyond `current_task`'s `artifacts.files` hint (state which files are added and why, in one line each).
 - **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`.
 
@@ -59,8 +60,12 @@
   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).
+- **Path and template**: as defined in the **Artifact Structure** section below. The artifact filename is ALWAYS `implementation.md` — one file per change, never per task. Do NOT invent task-suffixed names like `implementation-t1.md`.
+- **Multi-task plans (single-file accumulation)**: when `plan.yaml` drives the change and you implement tasks across separate invocations, all task implementations accumulate into the **same** `implementation.md`:
+  1. If `implementation.md` does not yet exist -> create it from the template.
+  2. If it already exists -> read it, then **append** a new `## Task: {current_task_id} — {task_title}` section for this task. Do NOT overwrite prior tasks' sections.
+  3. Under that task section, place this invocation's required content (the headings below). Keep earlier tasks' sections intact.
+  4. For single-task or plan-less changes, write the content at the top level without a per-task wrapper (existing behavior).
 - **Required content** (mapped to template headings):
   - `Implementation Summary` -- one paragraph: what was built, scope.
   - `Files Touched` -- table: path | create/modify/delete | one-line intent.
@@ -72,11 +77,9 @@
 
 ### 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).
+- If the files actually touched differ from `current_task`'s `artifacts.files` (extra files added during Step 3, or planned files left untouched), explicitly remind the user to run `/mvt-update-plan` so the plan's `artifacts.files` reflects reality for `/mvt-resume` and future sessions.
 - 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.
+- Do NOT modify `changes` directly; it is owned by `/mvt-plan-dev` / `/mvt-update-plan`.
 
 ## Edge Cases & Errors
 

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

@@ -43,6 +43,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -73,8 +76,21 @@ sections:
 
   - type: shared
     source: sections/session-update.md
+    params:
+      current_skill: mvt-implement
 
   - type: shared
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-implement
+      conditional_suggestions:
+        conditions:
+          - condition: "implementation complete, no tests written yet"
+            primary: mvt-test
+            primary_desc: "Generate tests for the implementation"
+          - condition: "implementation deviates from design"
+            primary: mvt-review
+            primary_desc: "Review code for design compliance"
+          - condition: "plan exists with remaining tasks"
+            primary: mvt-update-plan
+            primary_desc: "Mark current task done and advance to next"

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

@@ -126,7 +126,7 @@ For each target file, check if it already exists:
 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`
+- `session.yaml` is structurally intact and contains: `session` (with `initialized_at`, `last_synced_at`), `active_change` (with `plan_path`), `changes` (array), `history`
 
 If any validation fails → report the specific error and offer to retry or skip.
 
@@ -135,7 +135,7 @@ If any validation fails → report the specific error and offer to retry or skip
 When `--refresh` is specified:
 
 1. **Preserve** the following from existing files:
-   - `session.yaml` > `skill_history` and `recent_actions`
+   - `session.yaml` > `history`
    - `project-context.yaml` > any user-added custom fields (fields not in the standard schema)
    - `config.yaml` > `preferences` section
 

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

@@ -59,6 +59,9 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: shared
     source: sections/activation-preflight.md
     params:
@@ -75,6 +78,7 @@ sections:
   - type: shared
     source: sections/session-update.md
     params:
+      current_skill: mvt-init
       update_initialized_at: true
 
   - type: shared

package/sources/skills/mvt-manage-context/business.md

@@ -173,3 +173,14 @@ At the bottom of the list, optionally surface:
 - **No edits to framework files**: never write to `.ai-agents/knowledge/core/_framework/`. If user content would land there by accident, redirect to `core/user/`.
 - **Backups**: before mutating `registry.yaml` or `core/manifest.yaml`, copy them to `.ai-agents/.backup/{filename}-{timestamp}.yaml`.
 - **Idempotency**: re-running the same `add` (same content + same bindings) should detect the existing entry and offer "skip / overwrite / cancel" rather than silently duplicating.
+
+## Edge Cases & Errors
+
+| Case | Handling |
+|------|----------|
+| File path points outside `.ai-agents/knowledge/` | Reject with error: knowledge files must reside under the managed directory tree |
+| `registry.yaml` or `core/manifest.yaml` is malformed (parse error) | Abort the operation; print the parse error; suggest manual fix or restore from `.ai-agents/.backup/` |
+| User attempts to `remove` a core framework file (`core/_framework/*`) | Refuse: framework files are read-only and managed by the installer |
+| `add` target file already exists on disk but has no registry entry | Offer "register existing / overwrite / cancel" instead of blindly writing |
+| `move` destination binding already has an entry with the same id | Prompt for rename or cancel; do not silently overwrite |
+| Disk write fails mid-operation (permission denied, disk full) | Roll back all registry/manifest changes using the backup copies; report partial failure |

package/sources/skills/mvt-manage-context/manifest.yaml

@@ -14,6 +14,9 @@ sections:
 
       Unified CRUD entry point for project context and knowledge entries. Handles add (with AI-driven skill routing), remove, move, rename, and list operations across `project-context.yaml`, `project-context.md`, `knowledge/principle/`, `knowledge/project/`, `knowledge/core/user/`, and the corresponding `registry.yaml` / `core/manifest.yaml` references.
 
+  - type: shared
+    source: sections/project-context-profile.md
+
   - type: shared
     source: sections/role-header.md
     params:
@@ -34,8 +37,8 @@ sections:
           skill: "/mvt-design"
         - scope: "write implementation code"
           skill: "/mvt-implement"
-        - scope: "edit framework knowledge under core/_framework/"
-          skill: "(Read-only -- framework files are not user-editable)"
+        - scope: "edit framework knowledge under core/_framework/ (framework files are read-only)"
+          skill: "(constraint)"
 
   - type: shared
     source: sections/activation-load-context.md
@@ -46,9 +49,12 @@ sections:
   - type: shared
     source: sections/output-language-constraint.md
 
+  - type: shared
+    source: sections/output-format-constraint.md
+
   - type: inline
     content: |
-      ### Step 3: Pre-flight Checks
+      ### Step 4: Pre-flight Checks
       - No blocking checks required.
 
   - type: file
@@ -121,3 +127,14 @@ sections:
     source: sections/footer-next-steps.md
     params:
       current_skill: mvt-manage-context
+      conditional_suggestions:
+        conditions:
+          - condition: "knowledge added or moved"
+            primary: mvt-check-context
+            primary_desc: "Verify context health after the change"
+          - condition: "knowledge removed"
+            primary: mvt-check-context
+            primary_desc: "Confirm token savings"
+          - condition: "large knowledge files detected"
+            primary: mvt-cleanup
+            primary_desc: "Clean up workspace to reduce context load"