Skip to content

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.md is the body above plus the block and nothing else; CLAUDE.md is the reference's text; README.md holds every "Move" row's text.
  • The block's digest equals the one saved in step 1.
  • task docs:generate, task lint and task validate pass.

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.