majiayu000 · majiayu000 · Aug 15, 2026
diff --git a/README.md b/README.md
@@ -97,7 +97,7 @@ VibeGuard has two layers:
 | Surface | Scope | Canonical Source |
 |---------|-------|------------------|
 | **VibeGuard Core** | Rules, hooks, static guards, install/runtime contract, observability | `rules/claude-rules/`, `schemas/install-modules.json`, `hooks/`, `guards/` |
-| **VibeGuard Workflows** | Slash commands, agent prompts, planning/execution presets | `skills/`, `workflows/`, `agents/` |
+| **VibeGuard Workflows** | Slash commands, agent prompts, and shared command references | `.claude/commands/`, `workflows/references/`, `agents/` |
 
 If these surfaces disagree, treat the Core contract as authoritative first, then update workflow/docs surfaces to match it.
 

diff --git a/docs/directory-map.md b/docs/directory-map.md
@@ -21,8 +21,8 @@ VibeGuard keeps runtime and installable source directories at the repository roo
 | `.claude/commands/` | Claude slash command source installed into `~/.claude/commands/`. |
 | `.claude/skills/` | Repo-local maintainer skills for this repository. They are validated by skill-format checks but are not installable product skills unless promoted into `skills/` or `workflows/` and declared in `schemas/install-modules.json`. |
 | `agents/` | Claude agent prompt source installed into `~/.claude/agents/`. |
-| `skills/` | Core reusable skills installed into Claude and Codex skill locations. |
-| `workflows/` | Codex workflow skills and shared workflow references. |
+| `skills/` | Claude-only evaluation and retrieval skills declared by the install manifest. |
+| `workflows/` | Shared references used by command workflows; no user-level Codex skills are installed from this directory. |
 | `context-profiles/` | Claude context profiles installed into `~/.claude/context-profiles/`. |
 | `templates/` | Project and language templates copied or referenced by setup and docs. |
 | `claude-md/` | Text injected into user-level Claude memory during setup. |

diff --git a/docs/internal/history/spec.md b/docs/internal/history/spec.md
@@ -272,7 +272,7 @@ See `workflows/plan-flow/references/plan-template.md`
 
 ### 4.3 Review report template
 
-See `skills/vibeguard/references/review-template.md`
+The former bundled review template was retired in GH-763.
 
 ### 4.4 CI configuration recommendations
 

diff --git a/docs/specs/GH658/tasks.md b/docs/specs/GH658/tasks.md
@@ -13,8 +13,8 @@ GH-658
 
 - [ ] `SP658-T1` Add required closed `work_surface` and exact whole-array precedence contracts. Covers: B-001, B-002, B-003. Owner: schema worker. Dependencies: none. Writable files: `schemas/workflow-routing-decision.schema.json`. Done when: only complete surfaces and the exact six-stage array validate. Verify: `bash tests/test_workflow_contracts.sh`.
 - [ ] `SP658-T2` Add the deterministic classifier priority table, ordered ladder, writing/research and chat-support verification translations, pre-payload clarification stop, and examples to the canonical routing contract. Covers: B-003, B-006, B-009, B-011. Owner: routing-contract worker. Dependencies: none. Writable files: `workflows/references/routing-contract.md`. Done when: mixed and overlapping requests have one documented outcome and unresolved classification emits no routing payload before clarification. Verify: `bash scripts/ci/validate-workflow-contracts.sh`.
