@try-works/dsh-recursive-mode 0.3.0 → 0.3.1

package/lib/index.d.ts

@@ -23,6 +23,7 @@ export * from './policy.ts';
 export * from './snapshot.ts';
 export * from './live-route.ts';
 export * from './teams-loop.ts';
+export * from './skills.ts';
 /**
  * Bundle plugin entry. The Loader activates this row once `tools` is available
  * (`inject` below); the RecursiveRuntime service is constructed directly so it

package/lib/index.js

@@ -6712,12 +6712,12 @@ function createRecursiveAuditTeamTool(teams) {
 * references/ (never inlined TS string literals) and resolved relative to this
 * module (package install location), never process.cwd().
 */
-const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const MODULE_DIR$1 = dirname(fileURLToPath(import.meta.url));
 /** Package root: <package>/src/.. — references/ sits next to src/. */
-const PACKAGE_ROOT = join(MODULE_DIR, "..");
+const PACKAGE_ROOT$1 = join(MODULE_DIR$1, "..");
 /** references/ root (shipped package files). */
 function referencesRoot() {
-	return join(PACKAGE_ROOT, "references");
+	return join(PACKAGE_ROOT$1, "references");
 }
 const M = {
 	recursiveStart: "<!-- RECURSIVE-MODE-CANONICAL:START -->",
@@ -7626,6 +7626,91 @@ function mountRecursiveRoutesOnce(packageName, makeRoutes, webServer) {
 	};
 }
 //#endregion
