bundlewrap/docs/superpowers/plans/2026-05-10-agent-friendliness-plan.md

Implementation plan — agent-friendliness docs

Note (post-execution): This plan is a frozen pre-pivot artifact. It captures the approach as designed before Phase 1 landed and the per-bundle convention pivoted from AGENTS.md to README.md. Sections describing per-bundle AGENTS.md, bundles/AGENTS.template.md, and the Phase-2 seed-bundle migration reflect the original intent, not what shipped. For the current shape, read the spec's §0 Revisions (../specs/2026-05-10-agent-friendliness-design.md) and the handoff status note (../handoffs/2026-05-10-implementation-handoff.md). Kept in tree as a record of how the work was scoped and what validation findings (workflow + user-story) shaped Phase 1.

Context

This BundleWrap config repo (ckn-bw, ~22 nodes / 103 bundles) currently has no agent-facing orientation: no CLAUDE.md / AGENTS.md, only ~10 of 103 bundles have a README, and the root README.md is a personal TODO. Agents landing cold spelunk to figure out conventions (demagify magic strings, metadata_reactor patterns, lib helpers, what's safe to run).

Goal: ship one PR that scaffolds the documentation surface described in docs/superpowers/specs/2026-05-10-agent-friendliness-design.md, plus a second PR seeding 10 high-value bundle docs. After this work, an agent can land useful work in nodes / groups / bundles / libs without trial-and-error, and never invokes a state-mutating bw command without explicit user request.

Corrections since the spec was written.

• Verification on 2026-05-10 found the active venv ran upstream bundlewrap 4.24.0, the README's fork install was stale, and the user has since upgraded the venv to PyPI bundlewrap 5.0.3.
• The user refreshed /Users/mwiegand/Projekte/bundlewrap-fork to track upstream master at commit a97cdb13 (also version 5.0.3), and decided to make the fork agent-friendly first (separate session, separate plan), then return here. The ckn-bw plan therefore drops the docs/agents/bundlewrap/ folder it originally planned — bundlewrap-language docs live in the fork now.

This plan reflects the reduced ckn-bw scope. It is gated on the fork's AGENTS.md existing, since this repo's root AGENTS.md links out to it. See the handoff document delivered separately for the fork-session work.

Scope

Two PRs.

• PR1 — scaffolding. Root AGENTS.md, CLAUDE.md symlink, the docs/agents/ tree (just conventions.md and commands.md — no bundlewrap/ folder; that lives in the fork), all eight per-area AGENTS.md files, the per-bundle template, the docstring/header pass on libs/*.py / hooks/*.py / bin/*, and the README cleanup (remove the stale fork section, keep everything else). Spec correction in the same PR.
• PR2 — seed bundles. Per-bundle AGENTS.md for the 10 seed bundles; fold and remove any existing per-bundle README.md in those.

Phase 3 from the spec ("leave-as-you-go") is a convention, not a code task — captured in bundles/AGENTS.md as a contribution rule.

Approach (recommended)

PR1 — scaffolding

Order is dependency-respecting; each step's output is referenced by later steps' link targets.

Precondition: the fork's root AGENTS.md exists at /Users/mwiegand/Projekte/bundlewrap-fork/AGENTS.md. PR1 links out to it, so PR1 cannot land cleanly until the fork session has produced that file.

1. Spec correction. In docs/superpowers/specs/2026-05-10-agent-friendliness-design.md:

   • Replace "fork" framing with the actual reality: venv runs bundlewrap 5.0.3 (PyPI install today), the user maintains a separate fork at github.com/CroneKorkN/bundlewrap whose master tracks upstream and whose AGENTS.md is the canonical bundlewrap-language reference.
   • Replace the docs/agents/bundlewrap/ folder content (Section 2 IA, Section 6) with a single bullet: "bundlewrap-language reference lives in the fork at <URL>/AGENTS.md; ckn-bw links to it from root AGENTS.md and conventions.md."
   • Update Section 4 quickstart and Section 6 conventions.md accordingly.
   • Single commit before any other ckn-bw docs are written.

2. docs/agents/conventions.md (~80–120 lines): demagify magic strings; bundlewrap version note (5.0.3, link to the fork's AGENTS.md for language reference); group inheritance order; node/group naming conventions; the eval() idiom in nodes.py / groups.py and what that constrains for editors/agents (no top-level imports, etc.); do-not-touch file list (.secrets.cfg*, .venv, .cache, .bw_debug_history, .envrc).

3. docs/agents/commands.md (~30–50 lines, slimmed). The fork's AGENTS.md (at https://github.com/CroneKorkN/bundlewrap/blob/main/AGENTS.md) now carries the canonical bw runbook — tiers, after-change table, hash-diff workflow, bw debug sketch — verified against 5.0.3 source. This file shrinks to ckn-bw-specific deltas:

   • One-line lead pointing at the fork's AGENTS.md for the canonical read-only allowlist + after-change runbook.
   • Apt-key after-change row (S7 finding): editing data/apt/keys/*.{asc,gpg} → first verify with gpg --show-keys <newkey> locally + fingerprint diff against the expected source. Trial via bw apply is the failure path (a wrong key blocks unattended upgrades cluster-wide). Not in the fork's runbook because it's repo-specific.
   • *.py_ suspended-node interaction with bw nodes: a node file ending in .py_ is silently excluded from the loader; bw nodes won't list it. Document this so an agent doesn't think a node is missing when it's actually parked.
   • Vault magic-string handling: never echo decrypted output, even in bw debug exploration. Cross-link to conventions.md#secrets.

4. Per-area AGENTS.md — eight files, mechanism-focused, no enumeration. Order: bundles/, nodes/, groups/, libs/, hooks/, data/, items/, bin/. Each ~30–80 lines, same five-section shape from spec Section 5.

5. bundles/AGENTS.template.md — the per-bundle template (spec Section 3 verbatim, with placeholder text in each section).

6. Root AGENTS.md — written so all link targets exist. Spec Section 4, with the "Conventions you must know" first bullet now pointing at the fork's AGENTS.md (canonical bundlewrap language) instead of an internal bundlewrap/ folder. Quickstart bullet about the fork updated to: "bundlewrap reference lives in <fork-URL> — read first if new to bundlewrap." Then create CLAUDE.md as a symlink: ln -s AGENTS.md CLAUDE.md.

7. Docstring/header pass — for every libs/*.py and hooks/*.py without a top-of-file module docstring, add a one-liner. For every bin/* script without a header comment, add a # purpose: … line. Do not touch files that already have one. Mechanical: read each file's first ~10 lines, decide, edit only if missing.

8. Root README.md cleanup — remove the stale "install bw fork" section (the pip3 install --editable git+file:///…/bundlewrap-fork… block) since the venv runs PyPI 5.0.3. Leave the rest of the README untouched.

PR2 — seed bundles

For each of the 10 seed bundles, write bundles/<name>/AGENTS.md from bundles/AGENTS.template.md. Where a bundle already has README.md, fold its content into the new AGENTS.md and remove the old README.md in the same commit.

Seed list (from spec Section 7, validated empirically 2026-05-10):

#	Bundle	Existing README?	Notes
1	monitored	check	meta-bundle, often misunderstood
2	postgresql	check	foundational
3	wireguard	check	own lib + bin script
4	routeros-monitoring	no	most-churned bundle (15 commits / 18mo); replaces php per user-story rebalance
5	apt	check	own lib
6	nginx	check	web foundational
7	telegraf	check	high cross-bundle ripple
8	backup	check	cross-node coordination
9	letsencrypt	check	cross-cutting
10	nextcloud	yes (verified)	complex, recent activity

For each: derive Metadata dict by reading the bundle's metadata.py and running bw metadata <one-node-with-the-bundle> to confirm the resolved shape. Derive Produces from items.py. Derive Depends on by checking which other bundles' artifacts (apt packages, systemd services) the bundle's reactors and items reference. Use the ccc index (built 2026-05-10) for fast cross-bundle lookups when filling Depends on.

Workflow validation findings (2026-05-10) — content additions

Traced the "implement a new bundle" workflow against the planned docs. Natural agent path is root → bundles/AGENTS.md → example bundle → write files → wire to a node → verify. Seven gaps found; six are one-line additions to bundles/AGENTS.md, one is a rewrite of root §6's example pointers (~8 lines). All low-cost; fold into the corresponding files when written in PR1.

1. bundles/AGENTS.md — "Before you start" header. conventions.md is off the natural path; call it out as required reading at the top, not just in "see also." This repo's idioms (vault calls in reactors, repo.libs.hashable.hashable(...), demagify) live there. An agent who skips it will write subtly wrong code (e.g. dict-in-set TypeError, vault calls in the wrong place).

2. Root AGENTS.md §6 — use-case keyed example pointers. Replace the spec's "small bundle / complex bundle / node file" with one-line pointers per pattern: vault usage, templated files, cross-bundle reactor writing, download custom item. Pick concrete bundles at write time (grep for the patterns to find good exemplars). ~8 lines.

3. bundles/AGENTS.md "How to add" — explicit wiring step. Add a numbered step: "(4) Wire to nodes — see groups/AGENTS.md for application-style group wiring or nodes/AGENTS.md for direct attachment via a node's bundles list." Currently the wiring step is implicit; agent has to discover by cross-reading two area docs.

4. bundles/AGENTS.md Conventions — bundle naming. One line: bundle directory names are lowercase with hyphens (e.g. backup-server, bind-acme, dm-crypt); avoid underscores. Verify the convention by ls bundles | grep _ before writing — if the convention is mixed, document the actual rule.

5. bundles/AGENTS.md "See also" — items and templates. Cross-link to items/AGENTS.md (for the download custom item and how to write new custom item types) and to the fork's docs/content/guide/item_file_templates.md (template syntax). Both are common needs an agent writing a new bundle hits early.

6. bundles/AGENTS.md — first-thing-to-run after writing. One-liner pointing at commands.md with the canonical sequence: bw test (sanity) → bw items <node> (do items show up?) → bw hash <node> (changed as expected?). Saves the agent from hunting the runbook.

7. bundles/AGENTS.template.md — empty-section guidance. Add a note at the top of the template: "For a brand-new bundle without consumers yet, leave Depends on and Produces empty or marked TBD; fill in after the first verify run."

User-story validation findings (2026-05-10) — additional content adds

Empirical user-story extraction from 1169 commits (full history, with detailed analysis of the last 222 commits / 18 months) is at docs/superpowers/specs/2026-05-10-user-stories-from-history.md. It identified 21 recurring user stories. Coverage assessment vs the planned docs: 5 ✅ / 13 ⚠ / 3 ❌. Below are the 16 additional content adds, grouped by target file. Each is one paragraph or less. The ❌ items shape an agent's judgment (highest value); the ⚠ items shape lookups.

Root AGENTS.md

• F9 — Personal TODO callout. "Note: README.md is the maintainer's personal scratchpad, not project documentation. Onboarding lives here in AGENTS.md." One sentence in §1 ("What this repo is").

docs/agents/conventions.md

• S4 ❌ — Iterative-commit workflow style. "User commits are iterative checkpoints, not landing-ready snapshots. Terse messages (+, fix, whitespace, dowsnt exist) and successive 'fix' commits on the same file are normal. Don't rebase WIP without asking. As an agent, prefer to land complete-feeling commits rather than mimic the iterative style."
• S5 ❌ — Burst-state awareness. "Before writing into a subsystem, check git log --since='1 month ago' bundles/<x> (or nodes/<x>.py, etc.). If it shows ≥10 recent commits, the subsystem is in flux and your assumptions about its metadata shape may already be stale. Read the most recent diffs first."
• S11 ❌ — Suspension idiom ("for now / disable / dummy / offline"). "Commits with these markers indicate deliberate suspension, not bugs. If you encounter a stub or commented-out block, check git log -- <file> for the suspension reason before re-enabling. The user reverses these manually when ready."
• F6 — _old / _old2 soft-delete pattern. "Suffixed-with-_old directories are the user's recovery buffer during big refactors. Don't delete them without asking, even if they look orphaned."
• F8 — Branch naming for PRs. "PRs go through self-hosted Gitea/Forgejo. Branch names are lowercase-snake_case descriptive (debian-13, htz.mails_debian_13_squash, l4d2_the_next)."
• S20 — Bundlewrap version-migration recipe (optional). "When the next major bw version lands: read upstream migration guide → grep for affected reactor patterns → rewrite each → bump requirements.txt last." Captures the pattern from 186d503 (bw 4 → 5). Useful given the maintainer's tool-design pivot.

docs/agents/commands.md

• S7 — Apt-keys verification. Add a row to the after-change table: data/apt/keys/*.{asc,gpg} → first check is gpg --show-keys <newkey> locally + visual diff against expected fingerprint. Trial via bw apply is the failure path (a wrong key blocks unattended upgrades cluster-wide).
• S21 — bw debug content sketch. Resolved upstream: the fork's AGENTS.md now carries the canonical bw debug content sketch (probes for repo.get_node(...).metadata, repo.libs.<x>, repo.path). No ckn-bw addition needed — Approach step 3 already points at the fork.

bundles/AGENTS.md

• S3 — Template recognition. One paragraph: "Files under bundles/<x>/files/ are static unless the file: item declares content_type='mako' or the file extension triggers templating (see fork's docs/content/guide/item_file_templates.md). To check: read the matching file: entry in items.py."
• S13 — How to remove a bundle. 5-line section, symmetric to "How to add": "(1) git grep '<name>' to find references in nodes/groups/ other bundles; (2) remove those references; (3) rm -rf bundles/<x>/; (4) bw test and bw nodes to confirm clean."
• S18 — README transition state. "If a bundle has both README.md and AGENTS.md, AGENTS.md is canonical; the README is being phased out. ~23 bundle READMEs remain after the seed PR — Phase 3 leave- as-you-go folds them in over time."

bundles/AGENTS.template.md

• S12 — Optional ## Writes into section. Add to template (after ## Depends on): "List other namespaces this bundle's defaults or reactors write into (e.g. nextcloud writes into apt.packages and archive.paths). Skip section if none — most bundles don't write cross-namespace, but the ones that do create the highest-blast- radius surprises."

nodes/AGENTS.md

• S2 — Silent eval-load-failure pitfall. "Node files are eval()'d. A syntax error or top-level import causes the loader to silently drop the node. If bw nodes reports fewer nodes than expected, check groups.py (the user added explicit error printing in commit dc40295 after being bitten)."
• S9 — *.py_ suspend convention. "Appending _ to a node filename (e.g. htz.l4d2.py_) parks it without loading. Used to keep decommissioned-but-not-deleted node configs in tree."
• S9 — Symmetric "How to add a node" workflow. Numbered steps parallel to bundles/AGENTS.md "How to add": (1) create nodes/<location>.<role>.py with eval()-safe expression syntax, (2) populate id, hostname, groups, bundles, metadata, (3) add to relevant groups/<area>/<x>.py if group membership is the attachment point, (4) verify with bw nodes, bw nodes <node> -a groups, bw metadata <node>.
• S19 — Node-rename failure mode. "Renaming a node file renames the node. Vault entries (via !password_for:<node>), bw hash records, and ssh known_hosts associations all key on node name — search and replace before renaming, or vault lookups silently return new (wrong) values."

groups/AGENTS.md

• S10 — Family-file pattern. "OS variants commonly share a *-common.py parent (e.g. debian-13-common.py shared by debian-13.py and debian-13-pve.py). Use this when introducing related-but-distinct OS group families."
• S10/S15 — New-OS-variant recipe. "To introduce a new OS major: (1) add groups/os/debian-N.py + debian-N-common.py parallel to the existing files (don't edit in place); (2) add data/apt/keys/debian-N-*.{asc,gpg}; (3) bump dependent bundles that branch on OS string (e.g. bundles/bind/items.py); (4) bump affected nodes' groups lists one at a time; (5) delete the old OS file when no node references it."

data/AGENTS.md

• S7 — Two distinct content models. "data/apt/keys/ holds binary GPG keys consumed by bundles/apt; data/grafana/rows/ holds Python modules for Mako-templated dashboards. Same directory shape, different content models — when adding a new data subdir, declare which model it follows."
• F4 — data/ vs bundles/<x>/files/ heuristic. "If a data asset is read by exactly one bundle, prefer bundles/<x>/files/. Use data/ for shared/multi-consumer artifacts. Single-instance evidence: 78a8abc moved mikrotik.mib from data/ into the bundle for this reason."

hooks/AGENTS.md

• S17 — Broken-hook failure mode. "A hook that errors at load time breaks every bw command that fires that lifecycle (including bw test, defeating the obvious diagnostic). Test new hooks in isolation first: bw debug then import sys; sys.path.insert(0, 'hooks'); import <hookmodule>. Iterate there until the import is clean."

libs/AGENTS.md

• S16 — Find-consumers snippet. Add as a one-liner under Pitfalls: "Before changing a lib's API, find consumers: git grep -l 'repo.libs.<x>'. Lib changes have repo-wide blast radius — every bundle that imports the lib re-evaluates."

bin/AGENTS.md

• S14 — bin/script_template. "When introducing a new operator script, start from bin/script_template (the user maintains it as the canonical starter)."

Phase 2 seed list rebalance

User-story analysis (story 5, subsystem-burst evidence) found that 3 of 5 recent burst targets are unseeded. Strongest single swap:

• Drop php (8 node refs but ~zero recent commits — usage hub that doesn't change). Add routeros-monitoring (15 recent commits, the most-touched bundle in 18 months; not a dependency hub but high churn).

Optional second swap (judgment call):

• Drop apt (6 refs, has own lib, foundational but stable) and add bootshorn (recent burst target, has its own subsystem). Or keep apt for usage-hub coverage and accept that the seed misses bootshorn — Phase 3 covers it lazily.

Default this plan to the single swap (php → routeros-monitoring); note apt → bootshorn as a second-swap option if the user wants it.

Critical files

New:

• AGENTS.md (root)
• CLAUDE.md (symlink → AGENTS.md)
• docs/agents/conventions.md
• docs/agents/commands.md
• bundles/AGENTS.md, bundles/AGENTS.template.md
• nodes/AGENTS.md, groups/AGENTS.md, libs/AGENTS.md, hooks/AGENTS.md, data/AGENTS.md, items/AGENTS.md, bin/AGENTS.md
• bundles/{monitored,postgresql,wireguard,routeros-monitoring,apt,nginx,telegraf,backup,letsencrypt,nextcloud}/AGENTS.md

Modified:

• docs/superpowers/specs/2026-05-10-agent-friendliness-design.md (fork → upstream correction).
• README.md (remove stale "install bw fork" section).
• libs/*.py, hooks/*.py (add module docstrings where missing).
• bin/* (add # purpose: header where missing).

Deleted:

• bundles/<name>/README.md for each of the ~10 seed bundles that have one (content folded into AGENTS.md).

Existing utilities & assets to reuse

• Spec at docs/superpowers/specs/2026-05-10-agent-friendliness-design.md — the source of truth for what each file contains. Sections 3, 4, 5, 6 of the spec are nearly copyable into the actual files.
• User-story validation doc at docs/superpowers/specs/2026-05-10-user-stories-from-history.md — 21 stories grounded in git history with concrete commit evidence. When writing per-bundle docs, look up the relevant story for evidence of typical changes (e.g. for nextcloud, see Story 1 + Story 5 l4d2-style burst comparison). The "Implications for agent docs" paragraphs in each story map directly to the additions in §"User- story validation findings" above.
• ccc index built at .cocoindex_code/ on 2026-05-10 (768 chunks, 340 files) — useful in PR2 for finding bundles that consume a metadata key or import a particular lib.
• Bundlewrap CLI for verification: bw metadata <node>, bw items <node>, bw test, bw hash. Read-only; safe to run during writing.
• Existing bundle READMEs at bundles/{freescout,influxdb2,dm-crypt,gcloud,flask,nextcloud,build-server,raspberrymatic-cert,letsencrypt,nodejs}/README.md (and any others — verify with find bundles -name README.md) — content to fold into the matching AGENTS.md. These are the only existing human-prose source for those bundles; do not lose information when migrating.

Verification

Run after PR1:

1. bw test — repo-level sanity (passes today; should still pass).
2. bw nodes, bw groups, bw bundles — sanity that loaders work after the docstring/header additions.
3. Check every internal link in AGENTS.md and docs/agents/**.md resolves to a real file. A tiny shell loop with grep -oE '\]\([^)]+\.md[^)]*\)' then test -f each path.
4. readlink CLAUDE.md resolves to AGENTS.md.
5. grep -L '"""' libs/*.py hooks/*.py reports zero files (every lib/hook has a module docstring).
6. grep -L '^# purpose' bin/* reports zero non-binary scripts.
7. git grep -i "bw fork\|bundlewrap-fork" reports only the corrected docs locations (no leftover fork references in README.md).
8. Workflow walk-through. Trace the "implement a new bundle" path end-to-end against the written docs: root → bundles/AGENTS.md → example pointer → can the writer locate vault/hashable/template guidance from there without spelunking? Confirms the §"Workflow validation findings" fixes actually closed the gaps.

Run after PR2:

1. bw test — still green.
2. For each seed bundle <x>: pick one node that has it, run bw metadata <node> and confirm the keys listed in bundles/<x>/AGENTS.md Metadata section actually appear in the resolved metadata. Catches drift between docs and reality.
3. find bundles -name README.md — confirm none exist for the 10 seed bundles (folded into AGENTS.md).
4. Each new bundles/<x>/AGENTS.md follows the template structure (grep -L '^## Metadata' bundles/*/AGENTS.md reports zero).