-- [ ] `SP658-T3` Preserve the complete routing decision beside `plan_first` handoffs, register those dependencies, keep `execute_direct` free of a handoff requirement, and require consumers to return changed intent to the canonical router instead of reclassifying. Covers: B-004, B-005, B-010. Owner: consumer worker. Dependencies: SP658-T1, SP658-T2. Writable files: `schemas/workflow-contract-consumers.json`, `workflows/references/delivery-base.md`, `workflows/plan-flow/references/execplan-integration.md`, `workflows/plan-flow/SKILL.md`, `workflows/plan-mode/SKILL.md`, `workflows/auto-optimize/SKILL.md`, `workflows/fixflow/SKILL.md`, `workflows/optflow/SKILL.md`, `agents/dispatcher.md`. Done when: cross-session execution retains both required objects, direct execution requires only routing evidence, and local reclassification is forbidden. Verify: `bash tests/test_manifest_contract.sh` and `bash tests/test_workflow_contracts.sh`.
-- [ ] `SP658-T4` Update all shipped routing-summary surfaces without unrelated style-policy changes. Covers: B-006, B-007, B-009, B-011. Owner: instruction-surface worker. Dependencies: SP658-T2. Writable files: `AGENTS.md`, `templates/AGENTS.md`, `claude-md/vibeguard-rules.md`, `docs/CLAUDE.md.example`, `docs/command-schemas.md`, `docs/README_CN.md`, `.claude/commands/vibeguard/preflight.md`, `skills/vibeguard/SKILL.md`. Done when: each planned instruction surface classifies work surface before readiness and retains domain-appropriate verification. Verify: `bash scripts/ci/validate-workflow-contracts.sh` and `bash tests/test_manifest_contract.sh`.
+- [ ] `SP658-T3` Preserve the complete routing decision beside `plan_first` handoffs, register those dependencies, keep `execute_direct` free of a handoff requirement, and require consumers to return changed intent to the canonical router instead of reclassifying. Covers: B-004, B-005, B-010. Owner: consumer worker. Dependencies: SP658-T1, SP658-T2. Writable files: `schemas/workflow-contract-consumers.json`, `workflows/references/delivery-base.md`, `workflows/plan-flow/references/execplan-integration.md`, `agents/dispatcher.md`, plus the workflow Skill surfaces later retired in GH-763. Done when: cross-session execution retains both required objects, direct execution requires only routing evidence, and local reclassification is forbidden. Verify: `bash tests/test_manifest_contract.sh` and `bash tests/test_workflow_contracts.sh`.
+- [ ] `SP658-T4` Update all shipped routing-summary surfaces without unrelated style-policy changes. Covers: B-006, B-007, B-009, B-011. Owner: instruction-surface worker. Dependencies: SP658-T2. Writable files: `AGENTS.md`, `templates/AGENTS.md`, `claude-md/vibeguard-rules.md`, `docs/CLAUDE.md.example`, `docs/command-schemas.md`, `docs/README_CN.md`, `.claude/commands/vibeguard/preflight.md`, plus the bundled VibeGuard Skill surface later retired in GH-763. Done when: each planned instruction surface classifies work surface before readiness and retains domain-appropriate verification. Verify: `bash scripts/ci/validate-workflow-contracts.sh` and `bash tests/test_manifest_contract.sh`.
 - [ ] `SP658-T5` Add positive and negative schema/consumer regressions for all surfaces, exact precedence, clarification without payload emission, direct/planned object requirements, and persisted routing decisions. Covers: B-001, B-002, B-003, B-008, B-010, B-011. Owner: verification worker. Dependencies: SP658-T1, SP658-T2, SP658-T3, SP658-T4. Writable files: `tests/test_workflow_contracts.sh`. Done when: all valid surfaces pass and every missing, invalid, reordered, duplicated, conflicting, or lane-incomplete case fails with actionable evidence. Verify: `bash tests/test_workflow_contracts.sh`.
 
 ## Parallelization

diff --git a/plan/2026-04-19_00-15-39-main-architecture-convergence.md b/plan/2026-04-19_00-15-39-main-architecture-convergence.md
@@ -35,7 +35,7 @@ source_ref: origin/main@17504d0
   - Runtime adapters: `hooks/run-hook.sh`, `hooks/run-hook-codex.sh`, `vibeguard-runtime/src/codex_app_server.rs`
   - Metadata surfaces: `rules/claude-rules/**`, `rules/*.md`, `docs/rule-reference.md`, `schemas/install-modules.json`, `schemas/vibeguard-project.schema.json`
   - Verification surfaces: `.github/workflows/ci.yml`, `tests/test_hooks.sh`, `tests/test_setup.sh`, `tests/run_precision.sh`, `eval/run_eval.py`
