feat(archdev-skill): install harness hooks from the skill bootstrap through the CLI

[calvin-archastro]

Review on ArchCode

Problem and author intent

ArchDev's contract (read the room, post lifecycle moments, store PR review annotations after every push) reaches an agent in two ways: the archdev skill, and the harness hooks that archdev repo hook setup installs. Before this PR, both depended on something the agent or user had to do first:

user installs skill (npx skills add)          -> skill on disk, hooks not installed
session starts                                -> model decides whether to load the skill
  skill not loaded                            -> no bootstrap, no hooks, no contract
  skill loaded -> bootstrap.sh                -> repo hook setup --refresh
                                                 (updates existing hooks only; a user who never
                                                  ran the Map phase still has none)

Observed: in one operator session the skill was never loaded and about ten PRs went out without review annotations. archdev repo status on that machine reported hooks:claude missing even though ArchDev was installed and logged in.

The broken invariant: once ArchDev is installed for a harness, that harness's sessions (and, in Claude Code, their subagents) should receive the contract without anyone choosing to load a skill or run repo hook setup. This PR is Track 2 of that fix: the skill bootstrap installs hooks for the harness running it.

What changed

Bootstrap installs, not only refreshes (archdev/scripts/bootstrap.sh, bootstrap.ps1)

• Before (main): repo hook setup --refresh, which touches only harnesses that already have ArchDev hooks. A harness with none stays without hooks.
• After: the bootstrap detects the harness from the marker it sets on shells it spawns (CLAUDECODE=1 → claude, CODEX_THREAD_ID → codex, GROK_SESSION_ID → grok) and runs archdev repo hook setup --harness <h>, then repo hook setup --refresh as before. The CLI makes every decision: setup --harness <h> without --force leaves current hooks alone, replaces stale ones, and skips a harness the user removed with --uninstall (recorded in ~/.archdev/hook-opt-out.json). The bootstrap no longer reads any harness config file.
• Inside a Factory worker or daemon pipeline step (ARCHDEV_FACTORY_AGENT_ROLE, ARCHDEV_JOB_ID, or ARCHDEV_STEP_ID set) the bootstrap installs nothing and only refreshes, matching the CLI self-heal's rule that the host owns those sessions' harness config. repo hook setup --harness has no such guard of its own, so the bootstrap carries it.
• Minimum CLI is now 0.46.6 (was 0.46.5) in both scripts, SKILL.md, and references/bootstrap.md. 0.46.6 is the first release with the opt-out record and the self-healing install (firstlanding 0d7743c67d); against 0.46.5, setup --harness <h> would undo a deliberate uninstall. An older CLI is upgraded by the existing bootstrap upgrade path, so the capability probe is gone.
• Failures still print a remediation line (then run: archdev repo hook setup --harness <h>) and never block the skill; stdout is still only the archdev path.

Skill docs (archdev/SKILL.md, references/map.md, references/monitor.md, references/bootstrap.md, README.md)

• The CLI is stated as the single setup path, with the exact commands: install/upgrade the CLI (bootstrap or official installer), archdev setup (first run: login, repo, skills, and hooks for every harness), archdev setup --skills (skills only, via npx skills add ArchAstro/archdev --skill '*' --global --agent <detected>), archdev repo hook setup (every harness), archdev repo hook setup --harness <h> (one harness), and archdev repo status to verify (hooks:<harness> missing/stale).
• Documents that most archdev commands run inside Claude Code or Codex reinstall that harness's missing or stale hooks (not setup, repo hook …, --help/--version, or Factory/daemon sessions), and the opt-out rules: --uninstall records it; full setup, the self-heal, setup --harness, --refresh, and the bootstrap respect it; a bare repo hook setup or --force clears it. repo status still reports an opted-out harness as hooks:<h> missing, and the skill tells the agent not to "fix" that.
• New "Subagents and spawned agents" section in SKILL.md. What the CLI hooks already do (checked against CLI 0.46.8 and firstlanding harnesses.ts): Claude gets SessionStart, UserPromptSubmit, PostToolUse, Stop, SubagentStart, and SubagentStop; Codex gets the first four; Grok gets SessionStart, PostToolUse, Stop. In a Git checkout, repo hook subagent-start injects additionalContext that says "Load the archdev skill now … and follow it", the annotation rule, and "You are a subagent: do not post to the team room." subagent-stop holds the subagent once for a PR head it pushed without annotations. Harnesses without a subagent event (Codex, Grok) and Claude without hooks get nothing in spawned agents, so the section tells the parent to put the instruction in the spawned agent's prompt and to stay responsible for room posts and annotation checks.
• monitor.md still documents the Claude stop and subagent-stop annotation hold; map.md describes the simplified bootstrap and the opt-out semantics.

Unchanged: the skill description's session-start trigger, npx skills add as what archdev setup --skills runs, tasks/scripts/bootstrap.* (still refresh-only), and the CLI itself.

