Skip to content

docs: AGENTS.md for agentic maintenance - #81

Open
adamstankiewicz wants to merge 3 commits into
design/warm-minimalfrom
docs/agents-md
Open

docs: AGENTS.md for agentic maintenance#81
adamstankiewicz wants to merge 3 commits into
design/warm-minimalfrom
docs/agents-md

Conversation

@adamstankiewicz

@adamstankiewicz adamstankiewicz commented Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

What & why

First piece of setting the repo up for agentic OSS maintenance: a real AGENTS.md beneath the auto-generated Next.js block — the four seams, the five review-failing invariants, the verification command list (with the stale-.next and stale-shell traps), the known drift hazards, and the diff conventions. Written so gates, not vibes, decide merges. References upcoming surfaces with "once X lands" phrasing so it's honest on main today.

Invariant 2 reworded — worth a look, since invariants are the review contract. "Student identity never reaches this server" read as "this server can never know who a student is", which the reference app already contradicts: its roster maps anonymous ids to names in the deployment's own storage adapter, and that is the intended design. An evaluator whose deployment needs attributable records — a university, an employer — read the old wording as a blocker and stopped. It now names the boundary the rule actually protects: identity must not arrive from an integration, and must not leak to one, while the in-deployment mapping is stated as supported rather than an exception. Nothing loosens; the wire rule is identical.

Type of change

  • Docs

Breaking or contract changes

None. Invariant 2's wording changed (above) but its scope did not — the same traffic is forbidden before and after.

How it was verified

  • Every command in the file was run during this repo's own sessions; every invariant traces to a shipped mechanism or governance rule
  • The auto-generated nextjs-agent-rules block is preserved byte-for-byte (it re-adds itself otherwise)

Authorship

  • I understand every line of this diff
  • Agent-assisted or agent-authored: authored by Claude — an agent writing the guide it wishes it had had, from the mistakes it actually made
  • No package.json / pnpm-lock.yaml changes

🤖 Generated with Claude Code

@vercel

vercel Bot commented Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
interactive-learning-experiences Ready Ready Preview Aug 31, 2026 12:39am

Request Review

@adamstankiewicz
adamstankiewicz changed the base branch from main to design/warm-minimal August 30, 2026 18:49
adamstankiewicz and others added 3 commits August 30, 2026 20:38
@adamstankiewicz @claude
docs: AGENTS.md — the repo as an agent-maintainable project
cd0b0fe 
The auto-generated Next.js block stays; below it, what an agent (or any
new contributor) needs to land a correct change unassisted: the four
seams and where to extend, the five invariants that fail review, the
full verification command list with the two expensive gotchas (stale
.next, stale widget shell), the hand-maintained-union and
completion-semantics traps, and the conventions that keep diffs
reviewable. Gates decide merges; this file makes the gates findable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: testing doctrine in AGENTS.md — which instrument for which code
e6d66c9 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: invariant 2 names the boundary it actually protects
c2a1eb7 
"Student identity never reaches this server" reads as "this server can
never know who a student is", which the reference app already contradicts:
its roster maps anonymous ids to names in the deployment's own storage
adapter, and that is the intended design. An evaluator whose deployment
needs attributable records — a university, an employer — reads the old
wording as a blocker and stops.

The rule being protected is the boundary, not the deployment: identity must
not arrive from an integration, and must not leak to one. Reworded to say
that, and to name the in-deployment mapping as supported rather than an
exception. No behavior changes and nothing loosens — the wire rule is
identical.

Stated self-contained rather than linking docs/evidence.md, which does not
exist until the landing-and-docs branch further up the stack.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@adamstankiewicz