feat(agents): agent-assisted onboarding across CLI, skills, and MCP

hack init --with claude|codex|both hands a canonical onboarding prompt
to the agent CLI (or prints a copy-paste block when unavailable or
non-interactive). hack agent onboard emits it for existing projects.
Thin /hack-init skills install with hack setup claude|codex; MCP
serves a hack-init prompt. Content is one module: inventory, compose +
caddy setup, deps-container and ops-container patterns, running-things
guide (referenced from the instruction source), verification loop.
docs/guides/agent-first-setup.md carries the bootstrap block.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: roodboi

docs/guides/agent-first-setup.md

@@ -0,0 +1,76 @@
+# Agent-first setup
+
+Let a coding agent (Claude Code, Codex) stand a project up under hack — or adopt an
+existing setup — instead of doing it by hand. One canonical onboarding prompt drives
+every entry point below; the content lives in the CLI, so it is always current for
+your installed version.
+
+## Entry points (same prompt, four ways in)
+
+| You have | Use |
+| --- | --- |
+| A fresh repo + an agent CLI installed | `hack init --with claude\|codex\|both` |
+| An existing hack project | `hack agent onboard` (prints the prompt) |
+| An agent session with the hack skills installed | `/hack-init` |
+| A no-shell MCP client | the `hack-init` MCP prompt (`hack setup mcp`) |
+
+## New repo: `hack init --with`
+
+```bash
+cd /path/to/repo
+hack init --auto --with claude   # or codex, or both
+```
+
+- Runs the normal init, then launches the agent CLI interactively with the full
+  onboarding prompt (`claude "<prompt>"` / `codex "<prompt>"`).
+- If the agent CLI is not on PATH, the prompt is printed with copy-paste
+  instructions instead.
+- If `.hack/` already exists, init is skipped and the handoff proceeds in
+  existing-project mode.
+- With `--no-interactive` (or `HACK_NO_INTERACTIVE=1`, or no TTY) nothing is
+  spawned — the prompt is always printed.
+
+## Existing project: `hack agent onboard`
+
+```bash
+hack agent onboard          # prints the onboarding prompt for this project
+hack agent onboard | pbcopy # copy it for any agent session
+```
+
+The prompt picks up the project name and dev host from `.hack/hack.config.json`
+when present.
+
+## Agent-side skill: `/hack-init`
+
+`hack setup claude` and `hack setup codex` install a thin `hack-init` skill
+(`.claude/skills/hack-init/SKILL.md` / `.codex/skills/hack-init/SKILL.md`).
+The skill tells the agent to run `hack agent onboard` (or fetch the `hack-init`
+MCP prompt) and follow it — the content stays in the CLI, so installed skills
+never go stale on substance.
+
+## What the prompt covers
+
+1. Inventory — package manager, workspaces, services and ports, databases/queues,
+   `.env*` files (they become `hack env` candidates), scripts that need env.
+2. Setup — `hack init --auto` or config edits, compose services with Caddy labels
+   on the `hack-dev` network, dev_host/subdomain design, `hack env add`
+   (`--secret` for secrets; `.env` files get replaced by hack env +
+   `hack host exec`).
+3. Platform nuances — deps container pattern (named `node_modules` volume so
+   macOS-host installs never poison linux containers) and an ops/tooling
+   container for migrations and one-off jobs.
+4. Running things — the `hack run` / `hack exec` / `hack host exec` /
+   Caddy-hostname decision guide.
+5. Verification loop — `hack up --json` → `hack ps --json` → `hack open --json`
+   → curl or `hack logs`, iterating until `hack doctor` is clean.
+
+## Copy-paste bootstrap
+
+Paste this into a fresh Claude Code / Codex session started at the repo root:
+
+```text
+Set this repository up to run under the hack CLI. Run `hack agent onboard`
+(pass --no-interactive to hack commands) and follow the printed onboarding
+prompt exactly, phase by phase. If the hack CLI is missing, stop and tell me.
+Finish only when `hack doctor` is clean and every routable service responds.
+```

src/agents/claude.ts

@@ -7,12 +7,23 @@ import {
   writeTextFileIfChanged,
 } from "../lib/fs.ts";
 import { isRecord } from "../lib/guards.ts";
+import {
+  checkHackInitSkill,
+  installHackInitSkill,
+  removeHackInitSkill,
+} from "./hack-init-skill.ts";
 
 export type ClaudeScope = "project" | "user";
 
 export type ClaudeHookResult = {
   readonly scope: ClaudeScope;
-  readonly status: "updated" | "noop" | "removed" | "missing" | "error";
+  readonly status:
+    | "updated"
+    | "noop"
+    | "stale"
+    | "removed"
+    | "missing"
+    | "error";
   readonly path: string;
   readonly message?: string;
 };
