bundlewrap/docs/superpowers/specs/2026-05-10-agent-friendliness-design.md

# Agent-friendly repo — design

Date: 2026-05-10

## 1. Goals & non-goals

**Goal.** Make this BundleWrap config repo legible to agents (and humans) so an
agent can land useful work — adding/modifying a bundle, configuring a node,
running read-only `bw` introspection, doing a cross-cutting refactor — without
spelunking and without unsafe side effects.

**In scope.**

- Root entry point: `AGENTS.md` (with `CLAUDE.md` as a symlink to it).
- Per-area `AGENTS.md` for `bundles/`, `nodes/`, `groups/`, `libs/`, `hooks/`,
  `data/`, `items/`, `bin/`. Mechanism-focused; no enumeration of contents.
- Per-bundle `AGENTS.md`: one balanced doc per bundle, replacing existing
  bundle `README.md` files. Template provided.
- `docs/agents/conventions.md`: repo-specific idioms (vault magic strings,
  custom bundlewrap fork, files-not-to-touch).
- `docs/agents/commands.md`: read-only `bw` command allowlist and an
  after-change runbook keyed by what was edited.
- `docs/agents/bundlewrap/`: a focused folder explaining bundlewrap-as-used-here.
  Three files at first: `README.md`, `items.md`, `metadata.md`.
- A docstring/header pass on `libs/*.py`, `hooks/*.py`, `bin/*` so each
  individual file self-describes.
- Phase 2 seed: per-bundle `AGENTS.md` for 10 bundles selected empirically.

**Out of scope (explicitly).**

- No tooling changes: no `bw` wrapper, no Makefile, no lint, no CI.
- No code refactoring, renaming, or splitting bundles.
- No mass-fill of all 103 bundles' `AGENTS.md` up front. Phase 3 is leave-as-you-go.
- The root `README.md` (personal TODO list) stays untouched.
- Contributing `AGENTS.md` upstream to bundlewrap is acknowledged but out of
  scope for this work.

## 2. Information architecture

```
ckn-bw/
├── AGENTS.md                       # root entry point (agents + humans)
├── CLAUDE.md                       # → symlink to AGENTS.md
├── README.md                       # untouched (personal TODO)
├── docs/
│   └── agents/
│       ├── conventions.md
│       ├── commands.md
│       └── bundlewrap/
│           ├── README.md
│           ├── items.md
│           └── metadata.md
├── bundles/
│   ├── AGENTS.md                   # what bundles are, how they compose
│   ├── AGENTS.template.md          # template for per-bundle docs
│   └── <bundle>/
│       └── AGENTS.md               # per-bundle doc (replaces existing READMEs)
├── nodes/
│   └── AGENTS.md
├── groups/
│   └── AGENTS.md
├── libs/        AGENTS.md
├── hooks/       AGENTS.md
├── data/        AGENTS.md
├── items/       AGENTS.md
└── bin/         AGENTS.md
```

**Reading order an agent should follow.** Root `AGENTS.md` → relevant area
`AGENTS.md` → specific `bundles/<x>/AGENTS.md` → `docs/agents/conventions.md`
or `docs/agents/bundlewrap/<file>` only when something non-obvious comes up.

**Per-area files (not just root).** An agent editing `bundles/nextcloud/items.py`
already has `bundles/AGENTS.md` and `bundles/nextcloud/AGENTS.md` adjacent in
the file tree. Locality of reference matters more than centralization.

**Existing per-bundle `README.md` files (~10 of them).** Folded into the new
`AGENTS.md` and removed in the same change, so there is exactly one doc per
bundle.

## 3. Per-bundle `AGENTS.md` template

One balanced doc serving both audiences. Prose where prose helps, structure
where structure helps. Sections in order:

````markdown
# <bundle-name>

<1–3 sentences: what this bundle does and when you'd use it.>

## Usage

<How to apply: which group(s) typically include it, or how a node opts in.
Minimal example of node metadata if any keys are required.>

## Metadata

Keys read from `node.metadata`:

```python
{
    'nextcloud': {
        'domain': 'nc.example.com',   # str, required — public hostname
        'admin_user': 'admin',        # str, default 'admin'
        'apps': [],                   # list[str], default [] — apps to enable
        'preview': {
            'enabled': True,          # bool, default True
        },
    },
}
```

## Produces

<Brief list of items created: files, services, packages, users, etc.
One line each. Skip if trivially obvious from items.py.>

## Depends on

<Other bundles required, or "none". Note ordering quirks if any.>

## Gotchas

<Non-obvious behavior, manual steps, known pitfalls. Omit the section if none.>
````

**Design choices.**

