phasegate 0.160.15 → 0.160.16

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.160.16] - 2026-05-22
+
+### Fixed
+
+- **WI-210 — project install shared skills** — makes `phasegate install` deploy selected bundled skills to root `skills/` for project installs, validates missing skill target content in `doctor`, repairs older empty-skill installs through `reconcile` / `update-skills`, and keeps uninstall scoped to manifest-managed skill directories.
+
 ## [0.160.12] - 2026-05-20
 
 ### Added

package/README.ja.md

@@ -105,7 +105,7 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install` は既存の Claude / Codex hooks や Husky script を捨てずに PhaseGate の設定を merge します。書き込み前に変更予定を表示し、package scripts と `phasegate` devDependency、agent skill symlink、未作成の CI workflow、`.phasegate/manifest.json` を整えます。強制的な managed 更新が必要な場合は `npx phasegate install --apply --force` を使います。この場合、置き換え対象は `.phasegate/backups/` に退避されます。
+`install` は既存の Claude / Codex hooks や Husky script を捨てずに PhaseGate の設定を merge します。書き込み前に変更予定を表示し、package scripts と `phasegate` devDependency、root `skills/` への selected bundled skills 配布、agent skill symlink、未作成の CI workflow、`.phasegate/manifest.json` を整えます。強制的な managed 更新が必要な場合は `npx phasegate install --apply --force` を使います。この場合、置き換え対象は `.phasegate/backups/` に退避されます。<!-- @work-item-id WI-210 -->
 
 後で PhaseGate を外す場合は、manifest ベースの uninstall を使います。
 
@@ -123,7 +123,7 @@ npx phasegate reconcile --dry-run
 npx phasegate reconcile --apply
 ```
 
-`reconcile` は PhaseGate 管理部分だけを更新し、ユーザーの hook / script / dependency は保持します。新しい deploy target が追加されていれば install と同じく追加し、`.phasegate/manifest.json` の version / hash も更新します。install 後に user 改変された managed file は `--force` 無しでは refuse し、force 時は `.phasegate/backups/reconcile-<timestamp>/` に退避してから上書きします。
+`reconcile` は PhaseGate 管理部分だけを更新し、ユーザーの hook / script / dependency は保持します。新しい deploy target が追加されていれば install と同じく追加し、project install の shared skills 実体が欠落している場合も修復し、`.phasegate/manifest.json` の version / hash も更新します。install 後に user 改変された managed file は `--force` 無しでは refuse し、force 時は `.phasegate/backups/reconcile-<timestamp>/` に退避してから上書きします。<!-- @work-item-id WI-210 -->
 
 ### Codex CLI を使う場合
 

package/README.md

@@ -100,7 +100,7 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install` merges PhaseGate into the current project without discarding existing Claude/Codex hooks or Husky scripts. It reports planned changes before writing, adds package scripts and the `phasegate` devDependency, creates agent skill links, writes `AGENTS.md` / `CLAUDE.md` PhaseGate managed sections for the selected agent targets, writes the CI workflow when missing, and records managed files in `.phasegate/manifest.json`. If an existing file needs a forced managed update, run `npx phasegate install --apply --force`; PhaseGate backs up replaced files under `.phasegate/backups/`. <!-- @work-item-id WI-174 -->
+`install` merges PhaseGate into the current project without discarding existing Claude/Codex hooks or Husky scripts. It reports planned changes before writing, adds package scripts and the `phasegate` devDependency, deploys selected bundled skills to root `skills/`, creates agent skill links to that shared directory, writes `AGENTS.md` / `CLAUDE.md` PhaseGate managed sections for the selected agent targets, writes the CI workflow when missing, and records managed files in `.phasegate/manifest.json`. If an existing file needs a forced managed update, run `npx phasegate install --apply --force`; PhaseGate backs up replaced files under `.phasegate/backups/`. <!-- @work-item-id WI-174 --> <!-- @work-item-id WI-210 -->
 
 For personal evaluation inside a team-owned repository, use local-only install:
 
@@ -138,7 +138,7 @@ npx phasegate reconcile --dry-run
 npx phasegate reconcile --apply
 ```
 
