get-tbd 0.1.29 → 0.1.30

package/dist/tbd

@@ -14067,7 +14067,7 @@ function serializeIssue(issue) {
 * Package version, derived from git at build time.
 * Format: X.Y.Z for releases, X.Y.Z-dev.N.hash for dev builds.
 */
-const VERSION$1 = "0.1.29";
+const VERSION$1 = "0.1.30";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -97685,6 +97685,10 @@ const CHARS_PER_TOKEN = 3.5;
 * WHEN TO BUMP THE FORMAT VERSION:
 * - Bump when changes REQUIRE migration (deleting files, changing formats, moving files)
 * - **Bump when changing config schema** (adding, removing, or modifying fields)
+* - **Bump when the shape of a generated agent-integration surface changes** (e.g. the
+*   managed AGENTS.md block). This same format is stamped there via
+*   AGENT_INTEGRATION_FORMAT (integration-paths.ts), so there is ONE format code across
+*   all tbd-managed surfaces.
 * - Do NOT bump for additive changes that don't affect config.yml (new directories, etc.)
 *
 * HOW TO ADD A NEW FORMAT VERSION:
@@ -104232,9 +104236,10 @@ function renderFooter(suggestions, colors) {
 /**
 * Centralized path constants and utilities for coding agent integrations.
 *
-* IMPORTANT: All tbd integration files (hooks, settings, skills) are installed
-* to PROJECT-LOCAL directories (.claude/, AGENTS.md) ONLY. We do NOT install to
-* global/user directories (~/.claude/).
+* IMPORTANT: All tbd integration files (skills, hooks, settings, scripts) are
+* installed to PROJECT-LOCAL directories (.agents/, .claude/, .codex/,
+* scripts/agent/, AGENTS.md) ONLY. We do NOT install to global/user directories
+* (~/.claude/, ~/.codex/, ~/.agents/).
 *
 * This file defines all path constants in one place to:
 * 1. Ensure consistency across the codebase
@@ -104242,6 +104247,19 @@ function renderFooter(suggestions, colors) {
 * 3. Simplify future changes to path conventions
 */
 /**
+* Format version stamped into generated agent integration artifacts (e.g. the
+* AGENTS.md managed block's begin marker: `... format=f03 surface=...`).
+*
+* UNIFIED with the `.tbd/` directory format (`tbd_format`): there is one format
+* code for all tbd-managed surfaces, sourced from `tbd-format.ts` (the single
+* source of truth). Bump `CURRENT_FORMAT` there when any managed surface — config
+* schema OR a generated agent surface — changes shape. A marked AGENTS.md block
+* with no `format=` field predates this and is treated as `f01`; a running tbd
+* that finds a HIGHER format than it knows refuses to overwrite it and tells the
+* user to upgrade tbd.
+*/
+const AGENT_INTEGRATION_FORMAT = CURRENT_FORMAT;
+/**
 * Relative path to Claude Code settings file from project root.
 * This is where hooks are configured.
 */
@@ -104275,11 +104293,33 @@ const TBD_CLOSING_REMINDER_REL = ".claude/hooks/tbd-closing-reminder.sh";
 */
 const GH_CLI_SCRIPT_REL = ".claude/scripts/ensure-gh-cli.sh";
 /**
+* Canonical portable project Agent Skill, scanned by Codex, Gemini CLI, Cursor,
+* GitHub Copilot, Amp, OpenCode, pi, and other Agent Skills clients.
+*/
+const AGENTS_SKILL_REL = ".agents/skills/tbd/SKILL.md";
+/**
+* Repository distribution copy of the skill, for skills.sh-style installers
+* (`npx skills add`) and direct GitHub browsing.
+*/
+const SKILLS_DIST_REL = "skills/tbd/SKILL.md";
+/**
 * Relative path to AGENTS.md file from project root.
 * Used by Codex, Factory.ai, Cursor (v1.6+), and other compatible tools.
 */
 const AGENTS_MD_REL = "AGENTS.md";
 /**
+* Codex project-local config/hook directory.
+*/
+const CODEX_DIR_REL = ".codex";
+/**
+* Codex project-local hooks file (Claude-compatible event schema).
+*/
+const CODEX_HOOKS_REL = ".codex/hooks.json";
+/**
+* Codex project-local config; may also carry an inline `[hooks]` table.
+*/
+const CODEX_CONFIG_REL = ".codex/config.toml";
+/**
 * Global Claude Code directory in user's home.
 * Used ONLY for detecting if Claude Code is installed (for agent detection).
 * All installations are project-local.
@@ -104313,6 +104353,31 @@ function getAgentsMdPath(projectRoot) {
 	return join(projectRoot, AGENTS_MD_REL);
 }
 /**
+* Get the three SKILL.md targets: the portable Agent Skills install, the Claude
+* Code mirror, and the committed distribution copy.
+*
+* @param projectRoot - The project root directory (containing .tbd/)
+*/
+function getAgentSkillPaths(projectRoot) {
+	return {
+		portable: join(projectRoot, AGENTS_SKILL_REL),
+		claudeMirror: join(projectRoot, CLAUDE_SKILL_REL),
+		distribution: join(projectRoot, SKILLS_DIST_REL)
+	};
+}
+/**
+* Get project-local Codex config/hook paths.
+*
+* @param projectRoot - The project root directory
+*/
+function getCodexPaths(projectRoot) {
+	return {
+		dir: join(projectRoot, CODEX_DIR_REL),
+		hooks: join(projectRoot, CODEX_HOOKS_REL),
+		config: join(projectRoot, CODEX_CONFIG_REL)
+	};
+}
+/**
 * Display path for Claude Code settings in status/doctor output.
 */
 const CLAUDE_SETTINGS_DISPLAY = "./.claude/settings.json";
@@ -104320,6 +104385,14 @@ const CLAUDE_SETTINGS_DISPLAY = "./.claude/settings.json";
 * Display path for AGENTS.md in status/doctor output.
 */
 const AGENTS_MD_DISPLAY = "./AGENTS.md";
+/**
+* Display path for the portable Agent Skill in status/doctor output.
+*/
+const AGENTS_SKILL_DISPLAY = "./.agents/skills/tbd/SKILL.md";
+/**
+* Display path for the Codex hooks file in status/doctor output.
+*/
+const CODEX_HOOKS_DISPLAY = "./.codex/hooks.json";
 
 //#endregion
 //#region src/cli/commands/status.ts
@@ -104357,10 +104430,14 @@ var StatusHandler = class extends BaseCommand {
 			worktree_healthy: null,
 			workspaces: [],
 			integrations: {
+				portable_skill: false,
+				portable_skill_path: AGENTS_SKILL_DISPLAY,
 				claude_code: false,
 				claude_code_path: CLAUDE_SETTINGS_DISPLAY,
 				codex: false,
-				codex_path: AGENTS_MD_DISPLAY
+				codex_path: AGENTS_MD_DISPLAY,
+				codex_hooks: false,
+				codex_hooks_path: CODEX_HOOKS_DISPLAY
 			}
 		};
 		const gitInfo = await this.checkGitRepo();
@@ -104428,11 +104505,23 @@ var StatusHandler = class extends BaseCommand {
 		const claudePaths = getClaudePaths(projectRoot);
 		const agentsPath = getAgentsMdPath(projectRoot);
 		const result = {
+			portable_skill: false,
+			portable_skill_path: AGENTS_SKILL_DISPLAY,
 			claude_code: false,
 			claude_code_path: CLAUDE_SETTINGS_DISPLAY,
 			codex: false,
-			codex_path: AGENTS_MD_DISPLAY
+			codex_path: AGENTS_MD_DISPLAY,
+			codex_hooks: false,
+			codex_hooks_path: CODEX_HOOKS_DISPLAY
 		};
+		try {
+			await access(getAgentSkillPaths(projectRoot).portable);
+			result.portable_skill = true;
+		} catch {}
+		try {
+			await access(getCodexPaths(projectRoot).hooks);
+			result.codex_hooks = true;
+		} catch {}
 		try {
 			await access(claudePaths.settings);
 			const content = await readFile(claudePaths.settings, "utf-8");
@@ -104481,15 +104570,28 @@ var StatusHandler = class extends BaseCommand {
 			remote: data.remote,
 			displayPrefix: data.display_prefix
 		}, colors);
-		if (renderIntegrationsSection([{
-			name: "Claude Code hooks",
-			installed: data.integrations.claude_code,
-			path: data.integrations.claude_code_path
-		}, {
-			name: "Codex AGENTS.md",
-			installed: data.integrations.codex,
-			path: data.integrations.codex_path
-		}], colors)) {
+		if (renderIntegrationsSection([
+			{
+				name: "Portable Agent Skill",
+				installed: data.integrations.portable_skill,
+				path: data.integrations.portable_skill_path
+			},
+			{
+				name: "Claude Code hooks",
+				installed: data.integrations.claude_code,
+				path: data.integrations.claude_code_path
+			},
+			{
+				name: "Codex AGENTS.md",
+				installed: data.integrations.codex,
+				path: data.integrations.codex_path
+			},
+			{
+				name: "Codex hooks",
+				installed: data.integrations.codex_hooks,
+				path: data.integrations.codex_hooks_path
+			}
+		], colors)) {
 			console.log("");
 			console.log(`Run ${colors.bold("tbd setup auto")} to configure detected agents`);
 		}
@@ -104829,8 +104931,10 @@ var DoctorHandler = class extends BaseCommand {
 		healthChecks.push(await this.checkCloneScenarios());
 		healthChecks.push(await this.checkSyncConsistency());
 		const integrationChecks = [];
+		integrationChecks.push(await this.checkPortableSkill());
 		integrationChecks.push(await this.checkClaudeSkill());
 		integrationChecks.push(await this.checkCodexAgents());
+		integrationChecks.push(await this.checkCodexHooks());
 		const allChecks = [...healthChecks, ...integrationChecks];
 		const allOk = allChecks.every((c) => c.status === "ok");
 		const hasFixable = allChecks.some((c) => c.fixable && c.status !== "ok");
@@ -105294,6 +105398,25 @@ var DoctorHandler = class extends BaseCommand {
 			suggestion: "Run: tbd doctor --fix to create missing mappings"
 		};
 	}
+	async checkPortableSkill() {
+		const { portable } = getAgentSkillPaths(this.cwd);
+		try {
+			await access(portable);
+			return {
+				name: "Portable Agent Skill",
+				status: "ok",
+				path: AGENTS_SKILL_REL
+			};
+		} catch {
+			return {
+				name: "Portable Agent Skill",
+				status: "warn",
+				message: "not installed",
+				path: AGENTS_SKILL_REL,
+				suggestion: "Run: tbd setup --auto"
+			};
+		}
+	}
 	async checkClaudeSkill() {
 		const claudePaths = getClaudePaths(this.cwd);
 		try {
@@ -105313,6 +105436,25 @@ var DoctorHandler = class extends BaseCommand {
 			};
 		}
 	}
+	async checkCodexHooks() {
+		const codexPaths = getCodexPaths(this.cwd);
+		try {
+			await access(codexPaths.hooks);
+			return {
+				name: "Codex hooks",
+				status: "ok",
+				path: CODEX_HOOKS_REL
+			};
+		} catch {
+			return {
+				name: "Codex hooks",
+				status: "warn",
+				message: "not installed",
+				path: CODEX_HOOKS_REL,
+				suggestion: "Run: tbd setup --auto"
+			};
+		}
+	}
 	async checkCodexAgents() {
 		const agentsPath = getAgentsMdPath(this.cwd);
 		try {
@@ -108323,16 +108465,89 @@ async function getShortcutDirectory(quiet = false) {
 	return generateShortcutDirectory(shortcuts, guidelines);
 }
 /**
-* Get the tbd section content for AGENTS.md (Codex integration).
-* Loads from SKILL.md, strips frontmatter, and wraps in TBD INTEGRATION markers.
+* DO NOT EDIT marker inserted after the frontmatter of every generated SKILL.md.
+* Formatted to match flowmark output.
+*/
+const SKILL_DO_NOT_EDIT_MARKER = "<!-- DO NOT EDIT: Generated by tbd setup.\nRun 'tbd setup' to update.\n-->";
+/**
+* Build the full generated SKILL.md payload: the bundled skill content with the
+* shortcut/guideline directory appended and a DO NOT EDIT marker after the
+* frontmatter. This is the single source for every skill surface (the portable
+* .agents/skills install and the .claude/skills mirror) so they stay identical.
 *
-* @param quiet - If true, suppress auto-sync output (default: false)
+* @param quiet - If true, suppress auto-sync output.
 */
-async function getCodexTbdSection(quiet = false) {
-	let content = stripFrontmatter(await loadSkillContent());
+async function buildSkillPayload(quiet = false) {
+	let skillContent = await loadSkillContent();
 	const directory = await getShortcutDirectory(quiet);
-	if (directory) content = content.trimEnd() + "\n\n" + directory + "\n";
-	return `<!-- BEGIN TBD INTEGRATION -->\n${content}<!-- END TBD INTEGRATION -->\n`;
+	if (directory) skillContent = skillContent.trimEnd() + "\n\n" + directory;
+	skillContent = insertAfterFrontmatter(skillContent, SKILL_DO_NOT_EDIT_MARKER);
+	return skillContent.trimEnd() + "\n";
+}
+/**
+* Write a generated SKILL.md payload to a target path, creating parent dirs.
+*/
+async function writeSkillFile(targetPath, payload) {
+	await mkdir(dirname(targetPath), { recursive: true });
+	await writeFile(targetPath, payload);
+}
+/**
+* AGENTS.md managed-block markers. `CODEX_BEGIN_MARKER` is the stable PREFIX of
+* the begin line — the metadata (`format=fNN surface=agents-md`) follows it on the
+* same line, e.g. `<!-- BEGIN TBD INTEGRATION format=f02 surface=agents-md -->`.
+* Cleanup/upgrade code matches on this prefix so it finds both legacy
+* (`<!-- BEGIN TBD INTEGRATION -->`) and current marked blocks.
+*/
+const CODEX_BEGIN_MARKER = "<!-- BEGIN TBD INTEGRATION";
+const CODEX_END_MARKER = "<!-- END TBD INTEGRATION -->";
+/** The full begin marker line for newly generated blocks. */
+const CODEX_BEGIN_LINE = `${CODEX_BEGIN_MARKER} format=${AGENT_INTEGRATION_FORMAT} surface=agents-md -->`;
+/** Numeric value of an `fNN` format string, for ordering comparisons. */
+function formatToNumber(format) {
+	return Number.parseInt(format.replace(/^f/, ""), 10);
+}
+/**
+* Read the integration format (`fNN`) stamped in a generated artifact's begin
+* marker. Returns `f01` for a legacy marked block with no `format=` field, or
+* null when there is no tbd-managed block at all.
+*/
+function parseIntegrationFormat(content) {
+	const match = /format=f(\d+)/.exec(content);
+	if (match?.[1]) return `f${match[1]}`;
+	return content.includes(CODEX_BEGIN_MARKER) ? "f01" : null;
+}
+/**
+* Forward-compatibility guard. If a generated artifact was written by a NEWER
+* tbd than this one understands, refuse to rewrite it and tell the user to
+* upgrade tbd — overwriting would downgrade a newer managed format. This is what
+* makes pinning safe on a team: an older tbd fails loudly instead of clobbering.
+*/
+function assertNotNewerFormat(content, artifact) {
+	const format = parseIntegrationFormat(content);
+	if (format !== null && formatToNumber(format) > formatToNumber(AGENT_INTEGRATION_FORMAT)) throw new CLIError(`${artifact} was generated by a newer tbd (integration format ${format}; this tbd supports up to ${AGENT_INTEGRATION_FORMAT}).\nUpgrade tbd to manage it: npm install -g get-tbd@latest`);
+}
+/**
+* Get the tbd managed block for AGENTS.md.
+*
+* This is a COMPACT always-on bootstrap, not a copy of the full skill: it names
+* tbd, states the operating rule, and points to the CLI commands that provide
+* progressive disclosure (`tbd prime`, `tbd skill`, `tbd shortcut/guidelines
+* --list`). The full skill body lives in the SKILL.md surfaces, not here, so the
+* block stays well under the AGENTS.md prompt-budget guidance.
+*/
+function getCodexTbdSection() {
+	return `${CODEX_BEGIN_LINE}\n## tbd
+
+This repository uses **tbd** for git-native issue tracking (beads), spec-driven
+planning, and on-demand engineering guidelines.
+As the agent, you operate tbd on the user’s behalf — translate their requests into tbd
+actions rather than telling them to run commands.
+
+- Run \`tbd prime\` to load current project state and the full tbd workflow.
+- Run \`tbd skill\` for the complete reusable tbd skill instructions.
+- Run \`tbd shortcut --list\` and \`tbd guidelines --list\` for on-demand resources.
+- Track all work as beads: \`tbd create\`, \`tbd ready\`, \`tbd close\`, and \`tbd sync\`.
+\n${CODEX_END_MARKER}\n`;
 }
 /**
 * Script to ensure tbd CLI is installed and run tbd prime.
@@ -108344,82 +108559,32 @@ async function getCodexTbdSection(quiet = false) {
 *   tbd-session.sh --brief   # Ensure tbd + run tbd prime --brief (for PreCompact)
 */
 const TBD_SESSION_SCRIPT = `#!/bin/bash
-# Ensure tbd CLI is installed and run tbd prime for Claude Code sessions
-# Installed by: tbd setup --auto
-# This script runs on SessionStart and PreCompact
-
-# Get npm global bin directory (if npm is available)
-NPM_GLOBAL_BIN=""
-if command -v npm &> /dev/null; then
-    NPM_PREFIX=$(npm config get prefix 2>/dev/null)
-    if [ -n "$NPM_PREFIX" ] && [ -d "$NPM_PREFIX/bin" ]; then
-        NPM_GLOBAL_BIN="$NPM_PREFIX/bin"
-    fi
-fi
+# Ensure the tbd CLI is available and run \`tbd prime\`.
+# Installed by: tbd setup --auto. Runs on SessionStart and PreCompact.
+#
+# Local-first, then a VERSION-PINNED zero-install fallback. Pinning is both a
+# supply-chain control (an unpinned runner re-resolves to latest on every run
+# and bypasses any cool-off) and a consistency control (every teammate and agent
+# runs the same tbd version).
 
-# Add common binary locations to PATH (persists for entire script)
-# Include npm global bin if found
-export PATH="$NPM_GLOBAL_BIN:$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
+# Prefer common local bin locations.
+export PATH="$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
 
-# Function to ensure tbd is available
-ensure_tbd() {
-    # Check if tbd is already installed
-    if command -v tbd &> /dev/null; then
-        return 0
-    fi
-
-    echo "[tbd] CLI not found, installing..."
-
-    # Try npm first (most common for Node.js tools)
-    if command -v npm &> /dev/null; then
-        echo "[tbd] Installing via npm..."
-        npm install -g get-tbd 2>/dev/null || {
-            # If global install fails (permissions), try local install
-            echo "[tbd] Global npm install failed, trying user install..."
-            mkdir -p ~/.local/bin
-            npm install --prefix ~/.local get-tbd
-            # Create symlink if needed
-            if [ -f ~/.local/node_modules/.bin/tbd ]; then
-                ln -sf ~/.local/node_modules/.bin/tbd ~/.local/bin/tbd
-            fi
-        }
-    elif command -v pnpm &> /dev/null; then
-        echo "[tbd] Installing via pnpm..."
-        pnpm add -g get-tbd
-    elif command -v yarn &> /dev/null; then
-        echo "[tbd] Installing via yarn..."
-        yarn global add get-tbd
-    else
-        echo "[tbd] ERROR: No package manager found (npm, pnpm, or yarn required)"
-        echo "[tbd] Please install Node.js and npm, then run: npm install -g get-tbd"
-        return 1
-    fi
-
-    # Verify installation
-    if command -v tbd &> /dev/null; then
-        echo "[tbd] Successfully installed to $(which tbd)"
-        return 0
-    else
-        echo "[tbd] WARNING: tbd installed but not found in PATH"
-        echo "[tbd] Checking common locations..."
-        # Try to find and add to path (include npm global bin)
-        for dir in "$NPM_GLOBAL_BIN" ~/.local/bin ~/.local/node_modules/.bin /usr/local/bin; do
-            if [ -n "$dir" ] && [ -x "$dir/tbd" ]; then
-                export PATH="$dir:$PATH"
-                echo "[tbd] Found at $dir/tbd"
-                return 0
-            fi
-        done
-        echo "[tbd] Could not locate tbd after installation"
-        return 1
-    fi
-}
+# Local-first: use tbd if it is already on PATH.
+if command -v tbd &> /dev/null; then
+    tbd prime "$@"
+    exit $?
+fi
 
-# Main
-ensure_tbd || exit 1
+# Pinned zero-install fallback. Never use an unpinned runner here.
+if command -v npx &> /dev/null; then
+    npx --yes get-tbd@${VERSION} prime "$@"
+    exit $?
+fi
 
-# Run tbd prime with any passed arguments (e.g., --brief for PreCompact)
-tbd prime "$@"
+echo "[tbd] tbd CLI not found and npx is unavailable."
+echo "[tbd] Install it with: npm install -g get-tbd@${VERSION}"
+exit 1
 `;
 /**
 * Claude Code session hooks configuration.
@@ -108509,22 +108674,14 @@ async function loadBundledScript(name) {
 	throw new Error(`Bundled script not found: ${name}`);
 }
 /**
-* AGENTS.md integration markers for Codex/Factory.ai
-* Content is now generated dynamically from SKILL.md via getCodexTbdSection()
-*/
-const CODEX_BEGIN_MARKER = "<!-- BEGIN TBD INTEGRATION -->";
-const CODEX_END_MARKER = "<!-- END TBD INTEGRATION -->";
-/**
 * Generate a new AGENTS.md file with tbd integration.
-*
-* @param quiet - If true, suppress auto-sync output (default: false)
 */
-async function getCodexNewAgentsFile(quiet = false) {
+function getCodexNewAgentsFile() {
 	return `# Project Instructions for AI Agents
 
 This file provides instructions and context for AI coding agents working on this project.
 
-${await getCodexTbdSection(quiet)}
+${getCodexTbdSection()}
 ## Build & Test
 
 _Add your build and test commands here_
@@ -108545,6 +108702,54 @@ _Add your project-specific conventions here_
 `;
 }
 /**
+* Codex project-local script paths (relative to repo root). Codex hooks
+* reference ONLY these `.codex/` paths, never `.claude/`, so Codex setup stays
+* independent of Claude Code setup.
+*/
+const CODEX_SESSION_SCRIPT_REL = ".codex/tbd-session.sh";
+const CODEX_CLOSING_REMINDER_REL = ".codex/tbd-closing-reminder.sh";
+const CODEX_GH_CLI_SCRIPT_REL = ".codex/ensure-gh-cli.sh";
+/**
+* Build the Codex hooks.json content. Codex uses the same lifecycle event
+* schema as Claude Code (command handlers), so tbd's hooks map almost 1:1:
+* SessionStart and PreCompact run `tbd prime`, PostToolUse reminds about sync
+* after `git push`, and (when enabled) a second SessionStart entry ensures gh.
+*/
+function getCodexHooksConfig(useGhCli) {
+	const sessionStart = [{
+		matcher: "",
+		hooks: [{
+			type: "command",
+			command: `bash ${CODEX_SESSION_SCRIPT_REL}`
+		}]
+	}];
+	if (useGhCli) sessionStart.push({
+		matcher: "",
+		hooks: [{
+			type: "command",
+			command: `bash ${CODEX_GH_CLI_SCRIPT_REL}`,
+			timeout: 120
+		}]
+	});
+	return { hooks: {
+		SessionStart: sessionStart,
+		PreCompact: [{
+			matcher: "",
+			hooks: [{
+				type: "command",
+				command: `bash ${CODEX_SESSION_SCRIPT_REL} --brief`
+			}]
+		}],
+		PostToolUse: [{
+			matcher: "Bash",
+			hooks: [{
+				type: "command",
+				command: `bash ${CODEX_CLOSING_REMINDER_REL}`
+			}]
+		}]
+	} };
+}
+/**
 * Legacy script patterns to clean up from .claude/scripts/
 * These were used in older versions of tbd before hooks moved to `tbd prime`
 */
@@ -108805,13 +109010,7 @@ var SetupClaudeHandler = class extends BaseCommand {
 			await writeFile(claudePaths.closingReminder, TBD_CLOSE_PROTOCOL_SCRIPT);
 			await chmod(claudePaths.closingReminder, 493);
 			this.output.success("Installed sync reminder hook script");
-			await mkdir(dirname(skillPath), { recursive: true });
-			let skillContent = await loadSkillContent();
-			const directory = await getShortcutDirectory(this.ctx.quiet);
-			if (directory) skillContent = skillContent.trimEnd() + "\n\n" + directory;
-			skillContent = insertAfterFrontmatter(skillContent, "<!-- DO NOT EDIT: Generated by tbd setup.\nRun 'tbd setup' to update.\n-->");
-			skillContent = skillContent.trimEnd() + "\n";
-			await writeFile(skillPath, skillContent);
+			await writeSkillFile(skillPath, await buildSkillPayload(this.ctx.quiet));
 			this.output.success("Installed skill file");
 			this.output.info(`  ${skillPath}`);
 			this.output.info("");
@@ -108844,16 +109043,93 @@ var SetupCodexHandler = class extends BaseCommand {
 		this.projectDir = dir;
 	}
 	async run(options) {
-		const agentsPath = join(this.projectDir ?? process.cwd(), "AGENTS.md");
+		const cwd = this.projectDir ?? process.cwd();
+		const agentsPath = join(cwd, "AGENTS.md");
 		if (options.check) {
 			await this.checkCodexSetup(agentsPath);
 			return;
 		}
 		if (options.remove) {
 			await this.removeCodexSection(agentsPath);
+			await this.removeCodexHooks(cwd);
 			return;
 		}
 		await this.installCodexSection(agentsPath);
+		await this.installCodexHooks(cwd);
+	}
+	/**
+	* Read the use_gh_cli setting; defaults to true (so fresh setup installs it).
+	*/
+	async getUseGhCliSetting(cwd) {
+		try {
+			const tbdRoot = await findTbdRoot(cwd);
+			if (!tbdRoot) return true;
+			return (await readConfig(tbdRoot)).settings.use_gh_cli ?? true;
+		} catch {
+			return true;
+		}
+	}
+	/**
+	* Install Codex lifecycle hooks: writes .codex/ scripts and a .codex/hooks.json
+	* (merged idempotently with any user hooks). Scripts reuse the same bodies as
+	* the Claude install but live under .codex/ so Codex never references .claude/.
+	*/
+	async installCodexHooks(cwd) {
+		if (this.checkDryRun("Would install Codex hooks", { path: "./.codex/hooks.json" })) return;
+		const codexPaths = getCodexPaths(cwd);
+		await mkdir(codexPaths.dir, { recursive: true });
+		const useGhCli = await this.getUseGhCliSetting(cwd);
+		await writeFile(join(cwd, CODEX_SESSION_SCRIPT_REL), TBD_SESSION_SCRIPT);
+		await chmod(join(cwd, CODEX_SESSION_SCRIPT_REL), 493);
+		await writeFile(join(cwd, CODEX_CLOSING_REMINDER_REL), TBD_CLOSE_PROTOCOL_SCRIPT);
+		await chmod(join(cwd, CODEX_CLOSING_REMINDER_REL), 493);
+		if (useGhCli) {
+			const ghScriptContent = await loadBundledScript("ensure-gh-cli.sh");
+			await writeFile(join(cwd, CODEX_GH_CLI_SCRIPT_REL), ghScriptContent);
+			await chmod(join(cwd, CODEX_GH_CLI_SCRIPT_REL), 493);
+		} else await rm(join(cwd, CODEX_GH_CLI_SCRIPT_REL), { force: true });
+		let existing = {};
+		try {
+			existing = JSON.parse(await readFile(codexPaths.hooks, "utf-8"));
+		} catch {}
+		const isTbdOwned = (entry) => {
+			return (entry.hooks ?? []).some((h) => h.command?.includes(".codex/"));
+		};
+		const merged = { ...existing.hooks ?? {} };
+		const tbdHooks = getCodexHooksConfig(useGhCli).hooks;
+		for (const [event, entries] of Object.entries(tbdHooks)) merged[event] = [...(merged[event] ?? []).filter((e) => !isTbdOwned(e)), ...entries];
+		await writeFile(codexPaths.hooks, JSON.stringify({
+			...existing,
+			hooks: merged
+		}, null, 2) + "\n");
+		this.output.success("Installed Codex hooks (.codex/hooks.json)");
+	}
+	/**
+	* Remove tbd-owned Codex hook entries and scripts, preserving user hooks.
+	*/
+	async removeCodexHooks(cwd) {
+		const codexPaths = getCodexPaths(cwd);
+		try {
+			const existing = JSON.parse(await readFile(codexPaths.hooks, "utf-8"));
+			const hooks = existing.hooks ?? {};
+			for (const event of Object.keys(hooks)) {
+				const kept = (hooks[event] ?? []).filter((entry) => {
+					return !(entry.hooks ?? []).some((h) => h.command?.includes(".codex/"));
+				});
+				if (kept.length === 0) delete hooks[event];
+				else hooks[event] = kept;
+			}
+			if (Object.keys(hooks).length === 0) await rm(codexPaths.hooks, { force: true });
+			else await writeFile(codexPaths.hooks, JSON.stringify({
+				...existing,
+				hooks
+			}, null, 2) + "\n");
+		} catch {}
+		for (const rel of [
+			CODEX_SESSION_SCRIPT_REL,
+			CODEX_CLOSING_REMINDER_REL,
+			CODEX_GH_CLI_SCRIPT_REL
+		]) await rm(join(cwd, rel), { force: true });
 	}
 	async checkCodexSetup(agentsPath) {
 		const agentsRelPath = "./AGENTS.md";
@@ -108938,8 +109214,9 @@ var SetupCodexHandler = class extends BaseCommand {
 				existingContent = await readFile(agentsPath, "utf-8");
 			} catch {}
 			let newContent;
-			const tbdSection = await getCodexTbdSection(this.ctx.quiet);
+			const tbdSection = getCodexTbdSection();
 			if (existingContent) if (existingContent.includes(CODEX_BEGIN_MARKER)) {
+				assertNotNewerFormat(existingContent, "AGENTS.md");
 				newContent = this.updatetbdSection(existingContent, tbdSection);
 				await writeFile(agentsPath, newContent);
 				this.output.success("Updated existing tbd section in AGENTS.md");
@@ -108949,7 +109226,7 @@ var SetupCodexHandler = class extends BaseCommand {
 				this.output.success("Added tbd section to existing AGENTS.md");
 			}
 			else {
-				await writeFile(agentsPath, await getCodexNewAgentsFile(this.ctx.quiet));
+				await writeFile(agentsPath, getCodexNewAgentsFile());
 				this.output.success("Created new AGENTS.md with tbd integration");
 			}
 			this.output.info(`  File: ${agentsPath}`);
@@ -109319,9 +109596,11 @@ var SetupAutoHandler = class extends BaseCommand {
 			console.log(colors.dim(`Cleaned up legacy ${parts.join(" and ")}`));
 		}
 		await this.syncDocs(cwd);
-		const claudeResult = await this.setupClaudeIfDetected(cwd);
+		const targeting = this.resolveTargeting();
+		await this.installPortableSkill(cwd);
+		const claudeResult = await this.setupClaudeIfDetected(cwd, targeting.claude);
 		results.push(claudeResult);
-		const codexResult = await this.setupCodexIfDetected(cwd);
+		const codexResult = await this.setupCodexIfDetected(cwd, targeting.codex);
 		results.push(codexResult);
 		const installed = results.filter((r) => r.installed && !r.alreadyInstalled);
 		const alreadyInstalled = results.filter((r) => r.alreadyInstalled);
@@ -109364,16 +109643,51 @@ var SetupAutoHandler = class extends BaseCommand {
 		if (result.pruned.length > 0) console.log(colors.dim(`Pruned ${result.pruned.length} stale config entry/entries`));
 		if (result.errors.length > 0) for (const { path, error } of result.errors) console.log(colors.warn(`Warning: ${path}: ${error}`));
 	}
-	async setupClaudeIfDetected(cwd) {
+	/**
+	* Write the canonical portable Agent Skill to .agents/skills/tbd/SKILL.md.
+	* Runs for every initialized repo, independent of agent detection, so the
+	* skill is portable across Codex, Gemini CLI, Cursor, and other clients.
+	*/
+	async installPortableSkill(cwd) {
+		const colors = this.output.getColors();
+		if (this.checkDryRun("Would install portable Agent Skill", { path: AGENTS_SKILL_DISPLAY })) return;
+		const { portable } = getAgentSkillPaths(cwd);
+		await writeSkillFile(portable, await buildSkillPayload(this.ctx.quiet));
+		console.log(`  ${colors.success("✓")} Portable Agent Skill (${AGENTS_SKILL_DISPLAY})`);
+	}
+	/**
+	* Resolve which agent surfaces to install from the explicit targeting flags.
+	* `--all`/`--claude`/`--codex` force surfaces on (and suppress auto-detection
+	* of untargeted surfaces); `--skip-claude`/`--skip-codex` force them off; with
+	* no targeting flag each surface falls back to detection-based auto behavior.
+	*/
+	resolveTargeting() {
+		const opts = this.cmd.optsWithGlobals();
+		const all = opts.all === true;
+		const anyPositive = all || opts.claude === true || opts.codex === true;
+		const resolve = (on, skip) => {
+			if (skip === true) return "off";
+			if (on === true || all) return "on";
+			return anyPositive ? "off" : "auto";
+		};
+		return {
+			claude: resolve(opts.claude, opts.skipClaude),
+			codex: resolve(opts.codex, opts.skipCodex)
+		};
+	}
+	async setupClaudeIfDetected(cwd, mode) {
 		const result = {
 			name: "Claude Code",
 			detected: false,
 			installed: false,
 			alreadyInstalled: false
 		};
-		const hasClaudeDir = await pathExists(GLOBAL_CLAUDE_DIR);
-		const hasClaudeEnv = Object.keys(process.env).some((k) => k.startsWith("CLAUDE_"));
-		if (!hasClaudeDir && !hasClaudeEnv) return result;
+		if (mode === "off") return result;
+		if (mode === "auto") {
+			const hasClaudeDir = await pathExists(GLOBAL_CLAUDE_DIR);
+			const hasClaudeEnv = Object.keys(process.env).some((k) => k.startsWith("CLAUDE_"));
+			if (!hasClaudeDir && !hasClaudeEnv) return result;
+		}
 		result.detected = true;
 		const claudePaths = getClaudePaths(cwd);
 		try {
@@ -109393,17 +109707,20 @@ var SetupAutoHandler = class extends BaseCommand {
 		}
 		return result;
 	}
-	async setupCodexIfDetected(cwd) {
+	async setupCodexIfDetected(cwd, mode) {
 		const result = {
 			name: "Codex/AGENTS.md",
 			detected: false,
 			installed: false,
 			alreadyInstalled: false
 		};
+		if (mode === "off") return result;
 		const agentsPath = getAgentsMdPath(cwd);
 		const hasAgentsMd = await pathExists(agentsPath);
-		const hasCodexEnv = Object.keys(process.env).some((k) => k.startsWith("CODEX_"));
-		if (!hasAgentsMd && !hasCodexEnv) return result;
+		if (mode === "auto") {
+			const hasCodexEnv = Object.keys(process.env).some((k) => k.startsWith("CODEX_"));
+			if (!hasAgentsMd && !hasCodexEnv) return result;
+		}
 		result.detected = true;
 		if (hasAgentsMd) {
 			if ((await readFile(agentsPath, "utf-8")).includes("BEGIN TBD INTEGRATION")) result.alreadyInstalled = true;
@@ -109414,12 +109731,13 @@ var SetupAutoHandler = class extends BaseCommand {
 			await handler.run({});
 			result.installed = true;
 		} catch (error) {
+			if (error instanceof CLIError) throw error;
 			result.error = error.message;
 		}
 		return result;
 	}
 };
-const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--interactive", "Interactive mode with prompts (for humans)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--force", "Allow non-recommended prefix format (not 2-8 alphabetic)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").action(async (options, command) => {
+const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--interactive", "Interactive mode with prompts (for humans)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--force", "Allow non-recommended prefix format (not 2-8 alphabetic)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").option("--all", "Install every supported agent surface (Claude + Codex)").option("--claude", "Install the Claude Code surface (skill mirror + hooks)").option("--codex", "Install the Codex surface (AGENTS.md block + .codex hooks)").option("--skip-claude", "Skip the Claude Code surface even if detected").option("--skip-codex", "Skip the Codex surface even if detected").action(async (options, command) => {
 	if (options.auto || options.interactive) {
 		await new SetupDefaultHandler(command).run(options);
 		return;