okstra 0.82.1 → 0.83.0

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -0,0 +1,126 @@
+"""Shared worker prompt anchor header rendering."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from .paths import okstra_home
+
+
+class WorkerPromptHeaderError(Exception):
+    """Raised when worker prompt anchor headers cannot be rendered."""
+
+
+def worker_prompt_headers(
+    *,
+    project_root: Path,
+    prompt_rel: str,
+    result_rel: str,
+    worker_id: str,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> list[str]:
+    """Render the team-contract worker prompt anchor headers."""
+    prompt_path = _resolve_project_path(project_root, prompt_rel)
+    return [
+        f"**Project Root:** {project_root}",
+        f"**Prompt History Path:** {prompt_rel}",
+        f"**Result Path:** {result_rel}",
+        f"Assigned worker prompt history path: {prompt_path}",
+        f"**Worker Preamble Path:** {_worker_preamble_path()}",
+        f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}",
+        f"**Errors log path:** {_errors_log_path(project_root, manifest, active_context)}",
+        (
+            f"**Errors sidecar path:** "
+            f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
+        ),
+    ]
+
+
+def _worker_preamble_path() -> Path:
+    return okstra_home() / "templates" / "worker-prompt-preamble.md"
+
+
+def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
+    runtime_resources = active_context.get("runtimeResources")
+    if isinstance(runtime_resources, Mapping):
+        value = _string_value(runtime_resources.get("codingPreflightDir"))
+        if value:
+            return Path(value)
+    return okstra_home() / "prompts" / "coding-preflight"
+
+
+def _errors_log_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        value = _string_value(error_logs.get("runErrorsLogPath"))
+        if value:
+            return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    task_type = _require_string(manifest, "taskType")
+    seq = _sequence(manifest, "state")
+    return run_dir / "logs" / f"errors-{task_type}-{seq}.jsonl"
+
+
+def _worker_errors_sidecar_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        sidecars = error_logs.get("sidecarsByWorkerId")
+        if isinstance(sidecars, Mapping):
+            value = _string_value(sidecars.get(worker_id))
+            if value:
+                return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    task_type = _require_string(manifest, "taskType")
+    seq = _sequence(manifest, "workerResults")
+    return run_dir / "worker-results" / f"{worker_id}-worker-errors-{task_type}-{seq}.json"
+
+
+def _run_directory_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    value = _string_value(manifest.get("runDirectoryPath"))
+    if value:
+        return _resolve_project_path(project_root, value)
+    team_state_path = _resolve_project_path(
+        project_root,
+        _require_string(manifest, "teamStatePath"),
+    )
+    return team_state_path.parent.parent
+
+
+def _sequence(manifest: Mapping[str, Any], key: str) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if isinstance(seqs, Mapping):
+        return _string_value(seqs.get(key)) or _run_seq(manifest)
+    return _run_seq(manifest)
+
+
+def _run_seq(manifest: Mapping[str, Any]) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        raise WorkerPromptHeaderError("run manifest has no runSequencesByCategory object")
+    return _require_string(seqs, "manifests")
+
+
+def _resolve_project_path(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise WorkerPromptHeaderError(f"missing required string field: {key}")
+    return value
+
+
+def _string_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""

package/runtime/python/okstra_token_usage/claude.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from .cursor import MAX_NEEDLES, fresh_cache, load_cache, save_cache
 from .paths import claude_project_dir, ts_in_window
 
-# lead 의 단계 체크포인트 라인(agents/SKILL.md "Progress reporting") — phase id 가
+# lead 의 단계 체크포인트 라인(prompts/lead/okstra-lead-contract.md "Progress reporting") — phase id 가
 # `phase-<digit>` 로 시작하는 라인만 마커로 인정해 일반 대화의 오탐을 줄인다.
 _PROGRESS_RE = re.compile(r"^PROGRESS:\s+(phase-\d\S*(?:[ \t].*)?)$", re.MULTILINE)
 _PROGRESS_MARKER_MAX_CHARS = 160

package/runtime/python/okstra_token_usage/collect.py

@@ -159,7 +159,7 @@ def _wall_ms(start_iso: str | None, end_iso: str | None) -> int | None:
 
 
 def phase_timeline(markers: list[dict]) -> dict:
-    """lead 의 PROGRESS 체크포인트(agents/SKILL.md "Progress reporting")로
+    """lead 의 PROGRESS 체크포인트(prompts/lead/okstra-lead-contract.md "Progress reporting")로
     run 내부 단계 경계 wall-clock 을 복원한다 (perf plan v2 P0 계측).
 
     phase id = marker 의 첫 토큰(`phase-5.5-convergence` 등). 같은 phase 의

package/runtime/templates/reports/task-brief.template.md

@@ -112,7 +112,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ### Standing Ticket-Tagging Rule (always applied by every worker)
 
-- 모든 항목 및 표 행에 ticket을 명시한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: <id>]` 태그를 사용한다. 채움 우선순위·폴백·다중 ticket 규칙은 `okstra-team-contract` SKILL의 Ticket Tagging 절을 따른다.
+- 모든 항목 및 표 행에 ticket을 명시한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: <id>]` 태그를 사용한다. 채움 우선순위·폴백·다중 ticket 규칙은 `team-contract` SKILL의 Ticket Tagging 절을 따른다.
 
 ### Standing Scope-Discipline Questions (always answered by every worker)
 
@@ -138,7 +138,7 @@ taskType: "{{FM_TASK_TYPE}}"
 ## Phase Boundary
 
 - This okstra run executes the lifecycle phase named in `Task Type` and stops there. Outputs that belong to any other phase MUST NOT be produced inside this run.
-- Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`agents/SKILL.md`). The lead and every worker stay inside that boundary.
+- Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`prompts/lead/okstra-lead-contract.md`). The lead and every worker stay inside that boundary.
 - "다음 단계 진행해" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
 - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
 - For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.

package/runtime/templates/worker-prompt-preamble.md

@@ -18,7 +18,7 @@ Different recipients need different files. Do NOT include `final-report-template
 |---|---|
 | Claude / Codex / Gemini analysis workers | analysis-packet.md as the primary compact input; task-brief, analysis-profile, analysis-material, reference-expectations, and clarification-response remain source/fallback paths, not automatic first-read files |
 | Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
-| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [okstra-convergence](../skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
+| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [convergence](../prompts/lead/convergence.md) "Reverify prompt: required-reading suppression". |
 
 ### Reading rules
 
@@ -112,7 +112,7 @@ Every item in sections 1–5 (and any section 6) MUST carry a worker-internal it
 
 For task types `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items.
 
-See `skills/okstra-team-contract/SKILL.md` "Worker Output Contract" for the full frontmatter schema and section ordering rules. This preamble is consistent with that contract; the team-contract document is authoritative if the two ever diverge.
+See `prompts/lead/team-contract.md` "Worker Output Contract" for the full frontmatter schema and section ordering rules. This preamble is consistent with that contract; the team-contract document is authoritative if the two ever diverge.
 
 ## Return message to the lead (all workers)
 

package/runtime/validators/lib/validate-assets.sh

@@ -57,10 +57,18 @@ else:
             continue
         check(source_path, workers_target / source_path.name)
 
-# 2. Lead agent SKILL.md: agents/SKILL.md -> runtime/agents/SKILL.md
-lead_source = agents_source_root / "SKILL.md"
-if lead_source.is_file():
-    check(lead_source, runtime_root / "agents" / "SKILL.md")
+# 2. Lead contract + internal lead resources: prompts/lead/* + prompts/coding-preflight/*
+#    -> runtime/prompts/*. These ship as runtime resources (okstra install copies
+#    runtime/prompts -> ~/.okstra/prompts), no longer as agent skills.
+prompts_source_root = agents_source_root.parent / "prompts"
+for sub in ("lead", "coding-preflight"):
+    sub_root = prompts_source_root / sub
+    if not sub_root.is_dir():
+        errors.append(f"missing prompts source directory: {sub_root}")
+        continue
+    for source_path in sorted(sub_root.rglob("*.md")):
+        relative = source_path.relative_to(prompts_source_root)
+        check(source_path, runtime_root / "prompts" / relative)
 
 # 3. Skill packages: skills/<name>/SKILL.md -> runtime/skills/<name>/SKILL.md
 if not skills_source_root.is_dir():

package/runtime/validators/validate-run.py

@@ -436,7 +436,7 @@ def validate_team_state(
                     "team-state.teamCreate.attempted must be true once any worker has "
                     "been dispatched (status in completed/timeout/error/in-progress). "
                     "Phase 3 (TeamCreate) was skipped — workers ran in-process without "
-                    "the Teams split-pane surface. See agents/SKILL.md Phase 3. "
+                    "the Teams split-pane surface. See prompts/lead/okstra-lead-contract.md Phase 3. "
                     "(The no-team concurrent-run path is legal ONLY when the "
                     "run-manifest carries prepare-recorded `concurrentRun.detected: "
                     'true` AND team-state records `teamCreate: { attempted: false, '
@@ -1373,7 +1373,7 @@ def _validate_verdict_card_consistency(content: str, failures: list[str]) -> Non
     """Verdict Card is a non-authoritative index of §7. If both blocks
     carry a Verdict Token row, the values MUST byte-match (modulo case
     and surrounding whitespace) — divergence is a contract violation per
