CroneKorkN
7b44a8ad3a
- 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>
59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# Handoff — agent-friendly docs for ckn-bw (status: complete)
|
|
|
|
The 2026-05-10 work is finished. This file replaces the original
|
|
multi-page handoff (which described work that's now done plus a
|
|
Phase 2 that was dropped). Kept as a breadcrumb so future agents
|
|
know what landed.
|
|
|
|
## What landed
|
|
|
|
- **Phase 0** (`730625e`) — top-of-file docstrings on every
|
|
`libs/*.py` and `hooks/*.py`; `# purpose:` headers on every
|
|
`bin/*` script. Discovery is `ls + head -1`.
|
|
- **Phase 1** (`04558a9`) — root `AGENTS.md` (with `CLAUDE.md`
|
|
symlink), `docs/agents/{conventions,commands}.md`, per-area
|
|
`AGENTS.md` for `bundles/`, `nodes/`, `groups/`, `libs/`,
|
|
`hooks/`, `data/`, `items/`, `bin/`. Mechanism-focused; no
|
|
enumeration of contents.
|
|
- **Convention pivot** (`9e1bb2a`) — per-bundle docs are plain
|
|
`README.md`, not `AGENTS.md`. No template. `bundles/AGENTS.md`
|
|
"Per-bundle README" gives loose orientation pointing at the
|
|
more substantial existing READMEs.
|
|
|
|
`bw test` exit 0 throughout. All internal links in the new docs
|
|
resolve. Commits sit on local `master`, none pushed.
|
|
|
|
## Where current truth lives
|
|
|
|
- Root entry: [`AGENTS.md`](../../../AGENTS.md) (symlinked to
|
|
`CLAUDE.md`).
|
|
- Repo conventions + bw command deltas:
|
|
[`docs/agents/`](../../agents/).
|
|
- Per-area docs: `<dir>/AGENTS.md` for each top-level dir.
|
|
- Per-bundle docs: existing `README.md` files (~33 of them);
|
|
guidance in [`bundles/AGENTS.md`](../../../bundles/AGENTS.md).
|
|
- Self-describing files: `libs/*.py`, `hooks/*.py`, `bin/*`.
|
|
|
|
## Source documents
|
|
|
|
- Spec: [`../specs/2026-05-10-agent-friendliness-design.md`](../specs/2026-05-10-agent-friendliness-design.md)
|
|
— 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).
|
|
- Implementation plan: `~/.claude/plans/btw-are-you-sure-crystalline-balloon.md`
|
|
(frozen pre-pivot artifact, outside the repo).
|
|
|
|
## What's open
|
|
|
|
Nothing planned. Per-bundle README updates are reactive — when a
|
|
bundle gets materially edited, top up its `README.md` then. The
|
|
~33 existing READMEs vary in quality and shape; that's accepted.
|
|
|
|
Two minor items the maintainer may want to clean up at some point:
|
|
|
|
- The implementation plan and the spec's §3 / §7 still describe
|
|
the pre-pivot per-bundle `AGENTS.md` convention. Spec's §0 flags
|
|
this; the plan is a frozen artifact and probably stays as-is.
|
|
- The original handoff's verification list mentioned `bw bundles`,
|
|
which isn't a real bw subcommand. Not user-facing in any current
|
|
doc.
|