justinmclean opened a new pull request, #479:
URL: https://github.com/apache/airflow-steward/pull/479
## Summary
### What and why
AGENTS.md had grown to ~20K tokens (~1,730 lines). Per review feedback,
large always-loaded instruction files are better kept small, with agents
retrieving detail on demand. This reshapes AGENTS.md into a concise
glossary plus the load-bearing rules, and relocates elaboration into
focused docs that are pulled in only when relevant.
AGENTS.md is now ~10.8K tokens (~940 lines), roughly 46% smaller, with no
change to behaviour.
### What changed
- Extracted the full editorial playbook (tone, email brevity, Gmail
threading, ASF-relay drafting, dependency-claim phrasing, CVE and
tracker/PR link formats, maintainer @-mentions) into
`docs/editorial-guidelines.md`. AGENTS.md keeps a short normative
summary under each referenced anchor plus a "load this before drafting"
pointer.
- Extracted two confidentiality drafting elaborations ("sharing a tracker
URL with someone who cannot access it" and "where tracker URLs are
routinely OK to use") into `docs/confidentiality.md`. The three-layer
rule, the "what public surfaces must not contain" checklist, the content
scrub, and "other ASF projects" all stay inline.
- Compressed in place, pointing at existing canonical docs: the skills
catalogue, evals/mode-economics, local setup, per-project config, and
labeling.
- Trimmed only rationale and examples in the safety sections
(prompt-injection, confidentiality, privacy-LLM, CVSS). Every imperative
stays inline.
- Cleanups: removed a duplicated line in References, fixed two stale
"Reporter emails: CVE ID only" pointers (the subsection moved to
`docs/editorial-guidelines.md`), corrected a wrong anchor in
`projects/_template/pr-management-code-review-criteria.md`
(`#commits-and-prs` to `#commit-and-pr-conventions`), and added the
print-mode self-eval discipline to `tools/skill-evals/README.md` so the
evals pointer is accurate.
- Regenerated the doctoc TOC.
### Behaviour preservation
This is a documentation-only change. No skill, tool adapter, or runtime
code was touched. Verified that:
- Every normative imperative in the old AGENTS.md survives, inline or in a
pointer target that actually contains it (audited via an imperative-token
diff of old vs new; all dropped occurrences were rationale or examples).
- The moved content is preserved (confidentiality verbatim; editorial
verbatim apart from link-label adjustments).
- All anchor links resolve, and all external references to AGENTS.md
anchors still resolve.
- An independent review of the diff found no rule lost, weakened, or
drifted, and no pointer that over-promises.
### Generative-AI disclosure
Drafted with AI assistance and reviewed by the author before submission.
## Type of change
- [ ] Skill change (`.claude/skills/<name>/`) — eval fixtures updated below
- [ ] Tool / bridge contract (`tools/<system>/*.md`)
- [ ] Python package (`tools/*/` with `pyproject.toml`)
- [ ] Groovy reference impl
- [ ] Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
- [X] Documentation (`docs/`, `README.md`, `CONTRIBUTING.md`)
- [ ] Project template (`projects/_template/`)
- [ ] CI / dev loop (`prek`, workflows, validators)
- [ ] Other:
## Test plan
- [X] `prek run --all-files` passes
- [ ] For Python packages touched: `uv run pytest` / `ruff check` / `mypy`
passes
- [ ] For Groovy bridges touched: command-line invocation tested end-to-end
- [ ] For skill changes: eval suite passes for the affected skill
(`PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner
tools/skill-evals/evals/<skill>/`)
- [ ] For skill *behaviour* changes: a new or updated eval fixture is
included in this PR
(a regression test for the bug fixed / the behaviour added — see
CONTRIBUTING.md)
- [ ] Other:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