@@ -21,7 +32,11 @@ const HOOK_COMMAND = "hack agent prime";
 const HOOK_EVENTS = ["SessionStart", "PreCompact"] as const;
 
 /**
- * Install Claude Code hooks to run the hack agent primer.
+ * Install the Claude Code integration: primer hooks in settings plus the
+ * `/hack-init` onboarding skill (`.claude/skills/hack-init/SKILL.md`).
+ *
+ * The returned path points at the settings file; the status reflects both
+ * artifacts (any change reports as updated).
  */
 export async function installClaudeHooks(opts: {
   readonly scope: ClaudeScope;
@@ -57,9 +72,25 @@ export async function installClaudeHooks(opts: {
   const nextText = `${JSON.stringify(settings.value, null, 2)}\n`;
   const result = await writeTextFileIfChanged(path, nextText);
 
+  const initResult = await installHackInitSkill({
+    client: "claude",
+    scope: opts.scope,
+    projectRoot: opts.projectRoot,
+  });
+  if (initResult.status === "error") {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: initResult.path,
+      message: initResult.message,
+    };
+  }
+  const initChanged =
+    initResult.status === "created" || initResult.status === "updated";
+
   return {
     scope: opts.scope,
-    status: updated || result.changed ? "updated" : "noop",
+    status: updated || result.changed || initChanged ? "updated" : "noop",
     path,
   };
 }
@@ -97,7 +128,27 @@ export async function checkClaudeHooks(opts: {
   }
 
   const hasAll = hasHooks({ settings: settings.value, command: HOOK_COMMAND });
-  return { scope: opts.scope, status: hasAll ? "noop" : "missing", path };
+  if (!hasAll) {
+    return { scope: opts.scope, status: "missing", path };
+  }
+
+  const initResult = await checkHackInitSkill({
+    client: "claude",
+    scope: opts.scope,
+    projectRoot: opts.projectRoot,
+  });
+  if (initResult.status !== "noop") {
+    return {
+      scope: opts.scope,
+      status: initResult.status === "error" ? "error" : "stale",
+      path: initResult.path,
+      message:
+        initResult.message ??
+        "hack-init skill is missing or out of date. Run: hack setup claude",
+    };
+  }
+
+  return { scope: opts.scope, status: "noop", path };
 }
 
 /**
@@ -118,8 +169,16 @@ export async function removeClaudeHooks(opts: {
   }
 
   const path = resolved.path;
+  const initResult = await removeHackInitSkill({
+    client: "claude",
+    scope: opts.scope,
+    projectRoot: opts.projectRoot,
+  });
+  const initRemoved = initResult.status === "removed";
+
   if (!(await pathExists(path))) {
-    return { scope: opts.scope, status: "missing", path };
+    const status = initRemoved ? "removed" : "missing";
+    return { scope: opts.scope, status, path };
   }
 
   const settings = await readSettingsFile({ path });
@@ -137,7 +196,11 @@ export async function removeClaudeHooks(opts: {
     command: HOOK_COMMAND,
   });
   if (!changed) {
-    return { scope: opts.scope, status: "noop", path };
+    return {
+      scope: opts.scope,
+      status: initRemoved ? "removed" : "noop",
+      path,
+    };
   }
 
   const nextText = `${JSON.stringify(settings.value, null, 2)}\n`;

src/agents/codex-skill.ts

@@ -7,6 +7,11 @@ import {
   readTextFile,
   writeTextFileIfChanged,
 } from "../lib/fs.ts";
+import {
+  checkHackInitSkill,
+  installHackInitSkill,
+  removeHackInitSkill,
+} from "./hack-init-skill.ts";
 import {
   normalizeInstructionText,
   renderInstructionSections,
@@ -34,7 +39,11 @@ const SKILL_DIR = ".codex/skills";
 const HACK_CLI_MARKER_REGEX = /name:\s*hack-cli\b/i;
 
 /**
- * Install or update the Codex skill for hack CLI usage.
+ * Install or update the Codex skills for hack usage.
+ *
+ * Writes the main `hack-cli` skill and the companion `/hack-init` onboarding
+ * skill. The returned path points at the main skill; the status reflects both
+ * artifacts (any change reports as created/updated).
  */
 export async function installCodexSkill(opts: {
   readonly scope: CodexSkillScope;
@@ -55,7 +64,26 @@ export async function installCodexSkill(opts: {
   const existed = await pathExists(path);
   const result = await writeTextFileIfChanged(path, renderCodexSkill());
 
-  const status = resolveInstallStatus({ changed: result.changed, existed });
+  const initResult = await installHackInitSkill({
+    client: "codex",
+    scope: opts.scope,
+    projectRoot: opts.projectRoot,
+  });
+  if (initResult.status === "error") {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: initResult.path,
+      message: initResult.message,
+    };
+  }
+
+  const initChanged =
+    initResult.status === "created" || initResult.status === "updated";
+  const status = resolveInstallStatus({
+    changed: result.changed || initChanged,
+    existed,
+  });
   return { scope: opts.scope, status, path };
 }
 
@@ -99,6 +127,22 @@ export async function checkCodexSkill(opts: {
     };
   }
 
+  const initResult = await checkHackInitSkill({
+    client: "codex",
+    scope: opts.scope,
+    projectRoot: opts.projectRoot,
+  });
+  if (initResult.status !== "noop") {
+    return {
+      scope: opts.scope,
+      status: initResult.status === "error" ? "error" : "stale",
+      path: initResult.path,
+      message:
+        initResult.message ??
+        "hack-init skill is missing or out of date. Run: hack setup codex",
+    };
+  }
+
   return { scope: opts.scope, status: "noop", path };
 }
 
@@ -122,8 +166,15 @@ export async function removeCodexSkill(opts: {
   const path = resolved.path;
   const skillDir = resolve(path, "..");
 
+  const initResult = await removeHackInitSkill({
+    client: "codex",
+    scope: opts.scope,
+    projectRoot: opts.projectRoot,
+  });
+
   if (!(await pathExists(path))) {
-    return { scope: opts.scope, status: "missing", path };
+    const status = initResult.status === "removed" ? "removed" : "missing";
+    return { scope: opts.scope, status, path };
   }
 
   await rm(skillDir, { recursive: true, force: true });