diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 66e9f89..bc959ef 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "adept", - "version": "7.12.2", + "version": "7.12.3", "icon": "docs/assets/adept-logo-grimoire.png", "description": "Development-workflow skills: design, TDD, adversarial review, shipping, and campaign orchestration for Claude Code and Codex.", "author": { diff --git a/docs/bob-install-requirements.md b/docs/bob-install-requirements.md new file mode 100644 index 0000000..2d1a403 --- /dev/null +++ b/docs/bob-install-requirements.md @@ -0,0 +1,206 @@ +# IBM Bob install requirements + +This document records what a Bob user must supply to make adept skills work, and what +open decisions block a future installer. Each claim is marked with one of three markers: + +- **verified** — confirmed by static inspection of this repository (source code, documentation). + Environment: macOS arm64, 2026-10-29, no live Bob session. +- **documented** — stated in Bob's published documentation but not tested against a live Bob + instance in this run. +- **unverified** — neither tested against a live Bob instance nor documented by IBM. + Behaviour is inferred from repository source or logical inference. + +Related: issue #478, ADR 0001 (`docs/adr/0001-distribution-via-plugin-marketplace.md`). + +--- + +## 1. Minimum file tree + +A Bob install must produce the following tree for adept skills to work. + +### Global install (`~/.bob/skills/`) + +``` +~/.bob/ +├── skills/ +│ ├── attunement/ # all files from skills/attunement/ +│ ├── bounty/ +│ ├── campaign/ +│ ├── … (one directory per skill) … +│ └── quest/ +├── references/ # files from references/ at repo root +│ ├── dispatch-liveness.md +│ ├── heed-counsel.md +│ ├── merge-gate.md +│ ├── model-mapping.md +│ ├── model-selection.md +│ ├── network-bounds.md +│ ├── numbered-reservations.md +│ ├── review-depth.md +│ ├── review-lenses.md +│ ├── trial-by-fire.md +│ └── true-seeing.md +└── scripts/ + └── check-public-safety.sh # root-level wrapper +``` + +**Note on `scripts/check-public-safety.sh`:** **verified** — this file +(`scripts/check-public-safety.sh:4,11`) resolves `ROOT` as the directory two levels above +itself and then `exec`s `$ROOT/skills/quest/scripts/check-public-safety "$@"`. A Bob install +that copies only the `skills/` tree will not have this wrapper and will not have the inner +scanner. A full tree copy is required. The inner scanner lives at +`skills/quest/scripts/check-public-safety`. + +**Note on `references/` location:** **verified** — every script that addresses shared +standards uses a path like `../../references/` relative to a skill's own subdirectory +(e.g. `skills/quest/SKILL.md:57`, `skills/forge/SKILL.md:239`). The directory must be a +sibling of `skills/`, not nested inside it. + +### Project install (`/.bob/skills/`) + +Same tree as the global install, but rooted at `/.bob/` instead of `~/.bob/`. Bob's +skill location docs state that project skills take precedence over global ones on name +collision (see §5 below), so a project install can shadow a global one. + +--- + +## 2. `` resolution: copy install vs symlink install + +The `` convention is defined in skill text as "the directory two levels above +this skill's own directory" (e.g. `skills/attunement/SKILL.md:33–36`). Scripts resolve it at +runtime using `$BASH_SOURCE[0]`. + +**Copy install** (all files copied into `~/.bob/`): **verified** — all scripts resolve +ROOT correctly because the physical directory three levels up from any script is the copy +root. Both logical (`cd --`) and physical (`cd -P`) resolution agree when no symlinks are +present. + +**Symlink install** (skill directories symlinked into `~/.bob/skills/`): +**unverified** — behaviour depends on whether each script uses logical or physical `cd`: + +| Script | Resolution | ROOT under a symlink install | +|--------|-----------|------------------------------| +| `skills/deliver/scripts/deliver-write` | logical (`cd -- "$SCRIPT_DIR/../../.."`) | Resolves to `~/.bob/` (the directory containing `skills/`) | +| `skills/return-to-town/scripts/publish-handoff` | physical (`cd -P -- "$SCRIPT_DIR/../../.."`) | Resolves to the physical checkout | +| `skills/return-to-town/scripts/refresh-merge` | physical (`cd -P -- "$SCRIPT_DIR/../../.."`) | Resolves to the physical checkout | +| `skills/quest/scripts/publish-forge-review` | logical (`cd "$SCRIPT_DIR"`) then `../../..` | Resolves to `~/.bob/` | +| `skills/bounty/scripts/create-verified-issue.sh` | physical (`pwd -P`) | Resolves to the physical checkout | + +The issue body (`Evidence: Symlink sensitivity`) reported a measurement on macOS arm64 +(not re-run in this review) confirming the table's split result: logical-`cd` scripts +resolve ROOT to `~/.bob/`, while physical-`cd` scripts resolve it to the checkout. The +scripts therefore disagree with each other. A logical-`cd` script expects to find +`references/` and `scripts/check-public-safety.sh` inside `~/.bob/`; a physical-`cd` script +expects them in the checkout. Neither assumption holds for both script types simultaneously. + +**Supported path:** A copy install (no symlinks) is the only configuration where all +scripts agree on ROOT. A symlink install requires additional work (e.g. a symlink forest in +`~/.bob/` that mirrors `references/` and `scripts/`) to satisfy both; this work has not been +done. + +--- + +## 3. Symlink following and reload behaviour + +**Symlinks (IDE and Shell):** **unverified** — Bob Shell's sandboxing docs state that +"symlinks pointing outside the project directory may not work correctly" (sandboxing page, +File system limitations). Bob IDE has no separately documented sandboxing rule for skill +directories. Whether a symlinked `~/.bob/skills/` directory is followed when loading +skill content is not confirmed for either surface. + +**Reload:** **unverified** — the Bob IDE skills documentation states that "Skills load once +per conversation to avoid duplicate prompts." Whether newly added skill directories appear +without restarting Bob (IDE or Shell) is not documented. Best practice assumption: open a +new conversation or restart Bob after placing new skill directories. + +--- + +## 4. How a skill's directory is named to the model + +**documented (Bob documentation):** The `name` field in `SKILL.md` frontmatter is "the +skill's display name used in the Bob interface." The `use_skill` tool takes a `skill_name` +parameter; Bob matches it against this `name` field. + +**unverified:** Whether the directory name under `~/.bob/skills/` affects resolution (vs the +`name` field) is inferred, not confirmed by Bob documentation. Each adept skill already sets +a `name` field matching its directory name (e.g. `name: attunement`), so this ambiguity +does not affect adept in practice. + +**Harness naming at load time:** **verified** — skills refer to a `` that +"the harness names when it loads the skill" (e.g. `skills/attunement/SKILL.md:35–36`, +`skills/quest/SKILL.md:174–175`). Under Claude Code, the harness injects the plugin cache +path as this root. **unverified** — under Bob, whether an equivalent injection exists is not +documented; if it does not, ROOT derivation falls to the `cd`-based resolution in §2. + +--- + +## 5. Collision and idempotency rules + +**Priority:** **documented (Bob documentation)** — if both `/.bob/skills/` and +`~/.bob/skills/` contain a skill with the same `name` field, the project-level skill takes +precedence. Since adept's skill names are unique within the repository but not globally +reserved, a user with a pre-existing skill using the same name would have it silently shadowed +(global → project) or shadow adept's copy (project pre-existing → new global install). + +**Pre-existing content and update semantics:** **unverified** — no documentation describes +what happens if `~/.bob/skills/` already exists, if `~/.bob/references/` already contains +user-authored files, or what "re-run after an update" means (overwrite, merge, skip). A +copy-based install would need to address all three. None has been tested. + +--- + +## 6. adept features with no Bob equivalent + +The following adept capabilities are Claude Code– and Codex-specific and have no Bob +equivalent at the time of writing: + +| Feature | adept location | Bob status | +|---------|---------------|-----------| +| `$name` invocation shorthand (e.g. `$quest`) | Skill descriptions reference these as shorthand used by Claude Code / Codex operators | **unverified** — Bob has slash commands but adept's skills are invoked via `use_skill`; the `$name` shorthand is a Codex agent convention, not a Bob convention | +| `agents/openai.yaml` per-skill worker manifests | `skills/*/agents/openai.yaml` (22 skills) | **documented** — Bob has no feature for per-skill worker manifests; these files are Codex CLI-specific (Bob docs describe no equivalent) | +| Skills plugin marketplace | `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json` | **documented** — Bob's marketplace covers MCP servers and modes, not skills; adept skills must be placed manually | +| Version field | `.claude-plugin/plugin.json` (via ADR 0022) | **verified** — not relevant to Bob install | + +**`agents/openai.yaml` detail:** Each file provides a Codex CLI interface definition (display +name, short description, default prompt) used when a skill is invoked as an OpenAI Codex +agent. Bob does not read these files. A Bob install does not need to place them, but +including them as part of a full-tree copy is harmless. + +--- + +## 7. Open decisions blocking an installer + +Two existing records conflict with writing a Bob installer: + +### ADR 0001 — Distribution via a plugin marketplace + +`docs/adr/0001-distribution-via-plugin-marketplace.md` (Accepted 2026-08-11) records +that the harness owns "install, update, uninstall, caching, and version resolution" and +that `install.sh` (1,337 lines) has no successor. `.claude/CLAUDE.md:7` restates this as +"There is no install script and there will not be one." + +This decision was made in the context of Claude Code and Codex. It did not anticipate a +Bob user who must hand-place files. A new ADR would need to supersede or amend this +decision before an install script targeting Bob could be added to this repository. + +### Plan note — "Bob is retired" (2026-08-11) + +`docs/workflow/plans/2026-08-11-adept-dotfiles-separation.md:18` states: +> "Bob is retired. Task 9 is skipped in full; nothing under `$OLD/agents/bob/` is +> carried into either new repo, and Bob-related issues close as obsolete in Task 11." + +Line 967 of the same plan carries the section heading "SKIPPED (Bob retired 2026-08-11)." +Line 969 records that "Bob is retired, `~/.bob` does not exist on this machine, and no Bob +deployment manifest is present." Line 979 records that Bob "has no plugin system" and +describes a clone-plus-symlink approach that was planned but never executed. + +### Resolution required + +An installer cannot be written and reviewed until either: +1. An ADR supersedes the "no install script" clause of ADR 0001 for the Bob target, **and** +2. The project explicitly reverses the "Bob is retired" decision, opening Bob as a + supported target. + +This document records the requirements and constraints; it does not resolve these +decisions. See issue #478 for the proposed approach: file the installer as a separate +follow-up only after these decisions are made. diff --git a/docs/workflow/specs/478-bob-install-requirements.md b/docs/workflow/specs/478-bob-install-requirements.md new file mode 100644 index 0000000..2398f2d --- /dev/null +++ b/docs/workflow/specs/478-bob-install-requirements.md @@ -0,0 +1,40 @@ +# Light Spec: Bob Install Requirements Document (issue #478) + +## Problem + +adept has no written record of what a Bob user must supply to make its skills work. +The skills depend on a `` layout that the Claude Code and Codex harnesses provide +automatically; Bob has no equivalent plugin system, so the layout must be hand-supplied and is +currently undocumented. An installer cannot be specified or reviewed until these requirements +are written down and verified. + +## Scope + +One new file (`docs/bob-install-requirements.md`) plus the mandatory `plugin.json` version +bump (ADR 0022). Not in scope: writing an installer, resolving the ADR 0001 / "Bob is +retired" contradiction, or live Bob environment verification. + +## Success + +`docs/bob-install-requirements.md` exists and covers all seven items from issue #478 §Expected: +1. Minimum file tree for global (`~/.bob`) and project (`.bob`) scope, including `references/` + and `scripts/check-public-safety.sh`. +2. `` resolution for copy vs symlink install, per script, with supported path stated. +3. Whether Bob IDE and Bob Shell follow symlinked skill folders; reload behavior. +4. How a skill's directory is named to the model under Bob. +5. Collision and idempotency rules for pre-existing content and re-runs. +6. adept features with no Bob equivalent (slash-command syntax, `agents/openai.yaml`). +7. Open decisions blocking an installer (ADR 0001 conflict, "Bob is retired" plan note). + +Each claim carries a `verified` or `unverified` marker and the environment it was checked in. + +## Validation + +- `docs/bob-install-requirements.md` exists and is tracked by git. +- All seven items from the issue appear in the document. +- Every factual claim carries a verification marker. +- `just verify` passes (lint, test, records, shape). + +## Failure model + +N/A — this is a documentation-only change. No executable failure model applies.