gtapps/hatch

Initialize Autonomous Agent

Set up the autonomous agent for this project. This creates the per-project state directory, configures the project for session-based work, and optionally activates hermits.

Plan

1. Check if already initialized

Check whether .claude-code-hermit/config.json exists in the current project. That file (written at Step 5) is the authoritative "already initialized" signal — not the bare presence of the .claude-code-hermit/ directory. A lone state/hatch-resume.json marker (written by a domain hatch before it delegates here), an empty state/ tree, or a half-written tree left by an aborted prior run all count as not initialized.

• If .claude-code-hermit/config.json exists: inform the operator that the agent is already initialized. Ask if they want to reinitialize (which resets templates but preserves sessions, proposals, config, and OPERATOR.md). Record the choice as is_reinit (true if operator opted to reinitialize).
• Otherwise: is_reinit = false, proceed with initialization.

1.5. Pre-flight (silent — no operator interaction)

Before the setup-mode gate or any file writes, gather context silently. Run all commands in parallel where possible:

1. Auto-detect language and timezone:

   • Language: echo $LANG | cut -d_ -f1 (fallback: en)
   • Timezone: cat /etc/timezone 2>/dev/null || timedatectl show -p Timezone --value 2>/dev/null || date +%Z (fallback: UTC)

2. Silent hermit detection + core scope detection (split out so it's available before the mode gate without an operator prompt):

   • Core scope detection: run bun ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-siblings.ts "$(pwd)" --role core-scope. It emits { "core_scope": "local"|"project"|"user"|null, "target": "committed"|"local" } — set core_install_scope from core_scope and hatch_target from target. (project → committed; local/user/null → local, the safer default the operator can override in Advanced.)
   • Sibling hermit detection: run bun ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-siblings.ts "$(pwd)" --role siblings. It emits a JSON array of the project-or-local + enabled hermit siblings (each carrying plugin, id, marketplace_name, installPath), already excluding user-scope, disabled, cross-project, and claude-code-hermit itself.
   • Stash the array as detected_hermits. Step 3 reads state-templates/CLAUDE-APPEND.md and plugin.json from each entry's installPath directly.
   • Note: sibling detection is intentionally restrictive. A hermit installed at user scope does NOT auto-detect — operator can install it at project scope and re-run, or activate via /hermit-settings.

3. Detect git-init eligibility — run in parallel with items 1–2. Set git_init_eligible = true if and only if all three hold:

   • is_reinit == false.
   • git rev-parse --is-inside-work-tree 2>/dev/null is falsy (not already under version control).
   • ls -A of the project root yields only names from this explicit allowed set: .claude-code-hermit, .claude, .gitignore, .worktreeinclude, .bash_profile, .bashrc, .zshrc, .zprofile, .profile, .gitconfig, .ripgreprc. The dotfile entries (.bash_profile through .ripgreprc) come from the sandbox-dotfile block at the bottom of state-templates/GITIGNORE-APPEND.txt — keep those in sync if that block changes.

4. Print one summary line so the operator sees what was detected:

   Initializing hermit in <project-name>. Detected: language=<lang>, timezone=<tz>, scope=<project|local|user>, target=<committed|local>, hermit candidates=<N> (<comma-separated names or "none">), git=<fresh|existing|n/a>.

1.6. Setup mode gate

If is_reinit == true: skip this gate entirely and run Advanced — Quick is for first-time install. Re-init operators have existing customizations to preserve, and Advanced's merge logic is the right tool. Quick re-running on an existing config would risk destructive overwrites of operator-tuned fields.

Otherwise, ask:

questions: [
  {
    header: "Setup mode",
    question: "How would you like to configure hermit?",
    options: [
      { label: "Quick", description: "Sensible defaults, ~4 questions, ~3 min. Tweak via /hermit-settings later." },
      { label: "Advanced", description: "Full wizard — every option exposed (~15 questions, ~15 min)." }
    ]
  }
]

Branch on choice:

• Advanced → continue to Step 2 file writes, then Step 3 hermit activation prompt, then Step 4 setup wizard.
• Quick → continue to Step 2 file writes, then jump to Section "Quick Branch" (after Step 9).

Both branches share Steps 2 (file writes) and 5-9 (config write, CLAUDE.md/.gitignore/settings, deny patterns, report). Quick replaces Steps 3-4 with the Quick Branch turns described later.

2. Create state directory structure

Run the scaffold script once — it builds the whole tree and seeds every static file. The directory layout is state-templates/ plus hatch-scaffold.ts's own enumeration; it is not restated here, because a second copy in prose is a second thing to keep in sync.

Run the scaffold script once:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/hatch-scaffold.ts <PROJECT_ROOT> --reinit=<is_reinit>

Pass --reinit=true only when Step 1 recorded is_reinit = true; otherwise --reinit=false. The script:

• Seeds state/reflection-state.json (with a live ISO counters.since), the empty append-only ledgers state/routine-metrics.jsonl, state/proposal-metrics.jsonl, state/observations.jsonl, state/update-history.jsonl, state/channel-replies.jsonl, plus state/alert-state.json, state/micro-proposals.json, the templates/ files, HEARTBEAT.md, knowledge-schema.md, OPERATOR.md, and copies + chmod +x every file under state-templates/bin/ (enumerated, not hardcoded).
• Preserves operator/state artifacts — OPERATOR.md, HEARTBEAT.md, knowledge-schema.md, and every state/* file are created only if absent (in both modes), so re-init never clobbers accumulated learning/proposal state or operator edits. --reinit=true only refreshes the hermit-owned pristine files (templates/*, bin/*).
• Never creates state/pending-close.json (lazily created by daily-auto-close when the midnight routine fires while the operator is active).

Parse the JSON it prints — { created, overwritten, preserved, operator_existed } — and remember operator_existed for Step 5a (the OPERATOR.md guard).

The reasoned artifacts are NOT scaffolded here: config.json (Step 5), the OPERATOR.md content draft (Step 5a), and the CLAUDE.local.md / CLAUDE.md block (Step 6) keep their own steps.

• Seed state/template-manifest.json via manifest-seed.ts — records the sha256 pristine-baseline the hermit-evolve drift signals depend on. Deferred to the end of Step 8 (see the seeding sub-step there): the call needs the bun */scripts/manifest-seed.ts* permission that Step 8 merges. The source template files are stable, so running it after the permission merge records the same hashes it would record now. Do not run it here.

3. Hermit activation prompt (Advanced branch only)

Quick mode handles activation in Quick Turn 1 — skip this entire step in the Quick branch.

Use the detected_hermits list cached in Step 1.5 (no re-globbing).

If the list is non-empty:

• Present the candidates and ask: "Activate a hermit for this project?"
• If the operator selects one: record the full entry from detected_hermits as activated_hermit (carries plugin, id, marketplace_name, installPath).
  • Read <activated_hermit.installPath>/state-templates/CLAUDE-APPEND.md and append it to the target project's CLAUDE.md (after the core append in step 5).
  • Read <activated_hermit.installPath>/.claude-plugin/hermit-meta.json: if it declares a hermit.boot_skill field (e.g. "/claude-code-homeassistant-hermit:ha-boot"), record it for step 5 to write as boot_skill in config.json. This replaces the default /claude-code-hermit:session bootstrap so the domain hermit's custom boot logic fires on every always-on launch. If the field is absent, leave boot_skill unset (core behavior).
  • Read <activated_hermit.installPath>/.claude-plugin/plugin.json for its version field — this, together with activated_hermit.plugin (as slug) and the boot_skill above, is what Step 5 sends as activated_hermit in the hatch-config.ts answers payload.
• If the list is empty or the operator declines: skip.

4. Setup wizard

Collect project preferences in 4–5 interactions. Use AskUserQuestion for all questions. Every question requires 2-4 options — users can always type free text via the auto-provided "Other" option.

Phase 1 — Auto-detect (already done in Step 1.5)

Step 1.5 already ran the language/timezone detection silently. Reuse those values — do not re-run the commands.

Phase 2 — Identity

4a. Agent name — ask with AskUserQuestion (header: "Agent name"). Options: Atlas / Hermit / Skip — plus Other for a custom name.

• If "Skip" or Other left blank: record as agent_name: null
• Otherwise: record the selected or typed value as agent_name

4b+4c. Language + Timezone — batch both in one AskUserQuestion call (header: "Language" / "Timezone"). For each, offer the auto-detected value as the first option and one common alternative (e.g., "en" / "UTC"). If auto-detected already matches the alternative, swap in a different one to avoid duplicates.

• Record selected label or Other free-text as the value

4d. Sign-off style (only if agent_name was provided in 4a) — ask with AskUserQuestion (header: "Sign-off"). Options: {name} out. / -- {initial}. / Skip — plus Other for custom phrasing. Replace {name} and {initial} from the agent name.

• If "Skip": record as sign_off: null
• Otherwise: record selected or typed value as sign_off

Phase 3 — Behavior (AskUserQuestion batch, 3 questions)

Ask all three in a single AskUserQuestion call (the option marked (default) is the Recommended pre-selection):

| Header | Question | Options (label: description) | |---|---|---| | Autonomy | How autonomous should your assistant be? | Balanced: act on routine tasks, escalate significant changes (default) / Conservative: ask before most non-trivial actions / Autonomous: proceed unless blocked, minimize interruptions | | Remote ctrl | Enable remote control via claude.ai/code? | Yes: connect from claude.ai/code or phone (default) / No: local terminal only | | Idle | What should hermit do when idle between tasks? | Discover: proactively surface priority/maintenance work (default) / Wait: passive, only check for new tasks and messages |

Record: escalation (conservative/balanced/autonomous), remote (true/false), idle_behavior (wait/discover).

Phase 4 — Recommended plugins (AskUserQuestion, single multiSelect question)

<!-- Compatible-plugin list is mirrored in hatch Phase 4 options, Phase 4b eligibility, and session-start step 5b. Update all three when adding. -->

Before calling AskUserQuestion, print this one-line preamble to the operator:

All are official Anthropic plugins from the claude-plugins-official marketplace (https://claude.com/plugins).

Then ask:

questions: [
  {
    header: "Plugins",
    question: "Which recommended plugins should be installed?",
    options: [
      { label: "claude-code-setup", description: "Analyzes codebase, recommends automations (skills, hooks, MCP servers, subagents)" },
      { label: "claude-md-management", description: "Audits and improves CLAUDE.md files — grades quality, proposes fixes" },
      { label: "skill-creator", description: "Builds and refines new skills from proposals" },
      { label: "feature-dev", description: "Designs, explores, and reviews code for accepted-PROP implementation work" }
    ],
    multiSelect: true
  }
]

Note: multiSelect: true is intentional — all four plugins can be selected at once.

• All plugins are selected by default — deselect to skip
• If no plugins are selected, skip all plugin installs
• For each selected plugin, install it immediately at the hermit's scope (core_install_scope from Step 2; fall back to project when null): claude plugin install <plugin>@claude-plugins-official --scope <core_install_scope>

For each accepted plugin, also add the corresponding scheduled_checks entries to config.json:

• claude-code-setup → {"id":"automation-recommender","plugin":"claude-code-setup","skill":"/claude-code-setup:claude-automation-recommender","enabled":true,"trigger":"interval","interval_days":7}
• claude-md-management → two entries:
  • {"id":"md-audit","plugin":"claude-md-management","skill":"/claude-md-management:claude-md-improver","enabled":true,"trigger":"interval","interval_days":7}
  • {"id":"md-revise","plugin":"claude-md-management","skill":"/claude-md-management:revise-claude-md","enabled":true,"trigger":"session"}
• skill-creator → no entry (event-driven via proposal-act, not scheduled)
• feature-dev → no entry (manual on-demand via /feature-dev:feature-dev, not scheduled)

For each plugin the operator declines, skip silently. Note: "You can add it later with /claude-code-hermit:hermit-settings."

Phase 4b — Baseline audit marker (conditional)

<!-- Compatible-plugin list is mirrored in hatch Phase 4 options, Phase 4b eligibility, and session-start step 5b. Update all three when adding. -->

Create .claude-code-hermit/.baseline-pending (empty file) ONLY if all three are true:

1. This is a fresh init, not a re-init. (Step 1 of hatch branches on an existing .claude-code-hermit/; skip this phase on re-init.)
2. Phase 4 accepted either claude-md-management or claude-code-setup.
3. The project is an existing codebase — at least one of the following files exists at the project root:
   • package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json, pom.xml, build.gradle

README.md and CLAUDE.md alone do NOT qualify. If none of the eligibility conditions hold, skip silently — no operator prompt here.

The marker's existence is the entire state model. No JSON, no timestamp, no content.

Phase 5 — Channels (AskUserQuestion, single question)

questions: [
  {
    header: "Channels",
    question: "Configure a notification channel for this project?",
    options: [{ label: "Discord (recommended)" }, { label: "Telegram" }, { label: "None — skip channel setup" }]
  }
]

• If None: record channels: {}. Proceed to Phase 6. Do not ask channel follow-ups.

• If Discord or Telegram: create a channel entry under the channels object (e.g., channels.discord). Boot script maps the key to the full plugin identifier. Then ask follow-ups below.

• Channel plugins require Bun and manual setup (bot creation, token, pairing). After saving the preference to config.json, note:

  Channel preference saved. Activation depends on how you run hermit:

  • Docker (always-on): /claude-code-hermit:docker-setup configures the token and pairing inside the container.
  • tmux (always-on, host): boot with .claude-code-hermit/bin/hermit-start (passes --channels automatically), then run /claude-code-hermit:channel-setup to set the token and pair.
  • Interactive (just trying it): run /claude-code-hermit:channel-setup for token + pairing, then restart with claude --channels plugin:<channel>@claude-plugins-official so the channel is active in your session.
  • Full guide: https://code.claude.com/docs/en/channels

Channel follow-ups (only if Discord or Telegram was selected above — AskUserQuestion batch, 2 questions; the option marked (default) is the Recommended pre-selection):

| Header | Question | Options (label: description) | |---|---|---| | Access ctrl | Restrict who can send commands via this channel? | Allow everyone: no restrictions on who can message (default) / Restrict: type your Discord/Telegram user ID via Other | | Brief | Enable morning brief delivery via channel? | Yes — 07:00: daily summary delivered each morning / No: no automated brief delivery (default) |

• Access control: If "Restrict" and a numeric ID was typed via Other, record in channels.<channel>.allowed_users as ["<id>"]. If "Allow everyone" or no ID provided, omit the key (absent = accept all). Note: "Add more user IDs later with /claude-code-hermit:hermit-settings channels. An empty array [] blocks all messages."
• Morning brief: If "Yes — 07:00", record as channels.<channel>.morning_brief: { "enabled": true, "time": "07:00" }. If "No", omit the key (or set to null).

Phase 6 — Deployment (AskUserQuestion batch, 3 questions)

The Visibility question uses the scope-derived hatch_target to recommend an option. Place the recommended option at index 0 with (recommended) in the label so the recommendation is clear:

• If hatch_target == "local" (scope=local or scope=user): .local files is position 0 with (recommended).
• If hatch_target == "committed" (scope=project): Committed files is position 0 with (recommended).

questions: [
  {
    header: "Permissions",
    question: "Permission mode for Claude Code?",
    options: [
      { label: "auto", description: "**Default.** Classifier-reviewed autonomy — each action reviewed before it runs. Generally available to all users across subscription plans and API usage; supported models and provider configuration can vary. If Claude reports it unavailable for the current selection, choose a supported model or another permission mode." },
      { label: "acceptEdits", description: "Auto-approve file edits, prompt for shell commands. Good balance if auto is unavailable on your plan." },
      { label: "default", description: "Prompt for permission on first use of each tool" },
      { label: "dontAsk", description: "Deny all tools not in permissions.allow — requires curated allowlist" },
      { label: "bypassPermissions", description: "No permission prompts. Opt-in for fully unattended Docker-isolated hermits that cannot tolerate any pause." }
    ]
  },
  {
    header: "Routines",
    question: "Set up morning and evening routines? (morning brief reviews priorities, evening summarizes the day)",
    options: [
      { label: "Yes", description: "Morning at 08:30, evening at 22:30 (default)" },
      { label: "No", description: "No scheduled routines" }
    ]
  },
  {
    header: "Visibility",
    question: "Where should hermit-personal hatch outputs live? (CLAUDE.md block, hook permissions, deny patterns)",
    // Build options with recommended at index 0 based on hatch_target:
    // When hatch_target == "local":
    //   options: [
    //     { label: ".local files (recommended)", description: "Gitignored — operator-personal. Plugin installed at <scope> scope." },
    //     { label: "Committed files", description: "Shared with teammates. Override scope-derived default." }
    //   ]
    // When hatch_target == "committed":
    //   options: [
    //     { label: "Committed files (recommended)", description: "Shared with teammates. Plugin installed at project scope." },
    //     { label: ".local files", description: "Gitignored — operator-personal. Override scope-derived default." }
    //   ]
  }
]

The recommended option is always at index 0 with (recommended) in the label. When hatch_target == "local", .local files is index 0; when hatch_target == "committed", Committed files is index 0. Substitute <scope> with the actual core_install_scope value.

Record the operator's Visibility choice as hatch_target (overrides scope-derived default if different).

Record: permission_mode (auto/acceptEdits/default/dontAsk/bypassPermissions/plan). plan mode can be typed via Other if needed.

For routines — if Yes: use the config defaults (active_hours.start = 08:00, end = 23:00) to derive morning = 08:30 and evening = 22:30. Add to routines array:

• {"id":"morning","schedule":"30 8 * * *","skill":"claude-code-hermit:brief --morning","enabled":true,"run_during_waiting":true}
• {"id":"evening","schedule":"30 22 * * *","skill":"claude-code-hermit:brief --evening","enabled":true,"run_during_waiting":true}
• Always add (regardless of routine choice): {"id":"heartbeat-restart","schedule":"0 4 * * *","skill":"claude-code-hermit:heartbeat start","run_during_waiting":true,"enabled":true}
• If no routines: still add heartbeat-restart to the routines array (it's infrastructure, not a user routine)
• Routines auto-register only on always-on launches via hermit-start.ts (as one persistent routine monitor; CronCreate fallback where Monitor is unavailable). Interactive /session users who want routines active in interactive mode must run /claude-code-hermit:hermit-routines load themselves. Mention this once at the end of hatch if the operator is running interactively.
• If the operator wants a custom routine beyond the morning/evening defaults, point them at Routine Authoring for the cost-conscious authoring pattern (scoped skill, haiku pin, precheck gating) rather than hand-deriving it.

5. Write config.json

Source of truth: ${CLAUDE_SKILL_DIR}/../../state-templates/config.json.template. hatch-config.ts reads it as the base — it encodes every default field shipped by the current plugin version (including model, always_on, chrome, monitors, compact, knowledge, etc.). Do NOT maintain a parallel inline default object here — anything written inline in this skill drifts the moment a field is added to the template.

Build an answers payload from the wizard's collected answers, then run:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/hatch-config.ts <PROJECT_ROOT> [--reinit]

with the answers payload as JSON on stdin. The script reads the template (or, on --reinit, the existing .claude-code-hermit/config.json), overlays the answers, validates the result, and writes .claude-code-hermit/config.json.

Answers payload — include a key only when the wizard actually collected that answer (the script overlays by presence, so an omitted key leaves the existing/template value untouched):

{
  "project_name": "<project directory name, fresh hatch only>",
  "activated_hermit": { "slug": "<plugin>", "version": "<sibling's plugin.json version>", "boot_skill": "<hermit.boot_skill from hermit-meta.json, or null>" },
  "agent_name": "...", "language": "...", "timezone": "...", "sign_off": "...",
  "escalation": "...", "remote": true, "idle_behavior": "...",
  "permission_mode": "...",
  "routines": { "enabled": true, "morning_time": "08:30", "evening_time": "22:30" },
  "scheduled_checks_plugins": ["claude-code-setup", "claude-md-management"],
  "channels": { "discord": { "enabled": true, "allowed_users": ["<id>"], "morning_brief_time": "07:00" } }
}

• Phase 2 → agent_name, language, timezone, sign_off.
• Phase 3 → escalation, remote, idle_behavior.
• Phase 4 → scheduled_checks_plugins: only claude-code-setup and claude-md-management contribute entries (3 total when both selected); skill-creator and feature-dev contribute none — omit them from the list.
• Phase 5 → channels.<name>: enabled, allowed_users (omit if the operator skipped access control), morning_brief_time (omit if declined; on re-init, send it as null to turn off a brief the operator previously enabled). The script fills in dm_channel_id: null and state_dir: .claude.local/channels/<name> on first creation and preserves both (plus any other channel it doesn't recognize, channels.primary, and third-party marketplace channels) on re-init merge. Do not include push_notifications in the payload — the script never touches it; it stays at the template default (true) or, on re-init, whatever value is already on disk. The runtime channel-first/push-fallback guard in CLAUDE-APPEND.md already prevents double-notification.
• Phase 6 → permission_mode, routines (morning/evening only — heartbeat-restart and the other infrastructure routines are already in the template and are never touched by this payload).
• Step 3 hermit activation → activated_hermit. version is read from <activated_hermit.installPath>/.claude-plugin/plugin.json; boot_skill is read from <activated_hermit.installPath>/.claude-plugin/hermit-meta.json's hermit.boot_skill field (or null if absent).

Re-initialization is --reinit on the same call — the script reads the existing config as its base (never the template), so any field the payload doesn't mention (custom operator keys, push_notifications, docker, monitors, ...) survives untouched, _hermit_versions entries are never advanced (only added if a slug is newly absent), and scheduled_checks/channels/routines are reconciled/merged by id rather than replaced wholesale. shutdown_skill is never written by this script — leave it null; the operator sets it via config edit if they run always-on services that need stopping on full close.

Template-only fields (the wizard never asks about these — they come straight from config.json.template, and hatch-config.ts never touches them; the operator can tune them via /hermit-settings later): model, effort, auto_session, always_on, chrome, monitors, compact, heartbeat, knowledge, env, quality_gate, watchdog, budget, telemetry_export, artifacts, context_hygiene, reflection, routine_wake_lint, doctor, storage_drift, post_close_clear, ask_gate, operator_profile.

operator_profile ships "technical" (the operator on the channel is the person who runs the box, so technical/ops/spend detail may reach the primary chat). A client-facing install (where the person on the channel is a client or end-user, not the maintainer) sets it to "non-technical", which forces technical alerts and spend figures to a maintainer_channel_id (or SHELL.md Findings when none is set) and deflects client-chat spend questions. When a channel is configured, the plain framing for choosing this is "who reads this chat — you, or a client/end-user?"; a client answer means non-technical. Set it in config.json directly or via /hermit-settings; hatch-config.ts leaves the template default in place. The Quick branch and Advanced wizard both leave these at template defaults. routine_wake_lint.max_windows (default 6) is the wake-clustering lint threshold — hermit-routines load warns when enabled routines' fire-times spread across more than this many distinct 30-min windows. doctor.routine_cost_floor_usd (default 2) is the noise floor for the routine-cost doctor check: a routine warns only when its $/run exceeds both 3× the peer median (the other routines' median) and this floor, so a lone or uniformly-priced fleet never warns. budget ships inert (all caps null, action: "alert") — see docs/config-reference.md for daily/weekly/monthly USD caps and the alert/pause enforcement action. telemetry_export ships disabled (enabled: false, destination.url: null) — opt-in webhook export of a sanitized health/cost bundle from the watchdog tick, see docs/config-reference.md. artifacts.dashboard/artifacts.proposals/artifacts.weekly_review ship enabled (true) — three script-rendered, hash-gated Artifact pages (dashboard, open-proposals, weekly-review), refreshed by brief/weekly-review/proposal-create/proposal-act; see docs/artifacts.md and docs/config-reference.md. Publish authorization for unattended sessions is Step 9c below. ask_gate ships enabled (true) — on an always_on session with a reachable channel, it denies AskUserQuestion and redirects the model to the channel reply tool plus a durable micro-proposal entry; set to false to opt out, see docs/config-reference.md.

tmux_session_name is derived from project_name on fresh hatch only (hermit-<project_name>) — re-init never re-substitutes it.

5-task. Write task list ID to settings.local.json

Set CLAUDE_CODE_TASK_LIST_ID in .claude/settings.local.json so native Claude Code Tasks are persistent and hooks can read task files.

1. Derive the task list ID: hermit-{project_basename} where {project_basename} is the current directory name (lowercase, alphanumeric + hyphens)
2. Run: bun ${CLAUDE_PLUGIN_ROOT}/scripts/apply-settings.ts .claude/settings.local.json task-id hermit-{project_basename} (Creates the file if absent; merges the value into env, preserving all other keys.)

This enables native Tasks for plan tracking. The cost-tracker hook reads task files from ~/.claude/tasks/{task_list_id}/ to generate tasks-snapshot.md.

5b. Localize artifact chrome (non-en operators only)

The script-rendered Artifact pages (dashboard, proposals) read their fixed UI chrome from .claude-code-hermit/state/artifact-strings.json when present, overlaying it per key over the English defaults (a missing key or an absent file falls back to English). Model-authored content already follows language; this closes the gap for the ~35 hardcoded chrome labels so a non-en dashboard isn't half-English.

Run only when the chosen language is set and is not en:

1. Emit the English scaffold: bun ${CLAUDE_PLUGIN_ROOT}/scripts/artifact.ts scaffold-strings <language> <current-ISO-timestamp>.
2. Translate every value inside the strings object into the operator's language. Leave the keys and any {placeholder} tokens verbatim (word order may move around a token, but the token text must not change or be translated). Leave the language and generated fields as emitted.
3. Write the result to .claude-code-hermit/state/artifact-strings.json.

When language is en or unset, skip — absent file ⇒ English chrome, byte-identical to today.

5a. OPERATOR.md onboarding

Generate OPERATOR.md through a project scan and targeted conversation instead of asking the operator to edit it manually.

Re-init guard: If operator_existed is true (from step 2):

• Ask: "OPERATOR.md already exists — regenerate it from a fresh project scan? Your current one will be saved as OPERATOR.md.bak."
• If yes: rename existing to .claude-code-hermit/OPERATOR.md.bak, then proceed with phases below.
• If no: skip this entire step.

Phase 1 — Project scan (silent, no output to operator)

Scan the target project for context. Read ONLY the following if they exist — never read source code files. Read all existing files in parallel (batch into a single tool-call turn) to minimize scan time:

<!-- Intentionally NOT in this list: `.claude-code-hermit/config.json`. Reading config.json during the draft scan would invite the model to mine it for OPERATOR.md content, which is exactly the leak Phase 4's scrub exists to prevent. The model is config-blind during draft by design; the scrub catches any leakage from CLAUDE.md or Phase 3 answers. Do not add config.json to this scan. -->

| File | Read scope | | -------------------- | -------------------------------------------- | | CLAUDE.md | Full file | | README.md | First 200 lines | | package.json | Full file | | requirements.txt | Full file | | pyproject.toml | Full file | | Cargo.toml | Full file | | go.mod | Full file | | docker-compose.yml | Full file | | .github/workflows/ | List filenames; read the first workflow file | | .gitlab-ci.yml | First 100 lines | | Makefile | First 50 lines |

Also get the directory structure (2 levels deep) to understand the project layout.

Collect findings silently. Do NOT print scan results to the operator.

Phase 2 — Draft OPERATOR.md

Using the scan results, write a concise context document. Follow these rules:

1. Never duplicate CLAUDE.md content. If CLAUDE.md already covers a topic (testing, conventions, build commands), don't repeat it.
2. Never duplicate config.json fields. routines, channels (including Discord/Telegram user IDs and morning_brief), permission_mode, agent_name, sign_off, escalation, idle_behavior, boot_skill, shutdown_skill, and _hermit_versions are already loaded structurally — do not restate them as prose. OPERATOR.md is for context the model can't infer from config (project focus, constraints, approval gates, comms style, project rationale).
3. Only include high-confidence inferences. If the scan clearly reveals something (e.g., package.json shows Node.js, README describes the project), include it. If uncertain, leave it for Phase 3 questions.
4. Keep it under 50 lines. OPERATOR.md is loaded every session-start — bloat costs tokens. Write concise prose, not documentation.
5. No rigid sections required. Use headers if they help organize, but don't create empty sections. The goal is a useful context document, not a filled-in form.

Write the draft to .claude-code-hermit/OPERATOR.md.

Phase 3 — Targeted questions (AskUserQuestion batch)

Questions are split into two AskUserQuestion calls (max 4 per call). Q1–Q4 are never skipped and always form the first call. Q5–Q7 are conditional and form a second call only if any are included.

Call 1 — always sent (4 questions):

| # | Header | Question | Options (+ Other for free text) | | --- | ----------- | ----------------------------------------------------------------------- | ------------------------------------------------ | | 1 | Focus | "What should I focus on in this project?" | Active development / Stabilization / Exploration | | 2 | Constraints | "Are there hard rules or areas I should avoid touching without asking?" | None / Config files | | 3 | Approval | "What actions require your explicit approval before I proceed?" | Deploys only / Breaking changes / Nothing extra | | 4 | Comms style | "How do you prefer I communicate?" | Concise / Detailed / Ask first |

Accept any answer including free-text via Other. Expand into OPERATOR.md prose in Phase 4 — don't take options too literally.

Call 2 — only if any of Q5–Q7 apply (skip conditions below):

| # | Header | Question | Options | Skip if... | | --- | ------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | | 5 | CI/CD | "Any CI/CD quirks I should know about? (flaky tests, required checks, deploy process)" | Standard / Has quirks | No CI config found in Phase 1 | | 6 | Testing | "How should I handle testing? (run before commit, specific commands, coverage requirements)" | Before commit / CI handles it / As needed | CLAUDE.md already covers testing | | 7 | Team | "Who's working on this? (solo / small team / large team — and any ownership boundaries)" | Solo / Small team / Large team | Skip if Q5 or Q6 is included (batch already ≥2) |

If none of Q5–Q7 apply, skip Call 2 entirely.

Tell the operator before Call 1: "I've scanned your project and drafted OPERATOR.md. A few questions to fill in what I couldn't infer:"

All questions use the AskUserQuestion structures defined above. Accept short answers or free-text via Other; expand into prose in Phase 4. If the operator selects "Skip", leaves Other blank, or gives a minimal answer, don't include that topic in OPERATOR.md.

Hermit extension: If a hermit was activated in step 3 and provides a file at <activated_hermit.installPath>/state-templates/OPERATOR-QUESTIONS.md, read it and append those questions to Call 2 (or start a Call 3 if Call 2 is already at 4).

Phase 4 — Write final OPERATOR.md

Incorporate the operator's answers into the draft:

• Weave answers into the document as concise prose
• Use headers only where they add clarity — don't force a section for every answer
• Strip the HTML comment from the template (replace with actual content)
• Keep the document under 50 lines total
• For hermit-specific context, append after the core content

Before writing, scrub the draft for config.json mirroring. Re-scan and remove any sentence that restates a config.json field (routine schedules, Discord/Telegram user IDs, morning_brief time, permission_mode, agent_name, sign_off, escalation, idle_behavior, boot_skill, shutdown_skill). If removing a sentence leaves a paragraph hollow, drop the paragraph. Those facts are already loaded from config.json on every session-start — duplicating them in OPERATOR.md is pure token tax and drifts when config changes.

Write the final version to .claude-code-hermit/OPERATOR.md.

Phase 5 — Confirm

Tell the operator: "OPERATOR.md is ready. You can review it at .claude-code-hermit/OPERATOR.md. Refine anytime — just tell me what changed."

6. Append session discipline to CLAUDE.md or CLAUDE.local.md

The target file is determined by hatch_target (computed in Step 1.5):

• hatch_target == "local" → write to CLAUDE.local.md (gitignored, operator-personal)
• hatch_target == "committed" → write to CLAUDE.md (committed, current behavior)

Perform the idempotency check across both files first: if the marker claude-code-hermit: Session Discipline exists in the non-target file, surface a conflict — ask operator: Move to target file (diff-and-confirm) / Keep both (warn that both load) / Skip conflict. Never silently leave duplicate markers.

For the target file (the block is static — copy it with cat, never regenerate it by hand):

• If it exists: check if it already contains claude-code-hermit: Session Discipline
  • If yes: ask with AskUserQuestion (header: "CLAUDE block") — options: Yes — replace (update to latest) / No — keep (preserve current, default)
    • If "Yes — replace": remove the existing hermit block (from its <!-- claude-code-hermit: Session Discipline --> marker — and any blank line / --- separator immediately above it — through its closing <!-- /claude-code-hermit: Session Discipline --> marker; if the target's block predates the closing marker, fall back to the first standalone --- line after the opening marker, or end of file), then re-append the fresh template: cat "${CLAUDE_SKILL_DIR}/../../state-templates/CLAUDE-APPEND.md" >> <target>
    • If "No — keep": skip
  • If no: cat "${CLAUDE_SKILL_DIR}/../../state-templates/CLAUDE-APPEND.md" >> <target>
• If the target file doesn't exist: cat "${CLAUDE_SKILL_DIR}/../../state-templates/CLAUDE-APPEND.md" > <target>

If a hermit was activated in step 3, also append <activated_hermit.installPath>/state-templates/CLAUDE-APPEND.md to the same target file (using the same skip/overwrite logic if its marker already exists).

7. Update .gitignore

Use ${CLAUDE_SKILL_DIR}/../../state-templates/GITIGNORE-APPEND.txt.

Read the template. Determine which lines are missing from the project's .gitignore (per-line idempotent check — do not re-add lines already present). Only the missing lines are candidates to append.

• If .gitignore exists and candidate lines are non-empty: show the operator only the missing lines that will be appended, and ask with AskUserQuestion (header: "Update .gitignore") — options: Yes — append (add missing entries, default) / No — skip (you'll manage .gitignore manually). Append only if confirmed.
• If .gitignore exists and no lines are missing: skip silently.
• If .gitignore doesn't exist: show the operator the full template that will be written, and ask with AskUserQuestion (header: "Create .gitignore") — options: Yes — create (default) / No — skip. Create only if confirmed.

7a. Update .worktreeinclude

Use ${CLAUDE_SKILL_DIR}/../../state-templates/WORKTREEINCLUDE-APPEND.txt.

The file contains a managed block bounded by marker comments (# >>> claude-code-hermit ... / # <<< claude-code-hermit >>>). This block carries read-only hermit context (OPERATOR.md, compiled/) into claude --worktree worktrees. Write it unconditionally — no git-repo gate. A .worktreeinclude in a non-git project is harmless and ready when the operator later runs git init.

• If .worktreeinclude is absent: show the operator the template that will be written, and ask with AskUserQuestion (header: "Create .worktreeinclude") — options: Yes — create (default) / No — skip. Create only if confirmed.
• If .worktreeinclude exists and the # >>> claude-code-hermit marker is already present: skip silently.
• If .worktreeinclude exists and the marker is absent: append the managed block (preceded by a blank line) — ask with AskUserQuestion (header: "Update .worktreeinclude") — options: Yes — append (default) / No — skip. Append only if confirmed.

7.5. Initialize git repo (fresh dirs only)

Skip this step entirely if git_init_eligible is false. Skip silently with no operator interaction.

If git_init_eligible:

• Advanced branch: ask with AskUserQuestion (header: "Git init") — "Initialize a local git repo here? The hermit's build output will be tracked; its internal churn (sessions, proposals, state) stays gitignored." — options: Yes (default) / No. Run git init only on Yes.
• Quick branch: announced in the Quick Turn 5 confirm bundle and run as part of the shared steps only after the operator confirms (see "Quick — silent defaults applied to shared steps" table — Step 7.5 row). Never auto-runs before confirmation.

When run, git init creates the repo at the project root. The .gitignore written in Step 7 is immediately in effect.

8. Ensure plugin permissions in settings file

The plugin's hooks and boot scripts require specific Bash permissions to run without prompting. The target settings file is determined by hatch_target:

• hatch_target == "local" → merge into .claude/settings.local.json (gitignored)
• hatch_target == "committed" → merge into .claude/settings.json (committed, current behavior)

Do not restate the permission list here or anywhere else. apply-settings.ts holds the only copy (its sealed HERMIT_ALLOW); ask it what the target file is missing:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/apply-settings.ts <resolved-settings-file> permissions-plan

It writes nothing and prints one JSON line: {"missing":[...],"obsolete":[...]} — the sealed entries the target lacks, and any entries from retired plugin versions it still carries.

What the permissions buy:

• git diff, git status, git log — session-diff.ts hook auto-populates ## Changed in SHELL.md
• bun */scripts/<name>.ts — Stop hooks (cost-tracker, session-diff, evaluate-session) and precheck scripts (heartbeat.ts precheck, reflect-precheck), scoped to plugin scripts only. Includes manifest-seed.ts, which the seeding sub-step below runs to write the template-manifest baseline (deferred from Step 2 so the permission is in place first). Includes channel-log.ts, which weekly-review's consolidation step runs unattended to list/mark/prune the episodic channel log (PROP-010). Includes session-archive.ts, the deterministic session-lifecycle writer (idle/close/auto-close/open/recover) that replaced the session-mgr subagent — without this permission a hatched hermit would be asked (functionally denied headlessly) on its first idle transition. Includes proposal.ts — the single proposal CLI. Its create/patch/shell-append/next-task/routine verbs perform every .claude-code-hermit/ state-dir write proposal-create and proposal-act make; without it, proposal creation and every accept/defer/dismiss/resolve mutation would be functionally denied in background/worktree sessions (the harness's isolation guard blocks the Write/Edit tools there, not Bash). Its resolve-id/gate/queue-micro/micro/index/metrics/success-signal verbs are the proposal-act/proposal-create/reflect mechanics; without them, ID resolution, gate-verdict routing, and micro-approval queuing would all be functionally denied headlessly. Includes apply-reflection-actions.ts and transcript-digest.ts — reflect's transactional resolution-action apply and its behavioral-telemetry digest; without these a scheduled reflect silently degrades to introspection-only and never resolves a proposal. Includes setup-token-mint.ts — the login-token renewal driver /relogin runs; that skill exists to be driven from chat when the hermit's login is about to lapse, so a permission prompt there is an outright denial and the renewal it was meant to perform never happens
• .claude-code-hermit/bin/hermit-run proposal micro * / proposal metrics * — domain plugins (HA's ha-morning-brief, the domain-brainstorm skills) reach core's shared scripts through the project-resident bin/hermit-run, since their own ${CLAUDE_PLUGIN_ROOT} can't resolve core's versioned cache dir. Each grant is pinned to the one verb that plugin needs, never a bare hermit-run proposal * — that would also expose create, patch, shell-append, next-task and routine, i.e. arbitrary state-dir writes. The space before * is a word boundary — matches proposal micro .claude-code-hermit brief-cycle, not a micro…-prefixed verb — and hermit-exec.sh additionally rejects //.. in the script name, so the route can't reach a script outside core's scripts/. Without these, headless domain briefs and brainstorm metrics checks are functionally denied
• .claude-code-hermit/bin/hermit-run domain-hatch preflight * / ensure-target * / sync-block * — the shared domain-hatch protocol every domain plugin's /hatch runs: the core-version floor check, the CLAUDE target resolution, and the CLAUDE-APPEND block write. Pinned per verb for the same reason as above — a bare domain-hatch * would hand every caller ensure-target and sync-block, which write core state and the operator's CLAUDE.md, when most of a hatch run only reads preflight. Without these, a domain hatch cannot check whether core is new enough for it and would proceed against a core it declares it cannot run on
• bash -c 'AGENT_DIR=... — SessionStart hook that loads session context on every startup
• Edit on .claude-code-hermit/** — heartbeat appends to SHELL.md, increments config.json tick counter, and skills update session state without prompting (Edit rules cover all file-editing tools, including Write)

Steps:

1. Run permissions-plan (command above) against the resolved settings file and parse the JSON line.
2. If both missing and obsolete are empty: skip silently.
3. Otherwise show the operator the entries — what will be added, and what retired entries will be removed — and ask with AskUserQuestion (header: "Hook perms") — options: Yes — add (merge so hooks run without prompting, default) / No — skip (you'll be prompted during sessions).
4. If the operator confirms: run bun ${CLAUDE_PLUGIN_ROOT}/scripts/apply-settings.ts <resolved-settings-file> permissions-sync (Adds every missing sealed entry and removes only entries from retired plugin versions. Operator-authored rules are never touched.) Then run bun ${CLAUDE_PLUGIN_ROOT}/scripts/apply-settings.ts .claude/settings.local.json automode-seed — always .claude/settings.local.json, regardless of hatch_target: the auto-mode classifier reads autoMode config only from local/user scope, never a committed project .claude/settings.json, so seeding anywhere else would be a silent no-op. Tell the operator in one line: "Also recorded an auto-mode exception and environment context in .claude/settings.local.json so unattended upgrade migrations can run the plugin's sealed settings ops."
5. If the operator declines: skip (including the auto-mode seed above — an operator who wants prompts should not get a standing classifier exception), and note: "You may be prompted to approve hook commands during sessions. Run /claude-code-hermit:hermit-settings permissions to add them later."

Seed state/template-manifest.json (deferred from Step 2 — now that the bun */scripts/manifest-seed.ts* permission is in place). It records the sha256 pristine-baseline that the hermit-evolve drift signals depend on. The script computes the hashes (an LLM cannot sha256 reliably). Read the current plugin version from ${CLAUDE_SKILL_DIR}/../../.claude-plugin/plugin.json, then run bun ${CLAUDE_PLUGIN_ROOT}/scripts/manifest-seed.ts .claude-code-hermit with this JSON on stdin:

{
  "pluginVersion": "<version>",
  "entries": [
    { "key": "templates/SHELL.md.template", "file": "${CLAUDE_PLUGIN_ROOT}/state-templates/SHELL.md.template" },
    { "key": "templates/SESSION-REPORT.md.template", "file": "${CLAUDE_PLUGIN_ROOT}/state-templates/SESSION-REPORT.md.template" },
    { "key": "templates/PROPOSAL.md.template", "file": "${CLAUDE_PLUGIN_ROOT}/state-templates/PROPOSAL.md.template" },
    { "keyPrefix": "bin", "dir": "${CLAUDE_PLUGIN_ROOT}/state-templates/bin" }
  ]
}

The bin entry enumerates the source state-templates/bin/ (the authoritative core set), never the project's .claude-code-hermit/bin/ (which can hold operator/add-on files). The script writes { "version": 1, "files": { ... } } and on re-init preserves foreign keys (add-on hermit entries) while overwriting only the keys it re-seeds; it refuses to overwrite a present-but-corrupt manifest. The source files it hashes are stable, so seeding here does not change the recorded hashes.

The bare .claude-code-hermit argv is cwd-relative, which is safe here: hatch runs from the project root and never invokes docker compose or tmux, so cwd does not drift (unlike /docker-setup Step 7b.6, which anchors to an absolute <PROJECT_ROOT> for that reason).

9. Generate deny patterns (AskUserQuestion, single question)

Add safety deny rules to the target settings file's permissions.deny to prevent destructive operations. The target file is the same as Step 8 (hatch_target == "local" → .claude/settings.local.json; else → .claude/settings.json).

questions: [
  {
    header: "Safety rules",
    question: "Planning always-on operation (Docker/tmux)? This determines which deny rules to apply.",
    options: [
      { label: "Yes — hardened", description: "Adds git push, npm publish, and unattended-operation protections" },
      { label: "No — minimal", description: "Blocks destructive commands and credential exposure (default)" },
      { label: "Skip", description: "No deny rules — add later in settings.json" }
    ]
  }
]

• If hardened (always-on): default + always-on additions (excluding docker/kubectl/ssh — valid in devops contexts on host). Canonical source: state-templates/deny-patterns.json.
• If minimal (default): default set only. Same canonical source: state-templates/deny-patterns.json.
• If skip: note: "You can add deny rules later in .claude/settings.json under permissions.deny."

Run bun ${CLAUDE_PLUGIN_ROOT}/scripts/apply-settings.ts <resolved-settings-file> deny <minimal|hardened> to merge selected rules (never removes existing entries). The script reads the canonical deny list from state-templates/deny-patterns.json.

Do NOT include Bash(docker *), Bash(kubectl *), Bash(ssh *) in hatch — these are valid in devops contexts on the host. Docker-setup includes them because the container should not spawn child containers or SSH out.

9a. Sandbox nudge (informational only, no question, no write)

Claude Code ships its own native bash sandbox (sandbox.* settings, bwrap/sandbox-exec) with its own setup command (/sandbox). Hermit does not probe for it or configure it — predicting whether CC's own sandbox spawn will succeed from outside CC is unreliable and previously caused false-positive auto-configuration that broke Bash mid-hatch. This step only prints a one-time pointer; it never writes sandbox.*.

Step:

1. Resolve target settings file using hatch_target (local → .claude/settings.local.json; committed → .claude/settings.json).

2. Branch on deployment:

   If deployment == docker: print a one-line informational note (never a recommendation — recommending an in-container sandbox would push operators toward the Ubuntu 24.04+ AppArmor path where bwrap can't start in-container): "In Docker the container is the isolation boundary (Anthropic-recommended for unattended runs). Claude Code's bash sandbox is off by default; bubblewrap/socat are installed, so /sandbox is available if you want in-container defense-in-depth." No settings write.

   For non-Docker deployments (tmux or interactive), check the target settings file for an already-declared sandbox.enabled key (either value):

   • Not declared: print a one-time recommendation — "Bash sandboxing isn't set up. Claude Code can isolate Bash calls at the OS level — recommended. Run /sandbox to enable it (its Dependencies tab checks bubblewrap/socat for you); docs: https://code.claude.com/docs/en/sandboxing."
   • Already declared: stay silent — the operator already made the call.

No AskUserQuestion — enabling or disabling sandbox.* is entirely the operator's call via /sandbox or by editing their settings file directly.

9b. Persist hatch options

After Steps 6–9 complete, run:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/domain-hatch.ts ensure-target claude-code-hermit --target <local|committed>

with the target chosen in Step 6. The script owns the whole schema: it stamps the five canonical fields on a fresh file, and on an existing one (a domain hatch may have stamped it first) it preserves the original stamped_at/stamped_by and records this run in last_updated_at/last_updated_by. It also repairs a file that exists without a usable target, which the previous file-existence gate left unfixable. Exits non-zero on a failed write; it prints {ok, action, target, path} where action is created, repaired, updated or unchanged.

This file is read by hermit-evolve, docker-setup, and every domain hatch to inherit the operator's target choice without re-running scope detection.

9c. Artifact publish permission

Skip this step entirely if artifacts.dashboard, artifacts.proposals, and artifacts.weekly_review are all false in the config just written (Step 5) — nothing to authorize.

Otherwise, run bun ${CLAUDE_PLUGIN_ROOT}/scripts/apply-settings.ts <resolved-settings-file> artifact-allow (same target-file resolution as Step 8; additive merge, never removes existing entries). This adds Artifact to permissions.allow so unattended sessions never stall on the first-publish permission ask — a headless "ask" is an effective deny, which would otherwise silently no-op every artifact refresh. No prompt: it follows the same opt-out model as the feature itself (default-on, disable any page via /hermit-settings), and rides Claude Code's own governed Artifacts path (org toggle, RBAC, retention, audit log).

Then run bun ${CLAUDE_PLUGIN_ROOT}/scripts/settings-edit.ts .claude-code-hermit/config.json set artifacts.publish_authorized true — this arms hermit-start's boot-time grant (applyArtifactGrant) so the permission stays in place even if the settings file is later wiped or migrated, without ever needing another unattended settings write.

Note to the operator: "Artifact publishing is on — added Artifact to permissions.allow so refreshes from /brief, /weekly-review, /proposal-create, and /proposal-act never prompt. Re-ensured at every boot; revoke with /hermit-settings artifact-authorization (bank first publishes instead). Disable any page via /hermit-settings artifact-dashboard|artifact-proposals|artifact-weekly-review."

---

Domain hatch continuation protocol

When a domain plugin's hatch detects that core is not yet set up, it uses this protocol to resume automatically after core's terminus:

Writer (domain hatch, "yes" branch):

1. Write .claude-code-hermit/state/hatch-resume.json with { "skill": "<domain-slug>:hatch" }.
2. Print one fallback line: "(If setup doesn't continue automatically when core finishes, re-run /<domain>:hatch.)"
3. Invoke /claude-code-hermit:hatch via the Skill tool — terminal action, stop after the call.

Consumer (core terminus — "Resume pending domain hatch" at end of this skill): Read, immediately delete, then invoke the named skill via the Skill tool.

Idempotency and fail-open: The marker is self-consuming (delete-before-invoke). Core's Step 1 keys "already initialized" on config.json, never on the marker, so writing the marker before delegating here cannot trip the reinit prompt. The domain hatch's Step 1/2 re-checks _hermit_versions independently, so a plain manual re-run is always the fallback. Every failure mode (Esc mid-core, core error, un-bumped core) degrades to today's manual behavior. One residual edge: if core is aborted before its terminus, the marker persists and the next core hatch consumes it — surfacing one domain-hatch re-prompt the operator didn't explicitly ask for. That re-prompt is itself idempotent (the domain hatch re-checks state) and Esc-able, so it's a benign annoyance, not a failure — which is why no staleness timestamp is tracked.

5th-domain authors: follow this pattern exactly. Core's terminus handles the return hop.

---

Quick Branch

Replaces Steps 3-4 with batched turns + confirm; resumes shared Steps 5-9 after approval. Same files written, same config.json fields populated, same OPERATOR.md questionnaire, same security gates, same .baseline-pending eligibility — Quick just defaults incidental decisions and shows the resolved bundle before any config writes.

Entry condition: Step 1.6 returned Quick AND is_reinit is false (re-init forces Advanced).

Quick Turn 1 — Hermit activation (conditional)

Only fires if detected_hermits from Step 1.5 is non-empty. Same prompt shape as Step 3 of the Advanced branch — uses the cached candidate list, does not re-glob. If multiple hermits detected, list all + Skip. If none, this turn is skipped entirely.

If a hermit is selected: record the full entry from detected_hermits as activated_hermit (carries plugin, id, marketplace_name, installPath). Read <activated_hermit.installPath>/state-templates/CLAUDE-APPEND.md and stash for Step 6's CLAUDE.md append. Read <activated_hermit.installPath>/.claude-plugin/hermit-meta.json for the hermit.boot_skill field and <activated_hermit.installPath>/.claude-plugin/plugin.json for its version; stash both for Step 5's hatch-config.ts answers payload.

Quick Turn 2 — Identity batch (one AskUserQuestion, 3 questions)

questions: [
  {
    header: "Agent name",
    question: "What should I be called?",
    options: [
      { label: "Atlas" },
      { label: "Hermit" },
      { label: "Skip" }
    ]
  },
  {
    header: "Language",
    question: "Primary language?",
    options: [
      { label: "<auto-detected from Step 1.5> (auto-detected)" },
      { label: "<one common alternative — e.g. en if auto = pt, otherwise pt>" }
    ]
  },
  {
    header: "Timezone",
    question: "Timezone?",
    options: [
      { label: "<auto-detected from Step 1.5> (auto-detected)" },
      { label: "UTC" }
    ]
  }
]

Record agent_name (null if Skip), language, timezone.

Quick Turn 3 — Sign-off + Deployment + Channel + Idle batch

If a name was given in Turn 2, ask 3 questions (with sign-off). Otherwise ask 2 (drop sign-off).

questions: [
  // Conditional — only included if agent_name was set in Turn 2
  {
    header: "Sign-off",
    question: "How should I close messages?",
    options: [
      { label: "{name} out." },
      { label: "-- {initial}." },
      { label: "Skip" }
    ]
  },
  {
    header: "Deployment",
    question: "How will you run hermit?",
    options: [
      { label: "Docker always-on", description: "Recommended. Isolated, auto-restart, channel pairing handled by /docker-setup" },
      { label: "tmux always-on", description: "Persistent on host. Boots via .claude-code-hermit/bin/hermit-start" },
      { label: "Interactive", description: "Just trying it. /session in your terminal" }
    ]
  },
  {
    header: "Channel",
    question: "Notification channel?",
    options: [
      { label: "None" },
      { label: "Discord" },
      { label: "Telegram" }
    ]
  },
  {
    header: "Idle",
    question: "What should hermit do when idle between tasks?",
    options: [
      { label: "Discover", description: "Proactively surface priority/maintenance work (default)" },
      { label: "Wait", description: "Passive — only check for new tasks and messages" }
    ]
  }
]

Record sign_off, deployment (one of docker / tmux / interactive), channel (one of none / discord / telegram), idle_behavior (one of discover / wait).

push_notifications is left at the template default (true) — no follow-up question. Push is dormant whenever a channel is reachable (the runtime guard in CLAUDE-APPEND.md sends channel-first) and fires only as fallback when a channel is unreachable or absent.

Derived values from this turn (used in the confirm bundle and Step 5 overlay):

• permission_mode: auto (same default for both Docker and non-Docker deployments). Generally available to all users across subscription plans and API usage; supported models and provider configuration can vary. If Claude reports it unavailable for the current selection, choose a supported model or run /hermit-settings permissions to select another mode.
• Deny pattern profile: Docker → hardened (default + always_on), else → minimal (default only). Applied at Step 9 silently.
• auto-chain target: see "Quick — auto-chain at end of Step 10" table.

Quick Turn 4 — OPERATOR.md questionnaire (run "5a. OPERATOR.md onboarding" verbatim)

Run the existing "5a. OPERATOR.md onboarding" step verbatim — same scan, same draft, same Phase 3 questions (Call 1 always + Call 2 conditional per the existing skip-condition rules), same Phase 4 scrub. No changes to scan list, draft logic, or question wording. The questionnaire produces a complete OPERATOR.md before the confirm screen so the operator's answers shape the autonomous-mode context the hermit uses immediately.

Quick Turn 5 — Confirm bundle

Render the preview with the script, so what the operator approves is derived from the answers rather than re-typed:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/hatch-report.ts confirm <PROJECT_ROOT> <<'HERMIT_ANSWERS'
{ ...the same answers payload Step 5 will send to hatch-config.ts, plus "deployment", "channel", "plugins", "hatch_target", "git_init" }
HERMIT_ANSWERS

Print its output verbatim. Nothing has been written at this point — the preview says so.

Ask:

questions: [
  {
    header: "Confirm",
    question: "Apply this configuration?",
    options: [
      { label: "Yes", description: "Apply and continue" },
      { label: "Customize", description: "Restart in Advanced (your Quick answers will not carry over)" }
    ]
  }
]

• Customize: jump to Step 3 of the Advanced branch (no prefill — Advanced restarts from scratch). Discard all Quick answers.
• Yes: continue to the shared steps below.

Quick — silent defaults applied to shared steps

Quick replaces Step 4 entirely and applies these defaults silently at the shared Steps 5-9c (no prompts):

| Source | Field | Quick value | |---|---|---| | Advanced Phase 3 equivalent | escalation, remote | template defaults (balanced, true) — don't override | | Advanced Phase 4 equivalent | plugins + scheduled_checks | install all 4; write 3 scheduled_checks entries per Phase 4 mapping | | Advanced Phase 4b equivalent | .baseline-pending marker | same eligibility check as Advanced | | Step 5b | artifact chrome localization | run verbatim — generate the translated table only when language is set and not en; skip silently otherwise | | Advanced Phase 5 equivalent | channels.<name>.* | state_dir + enabled + dm_channel_id=null; omit allowed_users + morning_brief | | Quick Turn 3 idle choice | idle_behavior | set to answer (discover / wait) | | Quick Turn 3 channel choice | push_notifications | template default (true) — don't override | | Advanced Phase 6 equivalent | permission_mode, routines | permission_mode = auto; routines = morning 08:30 + evening 22:30 + (template) heartbeat 04:00 | | Step 6 | CLAUDE.md / CLAUDE.local.md append | apply silently to hatch_target file (default "keep" if marker already present) | | Step 7 | .gitignore append | apply silently (per-line idempotent) | | Step 7a | .worktreeinclude managed block | apply silently (marker-block idempotent — skip if marker already present) | | Step 7.5 | git init (fresh dirs only) | run git init if git_init_eligible; omit otherwise | | Step 8 | plugin permissions (target settings file) | merge silently into hatch_target settings file; also seeds the automode-seed auto-mode exception silently into .claude/settings.local.json (always local, regardless of hatch_target) | | Step 9 | deny patterns (target settings file) | derived profile silently (Docker → hardened, else → minimal); write to hatch_target settings file | | Step 9c | Artifact publish permission | same as Advanced — artifact-allow applied silently (skip entirely if all three artifacts.* are false) and artifacts.publish_authorized set to true in config |

Quick — auto-chain at end of Step 10

Skip this entire auto-chain if .claude-code-hermit/state/hatch-resume.json exists. A domain hatch is pending, and the "Resume pending domain hatch" terminus below will drive continuation instead — the two continuations must never both fire (whichever runs first drops the other). When a marker is present, emit no auto-chain slash command and fall straight through to the terminus.

After Step 10 prints the standard report, output the next slash command on its own line so Claude Code's harness can pick it up and run it. Map from Turn 3's deployment + channel:

| Deployment | Channel | Output | |---|---|---| | Docker | any | /claude-code-hermit:docker-setup quick | | tmux | configured | First print boot command .claude-code-hermit/bin/hermit-start, then /claude-code-hermit:channel-setup | | tmux | none | Print boot command .claude-code-hermit/bin/hermit-start (no skill chain) | | Interactive | configured | /claude-code-hermit:channel-setup, then /claude-code-hermit:session | | Interactive | none | /claude-code-hermit:session |

The quick positional arg passed to docker-setup tells it to skip its setup-mode gate and run Quick directly (same quick arg the operator can use manually). For chained skills with no quick arg (channel-setup, session), they run their normal interactive flows.

Operator can interrupt before the chained skill executes by hitting Esc — at which point they can re-run any of the printed slash commands later.

---

10. Report results

bun ${CLAUDE_PLUGIN_ROOT}/scripts/hatch-report.ts final <PROJECT_ROOT> --deployment <docker|tmux|interactive>

Print its output verbatim. It reads the written config.json, the stamped hatch-options.json, and the filesystem — it takes no file list from this session, because a model-composed report can claim a file was written that the operator declined. Anything it could not observe is reported as absent, and a run that never wrote config.json is reported as an incomplete hatch rather than a success.

--deployment is the one thing it cannot read: Quick Turn 3 asks for it and nothing persists it. On the Advanced branch, pass the deployment the operator described, or interactive if they didn't say.

Quick-mode report adjustment: collapse "Pick how you'll run hermit" to one line confirming Turn 3's deployment + channel, then emit the auto-chain slash command(s) per the mapping in "Quick — auto-chain at end of Step 10". Keep the "Anytime:" block unchanged.

---

Resume pending domain hatch

Applies on both Quick and Advanced paths and is the last action of the skill. On Quick, when a marker is present the Step-10 auto-chain is skipped (see above), so this terminus is the sole continuation — the two never both fire.

1. Attempt to read .claude-code-hermit/state/hatch-resume.json. If the file does not exist or is empty, stop — no domain hatch is pending.
2. Read the skill field (e.g. "laravel-forge-hermit:hatch").
3. Immediately delete .claude-code-hermit/state/hatch-resume.json.
4. Invoke the named skill via the Skill tool to complete domain setup — terminal action, stop after the call.