@link-assistant/hive-mind 1.75.0 → 1.76.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @link-assistant/hive-mind
 
+## 1.76.0
+
+### Minor Changes
+
+- 80c56fa: Add experimental `--use-handoff` HANDOFF.md continuity **Agent Skill** (issue
+  #1877). When enabled, Hive Mind deploys a real `SKILL.md` (the Agent Skills open
+  standard created by Anthropic) into the session working directory for both tools
+  natively — `.claude/skills/handoff/SKILL.md` for `--tool claude` and
+  `.agents/skills/handoff/SKILL.md` for `--tool codex` — so the very same skill
+  teaches each tool to read `HANDOFF.md` (repository root) first when present and
+  keep it updated with task, current state, decisions, next steps, gotchas, and
+  critical files. A minimal activation nudge in the system prompt ensures the
+  read-at-session-start behavior fires reliably. Because each Hive Mind working
+  session runs in an ephemeral working directory cloned from the PR branch, the
+  handoff file is committed to the branch — making it the shared cross-session,
+  cross-tool memory so Claude and Codex can continue each other's work in a single
+  pull request. The deployed `SKILL.md` is tooling (re-deployed every session) and
+  is kept out of the target repository via `.git/info/exclude`, so it never appears
+  in the PR. Disabled by default; auto-forwarded by `hive`. Includes a case study
+  in `docs/case-studies/issue-1877/` and tests in `tests/handoff-prompt.test.mjs`.
+
 ## 1.75.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.75.0",
+  "version": "1.76.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/claude.lib.mjs

