Install adept in non-marketplace coding agents (Bob, Gemini CLI, Copilot, Cursor, OpenCode) #482

Problem

adept installs only through the Claude Code and Codex plugin marketplaces. Five other
coding agents a user may run adept under — IBM Bob, Gemini CLI, GitHub Copilot, Cursor,
and OpenCode — have no adept marketplace path, so their users must hand-place files whose
required layout is recorded only for Bob (docs/bob-install-requirements.md, #478/#479).
Hand placement is error-prone: the skills need references/, sibling skills, and the
root-level scripts/check-public-safety.sh beyond their own folders
(docs/bob-install-requirements.md §1), and scripts disagree on <plugin root> under a
symlink install (§2: skills/deliver/scripts/deliver-write:4 resolves logically,
skills/return-to-town/scripts/publish-handoff:48 physically).

Policy currently forbids the fix: ADR 0001 (docs/adr/0001-distribution-via-plugin-marketplace.md)
gives install to the harness, and .claude/CLAUDE.md:7 / README.md:52 say "There is no
install script and there will not be one." The 2026-08-11 separation plan records "Bob is
retired" (docs/workflow/plans/2026-08-11-adept-dotfiles-separation.md:18). ADR 0006
(docs/adr/0006-release-management-out-of-scope.md) notes the repository has no tag and no
release, so nothing pinnable exists to download.

Goals

1. One verified install-requirements document per non-marketplace agent, sharing an
   agent-neutral core so the file-tree and root-resolution facts live in one place.
2. An ADR that decides — on the documents' evidence — whether and how adept ships an
   installer for non-marketplace agents, superseding ADR 0001's "no install script"
   clause and the "Bob is retired" note if it does.
3. A v<version> git tag on every verified push to main, matching
   .claude-plugin/plugin.json.
4. A curl … | bash installer that installs and updates adept for Bob, Gemini CLI,
   Copilot, Cursor, and OpenCode from a tag tarball.

Non-goals

• Changing the Claude Code or Codex install path; marketplace users never run the installer.
• An uninstall verb (removal is a documented manual step).
• Merging or editing any agent's configuration files (settings, rules, MCP config). The
  ADR 0001 failure class was the config-merge layer; the installer only copies files —
  into skill directories plus the root-level references/ and scripts/ paths
  <plugin root> requires (Bob doc §1) — and owns them file-by-file through a manifest.
• Symlink installs (ADR 0001 rejected symlinking a checkout; §2 of the Bob doc shows it
  splits <plugin root>).
• GitHub Release objects, release notes, or checksum assets — tags only.
• Fixing the logical-vs-physical cd disagreement in the skill scripts (a copy install
  makes it moot; report separately if needed).

Requirements

• R1. Each agent document marks every claim verified / documented / unverified with the
  environment, as the Bob doc does, and answers for that agent: skill directory locations
  (global and project scope), discovery format (does it read SKILL.md frontmatter
  name/description), whether supporting files beside SKILL.md are readable, reload
  behaviour, name-collision precedence, how <plugin root> is supplied or derived, what
  <plugin root> (two levels above a skill directory) is at each scope and whether its
  references/ and scripts/ siblings collide with paths users commonly own there (e.g.
  .github/scripts/ for a Copilot project install), and which adept features have no
  equivalent there. An agent with more than one surface (Copilot CLI vs VS Code agent
  mode) answers per surface.
• R2. Each agent document lists that agent's documented built-in command names, and the same
  PR adds them to scripts/reserved-skill-names.txt with source and retrieval date, matching
  the file's existing per-client header. scripts/check-skill-shape.sh rule 3 (:205-216)
  fails on any collision with a skill name, so a collision does not ship in the doc PR: it
  blocks that PR and is filed as its own rename issue (MAJOR bump), or the ADR drops the
  target. Items 2–5 all edit this file and merge serially.
• R3. The ADR records: the target list; copy-only install; the install root per target and
  scope, including the root-level references/ and scripts/ paths; how update identifies
  adept-owned files (a versioned placed-paths manifest) so it can replace them, remove files
  deleted upstream, and never touch user content; behaviour when any target path already
  holds non-adept content (refuse, not overwrite); where the script lives and the
  anatomy-rule-2 argument for it; which ref the documented install.sh URL uses and how
  installer and payload stay the same version (e.g. the bootstrap re-execs the installer
  from the fetched tarball); the integrity stance for curl | bash; and tagging adept's own
  repository, amending ADR 0006's "no tag" context. The ADR's own PR makes the matching
  edits so no doc states a reversed policy: .claude/CLAUDE.md:7, README.md:52, Bob doc
  §7, and the supersession banner on ADR 0001 that docs/adr/README.md:17-18 prescribes.
• R4. The tag workflow tags the pushed head of main (github.sha; a rebase merge pushes
  several commits and no merge commit) as v<version> from .claude-plugin/plugin.json,
  only after the Verify workflow succeeds for that sha; is idempotent on re-run; fails
  loudly if the tag exists at a different commit; and passes the repo's actions-check
  gate (actionlint + zizmor) with least-privilege permissions.
• R5. The installer: bash 3.2, set -euo pipefail, needs only curl and tar; fetches
  refs/tags/v<version> (default: latest tag, --version to pin); --target and
  --scope global|project; prints every path it writes; is idempotent; runs and exits
  (anatomy rule 3); is linted by just lint and covered by a suite under scripts/ or
  tests/ that runs offline against a local tarball fixture. README documents it in the
  same PR (no phantom features).

Success criteria

• docs/ holds an agent-neutral requirements doc plus one doc each for Bob, Gemini CLI,
  Copilot, Cursor, and OpenCode, with no fact duplicated between the core and an agent doc.
• A merged ADR either authorizes the installer or records why not (the latter closes items
  7, 8, and 9 as not-planned).
• After a push to main and a green Verify run, git ls-remote --tags origin v<version>
  returns the pushed head of main.
• On a clean macOS host and an ubuntu host, curl -fsSL <documented url> | bash -s -- --target <t> produces the tree the target's doc specifies, and a re-run after a version
  bump updates it, for every target; just verify stays green.

Decomposition

1. Extract agent-neutral install requirements from the Bob doc #483 — Extract agent-neutral install requirements from the Bob doc — Bob doc §1 (file tree),
   §2 (<plugin root> under copy vs symlink), and the non-Bob half of §6 are true for every
   non-marketplace agent; five copies would drift. Move them to an agent-neutral doc under
   docs/ and leave Bob-specific §3, §4, §5, §7 in docs/bob-install-requirements.md,
   linking the core. Seam: docs/bob-install-requirements.md is the only existing source.
   No dependencies.
2. Document Gemini CLI install requirements #484 — Document Gemini CLI install requirements — R1/R2 for Gemini CLI. Seam: new agent doc
   linking the core; scripts/reserved-skill-names.txt:1-15 header pattern for R2.
   Blocked by 1.
3. Document GitHub Copilot install requirements #485 — Document GitHub Copilot install requirements — R1/R2 per surface (CLI, VS Code agent
   mode). Same seam. Blocked by 1.