+//#region src/skills.ts
+/**
+* Packaged `recursive-mode` skill (dsh plugin standard).
+*
+* Ships the workflow's operating contract as a bundled skill through
+* `ctx.skills.registerProvider(...)` — the same shape as the shipped
+* `dsh-skill-badge` provider: a `bundled` candidate at `BUNDLED_SKILL_RANK`
+* (600), body read from the package's shipped `skills/recursive-mode/SKILL.md`
+* (never an inlined TS string literal), with a directory resource base so the
+* skill can resolve its own assets. Skills are optional instructions, not
+* session events: this emits nothing and never appends a recursive/* event.
+*
+* Optionality: `skills` is a host-plane registry; when the composition has
+* none, this is a no-op (returns undefined) rather than failing boot.
+*/
+/** Package root: <package>/src/.. — skills/ sits next to src/. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(MODULE_DIR, "..");
+/** Precedence rank for packaged/bundled skills (mirrors `BUNDLED_SKILL_RANK`). */
+const BUNDLED_SKILL_RANK = 600;
+const SKILL_NAME = "recursive-mode";
+const PROVIDER_NAME = "recursive-mode";
+const SKILL_BODY_PATH = join(PACKAGE_ROOT, "skills", SKILL_NAME, "SKILL.md");
+const SKILL_RESOURCE_BASE = join(PACKAGE_ROOT, "skills", SKILL_NAME);
+const SKILL_DESCRIPTION = "Drive the recursive-mode workflow: an audit-gated, phase-disciplined loop that carries one requirement from AS-IS through TO-BE plan, implementation, test, and manual QA to locked control-plane state and durable memory. Use whenever the user asks to implement, resume, or advance a recursive run, or when a repo carries a /.recursive/ control plane.";
+/** Invocation policy: both the model catalog and user `/name` surfaces may load it. */
+const INVOCATION = {
+	modelInvocable: true,
+	userInvocable: true
+};
+/** The bundled candidate, stable across every `list()` call. */
+function candidate() {
+	return {
+		name: SKILL_NAME,
+		description: SKILL_DESCRIPTION,
+		invocation: INVOCATION,
+		provider: PROVIDER_NAME,
+		source: "bundled",
+		resourceBase: {
+			kind: "directory",
+			path: SKILL_RESOURCE_BASE
+		},
+		rank: BUNDLED_SKILL_RANK,
+		locator: SKILL_BODY_PATH,
+		path: SKILL_BODY_PATH
+	};
+}
+/** Read the shipped operating-contract body (fail loud if the package lost it). */
+function readBody() {
+	return readFileSync(SKILL_BODY_PATH, "utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+/** The one bundled provider this plugin contributes. */
+function provider() {
+	return {
+		name: PROVIDER_NAME,
+		list: () => Promise.resolve([candidate()]),
+		get: async () => ({
+			name: SKILL_NAME,
+			description: SKILL_DESCRIPTION,
+			invocation: INVOCATION,
+			provider: PROVIDER_NAME,
+			source: "bundled",
+			resourceBase: {
+				kind: "directory",
+				path: SKILL_RESOURCE_BASE
+			},
+			content: readBody(),
+			path: SKILL_BODY_PATH
+		})
+	};
+}
+/**
+* Register the packaged `recursive-mode` skill into the host `skills` registry.
+*
+* Reads `ctx.get('skills')` optionally (the registry is host-plane; a
+* composition without it is valid). On success returns the exact disposer that
+* unregisters the provider; on absence returns undefined (a no-op, never a boot
+* failure).
+*/
+function registerRecursiveSkill(ctx) {
+	const skills = ctx.get("skills");
+	if (skills === void 0 || skills === null) return void 0;
+	return skills.registerProvider(() => provider());
+}
+//#endregion
 //#region src/index.ts
 const name = "@try-works/dsh-recursive-mode";
 /**
@@ -7656,7 +7741,9 @@ function apply(ctx, config) {
 		const repairedRoots = /* @__PURE__ */ new Set();
 		const reminderGate = new ReminderOnceGate();
 		const agentTeams = ctx.get("agentTeams");
+		const skillDisposer = registerRecursiveSkill(ctx);
 		const disposers = [
+			...skillDisposer ? [skillDisposer] : [],
 			ctx.tools.register(createRecursiveStatusTool(recursive)),
 			ctx.tools.register(createRecursiveInitTool(recursive)),
 			ctx.tools.register(createRecursiveLockTool(recursive)),
@@ -7775,4 +7862,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, auditToPass, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, coerceAskToDecision, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, defaultReviewToolFilter, delegate, delegateContinuable, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, drainContinuableChildren, drainContinuableDescendants, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, interruptContinuable, invalidateReceipt, isCoreArtifact, isTaskClaimedBy, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, readRepairFromStructured, readVerdictFromStructured, receiptPath, renderRecursivePolicy, renderTaskHistory, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };
+export { DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, auditToPass, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, coerceAskToDecision, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, defaultReviewToolFilter, delegate, delegateContinuable, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, drainContinuableChildren, drainContinuableDescendants, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, interruptContinuable, invalidateReceipt, isCoreArtifact, isTaskClaimedBy, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, readRepairFromStructured, readVerdictFromStructured, receiptPath, registerRecursiveSkill, renderRecursivePolicy, renderTaskHistory, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };

package/lib/skills.d.ts

@@ -0,0 +1,70 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** One skill contribution, mirrored from the `dsh-skill` registry contract. */
+export interface SkillInvocationPolicyLike {
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+}
+/** Provider-owned base for relative resource resolution. */
+export type SkillResourceBaseLike = {
+    readonly kind: 'directory';
+    readonly path: string;
+} | {
+    readonly kind: 'url';
+    readonly url: string;
+} | {
+    readonly kind: 'opaque';
+    readonly description: string;
+};
+/** Invocation-neutral summary fields shared by candidates and definitions. */
+export interface SkillSummaryLike {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: SkillInvocationPolicyLike;
+    readonly source: string;
+    readonly provider: string;
+    readonly resourceBase?: SkillResourceBaseLike;
+}
+/** Provider catalog entry: a summary plus rank and an opaque locator. */
+export interface SkillCandidateLike extends SkillSummaryLike {
+    readonly rank: number;
+    readonly locator: unknown;
+    readonly path?: string;
+}
+/** Complete loaded skill: a summary plus the markdown instruction body. */
+export interface SkillDefinitionLike extends SkillSummaryLike {
+    readonly content: string;
+    readonly path?: string;
+}
+/** Lookup options passed to provider `list`/`get`. */
+export interface SkillLookupOptionsLike {
+    readonly cwd?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+/** Registration-scoped control borrowed by one provider. */
+export interface SkillProviderControlLike {
+    readonly signal: AbortSignal;
+    readonly invalidate: () => void;
+}
+/** One source of skills, mirrored from the `dsh-skill` SkillProvider contract. */
+export interface SkillProviderLike {
+    readonly name: string;
+    readonly list: (options: SkillLookupOptionsLike) => Promise<readonly SkillCandidateLike[] | {
+        readonly candidates: readonly SkillCandidateLike[];
+        readonly complete: boolean;
+    }>;
+    readonly get: (candidate: SkillCandidateLike, options: SkillLookupOptionsLike) => Promise<SkillDefinitionLike | undefined>;
+}
+/** Minimal host-realm contract for ctx.skills (the seam we call). */
+export interface SkillsRuntimeLike {
+    registerProvider(create: (control: SkillProviderControlLike) => SkillProviderLike): () => void;
+}
+/**
+ * Register the packaged `recursive-mode` skill into the host `skills` registry.
+ *
+ * Reads `ctx.get('skills')` optionally (the registry is host-plane; a
+ * composition without it is valid). On success returns the exact disposer that
+ * unregisters the provider; on absence returns undefined (a no-op, never a boot
+ * failure).
+ */
+export declare function registerRecursiveSkill(ctx: Context): (() => void) | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + recursive_status tool",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -24,7 +24,8 @@
     "src",
     "preset",
     "scripts",
-    "references"
+    "references",
+    "skills"
   ],
   "license": "MIT",
   "dsh": {

package/skills/recursive-mode/SKILL.md

@@ -0,0 +1,66 @@
+# recursive-mode
+
+Drive the recursive-mode workflow: an audit-gated, phase-disciplined loop that
+carries one requirement from an AS-IS understanding through a TO-BE plan,
+implementation, test, and manual QA, to locked control-plane state and durable
+memory. Every phase follows `draft → audit → repair → re-audit → pass → lock`.
+
+## When to use
+
+- The user says "implement the run", "implement run <id>", "start a recursive
+  run", "resume <run-id>", or otherwise asks to advance a run.
+- The repo carries a `/.recursive/` control plane (RECURSIVE.md, STATE.md,
+  DECISIONS.md, memory/, run/).
+
+## Source of truth
+
+The canonical spec is `/.recursive/RECURSIVE.md`; read it before starting or
+resuming. The control plane lives under `/.recursive/`, one run under
+`/.recursive/run/<run-id>/`, and durable memory under `/.recursive/memory/`.
+Treat bridge docs (`AGENTS.md`, `CLAUDE.md`, `.codex/AGENTS.md`, `.agent/PLANS.md`)
+as harness adapters, not a second spec — on conflict, follow `/.recursive/RECURSIVE.md`.
+
+## Phases
+
+A run advances one phase at a time in order; each phase owns a Markdown artifact
+under `/.recursive/run/<run-id>/`:
+
+- Phase 0 — `00-requirements.md` (gather requirements)
+- Phase 0 (Worktree) — `00-worktree.md` (record the diff basis and scope)
+- Phase 1 — `01-as-is.md` (AS-IS analysis)
+- Phase 2 — `02-to-be-plan.md` (TO-BE plan)
+- Phase 3 — `03-implementation-summary.md` (implement, strict/pragmatic TDD)
+- Phase 3.5 — `03.5-code-review.md` (delegated or self review)
+- Phase 4 — `04-test-summary.md` (test evidence)
+- Phase 5 — `05-manual-qa.md` (manual QA)
+- Phase 6 — `06-decisions-update.md` (update `/.recursive/DECISIONS.md`)
+- Phase 7 — `07-state-update.md` (update `/.recursive/STATE.md`)
+- Phase 8 — `08-memory-impact.md` (update `/.recursive/memory/`)
+
+Use `recursive_status` to read the current phase and its state. Use `recursive_init`
+to scaffold a run, `recursive_lock` to lock a passed phase (it refuses premature
+locks), `recursive_lint` to machine-check an artifact before acceptance, and
+`recursive_closeout` to advance the receipt when the phase is done.
+
+## The audit loop
+
+Audited phases must follow `draft → audit → repair → re-audit → pass → lock`.
+Never set `Coverage: PASS` or `Approval: PASS` unless the artifact ends with
+`Audit: PASS`. When subagents are unavailable, perform the same audit as
+self-audit; do not weaken or skip it. Delegate an audit only with the full
+context bundle (phase name + artifact path, upstream artifacts reread for the
+audit, diff basis from `00-worktree.md`, changed files + code references,
+phase-specific audit questions); if the bundle is incomplete, perform the audit
+yourself and record `Audit Execution Mode: self-audit`. A `success: false` or any
+nonzero delegated exit is a failed attempt — preserve diagnostics, repair owned
+issues, rerun, and verify before acceptance.
+
+## Locking and memory
+
+Lock a phase with `recursive_lock` — it is the supported way to write
+`Status: LOCKED`, `LockedAt`, and `LockHash`, and it refuses a lock whose
+prerequisites are unmet. Phase 6 owns `/.recursive/DECISIONS.md`, Phase 7 owns
+`/.recursive/STATE.md`, Phase 8 owns `/.recursive/memory/**`. Read
+`/.recursive/memory/MEMORY.md` before loading other memory docs, and record
+durable, reusable conclusions (not raw transcripts) when a run teaches the repo
+something about capability availability, fit, or quality.

package/src/index.ts

@@ -20,6 +20,7 @@ import { renderRecursivePolicy } from './policy.ts'
 import { fsPolicyIntent } from './fs-intent.ts'
 import { snapshotWorkspace } from './snapshot.ts'
 import { mountRecursiveRoutesOnce, makeRecursiveRoutes, type RecursiveRouteHost } from './live-route.ts'
+import { registerRecursiveSkill } from './skills.ts'
 import { enumerateRuns, stageBWorkflowInit } from './bootstrap.ts'
 import { getNextLegalPhase, getLockStatus } from './lock.ts'
 import { phaseLintRulesMessage, ReminderOnceGate } from './phase-rules.ts'
@@ -74,6 +75,7 @@ export * from './policy.ts'
 export * from './snapshot.ts'
 export * from './live-route.ts'
 export * from './teams-loop.ts'
+export * from './skills.ts'
 
 /**
  * Bundle plugin entry. The Loader activates this row once `tools` is available
@@ -125,7 +127,14 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
     // the seam passes the exact live Agent the tool extracts from exec.agent.
     const agentTeams = ctx.get('agentTeams') as TeamRuntimeLike | undefined
 
+    // Packaged skill (dsh plugin standard): register the `recursive-mode` skill
+    // into the host skills registry via ctx.skills.registerProvider (the
+    // dsh-skill-badge bundled-provider shape). Optional — a composition without
+    // a skills registry is valid and this no-ops (returns undefined).
+    const skillDisposer = registerRecursiveSkill(ctx)
+
     const disposers = [
+      ...(skillDisposer ? [skillDisposer] : []),
       ctx.tools.register(createRecursiveStatusTool(recursive)),
       ctx.tools.register(createRecursiveInitTool(recursive)),
       ctx.tools.register(createRecursiveLockTool(recursive)),

package/src/skills.ts

@@ -0,0 +1,151 @@
+/**
+ * Packaged `recursive-mode` skill (dsh plugin standard).
+ *
+ * Ships the workflow's operating contract as a bundled skill through
+ * `ctx.skills.registerProvider(...)` — the same shape as the shipped
+ * `dsh-skill-badge` provider: a `bundled` candidate at `BUNDLED_SKILL_RANK`
+ * (600), body read from the package's shipped `skills/recursive-mode/SKILL.md`
+ * (never an inlined TS string literal), with a directory resource base so the
+ * skill can resolve its own assets. Skills are optional instructions, not
+ * session events: this emits nothing and never appends a recursive/* event.
+ *
+ * Optionality: `skills` is a host-plane registry; when the composition has
+ * none, this is a no-op (returns undefined) rather than failing boot.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Package root: <package>/src/.. — skills/ sits next to src/. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = join(MODULE_DIR, '..')
+
+/** Precedence rank for packaged/bundled skills (mirrors `BUNDLED_SKILL_RANK`). */
+const BUNDLED_SKILL_RANK = 600
+const SKILL_NAME = 'recursive-mode'
+const PROVIDER_NAME = 'recursive-mode'
+const SKILL_BODY_PATH = join(PACKAGE_ROOT, 'skills', SKILL_NAME, 'SKILL.md')
+const SKILL_RESOURCE_BASE = join(PACKAGE_ROOT, 'skills', SKILL_NAME)
+const SKILL_DESCRIPTION =
+  'Drive the recursive-mode workflow: an audit-gated, phase-disciplined loop that carries one requirement from AS-IS through TO-BE plan, implementation, test, and manual QA to locked control-plane state and durable memory. Use whenever the user asks to implement, resume, or advance a recursive run, or when a repo carries a /.recursive/ control plane.'
+
+/** Invocation policy: both the model catalog and user `/name` surfaces may load it. */
+const INVOCATION = { modelInvocable: true, userInvocable: true } as const
+
+/** One skill contribution, mirrored from the `dsh-skill` registry contract. */
+export interface SkillInvocationPolicyLike {
+  readonly modelInvocable: boolean
+  readonly userInvocable: boolean
+}
+
+/** Provider-owned base for relative resource resolution. */
+export type SkillResourceBaseLike =
+  | { readonly kind: 'directory'; readonly path: string }
+  | { readonly kind: 'url'; readonly url: string }
+  | { readonly kind: 'opaque'; readonly description: string }
+
+/** Invocation-neutral summary fields shared by candidates and definitions. */
+export interface SkillSummaryLike {
+  readonly name: string
+  readonly description: string
+  readonly whenToUse?: string
+  readonly invocation: SkillInvocationPolicyLike
+  readonly source: string
+  readonly provider: string
+  readonly resourceBase?: SkillResourceBaseLike
+}
+
+/** Provider catalog entry: a summary plus rank and an opaque locator. */
+export interface SkillCandidateLike extends SkillSummaryLike {
+  readonly rank: number
+  readonly locator: unknown
+  readonly path?: string
+}
+
+/** Complete loaded skill: a summary plus the markdown instruction body. */
+export interface SkillDefinitionLike extends SkillSummaryLike {
+  readonly content: string
+  readonly path?: string
+}
+
+/** Lookup options passed to provider `list`/`get`. */
+export interface SkillLookupOptionsLike {
+  readonly cwd?: string | undefined
+  readonly signal?: AbortSignal | undefined
+}
+
+/** Registration-scoped control borrowed by one provider. */
+export interface SkillProviderControlLike {
+  readonly signal: AbortSignal
+  readonly invalidate: () => void
+}
+
+/** One source of skills, mirrored from the `dsh-skill` SkillProvider contract. */
+export interface SkillProviderLike {
+  readonly name: string
+  readonly list: (options: SkillLookupOptionsLike) => Promise<readonly SkillCandidateLike[] | { readonly candidates: readonly SkillCandidateLike[]; readonly complete: boolean }>
+  readonly get: (candidate: SkillCandidateLike, options: SkillLookupOptionsLike) => Promise<SkillDefinitionLike | undefined>
+}
+
+/** Minimal host-realm contract for ctx.skills (the seam we call). */
+export interface SkillsRuntimeLike {
+  registerProvider(create: (control: SkillProviderControlLike) => SkillProviderLike): () => void
+}
+
+/** The bundled candidate, stable across every `list()` call. */
+function candidate(): SkillCandidateLike {
+  return {
+    name: SKILL_NAME,
+    description: SKILL_DESCRIPTION,
+    invocation: INVOCATION,
+    provider: PROVIDER_NAME,
+    source: 'bundled',
+    resourceBase: { kind: 'directory', path: SKILL_RESOURCE_BASE },
+    rank: BUNDLED_SKILL_RANK,
+    locator: SKILL_BODY_PATH,
+    path: SKILL_BODY_PATH,
+  }
+}
+
+/** Read the shipped operating-contract body (fail loud if the package lost it). */
+function readBody(): string {
+  return readFileSync(SKILL_BODY_PATH, 'utf8').replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+}
+
+/** The one bundled provider this plugin contributes. */
+function provider(): SkillProviderLike {
+  return {
+    name: PROVIDER_NAME,
+    list: () => Promise.resolve([candidate()]),
+    get: async () => ({
+      name: SKILL_NAME,
+      description: SKILL_DESCRIPTION,
+      invocation: INVOCATION,
+      provider: PROVIDER_NAME,
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: SKILL_RESOURCE_BASE },
+      content: readBody(),
+      path: SKILL_BODY_PATH,
+    }),
+  }
+}
+
+/**
+ * Register the packaged `recursive-mode` skill into the host `skills` registry.
+ *
+ * Reads `ctx.get('skills')` optionally (the registry is host-plane; a
+ * composition without it is valid). On success returns the exact disposer that
+ * unregisters the provider; on absence returns undefined (a no-op, never a boot
+ * failure).
+ */
+export function registerRecursiveSkill(ctx: Context): (() => void) | undefined {
+  const skills = ctx.get('skills')
+  if (skills === undefined || skills === null) return undefined
+  // SAFETY: the single boundary cast asserts the live ctx.skills satisfies the
+  // structural SkillsRuntimeLike seam (registerProvider). The live registry's
+  // method is a superset of this seam; the provider we return is a plain owned
+  // object read through its own leaf fields, never serialized.
+  const registry = skills as SkillsRuntimeLike
+  return registry.registerProvider(() => provider())
+}