[goosewobbler]

Reworks AGENTS.md around the principle that comprehensive / auto-generated context files hurt agent performance — a global instruction is spent on every request even when irrelevant. Keep only what an agent can't derive by exploring; move everything deterministic into tooling that fires exactly when relevant.

AGENTS.md: 103 → 16 lines

Kept only the non-derivable core: the six release architecture invariants, one orientation line (standing-PR / release/next), and a pointer to docs/adr/. Cut tech-stack, monorepo tree, verification gate, coding-standards prose, testing locations, doc tables, and the "read the tree" boilerplate — all derivable or now tooling-enforced.

Guidance moved into deterministic tooling

Test-title convention → eslint. "every it/test title starts with should" is now vitest/valid-title (mustMatch: ^should) in eslint.config.js (+ fixed the one straggler).

"Never hand-edit generated files" → banner + CI check. Each generated file now has both layers, so the AGENTS.md prose is redundant and removed:

• releasekit.schema.json gains a $comment banner (it lacked one — the config docs already had theirs), self-documenting on open.
• docs/configuration.md gains a CI check (docs:check, mirroring schema:check), so a hand-edit fails the build — it previously had only a banner, no enforcement.

Discovery (banner) catches it in-context; the CI check is the deterministic backstop that fires regardless of whether any agent read anything.

Relationship to #573

Supersedes the comment-ref codification that was on this branch (we're removing prose, not adding it). Remaining #573 work (bare-#NNN cleanup + a custom comment-ref lint rule) and the other replacements (pre-push hook, commitlint) are follow-ups.

Validation

• eslint + biome clean; the schema-generator test passes; schema:check and docs:check both green.
• Negative test: a hand-edit to docs/configuration.md now fails docs:check.

🤖 Generated with Claude Code

Greptile Summary

This PR moves repository guidance into focused lint and CI enforcement. The main changes are:

• Slimmed AGENTS.md to release architecture invariants.
• Enforced test titles and comment references through ESLint.
• Added a CI freshness check for generated configuration docs.
• Added generated-file notices to the schema and configuration docs.
• Regenerated the example smoke workflow from its templates.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues were found in the updated code.

Important Files Changed

Filename	Overview
AGENTS.md	Keeps the non-derivable release invariants and removes guidance now enforced or discoverable elsewhere.
eslint.config.js	Adds lint rules for test-title conventions and bare issue references in source comments.
scripts/generate-config-docs.ts	Adds check-mode support for detecting stale generated configuration documentation.
.github/workflows/ci.yml	Runs the generated configuration-document check in CI.
.github/workflows/examples-smoke.yml	Synchronizes generated smoke-test setup steps with the source example workflows.

_{Reviews (6): Last reviewed commit: "chore(ci): regenerate examples-smoke.yml..." | Re-trigger Greptile}

[github-actions]

Standing release PR: #595 · v0.41.2 queued (4 packages) · open 4h 52m · ✅ ready to merge

Release Preview — v0.41.1 → v0.41.2

Note: Labels on this PR are advisory in standing-pr mode. Bumps come from conventional commits in the standing PR; override by editing labels on the standing PR itself. Add release:immediate to bypass the standing PR and release this PR directly.

These changes will be added to the release PR (#595) when merged:

Changelog

monorepo 0.41.1 → 0.41.2

Changed

• regenerate examples-smoke.yml to match the example templates (ci)
• sweep bare issue refs from source comments; enforce in eslint (PR #600)
• enforce comment + test-title issue-ref conventions in eslint (lint) (PR #599)
• make generated files self-guarding; drop the AGENTS.md prose (config)
• slim AGENTS.md to non-derivable context; move test-title rule to eslint (agents)

Fixed

• recover the release tags output from git when stdout can't be parsed (action) (PR #597)
• retry action-dist network ops and auto-heal failed releases (ci) (PR #596)

All packages → 0.41.2 (sync versioning)

• @releasekit/version
• @releasekit/notes
• @releasekit/publish
• @releasekit/release

After merge — predicted release

No version escalation — this PR's changes will be included in the queued release without affecting the projected versions.

Package	Standing PR	This PR	After merge
monorepo	0.41.2	0.41.2	0.41.2

---

Updated automatically by ReleaseKit