cronekorkn/bundlewrap
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

spec/handoff: record per-bundle README pivot

Browse source 
- spec §0 gets a new revision bullet noting that per-bundle docs
  are README.md (not AGENTS.md), the rigid template is gone, and
  Phase 2 was dropped. flags §3 and §7 as pre-pivot intent only;
  doesn't back-fit them.
- handoff replaced with a short status note (~50 lines vs the
  original ~390): what landed, where current truth lives, and the
  fact that nothing is planned for a next session.

implementation plan in ~/.claude/plans/ is left as a frozen
pre-pivot artifact.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
CroneKorkN 2026-05-10 16:06:25 +02:00
parent 9e1bb2ac45
commit 7b44a8ad3a
Signed by: cronekorkn
SSH key fingerprint: SHA256:v0410ZKfuO1QHdgKBsdQNF64xmTxOF8osF1LIqwTcVw
2 changed files with 72 additions and 389 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

448
docs/superpowers/handoffs/2026-05-10-implementation-handoff.md
View file

@ -1,389 +1,59 @@
# Handoff — implement agent-friendly docs for ckn-bw # Handoff — agent-friendly docs for ckn-bw (status: complete)
Date written: 2026-05-10. Working directory for the next session: The 2026-05-10 work is finished. This file replaces the original
`/Users/mwiegand/Projekte/ckn-bw`. multi-page handoff (which described work that's now done plus a
Phase 2 that was dropped). Kept as a breadcrumb so future agents
This handoff is self-contained. Read top-to-bottom. Source documents know what landed.
referenced are tracked in this repo unless noted.
## What landed
## Why this work exists
- **Phase 0** (`730625e`) — top-of-file docstrings on every
This BundleWrap config repo (`ckn-bw`, ~22 nodes / 103 bundles) had no `libs/*.py` and `hooks/*.py`; `# purpose:` headers on every
agent-facing orientation: no `CLAUDE.md` / `AGENTS.md`, only ~33 of 103 `bin/*` script. Discovery is `ls + head -1`.
bundles have a `README`, and the root `README.md` is the maintainer's - **Phase 1** (`04558a9`) — root `AGENTS.md` (with `CLAUDE.md`
personal TODO list. Agents landing cold spelunked through magic-string symlink), `docs/agents/{conventions,commands}.md`, per-area
secrets, eval()-loaded node files, vault helpers, lib helpers, and a custom `AGENTS.md` for `bundles/`, `nodes/`, `groups/`, `libs/`,
bundlewrap fork. `hooks/`, `data/`, `items/`, `bin/`. Mechanism-focused; no
enumeration of contents.
The work over the last few sessions was: brainstorm → spec → plan → fork - **Convention pivot** (`9e1bb2a`) — per-bundle docs are plain
work (separate session) → user-story validation → Phase 0 prep → handoff `README.md`, not `AGENTS.md`. No template. `bundles/AGENTS.md`
(this file). The next session implements Phase 1 (PR1 scaffolding) and "Per-bundle README" gives loose orientation pointing at the
Phase 2 (seed bundle docs). more substantial existing READMEs.
The maintainer is also using this work as design exploration for a future `bw test` exit 0 throughout. All internal links in the new docs
agent-friendly config-management tool. Concrete bundlewrap-language resolve. Commits sit on local `master`, none pushed.
gotchas surfaced here (silent eval-load, magic strings, reactor
namespace-write side effects) inform that future tool's design. ## Where current truth lives
## Where we are right now (commit checkpoint) - Root entry: [`AGENTS.md`](../../../AGENTS.md) (symlinked to
`CLAUDE.md`).
`git log --oneline` (4 commits ahead of origin/master, none pushed): - Repo conventions + bw command deltas:
[`docs/agents/`](../../agents/).
``` - Per-area docs: `<dir>/AGENTS.md` for each top-level dir.
1da7097 README: drop stale 'install bw fork' instruction - Per-bundle docs: existing `README.md` files (~33 of them);
3daf70d spec: incorporate fork pivot and bw-syntax corrections guidance in [`bundles/AGENTS.md`](../../../bundles/AGENTS.md).
b804350 add user-stories validation doc - Self-describing files: `libs/*.py`, `hooks/*.py`, `bin/*`.
7486c78 switch bundlewrap install to editable from CroneKorkN/bundlewrap@main
8ec99db add agent-friendliness design spec ← prior session ## Source documents
```
- Spec: [`../specs/2026-05-10-agent-friendliness-design.md`](../specs/2026-05-10-agent-friendliness-design.md)
Working tree at handoff: — read its `§0. Revisions` first; §3 and §7 are now pre-pivot
intent only.
``` - User-stories validation: [`../specs/2026-05-10-user-stories-from-history.md`](../specs/2026-05-10-user-stories-from-history.md).
?? .claude/ # local Claude settings, leave alone - Implementation plan: `~/.claude/plans/btw-are-you-sure-crystalline-balloon.md`
?? bundles/left4dead2/files/scripts/overlays/test # pre-existing, unrelated, leave alone (frozen pre-pivot artifact, outside the repo).
```
## What's open
The venv runs **bundlewrap 5.0.3 editable** from
`https://github.com/CroneKorkN/bundlewrap.git@main`, cloned at Nothing planned. Per-bundle README updates are reactive — when a
`.venv/src/bundlewrap/`. `bw test` passes through the (full-network) bundle gets materially edited, top up its `README.md` then. The
sandbox. ~33 existing READMEs vary in quality and shape; that's accepted.
## Source documents (read in this order) Two minor items the maintainer may want to clean up at some point:
1. **Spec** — `docs/superpowers/specs/2026-05-10-agent-friendliness-design.md`. - The implementation plan and the spec's §3 / §7 still describe
Section §0 documents revisions; the rest describes target file shapes the pre-pivot per-bundle `AGENTS.md` convention. Spec's §0 flags
in detail. **Treat as source of truth for what each file must contain.** this; the plan is a frozen artifact and probably stays as-is.
- The original handoff's verification list mentioned `bw bundles`,
2. **User-stories validation** — which isn't a real bw subcommand. Not user-facing in any current
`docs/superpowers/specs/2026-05-10-user-stories-from-history.md`. doc.
21 stories grounded in 1169 commits of git history. Each story's
"Implications for agent docs" section maps to specific content adds
that the plan (below) records as "User-story validation findings."
3. **Implementation plan** —
`~/.claude/plans/btw-are-you-sure-crystalline-balloon.md`. Contains the
Approach (numbered steps), Workflow validation findings (7 content
adds), User-story validation findings (16 content adds), seed list,
and verification. **Read it.** Lives outside the repo because it was
produced under Claude's plan-mode workflow.
4. **Fork's `AGENTS.md`** — at
`https://github.com/CroneKorkN/bundlewrap/blob/main/AGENTS.md`. The
canonical bundlewrap-language reference: safety envelope (3 tiers),
after-change runbook, hash-diff workflow, dep-keyword cheat-sheet,
metadata.py pitfalls. ckn-bw's docs link out to it instead of
duplicating.
## Phase 0 — already done (don't redo)
✓ `requirements.txt` swapped from `bundlewrap ~=5.0, >=5.0.3` to the
editable github reference. Don't change back.
✓ User-stories doc added at `docs/superpowers/specs/2026-05-10-user-stories-from-history.md`.
✓ Spec corrected at `docs/superpowers/specs/2026-05-10-agent-friendliness-design.md`:
fork pivot, slim `commands.md` scope, bw-syntax corrections, seed-list
rebalance, and a new `§0. Revisions` log. Section numbering is unchanged
otherwise.
✓ Root `README.md` cleaned: stale "install bw fork" section removed.
Personal TODO above and the `# monitor timers` / `# git signing` blocks
below are untouched.
## Phase 0 — what's left
**Docstring/header pass on `libs/`, `hooks/`, `bin/`** — partially started
in this session, then reverted to a clean state at user request to land
this handoff. The next session does the whole pass cleanly.
Spec §5 corollary defines the rule: "Every `libs/*.py` and `hooks/*.py`
starts with a one-line module docstring. Every `bin/*` script starts with
a `# purpose:` header comment."
Files that need a docstring/header (verified absent at handoff time):
```
libs/ — 19 files: apt, bind, derive_string, grafana, hashable, hmac,
ini, ip, local, nextcloud, nginx, postgres, rsa, ssh, systemd,
tools, version, wireguard, wol (all .py)
hooks/ — 5 files: known_hosts, skip_local_nodes, test_ptr_records,
unique_node_ids, wake_on_lan (all .py)
bin/ — 9 scripts: mikrotik-firmware-updater, passwords-for, rcon,
script_template, sync_1password, timestamp_icloud_photos_for_nextcloud,
upgrade_and_restart_all, wake, wireguard-client-config
```
For each: read the file, write a concise one-line description capturing
**what it's for**, not how it works. Place the docstring at the very top
of the file (after the shebang, if present), followed by a blank line,
then the existing first line. Example shapes:
```python
# libs/wireguard.py
"""wireguard: deterministic WireGuard private/public key + PSK derivation backed by repo.vault."""
import base64
...
```
```bash
# bin/wake
#!/usr/bin/env python3
# purpose: wake one node via WoL by name — usage: wake <node>.
from bundlewrap.repo import Repository
...
```
For files with `#!/usr/bin/env python` shebang in `libs/` (only
`derive_string.py` currently), put the docstring on the line immediately
after the shebang.
For files with a leading comment in `libs/` (only `rsa.py` has the
`# https://stackoverflow.com/a/18266970` link), place the docstring above
that comment so it's still the first statement.
Commit message style for this pass: `libs/hooks/bin: add one-line module
docstrings and # purpose: headers`. Single commit for the whole pass.
Use the file headers / function names / surrounding code to derive the
descriptions; don't trust git log alone — terse commit messages won't
explain a lib's purpose. The user-stories doc gives indirect signal for
some (`libs/version.py` was introduced for `bin/mikrotik-firmware-updater`,
etc.).
## Phase 1 — main scaffolding (PR1)
The core writing work, ~800–1000 lines total per the plan's scope estimate.
### Order
Per plan Approach:
1. `docs/agents/conventions.md`
2. `docs/agents/commands.md`
3. The 8 per-area `AGENTS.md` files (`bundles/`, `nodes/`, `groups/`,
`libs/`, `hooks/`, `data/`, `items/`, `bin/`)
4. `bundles/AGENTS.template.md`
5. Root `AGENTS.md` (last so all link targets exist)
6. `ln -s AGENTS.md CLAUDE.md` (the symlink)
Each file's exact target content is in the spec (see paths above).
Augmentations beyond the spec are recorded in the plan as
"Workflow validation findings" (7 items) and "User-story validation
findings" (16 items). Examples of augmentations:
- `bundles/AGENTS.md` gets a "Before you start" header pointing at
`conventions.md` as required reading (workflow validation §1).
- `nodes/AGENTS.md` gets the silent-eval-load pitfall (user-story §S2),
the `*.py_` suspend convention (§S9), and the rename-failure-mode
pitfall (§S19).
- `conventions.md` gets the suspension idiom ("for now / disable / dummy"
— §S11), the iterative-commit context (§S4), the burst-state awareness
(§S5), and the `_old` soft-delete pattern (§F6).
- Per-bundle template gets an optional `## Writes into` section for
bundles whose reactors write cross-namespace (§S12).
**Read both validation-findings sections in the plan in full before
starting Phase 1.** They're scoped, file-keyed, and small individually,
but cumulatively they're the difference between "docs that look right" and
"docs that an agent can actually use."
### Style guardrails
- One balanced doc per audience boundary. The per-bundle `AGENTS.md`
template (spec §3) is the canonical shape: prose at top, structured
Python dict for metadata schema, optional sections only when useful.
- Mechanism over enumeration. Area docs say *how the area works*, not
*what's currently in it*. Specifics live in self-describing files
(per the docstring rule above).
- No editorializing. Don't write advice; write conventions.
- No comments unless they explain a non-obvious *why*. Same for prose:
short, factual.
- Use the path conventions the spec uses (`docs/agents/...`, not
`docs/agents/...md` repeatedly). Use full URLs to the fork
(`https://github.com/CroneKorkN/bundlewrap/blob/main/AGENTS.md`) so
links work in any rendered context.
### Verification before committing
Run all of these (some need network sandbox; sandbox is configured for
full-network access — see "Operating environment" below):
1. `bw test` — must pass (exit 0).
2. `bw nodes`, `bw groups`, `bw bundles` — repo loaders still work.
3. Internal-link integrity: `grep -oE '\]\([^)]+\.md[^)]*\)' AGENTS.md
docs/agents/**/*.md bundles/AGENTS*.md` then `test -f` each path.
4. `readlink CLAUDE.md` resolves to `AGENTS.md`.
5. `grep -L '"""' libs/*.py hooks/*.py` reports zero files.
6. `grep -L '^# purpose' bin/*` reports zero non-binary scripts.
7. `git grep -i "bw fork\|bundlewrap-fork"` reports only legitimate
fork-as-source references (no leftover stale install instructions).
8. **Workflow walk-through.** Trace the "implement a new bundle" path
end-to-end against the written docs as if you were a fresh agent.
Confirms the workflow-validation fixes actually closed the gaps.
## Phase 2 — seed bundle docs (PR2)
Ten bundles, each gets a `bundles/<x>/AGENTS.md` from the template.
| # | Bundle | Existing README? | Notes |
|---|---|---|---|
| 1 | `monitored` | check via `find bundles/<x> -name README.md` | 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) |
| 5 | `apt` | check | own lib |
| 6 | `nginx` | check | web foundational |
| 7 | `telegraf` | check | high cross-bundle ripple (writes into many namespaces) |
| 8 | `backup` | check | cross-node coordination |
| 9 | `letsencrypt` | check | cross-cutting |
| 10 | `nextcloud` | yes | complex, recent activity |
For each: derive the **Metadata** section 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 what other bundles' artifacts (apt packages,
systemd services) the bundle's reactors and items reference — use
`ccc search` (cocoindex; index already built at `.cocoindex_code/`) for
cross-bundle lookups when filling this in.
Where a bundle has an existing `README.md`, fold its content into the new
`AGENTS.md` and remove the old `README.md` in the same commit. Do not
lose information — those READMEs are the only existing human-prose
description for those bundles.
For bundles whose reactors write into other bundles' namespaces (notably
`telegraf`, `monitored`, `archive`, `wol-waker`, `apt`, `nextcloud`),
fill in the optional `## Writes into` section.
About 23 other bundles also have a `README.md` (not on the seed list).
Those stay in tree, untouched, until Phase 3 leave-as-you-go folds them.
Document this transition state in `bundles/AGENTS.md` so an agent
reading both isn't confused.
## Phase 3 — leave-as-you-go convention
Not a code task. The rule lives in `bundles/AGENTS.md`: any time an agent
or the maintainer materially edits a bundle, top-up or create its
`AGENTS.md`. The remaining ~93 bundles are filled lazily as they're
touched.
## Decisions captured (do not relitigate)
- **Doc audience.** One balanced doc per artifact, serving both humans
and agents. No separate `README.md` + `AGENTS.md` split per bundle.
- **Fork hosts bundlewrap-language docs.** Don't duplicate items / metadata
semantics in ckn-bw. Link out.
- **Read-only by default.** Agents do not run `bw apply`, `bw run`, or
`bw lock` autonomously. Never. Even with `-i`. The fork's AGENTS.md
spells this out as Tier 3.
- **No tooling work in this scope.** No `bw` wrapper, no Makefile, no CI,
no lint. The plan and spec both call this out as a non-goal.
- **Per-bundle metadata as Python dict** (not bullet list). Matches how
`metadata.py` actually looks; trailing comments carry type / required /
default.
- **Bundle naming**: lowercase-hyphenated (`bind-acme`, `routeros-monitoring`,
`wol-waker`). Underscores were used in deleted `_old` bundles, none
remain.
- **Node naming**: `<location>.<role>.py` (e.g. `home.server.py`, `htz.mails.py`).
- **`*.py_` suspend convention** is real and intentional — never delete.
- **Commit-message style**: lowercase, terse subject; multi-line body
with bullets when relevant; `Co-Authored-By: Claude Opus 4.7 (1M context)
<noreply@anthropic.com>` trailer when Claude assisted. Look at recent
commits for tone.
- **Don't push without asking.** Local commits only unless the user
explicitly says push.
## Pitfalls — things that bite
- **`bw hash` does NOT accept selectors.** Only literal node/group names.
Selectors (`bundle:<x>`, `group:<x>`) work for `bw apply`, `bw run`,
`bw nodes`, but `bw hash` is the exception. To scope to a bundle:
`bw nodes bundle:<x>` to enumerate, then `bw hash <node>` per result.
- **`bw items <node> <id> -p` is wrong** — the flag doesn't exist. Use
bare form for expected state, `--preview` (`-f`) for rendered file
content, `--attrs` for internal attributes.
- **`bw groups -n <node>` doesn't exist** — use `bw nodes <node> -a groups`.
- **Sandbox + macOS `localhost` quirk.** If you hit `errno 47
EAFNOSUPPORT` on a localhost-proxy connection, `/etc/hosts` may have
collapsed `127.0.0.1 localhost` and `::1 localhost` onto malformed
lines. Verify with `python3 -c "import socket;
print(socket.getaddrinfo('localhost', 80, type=socket.SOCK_STREAM))"` —
must include both `('127.0.0.1', 80)` and `('::1', 80, 0, 0)`. (This
was already fixed in this session; documenting in case it regresses.)
- **`bw test` makes outbound HEAD requests** to verify download URLs.
Sandbox needs `allowedDomains: ["*"]` (or equivalent) for it to pass.
Fall back to `dangerouslyDisableSandbox: true` if sandbox network
blocks unexpectedly.
- **Eval-loaded node files.** `nodes/*.py` and `groups/*.py` are
`eval()`'d as Python expressions. No top-level imports allowed. A
syntax error or import causes the loader to silently drop the node
from `bw nodes` (vanilla bundlewrap behavior). The maintainer's
`groups.py` was patched in `dc40295` to print errors — a real foot-gun
to document in `nodes/AGENTS.md`.
- **Don't restore the 9 partially-edited libs from the prior session.**
They were intentionally reverted to give the next session a clean
starting point; redo from scratch using your own judgment + file
contents.
## Operating environment
- **Working dir**: `/Users/mwiegand/Projekte/ckn-bw`.
- **venv path**: `.venv/`. `bundlewrap` is editable at `.venv/src/bundlewrap/`
on branch `main`, currently at commit `42dabfc2`. To pull upstream changes:
`(cd .venv/src/bundlewrap && git pull)`.
- **Sandbox**: enabled, `network.allowedDomains: ["*"]`, network passes
after `/etc/hosts` was un-corrupted. `bw test` works under the sandbox.
- **ccc index** at `.cocoindex_code/` — already built (768 chunks, 340
files). Use `ccc search "<query>"` for semantic codebase exploration.
Particularly useful in Phase 2 for finding what consumes a given
metadata key or imports a given lib.
## What is intentionally NOT in scope
Re-listing so the next session doesn't drift:
- No tooling: no Makefile, no `bw` wrapper, no lint, no CI, no
pre-commit hooks.
- 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) stays as-is now that the stale
fork-install section is gone. Don't add a project-readme on top.
- No upstream contribution to bundlewrap (acknowledged future work, not
this scope).
- No edits to the bundlewrap fork — that's a separate repo. The fork
agent already shipped its `AGENTS.md`.
## Success criteria
Phase 0 docstring pass complete + Phase 1 scaffolding done + Phase 2 seed
bundle docs done. Verifiable by:
- `find . -name 'AGENTS.md' -not -path './.venv/*' -not -path './.git/*'`
lists root, 8 area docs, the per-bundle template, and 10 seed bundle
docs. (~20 files.)
- `readlink CLAUDE.md` → `AGENTS.md`.
- All internal links resolve (verification step 3 above).
- All `libs/*.py`, `hooks/*.py`, `bin/*` self-describe.
- `bw test` passes.
- A fresh agent can trace "implement a new bundle" through root → bundles
→ example → write → wire → verify, without spelunking.
## Quick start for the new session
If the new session has zero prior context:
```bash
cd /Users/mwiegand/Projekte/ckn-bw
git log --oneline -5 # see Phase 0 commits
cat docs/superpowers/handoffs/2026-05-10-implementation-handoff.md # this file
cat docs/superpowers/specs/2026-05-10-agent-friendliness-design.md # the spec
cat ~/.claude/plans/btw-are-you-sure-crystalline-balloon.md # the plan
.venv/bin/bw test # confirm baseline still green
```
Then start with the docstring pass (Phase 0 remainder), commit, then move
into Phase 1 file-by-file in the order listed above.

13
docs/superpowers/specs/2026-05-10-agent-friendliness-design.md
View file

@ -36,6 +36,19 @@ reading the spec sees the current shape rather than the original intent.
`conventions.md`) are recorded in the implementation plan rather than `conventions.md`) are recorded in the implementation plan rather than
back-fitted into this spec — they're additions to file content, not back-fitted into this spec — they're additions to file content, not
scope changes. scope changes.
- **Per-bundle docs are `README.md`, not `AGENTS.md`** (revised
2026-05-10, after Phase 1 scaffolding landed). The spec originally
specified one balanced `AGENTS.md` per bundle (§3 template) plus a
Phase 2 seed migration that folded existing READMEs into new
AGENTS.md files (§7). After Phase 1 landed, the maintainer flagged
that the rigid template wouldn't survive contact with the existing
READMEs (which range from one-paragraph balanced docs to operational
scratchpads — see `bundles/{flask,dm-crypt,apt,nextcloud}/README.md`).
Resolution: one `README.md` per bundle, no fixed shape, no template;
Phase 2 dropped; existing READMEs stay in place under leave-as-you-go.
Current convention lives in `bundles/AGENTS.md` "Per-bundle README".
**Sections §3 and §7 are no longer authoritative — read them as
pre-pivot intent only.**
## 1. Goals & non-goals ## 1. Goals & non-goals