- Free-form prose at the top (purpose, usage) keeps it readable for humans skimming.
- Metadata is a Python dict literal — matches how `metadata.py` actually looks,
  shows nested structure at a glance. Trailing comment per leaf carries type,
  required/default, and a short note.
- `Produces` and `Gotchas` are optional — skip when there is nothing useful to say.
- No version/changelog/author fields — git already covers that.

## 4. Root `AGENTS.md` content

Target ~150 lines. Sections in order:

1. **What this repo is.** 2–3 sentences. BundleWrap config-management for
   personal/family infra (~22 nodes), Python-defined nodes/groups/bundles,
   applies to real machines.
2. **Quickstart for agents.** Five bullets, the operating envelope:
   - Default to read-only `bw` commands; never `bw apply`/`bw run`/`bw lock`
     without explicit user request. See `docs/agents/commands.md`.
   - Never paste/echo decrypted secret values; respect the demagify magic-string
     convention. See `docs/agents/conventions.md`.
   - Do not modify `.secrets.cfg*`, `.venv`, `.cache`, `.bw_debug_history`,
     `.envrc`. Everything else is editable, but treat `hooks/` and `items/`
     (custom item types) with extra care — they affect bw's behavior or item
     resolution across the whole repo.
   - Uses a custom **bundlewrap fork**, not upstream — check
     `docs/agents/conventions.md` before assuming upstream behavior.
   - Prefer adding helpers to `libs/` over duplicating logic across bundles.
3. **Layout map.** Terse, link-rich. One line per top-level dir, each linking
   to that area's `AGENTS.md`.
4. **How nodes/groups/bundles fit together.** 5–10 lines: nodes pick up bundles
   via groups; metadata flows from groups → node → metadata processors;
   `nodes.py` and `groups.py` (root) are the loaders that walk the dirs and
   run `demagify`.
5. **Conventions you must know.** One-line summary + link for each:
   - `docs/agents/bundlewrap/README.md` — read first if new to bundlewrap.
     `items.md` and `metadata.md` are deep dives for the hard parts.
   - `docs/agents/conventions.md#secrets` — secrets / demagify magic strings.
   - `docs/agents/conventions.md#fork` — custom bundlewrap fork.
   - `docs/agents/conventions.md#groups` — group inheritance order.
   - `docs/agents/commands.md` — safe `bw` commands and after-change checks.
   - Lib helpers — see top-of-file docstrings in `libs/*.py`.
6. **Where to look for examples.** Pointers to a small bundle, a complex
   bundle, and a node file.
7. **Where this doc lives.** Note that `CLAUDE.md` is a symlink to this file.

## 5. Per-area `AGENTS.md` content

**Rule.** An area `AGENTS.md` describes how that area works — mechanisms,
conventions, how to add or modify. It does **not** enumerate contents.
Specifics live with the thing itself (docstrings, top-of-file comments) or
in a per-subdir `AGENTS.md` only when that subdir has its own non-obvious
conventions.

**Corollary.** Every `libs/*.py` and `hooks/*.py` starts with a one-line
module docstring. Every `bin/*` script starts with a `# purpose:` header
comment. Discovery is by `ls` + reading those headers, not by an index page.

Each area `AGENTS.md` has the same five-section shape (target 30–80 lines):

1. What's in this directory (one paragraph).
2. Conventions (naming, file structure, what each kind of file does).
3. How to add / modify (concrete steps for the most common change).
4. Pitfalls (area-specific gotchas).
5. See also (links to relevant `docs/agents/*` and example files).

Per-area specifics:

- **`bundles/AGENTS.md`** — bundle anatomy (`items.py`, `metadata.py`, `files/`,
  `templates/`), where helpers go, when to extract to `libs/`. Links out to
  `docs/agents/bundlewrap/items.md` and `metadata.md` for language-level detail.
- **`nodes/AGENTS.md`** — `eval()` loading mechanism via `nodes.py`, demagify
  magic-string syntax, naming convention pattern (`<location>.<role>.py`).
  **Pitfall:** because node files are `eval()`'d, no top-level imports — only
  expression-level constructs.
- **`groups/AGENTS.md`** — same `eval()` mechanism via `groups.py`, subdir
  purpose convention (`applications/`, `locations/`, `machine/`, `os/`),
  how `all.py` interacts, group-membership rules, inheritance order.
- **`libs/AGENTS.md`** — what libs are (importable from bundles via
  `repo.libs.<x>`), conventions for adding a helper, contribution rule
  (one-line module docstring required).
- **`hooks/AGENTS.md`** — bw hook lifecycle, when each event fires, how to
  write a hook.