Non-goals (re-asserted from spec)

• No tooling changes (no bw wrapper, no Makefile, no lint, no CI).
• No code refactoring, renaming, or splitting bundles.
• No mass-fill of the remaining ~93 bundles up front.
• No upstream contribution to bundlewrap (acknowledged future work).
• The root README.md keeps everything except the fork section.

Risks & mitigations

• Drift between docs and code. Mitigation: per-bundle docs are short (low maintenance), the area docs are mechanism-focused (changes less often than enumerations), and PR2 verification step 2 catches metadata drift at write time.
• PR1 is gated on the fork's AGENTS.md existing. If you want to start ckn-bw work before the fork session lands, you can stub the link to the fork's AGENTS.md (e.g. point at the repo URL even if the file isn't there yet) and merge PR1, but that risks broken links if the fork URL or filename changes. Cleaner: do the fork session first, then PR1.
• PR1 is now a moderate writing chunk (~800–1000 lines instead of ~1500–2000), since the bundlewrap folder moved out. Single PR is comfortable. The user-story validation findings (16 small adds) push it to ~1000–1200; still manageable as one PR.
• README undercount. The plan/spec estimated ~10 existing bundle READMEs to fold; actual is 33 (verified 2026-05-10 from git history). The seed list intersects with only 4–5 of those (nextcloud has one verified; others — find bundles -name README.md will enumerate). PR2 only folds READMEs in seed bundles; ~28 remain untouched, addressed lazily by Phase 3. bundles/AGENTS.md notes this transition state explicitly (per user-story finding §S18) so agents reading both don't get confused.