-    `okstra-report-writer` SKILL.md "Authoring Contract".
+    `report-writer` SKILL.md "Authoring Contract".
     """
     card_value = _extract_verdict_card_token(content)
     final_value = _extract_final_verdict_token(content)
@@ -1828,7 +1828,7 @@ def _validate_session_conformance(
     claude_projects_dir: str | None,
     failures: list[str],
 ) -> None:
-    """agents/SKILL.md BLOCKING 계약 3종(PROGRESS 체크포인트 / claude-worker
+    """prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종(PROGRESS 체크포인트 / claude-worker
     heartbeat / implementation entry guard)의 post-hoc 검사를 위임하고 실패를
     ``session-conformance: `` 접두로 folding 한다. 설계:
     docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md

package/runtime/validators/validate_session_conformance.py

@@ -1,12 +1,12 @@
-"""agents/SKILL.md BLOCKING 계약 3종의 post-hoc conformance 검사.
+"""prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종의 post-hoc conformance 검사.
 
 설계: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md
 
 | 검사 | 선언 위치 | 증거 |
 |------|----------|------|
-| 1. lead PROGRESS 체크포인트 라인 | agents/SKILL.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
+| 1. lead PROGRESS 체크포인트 라인 | prompts/lead/okstra-lead-contract.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
 | 2. claude-worker 5분 heartbeat | agents/workers/claude-worker.md "Heartbeat" | audit 사이드카의 `- PROGRESS: <stage> <ISO>` 라인 |
-| 3. implementation sidecar entry guard | agents/SKILL.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
+| 3. implementation sidecar entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
 
 스캔 규칙 (false-pass 방지가 핵심):
 - `type == "assistant"` 레코드만 본다 — Skill 호출 시 SKILL.md 본문(체크포인트
@@ -336,7 +336,7 @@ def _check_worker_checkpoint_lines(
             errors.append(
                 f"PROGRESS checkpoint missing: no `phase-4-dispatch worker=<role>` "
                 f"line names worker `{role}` — one line per dispatched worker, "
-                "agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
         if status == "completed" and not _phase_mentions_worker(
             by_phase.get("phase-5-collect", []), needles
@@ -344,7 +344,7 @@ def _check_worker_checkpoint_lines(
             errors.append(
                 f"PROGRESS checkpoint missing: no `phase-5-collect worker=<role>` "
                 f"line names completed worker `{role}` — one line per collected "
-                "result, agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "result, prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
 
 
@@ -363,19 +363,19 @@ def _check_progress_checkpoints(
         if condition and phase not in by_phase:
             errors.append(
                 f"PROGRESS checkpoint missing: `{phase}` ({detail}) — "
-                "agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
 
     intake = by_phase.get("phase-1-intake", [])
     if not any("complete" not in line.lower() for _ts, line in intake):
         errors.append(
             "PROGRESS checkpoint missing: `phase-1-intake reading task bundle` "
-            "(start-of-Phase-1 line) — agents/SKILL.md 'Progress reporting (BLOCKING)'."
+            "(start-of-Phase-1 line) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
     if not any("complete" in line.lower() for _ts, line in intake):
         errors.append(
             "PROGRESS checkpoint missing: `phase-1-intake complete` "
-            "(after all intake reads) — agents/SKILL.md 'Progress reporting (BLOCKING)'."
+            "(after all intake reads) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
 
     workers = [w for w in (team_state.get("workers") or []) if isinstance(w, dict)]
@@ -427,7 +427,7 @@ def _check_heartbeat_sidecar(path: Path, errors: list[str]) -> None:
             f"`{rel}` has no `- PROGRESS: <stage> <ISO-8601-UTC>` heartbeat lines — "
             "the claude-worker MUST write `started` immediately and append one "
             "line per stage at <= 5-minute cadence (agents/workers/claude-worker.md "
-            "'Heartbeat', agents/SKILL.md Common Mistakes)."
+            "'Heartbeat', prompts/lead/okstra-lead-contract.md Common Mistakes)."
         )
         return
     if entries[0][0] != "started":
@@ -498,7 +498,7 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
                 f"implementation entry guard: no `Read` of `{basename}` found in "
                 f"the lead session jsonl within this run's window — the sidecar "
                 f"MUST be read fresh at {read_at} every implementation run "
-                "(agents/SKILL.md 'Entry guard (BLOCKING)')."
+                "(prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
             )
             continue
         anchor_ts = anchors.get(anchor_phase)
@@ -507,7 +507,7 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
                 f"implementation entry guard: `{basename}` was first Read at "
                 f"{min(ts_list)}, not before the first `PROGRESS: {anchor_phase}` "
                 f"line ({anchor_ts}) — it must be loaded at {read_at}, before "
-                "that checkpoint (agents/SKILL.md 'Entry guard (BLOCKING)')."
+                "that checkpoint (prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
             )
 
 

package/src/install.mjs

@@ -7,6 +7,7 @@ import { resolvePaths } from "./paths.mjs";
 import { fileExists } from "./_proc.mjs";
 import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "./runtime-manifest.mjs";
 import { normalizeRuntimeRequest, resolveRuntime } from "./runtime-resolver.mjs";
+import { OBSOLETE_INTERNAL_SKILL_NAMES, USER_SKILL_NAMES } from "./skill-catalog.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -41,6 +42,26 @@ const BIN_ENTRYPOINTS = [
   "okstra-spawn-followups.py",
 ];
 
+// Runtime prompt resources the launch prompt and routed coding-preflight pack
+// depend on. Intentionally an exact allowlist, not a directory wildcard.
+const REQUIRED_PROMPT_RESOURCE_FILES = Object.freeze([
+  ["prompts", "lead", "okstra-lead-contract.md"],
+  ["prompts", "lead", "context-loader.md"],
+  ["prompts", "lead", "team-contract.md"],
+  ["prompts", "lead", "convergence.md"],
+  ["prompts", "lead", "report-writer.md"],
+  ["prompts", "coding-preflight", "overview.md"],
+  ["prompts", "coding-preflight", "clean-code.md"],
+  ["prompts", "coding-preflight", "languages", "javascript-typescript.md"],
+  ["prompts", "coding-preflight", "languages", "python.md"],
+  ["prompts", "coding-preflight", "languages", "rust.md"],
+  ["prompts", "coding-preflight", "languages", "java.md"],
+  ["prompts", "coding-preflight", "languages", "kotlin.md"],
+  ["prompts", "coding-preflight", "languages", "sql.md"],
+  ["prompts", "coding-preflight", "frameworks", "node-server.md"],
+  ["prompts", "coding-preflight", "architectures", "hexagonal.md"],
+]);
+
 const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
 
 Usage:
@@ -57,6 +78,7 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/lib/validators <- runtime/validators  (stage/report structure validators)
   ${"$HOME"}/.okstra/bin           <- runtime/bin
   ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
+  ${"$HOME"}/.okstra/prompts       <- runtime/prompts  (lead contracts + coding-preflight pack)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- skills when ${"$HOME"}/.claude exists
   ${"$HOME"}/.codex/skills/<name>  <- skills when ${"$HOME"}/.codex exists
@@ -70,6 +92,7 @@ Effect (copy mode):
 Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
+  ${"$HOME"}/.okstra/prompts          -> <repo>/prompts
   ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name> when ${"$HOME"}/.claude exists
   ${"$HOME"}/.codex/skills/<name>     -> <repo>/skills/<name> when ${"$HOME"}/.codex exists
@@ -167,6 +190,16 @@ async function dirExists(path) {
   }
 }
 
+async function pathEntryExists(path) {
+  try {
+    await fs.lstat(path);
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
 async function* walkFiles(root) {
   let entries;
   try {
@@ -237,34 +270,6 @@ async function copyTreeIfChanged(srcRoot, dstRoot, opts) {
   return { copied, skipped, missingSource };
 }
 
-// Single-file variant of copyTreeIfChanged, used for the lead `okstra` skill
-// whose source is one file (agents/SKILL.md) rather than a skill directory.
-async function copyFileIfChanged(src, dst, opts) {
-  const { refresh = false, dryRun = false, mode } = opts ?? {};
-  let srcBuf;
-  try {
-    srcBuf = await fs.readFile(src);
-  } catch {
-    return { copied: 0, skipped: 0, missingSource: true };
-  }
-  let needsCopy = refresh;
-  if (!needsCopy) {
-    try {
-      const [srcHash, dstHash] = await Promise.all([hashFile(src), hashFile(dst)]);
-      needsCopy = srcHash !== dstHash;
-    } catch {
-      needsCopy = true;
-    }
-  }
-  if (!needsCopy) return { copied: 0, skipped: 1, missingSource: false };
-  if (dryRun) {
-    process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
-    return { copied: 1, skipped: 0, missingSource: false };
-  }
-  await writeFileAtomic(dst, srcBuf, mode);
-  return { copied: 1, skipped: 0, missingSource: false };
-}
-
 async function ensureSymlink(target, linkPath, opts) {
   const { dryRun = false } = opts ?? {};
   try {
@@ -341,6 +346,15 @@ async function installLinkMode(repoPath, paths, opts) {
     const action = await ensureSymlink(src, dst, { dryRun });
     if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
   }
+  const promptsSrc = join(repoAbs, "prompts");
+  const promptsDst = join(paths.home, "prompts");
+  if (await dirExists(promptsSrc)) {
+    const action = await ensureSymlink(promptsSrc, promptsDst, { dryRun });
+    if (!quiet) process.stdout.write(`  prompts: ${action}\n`);
+  } else if (!quiet) {
+    process.stdout.write("  prompts: missing in repo — skipped\n");
+  }
+
 
   const skillTargets = await detectSkillTargets();
   const installedSkillTargets = await installSkillTargetsLink(repoAbs, skillTargets, { dryRun, quiet });
@@ -376,16 +390,7 @@ async function installLinkMode(repoPath, paths, opts) {
     );
   }
   return 0;
-}
 
-async function listSkillDirs(skillsRoot) {
-  try {
-    const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-  } catch (err) {
-    if (err.code === "ENOENT") return [];
-    throw err;
-  }
 }
 
 async function detectSkillTargets() {
@@ -612,15 +617,12 @@ const SETTINGS_TEMPLATE_DESCRIPTOR = {
   label: "settings template",
 };
 
-const LEAD_SKILL_NAME = "okstra";
-
 async function installSkillsCopy(runtimeRoot, target, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
-  const names = await listSkillDirs(srcRoot);
   let copied = 0;
   let skipped = 0;
-  for (const name of names) {
+  for (const name of USER_SKILL_NAMES) {
     const r = await copyTreeIfChanged(
       join(srcRoot, name),
       join(target.skillsDir, name),
@@ -629,65 +631,48 @@ async function installSkillsCopy(runtimeRoot, target, opts) {
     copied += r.copied;
     skipped += r.skipped;
   }
-  const lead = await installLeadSkillCopy(runtimeRoot, target, opts);
+  const pruned = await pruneObsoleteInternalSkills(target, opts);
   if (!quiet) {
-    const totalCopied = copied + lead.copied;
-    const totalSkipped = skipped + lead.skipped;
-    const totalSkills = names.length + lead.installed.length;
     process.stdout.write(
-      `  ${target.provider} skills: copied=${totalCopied} skipped=${totalSkipped} -> ${target.skillsDir}/ (${totalSkills} skills)\n`,
+      `  ${target.provider} skills: copied=${copied} skipped=${skipped} pruned=${pruned} -> ${target.skillsDir}/ (${USER_SKILL_NAMES.length} skills)\n`,
     );
   }
-  return { ...target, installed: [...names, ...lead.installed] };
+  return { ...target, installed: [...USER_SKILL_NAMES] };
 }
 
 async function installSkillsLink(repoAbs, target, opts) {
   const { dryRun, quiet } = opts;
   const srcRoot = join(repoAbs, "skills");
-  const names = await listSkillDirs(srcRoot);
   if (!dryRun) await fs.mkdir(target.skillsDir, { recursive: true });
-  for (const name of names) {
+  for (const name of USER_SKILL_NAMES) {
     const src = join(srcRoot, name);
     const dst = join(target.skillsDir, name);
     const action = await ensureSymlink(src, dst, { dryRun });
     if (!quiet) process.stdout.write(`  ${target.provider} skills/${name}: ${action}\n`);
   }
-  const lead = await installLeadSkillLink(repoAbs, target, opts);
-  return { ...target, installed: [...names, ...lead] };
-}
-
-async function installLeadSkillCopy(runtimeRoot, target, opts) {
-  const { refresh, dryRun, quiet } = opts;
-  const src = join(runtimeRoot, "agents", "SKILL.md");
-  const dst = join(target.skillsDir, LEAD_SKILL_NAME, "SKILL.md");
-  const r = await copyFileIfChanged(src, dst, { refresh, dryRun, mode: 0o644 });
-  if (r.missingSource) {
-    if (!quiet) {
-      process.stdout.write(
-        `  ${target.provider} skills/okstra: runtime/agents/SKILL.md missing — skipped\n`,
-      );
-    }
-    return { installed: [], copied: 0, skipped: 0 };
+  const pruned = await pruneObsoleteInternalSkills(target, opts);
+  if (!quiet && pruned > 0) {
+    process.stdout.write(`  ${target.provider} obsolete internal skills: pruned=${pruned}\n`);
   }
-  return { installed: [LEAD_SKILL_NAME], copied: r.copied, skipped: r.skipped };
+  return { ...target, installed: [...USER_SKILL_NAMES] };
 }
 
-async function installLeadSkillLink(repoAbs, target, opts) {
-  const { dryRun, quiet } = opts;
-  const src = join(repoAbs, "agents", "SKILL.md");
-  if (!(await fileExists(src))) {
-    if (!quiet) {
-      process.stdout.write(
-        `  ${target.provider} skills/okstra: <repo>/agents/SKILL.md missing — skipped\n`,
-      );
+// Remove former internal skill directories left by older installs. Exact-name
+// only (OBSOLETE_INTERNAL_SKILL_NAMES) — those contracts now ship as runtime
+// resources under ~/.okstra/prompts/, not as agent skills.
+async function pruneObsoleteInternalSkills(target, opts) {
+  let pruned = 0;
+  for (const name of OBSOLETE_INTERNAL_SKILL_NAMES) {
+    const path = join(target.skillsDir, name);
+    if (!(await pathEntryExists(path))) continue;
+    pruned += 1;
+    if (opts.dryRun) {
+      process.stdout.write(`[dry-run] rm ${path}\n`);
+      continue;
     }
-    return [];
+    await fs.rm(path, { recursive: true, force: true });
   }
-  const dst = join(target.skillsDir, LEAD_SKILL_NAME, "SKILL.md");
-  if (!dryRun) await fs.mkdir(join(target.skillsDir, LEAD_SKILL_NAME), { recursive: true });
-  const action = await ensureSymlink(src, dst, { dryRun });
-  if (!quiet) process.stdout.write(`  ${target.provider} skills/okstra/SKILL.md: ${action}\n`);
-  return [LEAD_SKILL_NAME];
+  return pruned;
 }
 
 async function installSkillTargetsCopy(runtimeRoot, targets, opts) {
@@ -828,6 +813,17 @@ export async function runInstall(args) {
     join(paths.home, "lib", "validators"),
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
+  // prompts/ tree — lead/internal operating contracts (prompts/lead/*.md) and
+  // the coding-preflight resource pack (prompts/coding-preflight/*) are read at
+  // runtime by the lead and executor via absolute ~/.okstra/prompts/ paths
+  // (paths.py OKSTRA_LEAD_CONTRACT_PATH / OKSTRA_CODING_PREFLIGHT_DIR). Run-prep
+  // reads prompts/profiles + launch.template from the package runtime dir, but
+  // the lead's runtime Read needs them under the home tree like templates.
+  const promptsResult = await copyTreeIfChanged(
+    join(runtimeRoot, "prompts"),
+    join(paths.home, "prompts"),
+    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
+  );
 
   if (!opts.quiet) {
     summarise("python", pythonResult, paths.pythonpath);
@@ -835,6 +831,7 @@ export async function runInstall(args) {
     summarise("templates", templatesResult, join(paths.home, "templates"));
     summarise("schemas", schemasResult, join(paths.home, "schemas"));
     summarise("validators", validatorsResult, join(paths.home, "lib", "validators"));
+    summarise("prompts", promptsResult, join(paths.home, "prompts"));
   }
 
   if (pythonResult.missingSource && binResult.missingSource) {
@@ -857,6 +854,11 @@ export async function runInstall(args) {
       "warning: runtime/validators is empty. stage-structure / report validation will use stale or missing validators — re-run the build step.\n",
     );
   }
+  if (promptsResult.missingSource) {
+    process.stderr.write(
+      "warning: runtime/prompts is empty. lead contracts + coding-preflight resources will be missing — re-run the build step.\n",
+    );
+  }
 
   const skillTargets = await detectSkillTargets();
   const installedSkillTargets = await installSkillTargetsCopy(runtimeRoot, skillTargets, opts);
@@ -895,7 +897,7 @@ export async function runInstall(args) {
 async function skillTargetDriftReasons(targets) {
   const reasons = [];
   for (const target of targets) {
-    for (const name of ["okstra-run", LEAD_SKILL_NAME]) {
+    for (const name of USER_SKILL_NAMES) {
       const skillPath = join(target.skillsDir, name, "SKILL.md");
       if (!(await fileExists(skillPath))) {
         reasons.push(`missing ${skillPath}`);
@@ -905,6 +907,15 @@ async function skillTargetDriftReasons(targets) {
   return reasons;
 }
 
+async function promptResourceDriftReasons(paths) {
+  const reasons = [];
+  for (const parts of REQUIRED_PROMPT_RESOURCE_FILES) {
+    const path = join(paths.home, ...parts);
+    if (!(await fileExists(path))) reasons.push(`missing ${path}`);
+  }
+  return reasons;
+}
+
 async function agentDriftReasons(paths) {
   const reasons = [];
   const workersDir = join(paths.agents, "workers");
@@ -987,6 +998,9 @@ export async function runEnsureInstalled(args) {
   if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
     reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
   }
+  for (const reason of await promptResourceDriftReasons(paths)) {
+    reasons.push(reason);
+  }
   const skillTargets = await detectSkillTargets();
   for (const reason of await skillTargetDriftReasons(skillTargets)) {
     reasons.push(reason);