diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0dc4d3..fcfb7bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,6 @@ Thanks for helping keep AI-agent engineering knowledge accurate and fresh. - **Lessons are public-only.** `category: lessons` entries must come from famous, publicly-documented projects/post-mortems. Never include private, proprietary, or non-public project details (anyone's). - **Primary sources first** — official docs / papers / release notes over secondhand blogs. -## The maintainer bot +## The maintainer bot (planned) -An automated maintainer (Sutando) also opens PRs — proposing new entries from the latest releases/research and flagging entries whose `last_verified` is >90 days old. Bot PRs are reviewed and merged by a human, same as any other. +An automated maintainer that proposes new entries and flags entries whose `last_verified` is >90 days old is planned but **not running yet**. Until it exists, both jobs are human: `scripts/validate.mjs` warns on every `unrated` entry, and stale ones are found by the same rubric a bot would apply. Bot PRs, when they arrive, will be reviewed and merged by a human like any other. diff --git a/GRADING.md b/GRADING.md index 0cca5c0..5f010b6 100644 --- a/GRADING.md +++ b/GRADING.md @@ -10,7 +10,7 @@ Grades exist so "bad tech" and "outdated knowledge" are **evidence-based, not op | **B** | Solid and useful, with caveats. Maintained but niche, or accurate-but-aging, or best-for-specific-cases. Note the caveat in `evidence`. | | **C** | Use with caution. Slowing maintenance, partial adoption, known rough edges, or partially superseded. | | **D** | Discouraged. Deprecated, abandoned, superseded, or carrying unresolved security/correctness issues. Kept for the historical record and to warn readers — set `status: deprecated` (or `superseded`) and fill `superseded_by`. | -| **unrated** | Seeded or newly-added, not yet evidence-graded. The maintainer bot grades these on its next pass. | +| **unrated** | Seeded or newly-added, not yet evidence-graded. `scripts/validate.mjs` warns on each one; grading them is open contribution work. | ## Signals (what `evidence` should cite) @@ -35,4 +35,4 @@ Each `evidence` item should be a dated, checkable statement, e.g.: ## Staleness -An entry is **stale** when `last_verified` is more than **90 days** old. The maintainer bot flags stale entries in a `review-needed` PR; a human (or the bot with evidence) re-verifies and updates `last_verified` + `grade`. +An entry is **stale** when `last_verified` is more than **90 days** old. Re-verify it and update `last_verified` + `grade` with fresh evidence. (Automated flagging is planned; today this is a manual check — as of the last measurement no entry was over 90 days.) diff --git a/README.md b/README.md index a692219..9763d90 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A continuously-maintained, **quality-graded** knowledge base of AI-agent engineering — frameworks, orchestration, evaluation, memory, tools, protocols, security, and research. -Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`, and an automated maintainer bot proposes additions and flags stale entries for review. +Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`. An automated maintainer that proposes additions and flags stale entries is planned, not yet running — grading is done by maintainers and contributors today. It's **dual-use**: - **Human-browsable** — one markdown file per entry under [`entries/`](entries/). @@ -23,7 +23,7 @@ It's CC BY 4.0: any surface using this content must visibly credit **The Agent L ``` entries/*.md ──build──▶ dist/kb.json ──ingest──▶ agent-loop.xyz RAG ▲ - └── humans (PRs) + Sutando maintainer-bot (auto-PRs new entries, flags stale) + └── humans (PRs) [maintainer-bot: planned, not yet running] ``` ## Entry format @@ -55,7 +55,9 @@ Entries are graded **A/B/C/D** on an evidence-based rubric (see [`GRADING.md`](G ## Contributing -PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. The maintainer bot opens PRs too; humans review and merge. +PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. + +**Good first contribution:** any entry `scripts/validate.mjs` still flags as `grade: unrated`, or any entry whose `evidence` you can strengthen — or contradict — with a dated, checkable source. [`GRADING.md`](GRADING.md) is the rubric, and re-grading against it counts as much as first-grading. One entry, evidenced, is a complete and useful PR. ## Status