-`reconcile` updates only PhaseGate-managed portions, keeps user content, adds newly introduced managed targets, and refreshes `.phasegate/manifest.json` with the current version and hashes. If a managed file was edited after install, `reconcile --apply` refuses that entry until you rerun with `--force`; PhaseGate writes a backup under `.phasegate/backups/reconcile-<timestamp>/`.
+`reconcile` updates only PhaseGate-managed portions, keeps user content, adds newly introduced managed targets, repairs missing shared skill bodies for project installs, and refreshes `.phasegate/manifest.json` with the current version and hashes. If a managed file was edited after install, `reconcile --apply` refuses that entry until you rerun with `--force`; PhaseGate writes a backup under `.phasegate/backups/reconcile-<timestamp>/`. <!-- @work-item-id WI-210 -->
 
 ### Codex CLI
 

package/docs/guide/setup-artifacts.md

@@ -12,7 +12,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 | Class | Examples | Owner | Lifecycle |
 |---|---|---|---|
-| Managed target | `phasegate.config.json`, `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block, real runtime artifact, or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
+| Managed target | `phasegate.config.json`, `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, root `skills/` bundled skill bodies, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block, real runtime artifact, shared skill body, or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
 | Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init` or project install when absent; `install` may merge scripts/devDependency into `package.json` |
 | Generated artifact | `.phasegate/manifest.json`, `.phasegate/backups/*`, `.phasegate/uninstalled-*.json`, `.phasegate/baseline.json` | PhaseGate | Written by lifecycle commands and validators; safe to regenerate only through the owning command |
 | Runtime state/report | `.phasegate/hook-skip-events.jsonl`, explicit `doctor --report-out <path>` output, `reports/regression/*`, resolved `reporting.outputDir` reports | PhaseGate command output | Produced while hooks, doctor, and validation commands run |
@@ -29,6 +29,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 - Husky scripts when requested: `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`
 - CI workflow when requested: `.github/workflows/phasegate-aidlc-gate.yml`
 - Agent skill links: `.claude/skills`, `.codex/skills`
+- Project shared bundled skills: selected `skills/<name>/` directories plus `skills/.harness-version`
 - Project config: `phasegate.config.json` when absent, so installed agent hooks have a discoverable runtime config
 - Package metadata: PhaseGate scripts and `devDependencies.phasegate` in `package.json`
 - Manifest: `.phasegate/manifest.json`
@@ -43,6 +44,8 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 If `.claude/*` or `.codex/*` already exists and is not a PhaseGate-managed personal artifact, personal install reports manual review and preserves the existing path. <!-- @work-item-id WI-209 -->
 
+Project install uses a different topology: selected bundled skills are deployed once to root `skills/`, and `.claude/skills` / `.codex/skills` point to that shared target. If an older project install has the links but an empty `skills/` target, `phasegate doctor` reports the selected agent skill check and `phasegate reconcile --apply` repairs the shared skill bodies. <!-- @work-item-id WI-210 -->
+
 ## Doctor Findings
 
 `phasegate doctor` evaluates setup health from the managed targets and related project state. Findings include `repairMode`, optional `repairHint`, and optional `suggestedSkill`.

package/docs/guide/skills-overview.md

@@ -1,6 +1,6 @@
 # Skills Overview
 
-Phasegate provides 30 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` deploys the skill bodies to `skills/` and exposes them to enabled agents through `.claude/skills/` / `.codex/skills/` links.
+Phasegate provides 30 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` and project `npx phasegate install` deploy skill bodies to root `skills/` and expose them to enabled agents through `.claude/skills/` / `.codex/skills/` links. Personal install instead writes real local-only per-agent skill directories. <!-- @work-item-id WI-210 -->
 
 ## AIDLC Process — Skill Execution Order
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.15",
+  "version": "0.160.16",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/installation/application/checks/check-utils.ts

@@ -2,6 +2,7 @@
 // @layer application
 // @work-item-id WI-145
 // @work-item-id WI-209
+// @work-item-id WI-210
 
 import { join } from "node:path";
 import type { CheckId } from "../../domain/check-id.js";

package/scripts/harness/installation/application/checks/claude-skills-symlink-check.ts

@@ -2,6 +2,7 @@
 // @layer application
 // @work-item-id WI-145
 // @work-item-id WI-209
+// @work-item-id WI-210
 
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
@@ -14,15 +15,15 @@ export class ClaudeSkillsSymlinkCheck implements HeuristicCheck {
 
   async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
     const link = await inspector.readSymlink(projectPath(projectRoot, this.target));
-    if (skillTargetLooksValid(link)) return null;
     const files = await inspector.listFiles(projectPath(projectRoot, this.target));
-    if (skillDirectoryLooksValid(files)) return null;
+    if (skillTargetLooksValid(link) && skillDirectoryLooksValid(files)) return null;
+    if (link === null && skillDirectoryLooksValid(files)) return null;
     return createFinding({
       checkId: this.checkId,
       severity: "red",
       target: this.target,
       message: ".claude/skills に phasegate skills がありません",
-      repairMode: link === null ? "mechanical" : "manual",
+      repairMode: link === null || skillTargetLooksValid(link) ? "mechanical" : "manual",
     });
   }
 }

package/scripts/harness/installation/application/checks/codex-skills-symlink-check.ts

@@ -2,6 +2,7 @@
 // @layer application
 // @work-item-id WI-145
 // @work-item-id WI-209
+// @work-item-id WI-210
 
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
@@ -14,15 +15,15 @@ export class CodexSkillsSymlinkCheck implements HeuristicCheck {
 
   async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
     const link = await inspector.readSymlink(projectPath(projectRoot, this.target));
-    if (skillTargetLooksValid(link)) return null;
     const files = await inspector.listFiles(projectPath(projectRoot, this.target));
-    if (skillDirectoryLooksValid(files)) return null;
+    if (skillTargetLooksValid(link) && skillDirectoryLooksValid(files)) return null;
+    if (link === null && skillDirectoryLooksValid(files)) return null;
     return createFinding({
       checkId: this.checkId,
       severity: "red",
       target: this.target,
       message: ".codex/skills に phasegate skills がありません",
-      repairMode: link === null ? "mechanical" : "manual",
+      repairMode: link === null || skillTargetLooksValid(link) ? "mechanical" : "manual",
     });
   }
 }

package/scripts/harness/installation/application/usecases/run-install.ts

@@ -10,9 +10,11 @@
 // @work-item-id WI-207
 // @work-item-id WI-208
 // @work-item-id WI-209
+// @work-item-id WI-210
 
-import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink, readdir } from "node:fs/promises";
+import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink, readdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { getSkillsForSet, type SkillSet } from "../../../setup/skill-deployer.js";
 import { DeploymentEntry } from "../../domain/deployment-entry.js";
 import { DeploymentManifest } from "../../domain/deployment-manifest.js";
 import type { ManagedBlockInput } from "../../domain/managed-block.js";
@@ -86,6 +88,7 @@ const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 const TEXT_BEGIN = "# phasegate personal install exclude (BEGIN)";
 const TEXT_END = "# phasegate personal install exclude (END)";
 const PERSONAL_AGENT_RUNTIME_FILES = new Set([".claude/settings.json", ".codex/hooks.json"]);
+const SHARED_SKILLS_VERSION_PATH = "skills/.harness-version";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -122,6 +125,16 @@ async function copyDirectory(src: string, dest: string): Promise<void> {
   }
 }
 
+async function listSelectedBundledSkills(harnessRoot: string, skillSet: SkillSet): Promise<string[]> {
+  const skillsSource = join(harnessRoot, "skills");
+  const allowed = new Set(getSkillsForSet(skillSet));
+  const entries = await readdir(skillsSource, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && allowed.has(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+}
+
 function normalizeJsonEntry(value: unknown): string {
   return JSON.stringify(value);
 }
@@ -431,6 +444,32 @@ export class RunInstallUseCase {
       }
     }
 
+    if (!input.personal && (includeClaude || includeCodex)) {
+      const sharedSkills = await listSelectedBundledSkills(input.harnessRoot, skillSet);
+      const item = await this.planSharedSkillDirectory(input, sharedSkills, baseManifest);
+      plan.push(item);
+      if (input.apply && item.changed && item.repairMode === "mechanical") {
+        try {
+          await this.deploySharedSkills(input, sharedSkills, skillSet);
+        } catch (error) {
+          return this.withApplyError({ plan, refused, changed, backupDir }, item.path, "copyDirectory", error);
+        }
+        changed.push(item);
+        manifest = this.addManifestEntry(baseManifest, manifest, {
+          path: SHARED_SKILLS_VERSION_PATH,
+          mode: "created",
+          contentForHash: this.sharedSkillsVersionHashInput(input.phasegateVersion, skillSet, sharedSkills),
+        });
+        for (const skill of sharedSkills) {
+          manifest = this.addManifestEntry(baseManifest, manifest, {
+            path: `skills/${skill}`,
+            mode: "created",
+            contentForHash: this.sharedSkillHashInput(skill, input.phasegateVersion, skillSet),
+          });
+        }
+      }
+    }
+
     const linkSpecs = input.personal
       ? []
       : [
@@ -691,6 +730,62 @@ export class RunInstallUseCase {
     return `personal-skills:${path}:${version}:${skillSet}`;
   }
 
+  private async planSharedSkillDirectory(
+    input: RunInstallInput,
+    skills: readonly string[],
+    baseManifest: DeploymentManifest,
+  ): Promise<InstallPlanItem> {
+    const versionPath = join(input.projectRoot, SHARED_SKILLS_VERSION_PATH);
+    const current = await readTextOrNull(versionPath);
+    const skillSet = input.skillSet ?? "all";
+    const expectedVersion = `"version": "${input.phasegateVersion}"`;
+    const expectedSkillSet = `"skillSet": "${skillSet}"`;
+    let missingSkill = false;
+    for (const skill of skills) {
+      if (!(await exists(join(input.projectRoot, "skills", skill, "SKILL.md")))) {
+        missingSkill = true;
+        break;
+      }
+    }
+    const missingManifest = baseManifest.findEntry(SHARED_SKILLS_VERSION_PATH) === null
+      || skills.some((skill) => baseManifest.findEntry(`skills/${skill}`) === null);
+    const changed = current === null || !current.includes(expectedVersion) || !current.includes(expectedSkillSet) || missingSkill || missingManifest;
+    return {
+      path: "skills",
+      action: changed ? "missing" : "will-skip",
+      repairMode: "mechanical",
+      strategy: "copy-dir",
+      changed,
+      summary: changed ? "skills: deploy shared bundled skills" : "skills: already up to date",
+      diff: changed ? `+ ${skills.length} bundled skills (${skillSet})` : "no changes",
+      skillHint: null,
+    };
+  }
+
+  private async deploySharedSkills(input: RunInstallInput, skills: readonly string[], skillSet: SkillSet): Promise<void> {
+    const targetRoot = join(input.projectRoot, "skills");
+    await mkdir(targetRoot, { recursive: true });
+    for (const skill of skills) {
+      const source = join(input.harnessRoot, "skills", skill);
+      const target = join(targetRoot, skill);
+      await rm(target, { recursive: true, force: true });
+      await copyDirectory(source, target);
+    }
+    await writeFile(
+      join(targetRoot, ".harness-version"),
+      `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  private sharedSkillsVersionHashInput(version: string, skillSet: SkillSet, skills: readonly string[]): string {
+    return `shared-skills-version:${version}:${skillSet}:${skills.join(",")}`;
+  }
+
+  private sharedSkillHashInput(skill: string, version: string, skillSet: SkillSet): string {
+    return `shared-skill:${skill}:${version}:${skillSet}`;
+  }
+
   private addManifestEntry(
     baseManifest: DeploymentManifest,
     manifest: DeploymentManifest,

package/scripts/harness/installation/application/usecases/run-reconcile.ts

@@ -3,9 +3,11 @@
 // @work-item-id WI-148
 // @work-item-id WI-174
 // @work-item-id WI-198
+// @work-item-id WI-210
 
-import { access, chmod, copyFile, lstat, mkdir, readFile, readlink, symlink, writeFile } from "node:fs/promises";
+import { access, chmod, copyFile, lstat, mkdir, readFile, readlink, readdir, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
+import { getSkillsForSet, type SkillSet } from "../../../setup/skill-deployer.js";
 import { DeploymentEntry } from "../../domain/deployment-entry.js";
 import { DeploymentManifest } from "../../domain/deployment-manifest.js";
 import type { ManagedBlockInput } from "../../domain/managed-block.js";
@@ -14,7 +16,7 @@ import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
 type ReconcileAction = "missing-manifest" | "update" | "add" | "link" | "skip" | "refuse";
-type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "symlink" | "unknown";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "copy-dir" | "symlink" | "unknown";
 
 export interface ReconcilePlanItem {
   readonly path: string;
@@ -56,6 +58,7 @@ const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
 const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
 const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
+const SHARED_SKILLS_VERSION_PATH = "skills/.harness-version";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -78,6 +81,29 @@ async function readTextOrNull(path: string): Promise<string | null> {
   }
 }
 
+async function copyDirectory(src: string, dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath);
+    } else if (entry.isFile()) {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function listSelectedBundledSkills(harnessRoot: string, skillSet: SkillSet): Promise<string[]> {
+  const allowed = new Set(getSkillsForSet(skillSet));
+  const entries = await readdir(join(harnessRoot, "skills"), { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && allowed.has(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+}
+
 function normalizeJsonEntry(value: unknown): string {
   return JSON.stringify(value);
 }
@@ -259,6 +285,13 @@ export class RunReconcileUseCase {
       }
     }
 
+    if (this.manifestIntendsSharedSkills(manifest)) {
+      const sharedSkills = await listSelectedBundledSkills(input.harnessRoot, "all");
+      const outcome = await this.planSharedSkills(input, manifest, sharedSkills, "all");
+      outcomes.push(outcome);
+      plan.push(outcome.item);
+    }
+
     if (!input.apply || refused.length > 0) {
       return { plan, refused, changed, backupDir: null };
     }
@@ -272,16 +305,24 @@ export class RunReconcileUseCase {
       const hashContent = await outcome.apply();
       changed.push(outcome.item);
       if (hashContent !== null) {
-        const mode = outcome.item.strategy === "symlink" ? "symlink" : outcome.item.action === "add" ? "created" : (manifest.findEntry(outcome.item.path)?.mode ?? "merged");
-        nextManifest = nextManifest.addEntry(
-          DeploymentEntry.create({
-            path: outcome.item.path,
-            mode,
-            block: mode === "merged" ? this.managedBlockFor(outcome.item.path, outcome.item.strategy) : null,
-            hash: this.hashCalculator.compute(hashContent),
-            deployedAt: new Date().toISOString(),
-          }),
-        );
+        if (outcome.item.strategy === "copy-dir" && outcome.item.path === "skills") {
+          const sharedSkills = await listSelectedBundledSkills(input.harnessRoot, "all");
+          nextManifest = nextManifest.addEntry(this.createdEntry(SHARED_SKILLS_VERSION_PATH, this.sharedSkillsVersionHashInput(input.phasegateVersion, "all", sharedSkills)));
+          for (const skill of sharedSkills) {
+            nextManifest = nextManifest.addEntry(this.createdEntry(`skills/${skill}`, this.sharedSkillHashInput(skill, input.phasegateVersion, "all")));
+          }
+        } else {
+          const mode = outcome.item.strategy === "symlink" ? "symlink" : outcome.item.action === "add" ? "created" : (manifest.findEntry(outcome.item.path)?.mode ?? "merged");
+          nextManifest = nextManifest.addEntry(
+            DeploymentEntry.create({
+              path: outcome.item.path,
+              mode,
+              block: mode === "merged" ? this.managedBlockFor(outcome.item.path, outcome.item.strategy) : null,
+              hash: this.hashCalculator.compute(hashContent),
+              deployedAt: new Date().toISOString(),
+            }),
+          );
+        }
       }
     }
 
@@ -388,6 +429,84 @@ export class RunReconcileUseCase {
     }
   }
 
+  private manifestIntendsSharedSkills(manifest: DeploymentManifest): boolean {
+    return manifest.findEntry(".claude/skills") !== null
+      || manifest.findEntry(".codex/skills") !== null
+      || manifest.entries.some((entry) => entry.path.startsWith("skills/"));
+  }
+
+  private async planSharedSkills(
+    input: RunReconcileInput,
+    manifest: DeploymentManifest,
+    skills: readonly string[],
+    skillSet: SkillSet,
+  ) {
+    const versionContent = await readTextOrNull(this.resolveProjectPath(input.projectRoot, SHARED_SKILLS_VERSION_PATH));
+    const expectedVersion = `"version": "${input.phasegateVersion}"`;
+    let missingSkill = false;
+    for (const skill of skills) {
+      if (!(await exists(this.resolveProjectPath(input.projectRoot, `skills/${skill}/SKILL.md`)))) {
+        missingSkill = true;
+        break;
+      }
+    }
+    const missingManifest = manifest.findEntry(SHARED_SKILLS_VERSION_PATH) === null
+      || skills.some((skill) => manifest.findEntry(`skills/${skill}`) === null);
+    const changed = versionContent === null || !versionContent.includes(expectedVersion) || missingSkill || missingManifest;
+    return {
+      item: this.item(
+        "skills",
+        changed ? "add" : "skip",
+        "mechanical",
+        "copy-dir",
+        changed,
+        changed ? "skills: deploy shared bundled skills" : "skills: already up to date",
+        changed ? `+ ${skills.length} bundled skills (${skillSet})` : "no changes",
+        null,
+      ),
+      needsBackup: false,
+      apply: async () => {
+        if (!changed) return null;
+        await this.deploySharedSkills(input, skills, skillSet);
+        return this.sharedSkillsVersionHashInput(input.phasegateVersion, skillSet, skills);
+      },
+    };
+  }
+
+  private async deploySharedSkills(input: RunReconcileInput, skills: readonly string[], skillSet: SkillSet): Promise<void> {
+    const targetRoot = this.resolveProjectPath(input.projectRoot, "skills");
+    await mkdir(targetRoot, { recursive: true });
+    for (const skill of skills) {
+      const source = join(input.harnessRoot, "skills", skill);
+      const target = join(targetRoot, skill);
+      await rm(target, { recursive: true, force: true });
+      await copyDirectory(source, target);
+    }
+    await writeFile(
+      join(targetRoot, ".harness-version"),
+      `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  private createdEntry(path: string, hashInput: string): DeploymentEntry {
+    return DeploymentEntry.create({
+      path,
+      mode: "created",
+      block: null,
+      hash: this.hashCalculator.compute(hashInput),
+      deployedAt: new Date().toISOString(),
+    });
+  }
+
+  private sharedSkillsVersionHashInput(version: string, skillSet: SkillSet, skills: readonly string[]): string {
+    return `shared-skills-version:${version}:${skillSet}:${skills.join(",")}`;
+  }
+
+  private sharedSkillHashInput(skill: string, version: string, skillSet: SkillSet): string {
+    return `shared-skill:${skill}:${version}:${skillSet}`;
+  }
+
   private reconcileContent(target: ReconcileTarget, before: string | null, template: string, version: string): string {
     if (target.strategy === "yaml-add") return template;
     if (target.strategy === "shell") return reconcileShell(before, template);