4. Document Cursor install requirements #486 — Document Cursor install requirements — R1/R2. Same seam. Blocked by 1.
5. Document OpenCode install requirements #487 — Document OpenCode install requirements — R1/R2. Same seam. Blocked by 1.
   Items 2–5 share scripts/reserved-skill-names.txt (R2) and merge one at a time.
6. ADR: installer for non-marketplace agents #488 — ADR: installer for non-marketplace agents — R3. Partially supersedes ADR 0001's
   Decision ("The harness owns install…") and Consequences (install.sh "has no
   successor") for non-marketplace targets only; reverses the "Bob is retired" plan note
   (docs/workflow/plans/2026-08-11-adept-dotfiles-separation.md:18); amends ADR 0006's
   "no tag" context; makes the R3 doc edits. ADRs are append-only once merged, so this is a
   new record plus the banner on 0001 that docs/adr/README.md:17-18 permits. Blocked by
   2, 3, 4, 5 (the decision rests on their findings).
7. Tag v<version> on every verified push to main #489 — Tag v<version> on every verified push to main — R4. Seam: new workflow triggered
   after .github/workflows/verify.yml (which runs on push: main with contents: read);
   version source .claude-plugin/plugin.json:3 per ADR 0022. Blocked by 6, and closed
   not-planned if 6 declines the installer — tags have no other consumer.
8. Installer core with the Bob target #490 — Installer core with the Bob target — R5 for Bob only, plus README install section.
   Bob first because its requirements are the most complete (Document IBM Bob install requirements as the basis for a Bob installer #478). Seam: Justfile lint
   recipe discovers shell via scripts/list-shell-sources.sh; suites sit beside their
   scripts under scripts/. Blocked by 6, 7.
9. Add Gemini CLI, Copilot, Cursor, and OpenCode installer targets #491 — Add Gemini CLI, Copilot, Cursor, and OpenCode installer targets — per-target layout
   from each doc, suite cases per target, README rows. Blocked by 2, 3, 4, 5, 8.

Open questions

• Does each agent read the shared Agent Skills SKILL.md format directly, or need a
  translation (e.g. Cursor rules)? A target needing translation is out of a copy-only
  installer; the ADR (6) drops it from the target list and its doc records why.
• Project-scope installs write into the user's repository (.bob/, .github/, …): does
  the installer support project scope for every target, or global only where a target
  offers it?
• Integrity (decided in 6): tag tarballs from github.com over HTTPS carry no checksum;
  is that acceptable for curl | bash?