-  - Product/workflow surfaces: `README.md`, `docs/README_CN.md`, `docs/internal/history/spec.md`, `skills/vibeguard/SKILL.md`, `agents/dispatcher.md`, `workflows/**`
+  - Product/workflow surfaces: `README.md`, `docs/README_CN.md`, `docs/internal/history/spec.md`, `agents/dispatcher.md`, `workflows/**`, and the bundled VibeGuard Skill later retired in GH-763
 - Root-cause findings:
 
 | id | category | files and symbols | evidence | impact | risk | suggested convergence |
@@ -44,7 +44,7 @@ source_ref: origin/main@17504d0
 | F2 | split install contract | `scripts/lib/settings_json.py`, `scripts/lib/codex_hooks_json.py`, `schemas/install-modules.json`, `schemas/vibeguard-project.schema.json` | profile names and module composition diverge across code, schema, and docs | high | high | define one canonical install/capability manifest and generate/validate secondary surfaces |
 | F3 | runtime artifact split | `scripts/setup/install.sh`, `hooks/run-hook.sh`, `scripts/install-hook.sh`, `scripts/project-init.sh` | Claude/Codex use installed snapshot while Git hooks still point at live repo | high | medium | unify all runtime entrypoints on installed snapshot plus shared wrapper stack |
 | F4 | verification false confidence | `.github/workflows/ci.yml`, `tests/run_precision.sh`, `tests/test_hooks.sh`, `eval/run_eval.py`, `scripts/benchmark.sh` | Windows lane mostly skips behavior tests, precision never fails CI, rewrite path is provisioned but skipped, eval reads `$HOME` | high | medium | convert CI from report-first to contract-first and pin eval inputs to repo snapshot |
-| F5 | product/document surface sprawl | `README.md`, `docs/README_CN.md`, `docs/internal/history/spec.md`, `skills/vibeguard/SKILL.md`, `agents/dispatcher.md`, `workflows/**` | planning and routing are duplicated across too many top-level surfaces | medium | medium | separate canonical contract from generated/localized/preset surfaces |
+| F5 | product/document surface sprawl | `README.md`, `docs/README_CN.md`, `docs/internal/history/spec.md`, `agents/dispatcher.md`, `workflows/**`, and the bundled VibeGuard Skill later retired in GH-763 | planning and routing are duplicated across too many top-level surfaces | medium | medium | separate canonical contract from generated/localized/preset surfaces |
 
 ## 2. Detailed steps
 
@@ -229,7 +229,7 @@ source_ref: origin/main@17504d0
   - `README.md`
   - `docs/README_CN.md`
   - `docs/internal/history/spec.md`
-  - `skills/vibeguard/SKILL.md`
+  - The bundled VibeGuard Skill surface later retired in GH-763
   - `agents/dispatcher.md`
   - `workflows/**`
 - Detailed changes:
@@ -352,7 +352,7 @@ source_ref: origin/main@17504d0
       - `README.md`
       - `docs/README_CN.md`
       - `docs/internal/history/spec.md`
-      - `skills/vibeguard/SKILL.md`
+      - The bundled VibeGuard Skill surface later retired in GH-763
       - `agents/dispatcher.md`
       - `tests/test_eval_contract.sh`
     - Main changes:

diff --git a/plugins/vibeguard/skills/vibeguard/SKILL.md b/plugins/vibeguard/skills/vibeguard/SKILL.md
@@ -38,4 +38,4 @@ For dashboard, stats, health, doctor, or metrics work, read the
 `vibeguard-observe` skill first. For setup, install, status, or uninstall work,
 read the `vibeguard-setup` skill first.
 For repository development work, follow the root VibeGuard `AGENTS.md` and the
