Describe repository hook setup as detecting harnesses; test that contract

[calvin-archastro]

Problem

"Skill bootstrap with the released CLI" and "Explicit placement with the released CLI (Windows)" fail on main. The last green run was 2026-10-08, and #64 (shots skill) inherits the failure.

scripts/test-skill-bootstrap-cli.sh
  archdev repo hook setup --local          # clean runner, no coding agents installed
  → claude: installed, archdev: installed
  → codex / gemini / grok / pi: absent
  assert .codex/hooks.json .grok/hooks/archdev.json .pi/extensions/archdev.js exist → FAIL

This isn't a CLI bug. firstlanding #17487 (CLI 0.50.1) deliberately changed archdev setup and repo hook setup to configure only the agents they detect, plus ArchDev itself. Detection means the harness's user config directory exists or, for repository setup, its directory is already in the repo. --harness <names> selects specific agents, and --all-harnesses restores the install-everything behavior. The TS and Rust CLIs behave the same (checked against tag archdev-ts-final).

The skill still told agents that repository setup "prepares Claude Code, Codex, Grok, Pi, and ArchDev, even before those tools are installed", and the bootstrap scripts asserted exactly that.

What changed

• archdev/SKILL.md ("Scoped hook installation and repair") and archdev/references/map.md now describe the real behavior:
  • Both scopes set up ArchDev plus the detected harnesses.
  • Use --harness claude codex when the user picks tools.
  • Use --all-harnesses (CLI 0.50.1+) to prepare every supported harness for teammates who use other tools.
  • The Gemini path .agents/hooks.json is listed.
• Plugin copies under plugins/*/skills/archdev/ were regenerated with tools/plugin-gen npm run build, with no hand edits.
• scripts/test-skill-bootstrap-cli.sh / .ps1 test both commands the skill names:
  • Plain archdev --json repo hook setup --local installs claude and archdev, reports codex/grok/pi as absent, and creates no .codex, .grok, .pi or .agents directories.
  • repo hook setup --local --all-harnesses writes all five files.
  • In both cases HOME is unchanged and no .claude/settings.local.json appears.
• Flake fix: both snapshot helpers ignore .archdev/hooks/<hash>/queue/. A background worker drains queued hook events on its own schedule, and 1 of 6 runs of the original script failed a HOME byte-comparison on such a file.

Testing

• Released v0.52.1 (installed with this repo's install.sh):
  • The unmodified test-skill-bootstrap-cli.sh reproduces the CI failure.
  • The new one passes 8/8 runs.
  • scripts/test-skill-bootstrap.sh passes.
• tools/plugin-gen: npm run check (124 files match), npm run typecheck and npm test (62/62) pass.
• The .ps1 was not run locally because PowerShell isn't available. Its new step follows the Windows CI log of run 38412532179 (claude installed; codex/grok/pi absent). This PR's Windows job is its first real run.

Follow-ups

• The skill bootstraps still accept CLI 0.49.6+, where --all-harnesses doesn't exist; the text marks it as 0.50.1+. Raising min_version is a separate decision.
• Check that https://archdev.ai/install.md doesn't make the same "all harnesses" promise for repository placement.

🤖 Generated with Claude Code