F16.7 — Instruction files follow kiln's standard
| State | Closed |
| Parent | E16 |
| Iteration | Release 8 |
| Start Date | 2026-11-13 |
| Closed Date | 2026-11-13 |
| Predecessors | F16.3 |
| Source | Owner decision, 2026-11-09: pykit follows kiln's standard for its instruction files |
Stories: 1 Closed
| Story | State | Depends on |
|---|---|---|
S16.7.1 — Move the instructions into AGENTS.md and README.md |
Closed | S16.3.1 |
pykit's CLAUDE.md carries about 120 lines of its own prose, and its
README.md says that CLAUDE.md is the agent-instruction file. kiln's standard
splits the instruction files by audience: README.md is for people, AGENTS.md
holds what an agent needs beyond it (with kiln's block), and CLAUDE.md is
@AGENTS.md plus what only Claude should read. This feature moves the prose.
Context
Outcome: S16.3.1 step 3 left pykit's prose in CLAUDE.md and kiln's block
in AGENTS.md; S16.7.1 ran after it and reversed that, so S16.3.1's 31 0
check on AGENTS.md is a point-in-time check of the cutover commit. pykit keeps
its own README.md and leaves out the reference's placeholder ## Examples and
## Story workflow sections.
S16.7.1 — Move the instructions into AGENTS.md and README.md
State: Closed · Depends on: S16.3.1
Outcome: every part of the old CLAUDE.md moved to README.md
(## Working here, ## Conventions) or AGENTS.md (## Start here,
## Rules, ## Guardrails, ## Do and don't), or was dropped where the README
or kiln's block already says it; CLAUDE.md is @AGENTS.md plus
## Claude-only, and kiln's block is untouched.
Acceptance:
AGENTS.mdis the body above plus the block and nothing else;CLAUDE.mdis the reference's text;README.mdholds every "Move" row's text.- The block's digest equals the one saved in step 1.
task docs:generate,task lintandtask validatepass.
Outcome: it ran on feature/release-8 after the cutover merge (2026-11-13),
where task lint failed only at pip-audit on opentelemetry-api 1.45.1, as
the base tree did.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
# AGENTS.md: the body, then the block unchanged, nothing after it
test "$(sed -n '/BEGIN rn-forge kiln/,/END rn-forge kiln/p' AGENTS.md | shasum -a 256)" = "$(cat "${TMPDIR:-/tmp}"/pykit-kiln-block.sha)"
test "$(sed -n '/END rn-forge kiln/,$p' AGENTS.md | wc -l | tr -d ' ')" = 1
test "$(sed -n 1p AGENTS.md)" = "# AGENTS.md"
grep -q '^## Start here$' AGENTS.md
grep -q '^## Guardrails$' AGENTS.md
absent 'Read `CLAUDE.md` now|Constraints that bite|Orientation' AGENTS.md
# CLAUDE.md: the import and the Claude-only section, no block, no prose
test "$(sed -n 1p CLAUDE.md)" = "@AGENTS.md"
grep -q '^## Claude-only$' CLAUDE.md
absent 'BEGIN rn-forge kiln|Docstrings describe|uv run' CLAUDE.md
# README: the moved sections exist once, the conventions are not repeated elsewhere
test "$(grep -c '^## Working here$' README.md)" = 1
test "$(grep -c '^## Conventions$' README.md)" = 1
grep -q 'Docstrings describe the contract' README.md
grep -q 'pytest-randomly' README.md
absent 'Docstrings describe the contract' AGENTS.md CLAUDE.md
absent 'is the agent-instruction file' README.md
task docs:generate
task lint
task validate
task validate is the gate; run it once, after task lint.
Open questions
None. Every part of CLAUDE.md has a row above.