From 0952ea35e96319efde36ac00ca3987a10d0ca9c9 Mon Sep 17 00:00:00 2001 From: David Christensen Date: Fri, 30 Oct 2026 11:15:56 -0400 Subject: [PATCH 1/3] docs: extract agent-neutral install requirements from the Bob doc Move the minimum file tree, resolution, and the adept-side half of the Claude Code/Codex-only feature table into docs/agent-install-requirements.md, written against . The Bob doc keeps its install root, sections 3-5 and 7, and the Bob column of section 6, and links the core for the rest. Refs #483 --- docs/agent-install-requirements.md | 125 +++++++++++++++++++++++++++++ docs/bob-install-requirements.md | 122 +++++++--------------------- 2 files changed, 152 insertions(+), 95 deletions(-) create mode 100644 docs/agent-install-requirements.md diff --git a/docs/agent-install-requirements.md b/docs/agent-install-requirements.md new file mode 100644 index 0000000..5951d93 --- /dev/null +++ b/docs/agent-install-requirements.md @@ -0,0 +1,125 @@ +# Agent-neutral install requirements + +This document records what any coding agent without an adept plugin marketplace must be +given for adept skills to work: the file tree, how `` resolves, and which adept +features exist only for Claude Code and Codex. Each agent's own document links here and +records only what is specific to that agent, starting with its install root. 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 the agent's published documentation but not tested against a live + instance in this run. +- **unverified** — neither tested against a live instance nor documented by the agent's vendor. + Behaviour is inferred from repository source or logical inference. + +`` is the directory that holds the agent's `skills/` directory — for example +`~/./` for a global install, or `/./` for a project install. Each agent +document names its own. + +Agent documents: [IBM Bob](bob-install-requirements.md). + +Related: issue #478, ADR 0001 (`docs/adr/0001-distribution-via-plugin-marketplace.md`). + +--- + +## 1. Minimum file tree + +An install must produce the following tree for adept skills to work. + +### Global install (`~/./skills/`) + +``` + +├── 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 "$@"`. An 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 (`/./skills/`) + +Same tree as the global install, but rooted at `/./` instead of `~/./`. + +--- + +## 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 ``): **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 `/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 `` (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 `` | +| `skills/bounty/scripts/create-verified-issue.sh` | physical (`pwd -P`) | Resolves to the physical checkout | + +Issue #478's 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 ``, 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 ``; 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 +`` that mirrors `references/` and `scripts/`) to satisfy both; this work has not +been done. + +--- + +## 3. adept features specific to Claude Code and Codex + +The following adept capabilities are Claude Code– and Codex-specific. Each agent document +records whether that agent has an equivalent. + +| Feature | adept location | +|---------|---------------| +| `$name` invocation shorthand (e.g. `$quest`) | Skill descriptions reference these as shorthand used by Claude Code / Codex operators | +| `agents/openai.yaml` per-skill worker manifests | `skills/*/agents/openai.yaml` (22 skills) | +| Skills plugin marketplace | `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json` | +| Version field | `.claude-plugin/plugin.json` (via ADR 0022) | + +**`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. diff --git a/docs/bob-install-requirements.md b/docs/bob-install-requirements.md index 2d1a403..1f2bb37 100644 --- a/docs/bob-install-requirements.md +++ b/docs/bob-install-requirements.md @@ -1,102 +1,23 @@ # 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. +open decisions block a future installer. The requirements every non-marketplace agent shares +— the minimum file tree, `` resolution, and the adept features specific to +Claude Code and Codex — are in [Agent-neutral install requirements](agent-install-requirements.md), +which also defines the **verified**, **documented**, and **unverified** markers used here. 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. +## 1–2. Install root -**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. +Bob's `` is `~/.bob/` for a global install (`~/.bob/skills/`) and +`/.bob/` for a project install (`/.bob/skills/`). Both take the tree in +[§1](agent-install-requirements.md#1-minimum-file-tree) of the agent-neutral document, and +ROOT resolves as its [§2](agent-install-requirements.md#2-plugin-root-resolution-copy-install-vs-symlink-install) +describes. 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. --- @@ -130,7 +51,8 @@ does not affect adept in practice. "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. +documented; if it does not, ROOT derivation falls to the `cd`-based resolution in +[agent-neutral §2](agent-install-requirements.md#2-plugin-root-resolution-copy-install-vs-symlink-install). --- @@ -151,11 +73,21 @@ 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: +The adept capabilities specific to Claude Code and Codex +([agent-neutral §3](agent-install-requirements.md#3-adept-features-specific-to-claude-code-and-codex)) +have no Bob equivalent at the time of writing: + +| Feature | Bob status | +|---------|-----------| +| `$name` invocation shorthand (e.g. `$quest`) | **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 | **documented** — Bob has no feature for per-skill worker manifests (Bob docs describe no equivalent) | +| Skills plugin marketplace | **documented** — Bob's marketplace covers MCP servers and modes, not skills; adept skills must be placed manually | +| Version field | **verified** — not relevant to Bob install | + +**`agents/openai.yaml` detail:** 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. -| 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 | From ac19d6ba23d09f8554af131830f4f3470bbcdf18 Mon Sep 17 00:00:00 2001 From: David Christensen Date: Fri, 30 Oct 2026 11:16:08 -0400 Subject: [PATCH 2/3] chore: bump plugin version to 7.12.5 Refs #483 --- .claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 4754341..04610a3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "adept", - "version": "7.12.4", + "version": "7.12.5", "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": { From 24cb65c6e91e73dd6a25e41c0d796279629c4eea Mon Sep 17 00:00:00 2001 From: David Christensen Date: Fri, 30 Oct 2026 11:19:13 -0400 Subject: [PATCH 3/3] docs: drop leftover old feature table from the Bob doc Refs #483 --- docs/bob-install-requirements.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/bob-install-requirements.md b/docs/bob-install-requirements.md index 1f2bb37..b0bd843 100644 --- a/docs/bob-install-requirements.md +++ b/docs/bob-install-requirements.md @@ -87,17 +87,6 @@ have no Bob equivalent at the time of writing: **`agents/openai.yaml` detail:** 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. ----------|---------------|-----------| -| `$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