@@ -28,6 +28,7 @@ import { fetchModelInfo } from './model-info.lib.mjs';
 import { classifyRetryableError, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
 import { resolveSubSessionSize } from './sub-session-size.lib.mjs'; // Issue #1706
 import { withAgentsMdAsClaudeMd } from './agents-md-claude-support.lib.mjs';
+import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
 import { createThinkingBlockRecovery } from './claude.thinking-block-recovery.lib.mjs'; // Issue #1834 (PR #1835 feedback)
 export { availableModels, fetchModelInfo }; // Re-export for backward compatibility
 const showResumeCommand = async (sessionId, tempDir, claudePath, model, log, argv = null) => {
@@ -353,6 +354,10 @@ export const executeClaude = async params => {
   const escapedPrompt = prompt.replace(/"/g, '\\"').replace(/\$/g, '\\$');
   const escapedSystemPrompt = systemPrompt.replace(/"/g, '\\"').replace(/\$/g, '\\$');
 
+  // Issue #1877: deploy the experimental HANDOFF.md Agent Skill so Claude loads
+  // it natively from .claude/skills/handoff/SKILL.md (no-op unless --use-handoff).
+  await deployHandoffSkill({ tempDir, argv, log, $ });
+
   return await withAgentsMdAsClaudeMd({ tempDir, branchName, argv, prompt, fs, path, $, log, formatAligned }, () =>
     executeClaudeCommand({
       tempDir,

package/src/claude.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getHandoffSubPrompt } from './handoff.prompts.lib.mjs';
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { primaryModelNames } from './models/index.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
@@ -338,7 +339,7 @@ Visual UI work and screenshots.
    - When the fix is visual, include side-by-side or sequential comparison of before/after states in the PR description.
    - When possible, create automated visual regression tests to prevent the UI bug from recurring.`
        : ''
-   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${buildWorkLanguageDirective()}`;
+   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${getHandoffSubPrompt(argv)}${buildWorkLanguageDirective()}`;
 };
 
 // Export all functions as default object too

package/src/codex.lib.mjs

@@ -29,6 +29,7 @@ import { defaultModels } from './models/index.mjs';
 import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
 import { parseSubSessionSize, buildCodexSubSessionSizeConfigArgs, buildCodexDisable1mContextConfigArgs } from './sub-session-size.lib.mjs'; // Issue #1706
 import { getCumulativeContextInputTokens } from './context-fill.lib.mjs';
+import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
 import Decimal from 'decimal.js-light';
 
 const CODEX_USAGE_FIELD_NAMES = ['input_tokens', 'cached_input_tokens', 'output_tokens', 'cache_write_tokens', 'cache_creation_input_tokens', 'reasoning_tokens', 'input_tokens_details.cached_tokens', 'input_tokens_details.cache_read_tokens', 'input_tokens_details.cache_write_tokens', 'input_tokens_details.cache_creation_tokens', 'input_tokens_details.cache_creation_input_tokens', 'output_tokens_details.reasoning_tokens'];
@@ -661,6 +662,10 @@ export const executeCodex = async params => {
     }
   }
 
+  // Issue #1877: deploy the experimental HANDOFF.md Agent Skill so Codex loads
+  // it natively from .agents/skills/handoff/SKILL.md (no-op unless --use-handoff).
+  await deployHandoffSkill({ tempDir, argv, log, $ });
+
   // Execute the Codex command
   return await executeCodexCommand({
     tempDir,

package/src/codex.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getHandoffSubPrompt } from './handoff.prompts.lib.mjs';
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
@@ -306,7 +307,7 @@ Visual UI work and screenshots.
    - When the fix is visual, include side-by-side or sequential comparison of before/after states in the PR description.
    - When possible, create automated visual regression tests to prevent the UI bug from recurring.`
        : ''
-   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${buildWorkLanguageDirective()}`;
+   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${getHandoffSubPrompt(argv)}${buildWorkLanguageDirective()}`;
 };
 
 // Export all functions as default object too

package/src/handoff-skill.lib.mjs

@@ -0,0 +1,256 @@
+/**
+ * HANDOFF.md Agent Skill deployment (issue #1877)
+ *
+ * Writes the canonical handoff `SKILL.md` (built by handoff.prompts.lib.mjs)
+ * into the session working directory so the AI tool loads it natively as an
+ * Agent Skill, instead of relying on an injected prompt.
+ *
+ * Both supported tools read the Agent Skills standard, but from different
+ * hardcoded project directories (neither tool exposes a setting or env var to
+ * point at a custom/shared folder):
+ *   - Claude Code:  .claude/skills/<name>/SKILL.md
+ *   - Codex:        .agents/skills/<name>/SKILL.md
+ *
+ * To answer "can both CLIs use the SAME folder?": there is no native shared
+ * location, so we make one ourselves. The SKILL.md is written exactly ONCE into
+ * a single real directory (the Claude path, `.claude/skills/handoff/`), and the
+ * Codex path (`.agents/skills/handoff`) is a relative **symlink** pointing at
+ * that one real directory. Both tools therefore read byte-for-byte the same
+ * file from a single source of truth on disk — not two copies that could drift.
+ * If the filesystem cannot create a symlink (e.g. Windows without privilege),
+ * we fall back to writing a real second copy so the feature still works.
+ *
+ * The deployed skill is tool configuration, not project state, so it is:
+ *   - re-deployed every session by hive-mind (each session clones fresh), and
+ *   - excluded from git via `.git/info/exclude` (a local, never-committed
+ *     ignore) so it never pollutes the pull request or the "uncommitted
+ *     changes" checks. Only the HANDOFF.md the tool produces is committed.
+ */
+
+// Fetch use-m if not available (matches the rest of src/*.lib.mjs).
+if (typeof globalThis.use === 'undefined') {
+  globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
+}
+const fs = (await use('fs')).promises;
+const path = (await use('path')).default;
+
+import { buildHandoffSkillFile, HANDOFF_SKILL_NAME } from './handoff.prompts.lib.mjs';
+
+const noopLog = async () => {};
+
+const SKILL_FILE = 'SKILL.md';
+
+/**
+ * The single real skill directory the SKILL.md is written into. Claude Code
+ * reads it directly; Codex reaches the same files through a symlink (below).
+ * @type {string}
+ */
+export const HANDOFF_PRIMARY_SKILL_DIR = path.join('.claude', 'skills', HANDOFF_SKILL_NAME);
+
+/**
+ * Additional skill directories that should resolve to the same SKILL.md. Each
+ * is created as a symlink to HANDOFF_PRIMARY_SKILL_DIR (one source of truth),
+ * falling back to a real copy only if symlinking is unsupported.
+ * @type {string[]}
+ */
+export const HANDOFF_LINKED_SKILL_DIRS = Object.freeze([
+  path.join('.agents', 'skills', HANDOFF_SKILL_NAME), // Codex
+]);
+
+/**
+ * All skill directories the deployment touches (primary + links). Kept for the
+ * git-exclude bookkeeping and for callers/tests that enumerate every location.
+ * @type {string[]}
+ */
+export const HANDOFF_SKILL_DIRS = Object.freeze([HANDOFF_PRIMARY_SKILL_DIR, ...HANDOFF_LINKED_SKILL_DIRS]);
+
+/**
+ * Determine whether a path is already tracked by git in the working dir. We
+ * never clobber a file/dir the target repository tracks itself.
+ */
+const isTracked = async ({ $, tempDir, relPath }) => {
+  if (!$) return false;
+  try {
+    const result = await $({ cwd: tempDir })`git ls-files --error-unmatch ${relPath} 2>/dev/null`;
+    return result.code === 0;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Resolve the local git exclude file (`.git/info/exclude`), honoring worktrees
+ * via `git rev-parse --git-path`. Falls back to the conventional location.
+ */
+const resolveExcludePath = async ({ $, tempDir }) => {
+  if ($) {
+    try {
+      const result = await $({ cwd: tempDir })`git rev-parse --git-path info/exclude 2>/dev/null`;
+      const rel = (result.stdout || '').toString().trim();
+      if (result.code === 0 && rel) {
+        return path.isAbsolute(rel) ? rel : path.join(tempDir, rel);
+      }
+    } catch {
+      // fall through to default
+    }
+  }
+  return path.join(tempDir, '.git', 'info', 'exclude');
+};
+
+/**
+ * Append the skill directories to `.git/info/exclude` (idempotent) so the
+ * deployed SKILL.md files (real dir and symlink alike) stay invisible to git.
+ * Entries are written WITHOUT a trailing slash so they match both a real
+ * directory and a directory symlink (git would not match a symlink against a
+ * `dir/` pattern).
+ */
+const updateGitExclude = async ({ $, tempDir, log }) => {
+  const excludePath = await resolveExcludePath({ $, tempDir });
+  // Only touch the exclude file if its parent (.git/info) exists — i.e. this is
+  // a real git working dir. Avoid creating a stray `.git/` in non-git dirs.
+  try {
+    await fs.access(path.dirname(excludePath));
+  } catch {
+    await log('   Handoff skill: no .git/info directory; skipping git-exclude update', { verbose: true });
+    return false;
+  }
+
+  let existing = '';
+  try {
+    existing = await fs.readFile(excludePath, 'utf8');
+  } catch {
+    existing = '';
+  }
+
+  const entries = HANDOFF_SKILL_DIRS.map(dir => `/${dir.split(path.sep).join('/')}`);
+  const existingLines = existing.split(/\r?\n/);
+  const missing = entries.filter(entry => !existingLines.includes(entry));
+  if (missing.length === 0) return true;
+
+  const header = '# hive-mind --use-handoff: experimental HANDOFF.md Agent Skill (issue #1877)';
+  const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  const block = `${prefix}${existing.includes(header) ? '' : header + '\n'}${missing.join('\n')}\n`;
+  await fs.writeFile(excludePath, existing + block, 'utf8');
+  return true;
+};
+
+/**
+ * Write the real SKILL.md into the primary skill directory.
+ */
+const writeRealSkill = async ({ tempDir, content }) => {
+  const absDir = path.join(tempDir, HANDOFF_PRIMARY_SKILL_DIR);
+  await fs.mkdir(absDir, { recursive: true });
+  await fs.writeFile(path.join(absDir, SKILL_FILE), content, 'utf8');
+  return absDir;
+};
+
+/**
+ * Make `relLinkDir` resolve to the same files as the primary skill directory.
+ * Prefers a relative symlink (single source of truth); if symlinking is not
+ * supported, falls back to writing a real copy of the SKILL.md.
+ *
+ * @returns {Promise<'symlink'|'copy'>}
+ */
+const linkOrCopySkill = async ({ tempDir, relLinkDir, primaryAbsDir, content }) => {
+  const absLinkDir = path.join(tempDir, relLinkDir);
+  const parent = path.dirname(absLinkDir);
+  await fs.mkdir(parent, { recursive: true });
+  const relTarget = path.relative(parent, primaryAbsDir);
+
+  // Reconcile any pre-existing entry (e.g. from a prior session re-deploy).
+  try {
+    const st = await fs.lstat(absLinkDir);
+    if (st.isSymbolicLink()) {
+      const current = await fs.readlink(absLinkDir);
+      if (current === relTarget) return 'symlink'; // already correct
+      await fs.rm(absLinkDir, { recursive: true, force: true });
+    } else if (st.isDirectory()) {
+      // A real directory is already there (prior copy fallback). Refresh the
+      // copy in place rather than replacing the directory.
+      await fs.writeFile(path.join(absLinkDir, SKILL_FILE), content, 'utf8');
+      return 'copy';
+    } else {
+      await fs.rm(absLinkDir, { force: true });
+    }
+  } catch {
+    // Nothing there yet — fall through and create it.
+  }
+
+  try {
+    await fs.symlink(relTarget, absLinkDir, 'dir');
+    return 'symlink';
+  } catch {
+    await fs.mkdir(absLinkDir, { recursive: true });
+    await fs.writeFile(path.join(absLinkDir, SKILL_FILE), content, 'utf8');
+    return 'copy';
+  }
+};
+
+/**
+ * Deploy the handoff SKILL.md into the session working directory.
+ *
+ * @param {Object} params
+ * @param {string} params.tempDir - The repo working directory.
+ * @param {Object} params.argv - Parsed CLI args (uses argv.useHandoff).
+ * @param {Function} [params.log] - Logger.
+ * @param {Function} [params.$] - Command runner (for git checks); optional.
+ * @returns {Promise<{deployed: boolean, reason?: string, paths: string[], shared: boolean}>}
+ */
+export const deployHandoffSkill = async ({ tempDir, argv, log = noopLog, $ = null } = {}) => {
+  if (!argv || !argv.useHandoff) {
+    return { deployed: false, reason: 'disabled', paths: [], shared: false };
+  }
+  if (!tempDir) {
+    return { deployed: false, reason: 'no-temp-dir', paths: [], shared: false };
+  }
+
+  const content = buildHandoffSkillFile();
+  const written = [];
+  let allShared = true;
+
+  // 1. Write the single real SKILL.md (unless the repo tracks it itself).
+  const primaryRelFile = path.join(HANDOFF_PRIMARY_SKILL_DIR, SKILL_FILE);
+  let primaryAbsDir = path.join(tempDir, HANDOFF_PRIMARY_SKILL_DIR);
+  if (await isTracked({ $, tempDir, relPath: primaryRelFile })) {
+    await log(`   Handoff skill: ${primaryRelFile} is tracked by the repo; leaving it untouched`, { verbose: true });
+  } else {
+    try {
+      primaryAbsDir = await writeRealSkill({ tempDir, content });
+      written.push(primaryRelFile);
+    } catch (error) {
+      await log(`   Handoff skill: failed to deploy ${primaryRelFile}: ${error.message}`, { verbose: true });
+      return { deployed: false, reason: 'write-failed', paths: [], shared: false };
+    }
+  }
+
+  // 2. Point every other tool's skill dir at that same real directory.
+  for (const relLinkDir of HANDOFF_LINKED_SKILL_DIRS) {
+    const relFile = path.join(relLinkDir, SKILL_FILE);
+    if (await isTracked({ $, tempDir, relPath: relFile })) {
+      await log(`   Handoff skill: ${relFile} is tracked by the repo; leaving it untouched`, { verbose: true });
+      continue;
+    }
+    try {
+      const mode = await linkOrCopySkill({ tempDir, relLinkDir, primaryAbsDir, content });
+      if (mode !== 'symlink') allShared = false;
+      written.push(relFile);
+    } catch (error) {
+      await log(`   Handoff skill: failed to link ${relFile}: ${error.message}`, { verbose: true });
+    }
+  }
+
+  if (written.length > 0) {
+    await updateGitExclude({ $, tempDir, log });
+    const how = allShared ? 'one shared folder via symlink' : 'copied (symlink unsupported)';
+    await log(`   Handoff skill deployed (--use-handoff, ${how}): ${written.join(', ')}`, { verbose: true });
+  }
+
+  return { deployed: written.length > 0, paths: written, shared: allShared };
+};
+
+export default {
+  HANDOFF_PRIMARY_SKILL_DIR,
+  HANDOFF_LINKED_SKILL_DIRS,
+  HANDOFF_SKILL_DIRS,
+  deployHandoffSkill,
+};

package/src/handoff.prompts.lib.mjs

@@ -0,0 +1,158 @@
+/**
+ * HANDOFF.md support — Agent Skill (issue #1877)
+ *
+ * Instead of injecting a bespoke sub-prompt, this module ships a real
+ * **Agent Skill** (https://agentskills.io) — a `SKILL.md` document with YAML
+ * frontmatter — that teaches the AI tool to read and maintain a HANDOFF.md file
+ * in the repository root. The Agent Skills format is an open standard (created
+ * by Anthropic) that BOTH supported tools load natively:
+ *   - Claude Code discovers project skills from `.claude/skills/<name>/SKILL.md`.
+ *   - Codex discovers project skills from `.agents/skills/<name>/SKILL.md`.
+ * The exact same `SKILL.md` works for both, so "same skill, same way" is
+ * satisfied by a single canonical file rather than a tool-specific prompt.
+ * Because neither tool lets you redirect its skills folder, the deployment
+ * writes that file ONCE and symlinks the second tool's path to it, so both
+ * tools literally read the same folder (see handoff-skill.lib.mjs).
+ *
+ * The skill is deployed into the session working directory by
+ * `handoff-skill.lib.mjs` (gated behind the experimental --use-handoff flag).
+ * This module only builds the canonical text; the deployment module writes it.
+ *
+ * Goal: cross-session AND cross-tool continuity — a session driven by one tool
+ * (e.g. Claude) can be continued by another tool (e.g. Codex) inside the same
+ * pull request, because the HANDOFF.md state travels with the branch.
+ *
+ * Design rationale specific to hive-mind:
+ *   - Each working session runs in an ephemeral temp working directory that is
+ *     cloned fresh from the pull request branch. The ONLY state that persists
+ *     between sessions (and between different tools) is what is committed to the
+ *     branch. Therefore, unlike the general "disposable temp-dir handoff"
+ *     convention, the handoff file here MUST be committed to the PR branch so
+ *     the next session/tool can read it. We keep a single active HANDOFF.md per
+ *     branch to avoid ambiguity.
+ *   - The skill file itself (SKILL.md) is tool configuration, not project state,
+ *     so it is re-deployed each session by hive-mind and is NOT committed to the
+ *     target repository (see handoff-skill.lib.mjs).
+ */
+
+/**
+ * The default handoff file name (repository root, relative path).
+ * @type {string}
+ */
+export const HANDOFF_FILE_NAME = 'HANDOFF.md';
+
+/**
+ * The skill directory / invocation name (Agent Skills standard).
+ * @type {string}
+ */
+export const HANDOFF_SKILL_NAME = 'handoff';
+
+/**
+ * The skill description used in the SKILL.md frontmatter. Front-loads the key
+ * use case and trigger words so the tool can match the skill implicitly.
+ * @type {string}
+ */
+export const HANDOFF_SKILL_DESCRIPTION = "Maintain a HANDOFF.md continuity document in the repository root so any session can continue a previous session's work — even across different AI tools (Claude and Codex) in the same pull request. Use when starting, resuming, or finishing work on a long-running task, issue, or pull request.";
+
+/**
+ * Build the canonical handoff skill instructions (the markdown body that follows
+ * the YAML frontmatter in SKILL.md). This is tool-agnostic and identical for
+ * Claude and Codex.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.fileName=HANDOFF_FILE_NAME] - Handoff file name.
+ * @returns {string} The markdown instructions body.
+ */
+export const buildHandoffSkillBody = ({ fileName = HANDOFF_FILE_NAME } = {}) => {
+  return `# HANDOFF.md continuity skill
+
+${fileName} is a single shared handoff document in the repository root that lets any session continue the work of any previous session, even when a different AI tool (for example Claude and Codex) is used. It travels with the pull request branch, so it is the cross-tool, cross-session memory for this PR.
+
+## When to use this skill
+
+- When you start a working session, read ${fileName} first if it exists. Treat its "Next steps" section as your immediate starting point and honor the decisions and constraints it records before exploring anything else.
+- When ${fileName} does not exist yet and the task is non-trivial, create it early so an interrupted session can always be resumed.
+- When you make meaningful progress, update ${fileName} so it always reflects the current truth. Keep exactly one active ${fileName} per pull request branch (do not create per-session copies).
+- When all requirements are fully met and the work is complete, record that completion at the top of ${fileName} (or delete the file) so the next session knows there is nothing left to continue.
+
+## How to write ${fileName}
+
+- Keep it concise and tool-agnostic: describe state by referencing file paths, function names, branch, and commit SHAs rather than tool-specific commands, so the next tool (Claude or Codex) can act on it directly. Prefer pointers to existing artifacts over duplicating their content.
+- Include these sections:
+  1. **Task** — the issue/PR being solved and the goal.
+  2. **Current state** — what is done and verified.
+  3. **Decisions** — key choices made and why (so they are not re-litigated).
+  4. **Next steps** — the concrete, ordered actions the next session should take.
+  5. **Gotchas** — known pitfalls, failing checks, or constraints.
+  6. **Critical files** — the important paths and what each is for.
+- When you record next steps, make them specific and actionable (a path, a function, a command to run) instead of vague goals, and remove items as they are completed.
+
+## Committing and safety
+
+- When you finish a step that changes the state, commit ${fileName} together with the related code changes so the handoff stays in sync with the branch and is never lost if the session is interrupted.
+- Never include secrets, tokens, API keys, passwords, or personal data in ${fileName} — it is committed to the repository.`;
+};
+
+/**
+ * Build a complete SKILL.md document (Agent Skills standard): YAML frontmatter
+ * with `name` and `description`, followed by the instructions body. This exact
+ * file is deployed verbatim for both Claude (.claude/skills/handoff/SKILL.md)
+ * and Codex (.agents/skills/handoff/SKILL.md).
+ *
+ * @param {Object} [options]
+ * @param {string} [options.fileName=HANDOFF_FILE_NAME] - Handoff file name.
+ * @param {string} [options.name=HANDOFF_SKILL_NAME] - Skill name (frontmatter).
+ * @param {string} [options.description=HANDOFF_SKILL_DESCRIPTION] - Skill description.
+ * @returns {string} The full SKILL.md content.
+ */
+export const buildHandoffSkillFile = ({ fileName = HANDOFF_FILE_NAME, name = HANDOFF_SKILL_NAME, description = HANDOFF_SKILL_DESCRIPTION } = {}) => {
+  return `---
+name: ${name}
+description: ${description}
+---
+
+${buildHandoffSkillBody({ fileName })}
+`;
+};
+
+/**
+ * Build a minimal activation nudge for the system prompt. The full procedure
+ * lives in the deployed SKILL.md (loaded natively by the tool); this short
+ * pointer only ensures the read-at-session-start behavior reliably fires, since
+ * that is triggered by session lifecycle rather than by a task description.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.fileName=HANDOFF_FILE_NAME] - Handoff file name.
+ * @param {string} [options.name=HANDOFF_SKILL_NAME] - Skill name.
+ * @returns {string} The activation nudge.
+ */
+export const buildHandoffSubPrompt = ({ fileName = HANDOFF_FILE_NAME, name = HANDOFF_SKILL_NAME } = {}) => {
+  return `
+HANDOFF.md continuity skill (experimental, --use-handoff).
+   - A reusable "${name}" Agent Skill is installed in this workspace (.claude/skills/${name}/ for Claude, .agents/skills/${name}/ for Codex). It defines how to read and maintain ${fileName} so any session can continue the work of a previous one — even across tools (Claude and Codex) in the same pull request.
+   - At the start of this session, use the ${name} skill: if ${fileName} exists in the repository root, read it first and continue from its "Next steps". Create or update ${fileName} as you make progress and commit it to the pull request branch.`;
+};
+
+/**
+ * Get the handoff skill activation nudge if enabled.
+ *
+ * @param {Object} argv - Parsed command line arguments.
+ * @returns {string} The sub-prompt content, or an empty string when disabled.
+ */
+export const getHandoffSubPrompt = argv => {
+  if (argv && argv.useHandoff) {
+    return buildHandoffSubPrompt();
+  }
+  return '';
+};
+
+// Export all functions as default object too (mirrors architecture-care module)
+export default {
+  HANDOFF_FILE_NAME,
+  HANDOFF_SKILL_NAME,
+  HANDOFF_SKILL_DESCRIPTION,
+  buildHandoffSkillBody,
+  buildHandoffSkillFile,
+  buildHandoffSubPrompt,
+  getHandoffSubPrompt,
+};

package/src/option-suggestions.lib.mjs

@@ -189,6 +189,7 @@ const KNOWN_OPTION_NAMES = [
   'prompt-issue-reporting',
   'prompt-architecture-care',
   'prompt-case-studies',
+  'use-handoff',
   'prompt-playwright-mcp',
   'prompt-check-sibling-pull-requests',
   'enable-workspaces',

package/src/solve.config.lib.mjs

@@ -480,6 +480,11 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Supported for --tool claude and --tool codex.',
     default: false,
   },
+  'use-handoff': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] Enable the HANDOFF.md continuity Agent Skill so a session can continue the work of a previous session — even when a different AI tool is used (e.g. Claude and Codex continuing each other in the same pull request). A real SKILL.md (the open Agent Skills standard) is deployed into the working directory so each tool loads it natively (.claude/skills/handoff/ for Claude, .agents/skills/handoff/ for Codex). The AI reads HANDOFF.md (repository root) first when present and keeps it updated with task, current state, decisions, next steps, gotchas, and critical files. HANDOFF.md is committed to the PR branch so it persists across the ephemeral per-session working directories; the SKILL.md itself is re-deployed each session and git-excluded so it never pollutes the PR. The same skill file is used identically for --tool claude and --tool codex. Disabled by default (issue #1877).',
+    default: false,
+  },
   'prompt-playwright-mcp': {
     type: 'boolean',
     description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Supported for --tool claude, --tool codex, --tool opencode, --tool agent, --tool qwen, and --tool gemini.',