-existing `skills/vibeguard/SKILL.md` in the source checkout.
+repository contribution guidance in `CONTRIBUTING.md`.
diff --git a/schemas/install-modules.json b/schemas/install-modules.json
@@ -150,50 +150,16 @@
     {
       "id": "skills-core",
       "kind": "skills",
-      "description": "Claude core skills (vibeguard, auto-optimize, eval-harness, iterative-retrieval, agentsmd-audit, trajectory-review)",
+      "description": "Claude evaluation and retrieval skills (eval-harness, iterative-retrieval)",
       "paths": [
-        "skills/vibeguard/",
-        "workflows/auto-optimize/",
         "skills/eval-harness/",
-        "skills/iterative-retrieval/",
-        "skills/agentsmd-audit/",
-        "skills/trajectory-review/"
+        "skills/iterative-retrieval/"
       ],
       "target": "~/.claude/skills/",
       "defaultInstall": true,
       "cost": "light",
       "stability": "stable"
     },
-    {
-      "id": "skills-codex-core",
-      "kind": "skills",
-      "description": "Codex core skills (vibeguard, agentsmd-audit, trajectory-review)",
-      "paths": [
-        "skills/vibeguard/",
-        "skills/agentsmd-audit/",
-        "skills/trajectory-review/"
-      ],
-      "target": "~/.codex/skills/",
-      "defaultInstall": true,
-      "cost": "light",
-      "stability": "stable"
-    },
-    {
-      "id": "workflows",
-      "kind": "skills",
-      "description": "Workflow skills (plan-flow, fixflow, optflow, auto-optimize)",
-      "paths": [
-        "workflows/plan-flow/",
-        "workflows/fixflow/",
-        "workflows/optflow/",
-        "workflows/plan-mode/",
-        "workflows/auto-optimize/"
-      ],
-      "target": "~/.codex/skills/",
-      "defaultInstall": true,
-      "cost": "light",
-      "stability": "stable"
-    },
     {
       "id": "commands",
       "kind": "commands",
@@ -286,7 +252,7 @@
       "modules": [
         "rules-common", "rules-rust", "rules-python", "rules-typescript", "rules-golang",
         "hooks-pre", "hooks-post",
-        "agents-core", "skills-core", "skills-codex-core", "workflows", "commands",
+        "agents-core", "skills-core", "commands",
         "guards-universal", "guards-rust", "guards-python", "guards-typescript", "guards-go",
         "context-profiles"
       ]

diff --git a/scripts/lib/install-state.sh b/scripts/lib/install-state.sh
@@ -83,7 +83,7 @@ state_runtime_path() {
 state_runtime_supports() {
   local runtime="$1" capability_out command probe_out
   capability_out="$("${runtime}" setup-state-capabilities 2>/dev/null)" || return 1
-  [[ "${capability_out}" == "complete-snapshot-v1" ]] || return 1
+  [[ "${capability_out}" == "complete-snapshot-v2" ]] || return 1
   for command in \
     setup-state-init \
     setup-state-list \
@@ -159,10 +159,14 @@ state_reject_nonregular_paths() {
 }
 
 # Validate both install-state generations before any active install mutation.
+state_codex_skills_dir() {
+  printf '%s\n' "${CODEX_DIR:-${CODEX_HOME:-${HOME}/.codex}}/skills"
+}
+
 state_preflight() {
   state_reject_legacy_publish_artifacts || return 1
   state_reject_nonregular_paths || return 1
-  state_runtime setup-state-validate-managed-tree-transactions "${HOME}/.codex/skills" || return 1
+  state_runtime setup-state-validate-managed-tree-transactions "$(state_codex_skills_dir)" || return 1
   if [[ -f "$STATE_FILE" ]] \
     && ! state_runtime setup-state-quarantine-count "$STATE_FILE" >/dev/null; then
     printf 'ERROR: refusing to mutate malformed install-state: %s\n' "$STATE_FILE" >&2
@@ -270,7 +274,8 @@ state_init() {
       return 1
     fi
     if ! state_runtime setup-state-init \
-      "$snapshot_tmp" "" "" "$current_generation" "" "$carry_state" complete-snapshot; then
+      "$snapshot_tmp" "" "" "$current_generation" "" "$carry_state" complete-snapshot \
+      "$(state_codex_skills_dir)"; then
       rm -f -- "$snapshot_tmp"
       return 1
     fi
@@ -290,7 +295,8 @@ state_init() {
     return 1
   fi
   state_runtime setup-state-init \
-    "$STATE_FILE" "$profile" "$languages" "$next_generation" "$disabled_csv" "$carry_state"
+    "$STATE_FILE" "$profile" "$languages" "$next_generation" "$disabled_csv" "$carry_state" "" \
+    "$(state_codex_skills_dir)"
 }
 
 state_mark_complete() {
@@ -439,7 +445,7 @@ state_prepare_clean() {
   state_reject_legacy_publish_artifacts || return 1
   state_reject_nonregular_paths || return 1
   state_runtime setup-state-validate-managed-tree-transactions \
-    "${HOME}/.codex/skills" "$STATE_FILE" "$STATE_PREVIOUS_FILE" || return 1
+    "$(state_codex_skills_dir)" "$STATE_FILE" "$STATE_PREVIOUS_FILE" || return 1
   if [[ -f "$STATE_FILE" ]]; then
     current_count="$(state_runtime setup-state-quarantine-count "$STATE_FILE")" || return 1
   fi

diff --git a/scripts/setup/check.sh b/scripts/setup/check.sh
@@ -426,11 +426,11 @@ _check_execution_sources() {
   _check_execution_source_file "Git pre-push" "hooks/git/pre-push"
   _check_execution_source_dir "Native rules" "rules/claude-rules"
   _check_execution_source_dir "Claude commands" ".claude/commands"
-  _check_execution_source_dir "Skills" "skills"
+  _check_execution_source_dir "Claude skills" "skills"
   if [[ -d "$(_execution_source_path "workflows")" ]]; then
-    green "[OK] Workflow skills execution source: $(_execution_source_label) ($(_execution_source_path "workflows"))"
+    green "[OK] Workflow references execution source: $(_execution_source_label) ($(_execution_source_path "workflows"))"
   else
-    red "[BROKEN] Workflow skills execution source missing: $(_execution_source_label) ($(_execution_source_path "workflows"))"
+    red "[BROKEN] Workflow references execution source missing: $(_execution_source_label) ($(_execution_source_path "workflows"))"
   fi
   if [[ -x "${HOME}/.vibeguard/installed/bin/vibeguard-runtime" ]]; then
     green "[OK] Runtime execution source: installed snapshot (${HOME}/.vibeguard/installed/bin/vibeguard-runtime)"

diff --git a/scripts/setup/install.sh b/scripts/setup/install.sh
@@ -793,7 +793,7 @@ echo "  VIBEGUARD_DISABLED_HOOKS=hook1,hook2           Disable project hooks"
 echo "  VIBEGUARD_GC_*                                 Project GC thresholds; see schemas/vibeguard-project.schema.json"
 echo
 echo "User runtime tuning (~/.vibeguard/config.json or env vars):"
-printf '%s\n' "  VIBEGUARD_WRITE_MODE=warn|block                New-source write guard mode" "  VG_U16_WARN_LIMIT / VG_U16_LIMIT               U-16 advisory and hard limits" "  VIBEGUARD_DISABLED_SKILLS=plan-flow,fixflow     Temporary Codex managed-skill override"
+printf '%s\n' "  VIBEGUARD_WRITE_MODE=warn|block                New-source write guard mode" "  VG_U16_WARN_LIMIT / VG_U16_LIMIT               U-16 advisory and hard limits"
 echo
 printf '%s\n' "Git Hooks:" "Automatically installed to VibeGuard repository (pre-commit + pre-push)" "Other projects: bash scripts/project-init.sh <project_dir>"
 setup_lock_release
diff --git a/scripts/setup/lib.sh b/scripts/setup/lib.sh
@@ -76,7 +76,7 @@ setup_runtime_version_matches() {
 setup_runtime_supports() {
   local runtime="$1" capability_out probe_state="${TMPDIR:-/tmp}/vibeguard-runtime-probe.$$.json"
   capability_out="$("${runtime}" setup-state-capabilities 2>/dev/null)" || return 1
-  [[ "${capability_out}" == "complete-snapshot-v1" ]] || return 1
+  [[ "${capability_out}" == "complete-snapshot-v2" ]] || return 1
   "${runtime}" setup-state-list-symlinks-under "${probe_state}" "${TMPDIR:-/tmp}" >/dev/null 2>&1 || return 1
   setup_runtime_version_matches "${runtime}" || return 1
 
@@ -100,6 +100,7 @@ setup_runtime_supports() {
     setup-state-list-tracked-under \
     setup-state-verify-managed-tree \
     setup-state-quarantine-managed-tree \
+    setup-state-remove-managed-tree \
     setup-state-quarantine-count \
     setup-state-validate-managed-tree-transactions \
     setup-state-release-quarantined-tree \
@@ -503,7 +504,7 @@ manifest_rule_labels_checked() {
 }
 
 manifest_skill_links_checked() {
-  local target="$1"
+  local target="$1" allow_empty="${2:-0}"
   local output
   if ! output="$(manifest_skill_links "${target}" 2>&1)"; then
     red "  ERROR: failed to enumerate manifest skills for ${target}" >&2
@@ -513,8 +514,11 @@ manifest_skill_links_checked() {
     return 1
   fi
   if [[ -z "${output//[[:space:]]/}" ]]; then
-    red "  ERROR: no manifest skills declared for ${target}" >&2
-    return 1
+    if [[ -n "${output}" || "${allow_empty}" != "1" ]]; then
+      red "  ERROR: no manifest skills declared for ${target}" >&2
+      return 1
+    fi
+    return 0
   fi
   printf '%s\n' "${output}"
 }
@@ -527,10 +531,10 @@ manifest_skill_links_for_cleanup() {
     while IFS= read -r line; do
       [[ -n "${line}" ]] && yellow "  ${line}" >&2
     done <<< "${output}"
-    return 0
+    return 1
   fi
-  if [[ -z "${output//[[:space:]]/}" ]]; then
-    yellow "  WARN: no manifest skills declared for ${target}; skipping skill link cleanup" >&2
+  if [[ -n "${output}" && -z "${output//[[:space:]]/}" ]]; then
+    yellow "  WARN: no manifest skills declared for ${target}; skipping malformed skill link output" >&2
     return 0
   fi
   printf '%s\n' "${output}"
@@ -545,8 +549,9 @@ cleanup_retired_manifest_skill_links() {
     return 0
   fi
 
-  active_links="$(manifest_skill_links_for_cleanup "${target}")"
-  [[ -n "${active_links//[[:space:]]/}" ]] || return 0
+  if ! active_links="$(manifest_skill_links_for_cleanup "${target}")"; then
+    return 0
+  fi
 
   local active_names=$'\n'
   local source_path skill

diff --git a/scripts/setup/targets/claude-home.sh b/scripts/setup/targets/claude-home.sh
@@ -648,7 +648,9 @@ clean_claude_home_installation() {
     "${REPO_DIR}/.claude/commands/vg" \
     "${HOME}/.vibeguard/installed/.claude/commands/vg"
   local skill_links source_path skill
-  skill_links="$(manifest_skill_links_for_cleanup "~/.claude/skills/")"
+  if ! skill_links="$(manifest_skill_links_for_cleanup "~/.claude/skills/")"; then
+    skill_links=""
+  fi
   while IFS=$'\t' read -r source_path skill; do
     [[ -n "${source_path}" && -n "${skill}" ]] || continue
     rm -f "${CLAUDE_DIR}/skills/${skill}"