|
| 1 | +# agentic-coding-playbook (acq mixin kit, `hybrid/v1`) |
| 2 | + |
| 3 | +A neutral [`acq`](https://github.com/GSA-TTS/agentic-coding-quickstart) **mixin |
| 4 | +kit** that delivers the GSA |
| 5 | +[agentic-coding-playbook](https://github.com/GSA-TTS/agentic-coding-playbook) — |
| 6 | +the federal `AGENTS.md` rules and the Agent Skills — into a sandbox. |
| 7 | + |
| 8 | +> **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` |
| 9 | +> form consumed by `acq`, which selects an isolation backend (`sbx` today; `msb` |
| 10 | +> from Phase 2). It replaces the former `sbx-kits/playbook-kit/` sbx-only spec. |
| 11 | +> See [backend parity](#backend-parity) and |
| 12 | +> [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). |
| 13 | +
|
| 14 | +The kit ships one small script. At container **startup** it: |
| 15 | + |
| 16 | +1. clones the playbook at a pinned ref into `~/.agentic-coding-playbook`, then |
| 17 | +2. symlinks the playbook's `AGENTS.md` and skills into each supported agent's |
| 18 | + search paths. |
| 19 | + |
| 20 | +Clone-at-startup (rather than vendoring the playbook into the kit's `files/`) |
| 21 | +keeps the kit tiny and lets the playbook version be pinned and bumped |
| 22 | +independently. See [Failure behavior](#failure-behavior) for how it degrades |
| 23 | +when the clone can't run. |
| 24 | + |
| 25 | +## Backend parity |
| 26 | + |
| 27 | +All backends use the **same** mechanism: allow-list `github.com` / |
| 28 | +`codeload.github.com` and run the same clone+link script |
| 29 | +(`files/home/playbook-clone.sh`) at startup. No backend shortcut. The GitHub |
| 30 | +token needed while the playbook repo is private is injected by the active |
| 31 | +backend on the outbound clone (see [Prerequisites](#prerequisites)); the kit |
| 32 | +never holds it. Behavioral parity: the playbook's `AGENTS.md` + skills end up |
| 33 | +linked into the agent search paths on every backend. |
| 34 | + |
| 35 | +## Usage |
| 36 | + |
| 37 | +```bash |
| 38 | +acq run opencode /path/to/project # acq applies the pinned kits, incl. this one |
| 39 | +``` |
| 40 | + |
| 41 | +The kit is a `mixin`, so it composes with the other acq-kits. |
| 42 | + |
| 43 | +## Prerequisites |
| 44 | + |
| 45 | +While the playbook repo is **private**, the clone needs a GitHub token. This kit |
| 46 | +does **not** declare its own `github` credential — the base agent sandbox |
| 47 | +already provides one, and `acq`'s backend injects it on the outbound clone (the |
| 48 | +container never sees the real token). Set it once: |
| 49 | + |
| 50 | +```bash |
| 51 | +acq secret set github |
| 52 | +``` |
| 53 | + |
| 54 | +If you apply this kit on a base agent whose kit doesn't provide `github`, a |
| 55 | +private-repo clone has no credential and will fail — the kit degrades gracefully |
| 56 | +(warns and continues). Make the playbook repo public or supply a GitHub |
| 57 | +credential via that base. Once the repo is public, no token is needed. |
| 58 | + |
| 59 | +## What it links |
| 60 | + |
| 61 | +`AGENTS.md` is linked to each agent's user-level rules path; skills are linked |
| 62 | +per the cross-agent [agentskills.io](https://agentskills.io) standard root |
| 63 | +(`~/.agents/skills`) plus per-agent roots for agents that only scan their own |
| 64 | +directory. |
| 65 | + |
| 66 | +| Agent | Rules file linked | Skills root linked | Confidence | |
| 67 | +|-------|-------------------|--------------------|-----------| |
| 68 | +| OpenCode | `~/.config/opencode/AGENTS.md` | `~/.agents/skills` | high | |
| 69 | +| Codex | `~/.codex/AGENTS.md` | `~/.agents/skills` | high | |
| 70 | +| Droid (Factory.ai) | `~/.factory/AGENTS.md` | `~/.factory/skills` | high | |
| 71 | +| Claude Code | `~/.claude/CLAUDE.md` | `~/.claude/skills` | high | |
| 72 | +| GitHub Copilot CLI | `~/.copilot/copilot-instructions.md` | `~/.copilot/skills` | high | |
| 73 | +| Cursor | — (rules live in app settings) | `~/.cursor/skills` | medium | |
| 74 | +| Kiro | — (steering dir, not a rules file) | — (no confirmed skills dir) | low | |
| 75 | +| Docker Agent (cagent) | — (instructions in agent YAML) | `~/.agents/skills` | high | |
| 76 | + |
| 77 | +Notes: |
| 78 | + |
| 79 | +- **`~/.agents/skills`** is read natively by Codex, OpenCode, Docker Agent, and |
| 80 | + Copilot CLI — one symlink root covers them all. The per-agent roots |
| 81 | + (`~/.claude/skills`, `~/.factory/skills`, `~/.cursor/skills`, |
| 82 | + `~/.copilot/skills`) cover agents that only scan their own directory. |
| 83 | +- **Cursor / Kiro / Docker Agent** have no user-level rules *file* convention |
| 84 | + (rules live in app settings or the agent's YAML), so they get skills only. |
| 85 | +- Low/medium-confidence rows should be **verified in-sandbox**; the kit links |
| 86 | + them best-effort and never fails if a path is wrong. |
| 87 | + |
| 88 | +## Pinning the playbook version |
| 89 | + |
| 90 | +The kit pins the playbook with two values passed to the startup script: |
| 91 | + |
| 92 | +- `PLAYBOOK_REF` — a human-legible release tag (e.g. `v0.14.0`), what the clone |
| 93 | + fetches. |
| 94 | +- `PLAYBOOK_SHA` — the exact commit that tag must resolve to (the integrity pin). |
| 95 | + |
| 96 | +At startup the script shallow-clones `PLAYBOOK_REF`, then verifies the cloned |
| 97 | +`HEAD` equals `PLAYBOOK_SHA`; on mismatch it removes the clone and starts |
| 98 | +without the playbook rather than linking unexpected content. A tag is a |
| 99 | +**mutable** ref, and (with the sibling CA kit) the clone traverses a Zscaler MITM |
| 100 | +proxy, so a tag match alone is not sufficient integrity — hence the SHA gate. |
| 101 | + |
| 102 | +To adopt a newer playbook release, bump **both** `PLAYBOOK_REF` and |
| 103 | +`PLAYBOOK_SHA` together — in `spec.yaml`'s startup command **and** the matching |
| 104 | +fallback defaults in `files/home/playbook-clone.sh` — then recreate sandboxes. |
| 105 | + |
| 106 | +> Signed-tag verification (`git verify-tag`) is a possible future hardening; |
| 107 | +> it depends on the playbook signing its releases and is tracked separately. |
| 108 | +
|
| 109 | +## Failure behavior |
| 110 | + |
| 111 | +The startup script is **idempotent** and **non-fatal**: |
| 112 | + |
| 113 | +- Clones once (clone-if-missing); no refetch on later starts. |
| 114 | +- On clone failure (offline, missing token, bad ref) it **warns and exits 0** — |
| 115 | + the sandbox starts **without** the playbook rather than failing to create. |
| 116 | +- Because startup runs on every container start, a sandbox created offline |
| 117 | + **self-heals**: the clone is retried on the next start once the network/token |
| 118 | + is available. |
| 119 | + |
| 120 | +## Troubleshooting |
| 121 | + |
| 122 | +See [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md). |
| 123 | + |
| 124 | +## Design decisions |
| 125 | + |
| 126 | +- [`docs/decisions/playbook-clone-at-startup.md`](docs/decisions/playbook-clone-at-startup.md) |
| 127 | + — why the kit clones the playbook at startup (vs. a vendored copy or a `files/` |
| 128 | + payload), startup vs install, pinning, and the GitHub auth approach. |
| 129 | +- [`docs/decisions/extract-clone-script-to-file.md`](docs/decisions/extract-clone-script-to-file.md) |
| 130 | + — why Phase 2 extracted the inline startup shell into |
| 131 | + `files/home/playbook-clone.sh`. |
| 132 | + |
| 133 | +The move to the neutral `hybrid/v1` spec is recorded in the area-level ADR |
| 134 | +[`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). |
| 135 | + |
| 136 | +## Verifying |
| 137 | + |
| 138 | +Run the bundled check on a host with a backend CLI (e.g. `sbx`) installed and |
| 139 | +logged in: |
| 140 | + |
| 141 | +```bash |
| 142 | +./scripts/verify |
| 143 | +``` |
| 144 | + |
| 145 | +It validates the spec, creates a throwaway sandbox with the kit, and confirms |
| 146 | +the playbook cloned and `AGENTS.md` + skills resolved at the agent paths. Set |
| 147 | +`KEEP=1` to keep the sandbox for inspection. |
0 commit comments