Scope and risk

• Scope: skill scripts, docs, tests, CI in the public distribution repo. No CLI or server code.
• Risk: low to medium. The bootstrap now writes harness config, but only through archdev repo hook setup --harness <h> for the harness running it, which is the same install archdev setup and the CLI self-heal already perform. Raising the minimum to 0.46.6 means bootstrap upgrades 0.46.5 installs on next skill load (the same upgrade path used for every previous minimum bump).

User impact

• A user who loads the archdev skill in Claude Code, Codex, or Grok gets that harness's hooks without running the Map phase; later sessions and Claude subagents get the contract even if they never load the skill.
• README and skill point at archdev setup / archdev repo hook setup as the setup path.

Testing

Canonical end-to-end proof: scripts/test-skill-bootstrap-cli.sh. Actors: the real archdev/scripts/bootstrap.sh, the released archdev CLI on PATH (CI installs the latest release with ./install.sh), and a throwaway HOME per case under env -i. It asserts:

1. With CLAUDECODE=1 and an empty ~/.claude, bootstrap prints only the archdev path and settings.json gets archdev hooks for exactly PostToolUse, SessionStart, Stop, SubagentStart, SubagentStop, UserPromptSubmit (the hooks:claude missing state is fixed).
2. The installed SessionStart and SubagentStart commands, read from settings.json and run in a Git checkout, both print "Load the archdev skill".
3. A second bootstrap leaves settings.json byte-identical.
4. After archdev repo hook setup --uninstall --harness claude, another bootstrap leaves no archdev hooks (opt-out respected).
5. With CLAUDECODE=1 ARCHDEV_FACTORY_AGENT_ROLE=worker, no Claude hooks are written.
6. With CODEX_THREAD_ID, ~/.codex/hooks.json gets PostToolUse, SessionStart, Stop, UserPromptSubmit.

Control: with the bootstrap's install step disabled, 5 of the checks fail. All 8 pass locally against CLI 0.46.8.

Unit-level, fake CLI (scripts/fake-archdev, which records every repo hook setup argv and prints to stdout to catch leaks):

• scripts/test-skill-bootstrap.sh (10 checks) and scripts/test-skill-bootstrap.ps1 (9 cases): Claude/Codex/Grok markers → setup --harness <h> then --refresh; CLAUDECODE=0, no marker, and each of ARCHDEV_FACTORY_AGENT_ROLE / ARCHDEV_JOB_ID / ARCHDEV_STEP_ID → --refresh only; failing setup → bootstrap exits 0, still refreshes, prints the path, and (bash) names the remediation command. Every case requires stdout to be exactly the archdev path. Control: with the install step disabled, both suites fail. Both pass locally (PowerShell 7.6.6 on Linux).
• Also ran bootstrap.ps1 under pwsh against real CLI 0.46.8 with CLAUDECODE=1: all six Claude hook events installed, stdout only the path.
• bash -n on every script.

CI: workflow Skill Bootstrap Checks (.github/workflows/skill-bootstrap-checks.yml), on every PR and push to main. Jobs: skill-bootstrap (bash and pwsh fake-CLI suites on ubuntu), skill-bootstrap-windows (PowerShell suite under Windows PowerShell 5.1 with the fake CLI via Git Bash), and skill-bootstrap-cli (latest release + scripts/test-skill-bootstrap-cli.sh). The Windows PowerShell 5.1 job was not run locally. An independent review pass found the Factory/daemon install, the opt-out remediation loop in the docs, and several overstated doc claims; all are fixed here.

Follow-ups and known issues

• The CLI still carries unused Claude plugin detection from firstlanding 0d7743c67d; ArchAstro/firstlanding#15536 removes it. No ArchDev plugin was ever released, so nothing depends on it.
• A user who ran repo hook setup --uninstall on 0.46.5 or earlier has no opt-out record, so the first bootstrap after upgrading reinstalls their hooks. repo hook setup --uninstall --harness <h> on 0.46.6+ records it.
• Grok detection uses GROK_SESSION_ID, which Grok documents for hook processes; that it is also set in the shell tool's environment is unverified. A missed detection falls back to --refresh.
• CI runs the real-CLI suite against the latest release, not pinned 0.46.6, so the 0.46.6 floor is taken from the release history (0.46.5 lacks the opt-out record; 0.46.6 contains firstlanding 0d7743c67d).
• The bootstrap does not detect Pi (--harness pi is documented for manual setup).
• archdev repo status reports an opted-out harness as missing with a remediation that a bare repo hook setup would apply; a distinct opted-out state belongs in the CLI (firstlanding).
• Codex and Grok have no subagent hook event, so spawned agents there rely on the parent's prompt (documented in SKILL.md).
• tasks/scripts/bootstrap.sh|ps1 still only refresh.

🤖 Generated with Claude Code