- **`data/AGENTS.md`** — what `data/` is for (data sources templated and
  consumed by bundles), conventions for adding a new data source.
- **`items/AGENTS.md`** — what custom item types are, how to write one,
  when to use a custom item type vs a `file` item.
- **`bin/AGENTS.md`** — what `bin/` is for (operator tooling, not invoked by
  bundlewrap).

## 6. `docs/agents/` content

### `conventions.md` (~80–120 lines)

- **Secrets / demagify.** `!password_for:`, `!decrypt:`, `!decrypt_file:`,
  `!32_random_bytes_as_base64_for:`. What each does, where they're allowed
  (node files, evaluated through `nodes.py`), why agents must never echo
  decrypted values.
- **Custom bundlewrap fork.** How it's installed
  (`pip install --editable git+file:///…/bundlewrap-fork@main`), implications
  (don't assume upstream-only behavior), pointer to the fork source.
- **Group inheritance order** & how metadata merges
  (`all.py` → location → os → machine → applications → node).
- **Naming conventions** for nodes (`<location>.<role>.py`) and groups
  (subdir purpose).
- **Files agents must not modify.** `.secrets.cfg*`, `.venv`, `.cache`,
  `.bw_debug_history`, `.envrc`.

### `commands.md` (~80–120 lines)

**Side-effect model** (paragraph up front):

- `bundles/<x>/metadata.py` `defaults` and `@metadata_reactor` can write into
  *any* namespace (e.g. nextcloud's metadata writes into `apt.packages` and
  `archive.paths`). Changing it can ripple into other bundles' inputs.
- `libs/<x>.py` is imported by both `items.py` and `metadata.py` across many
  bundles — biggest blast radius.
- `groups/*.py` changes membership (which bundles a node gets) and merged
  metadata.
- `bw hash` is the primary integrated check because it captures bundle
  membership + metadata + items + file content.

**Read-only command reference** (one line each):
`bw hash`, `bw metadata`, `bw items`, `bw items <node> <id> -p`, `bw nodes`,
`bw groups`, `bw verify`, `bw debug`, `bw test`, `bw plot`. Each tagged
read-only.

**After-change checks, keyed by what you changed:**

| You changed | First check | Drill-in |
|---|---|---|
| `bundles/<x>/items.py` | `bw hash <node>` for a node with bundle `<x>` | `bw items <node> <id> -p`; `bw verify <node>` |
| `bundles/<x>/metadata.py` | `bw hash` for *all nodes including bundle `<x>`* (reactors can ripple beyond `<x>`'s namespace) | `bw metadata <node>`; `bw metadata <node> -k <key>` |
| `bundles/<x>/files/*` (template) | `bw hash <node>` | `bw items <node> <path> -p` |
| `groups/*.py` | `bw hash` every node in/near the group | `bw groups -n <node>`; `bw metadata <node>` |
| `libs/<x>.py` | `bw hash` **all** nodes (cheap, no network) — biggest blast radius | `bw debug` to inspect helper outputs |
| `nodes/<x>.py` | `bw hash <node>` | `bw metadata <node>` |
| `hooks/*.py` | re-run the `bw` command whose lifecycle the hook hooks | — |
| Anything | `bw test` — cheapest repo-level sanity | — |

**Mutating commands (forbidden without explicit user request).** `bw apply`,
`bw run`, `bw lock` — what each does and why agents must not invoke them
autonomously.

**Hash diff workflow.** Capture `bw hash > before.txt`, make change,
`bw hash > after.txt`, diff. Canonical pre/post comparison.

**Targeting.** How to scope to one node / one group (`-t`, group selectors).

### `bundlewrap/README.md` (~80 lines)

Mental model paragraph: nodes ← groups → bundles → items; metadata flow
(groups → node → metadata processors → bundle items); hooks vs items vs libs.
Glossary, one paragraph each: node, group, bundle, item, items.py, metadata.py,
metadata reactor, hook, lib, `repo.libs`. Folder index. Fork callout
(explicit "we use a fork — here's what differs (or 'nothing day-to-day')";
link to fork source). Links out to <https://docs.bundlewrap.org> for depth.

### `bundlewrap/items.md` (~200–300 lines)

The item types this repo actually uses — file, pkg_apt, svc_systemd, action,
symlink, group, user, … — with common attributes and examples drawn from
this repo. The dependency keyword glossary: `needs`, `needed_by`, `triggers`,
`triggered`, `triggered_skip_for`, `tags`, `cascade_skip`, `unless` — each
with one sentence and a real example. Custom item types from `items/`
(currently `download`). "When in doubt, see upstream items reference" with
a link.

### `bundlewrap/metadata.md` (~200–300 lines)

`defaults` dict semantics (deep-merge into resolved metadata, can write into
any namespace). `@metadata_reactor.provides(...)` contract: signature, return
shape, fixpoint resolution, when to declare `provides` narrowly vs broadly.
Vault integration: `repo.vault.password_for`, `repo.vault.random_bytes_as_base64_for`,
`repo.vault.decrypt`, `repo.vault.decrypt_file` — and how they tie back to
demagify magic strings in node files. `repo.libs.hashable.hashable(...)` for
putting dicts in sets — a pattern used heavily in this repo, worth explicit
example. Common pitfalls: reactor declared narrower than it writes; reactor
that doesn't reach fixpoint; reactor that reads a key it didn't declare reading.

## 7. Seed work & rollout

### Phase 1 — scaffolding (one PR-sized chunk)

1. Root `AGENTS.md` (Section 4) + `CLAUDE.md` symlink → `AGENTS.md`.
2. `docs/agents/bundlewrap/README.md`, `items.md`, `metadata.md` (Section 6).
3. `docs/agents/conventions.md` and `commands.md` (Section 6).
4. Per-area `AGENTS.md` for `bundles/`, `nodes/`, `groups/`, `libs/`, `hooks/`,
   `data/`, `items/`, `bin/` (Section 5).
5. `bundles/AGENTS.template.md` so future bundle docs have something to copy.
6. Docstring/header pass: add a one-line module docstring to any `libs/*.py`
   and `hooks/*.py` lacking one; `# purpose:` header to any `bin/*` script
   lacking one.

Order within Phase 1: root → bundlewrap folder → conventions → commands →
area docs → docstring pass → template. Each piece can be reviewed in
isolation; the work bisects cleanly.

Honest scope: the bundlewrap folder is ~600 lines of focused writing total
(80 + 250 + 250). The rest is shorter — area docs and conventions land in
30–120 lines each.

### Phase 2 — seed bundles (10)

Bundles selected empirically (node+group references and recent commit
activity, validated 2026-05-10):

**Usage hubs (6):**

1. `monitored` (12 node refs) — meta-bundle, often misunderstood.
2. `postgresql` (9 refs, 3 cross-bundle).
3. `wireguard` (8 refs, has own lib + bin script).
4. `php` (8 refs).
5. `apt` (6 refs, has own lib).
6. `nginx` (4 refs, web foundational).

**Recently active or complex (4):**

7. `telegraf` (9 cross-bundle refs, 6 recent commits) — monitoring snippets
   ripple across bundles.
8. `backup` (7 refs, cross-node coordination).
9. `letsencrypt` (6 refs, cross-cutting).
10. `nextcloud` (5 recent commits, complex, actively edited).

For each: write one `AGENTS.md` from the template — purpose, usage, metadata
dict, produces, depends-on, gotchas. Migrate any existing
`bundles/<x>/README.md` content into it and remove the old `README.md`.

### Phase 3 — leave-as-you-go

- Convention from this point: any time an agent (or you) materially edits a
  bundle, top-up or create its `AGENTS.md`. Documented as a rule in
  `bundles/AGENTS.md`.
- No mass-fill of the remaining ~95 bundles up front — most are simple enough
  that `items.py`/`metadata.py` are self-explanatory.

## 8. Future work (not this spec)

- Contributing an `AGENTS.md` to bundlewrap upstream (or to your fork)
  describing items/metadata semantics for agents — would shrink the
  bundlewrap folder over time and shift authority back upstream.
- Tooling: a read-only `bw` wrapper or lint that nudges new bundles toward
  having an `AGENTS.md`. Worth considering only after Phase 1+2 reveal which
  conventions actually drift.
- More bundlewrap docs files (`groups-nodes.md`, `hooks.md`) if real gaps
  surface during Phase 2 or Phase 3 work.

## 9. Open questions / risks

- **Risk: docs drift.** As the repo evolves, `AGENTS.md` files lag behind
  code. Mitigations: per-bundle docs are short (low maintenance); Phase 3
  rule attaches doc updates to material code edits; the area docs are
  mechanism-focused, which changes less often than enumerations.
- **Risk: bundlewrap-folder duplicates upstream.** Acknowledged trade-off.
  Mitigation: the folder is scoped to *as we use it here*, with explicit
  upstream links; not trying to be a full bundlewrap manual.
- **Open: which seed bundles to swap.** Phase 2 list is empirically grounded
  but not rigid — `zfs` (8 refs), `bind` (4 refs, own lib), and
  `routeros-monitoring` (15 recent commits, specialized) are honourable
  mentions if a swap is wanted later.