Skip to content

docs: the maintainer bot does not exist — say what is true, and ask for help #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
john-the-dev wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: the maintainer bot does not exist — say what is true, and ask for help #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ 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
## Automation

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.
CI validates the schema and rubric on every PR; `node scripts/validate.mjs` runs the same checks locally and lists every `unrated` entry and every entry past the 90-day staleness bar.

There is **no bot proposing or grading entries** — grading requires independent sources a human has actually read, which is the whole point of the rubric. If that changes, this section changes with it.
4 changes: 2 additions & 2 deletions GRADING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. Nothing grades these automatically — an unrated entry is an open task, and `scripts/validate.mjs` lists them all. |

## Signals (what `evidence` should cite)

Expand All @@ -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. `scripts/validate.mjs` flags them; a human re-verifies and updates `last_verified` + `grade`.
6 changes: 4 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`, and every entry is graded by a human against a published rubric.

It's **dual-use**:
- **Human-browsable** — one markdown file per entry under [`entries/`](entries/).
Expand Down Expand Up @@ -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.

**The best first contribution is grading an `unrated` entry.** 48 of 59 entries are `unrated` today — `node scripts/validate.mjs` names every one of them. Pick one, find the independent sources the rubric asks for, and open a PR with `grade` + `evidence[]` filled in.

## Status

Expand Down
Loading