Proposal: Auto-generated Agent Index for README.md

[cyberpinkman]

Problem

The repository now has 100+ agents across 13+ categories. During the recent triage session, missing README entries were a recurring problem (e.g. finance division, 14 specialized agents). Keeping the README index in sync by hand is error-prone and does not scale.

Proposed Solution

A script (scripts/generate-readme-agent-index.sh) that scans agent .md files and generates a consistent Agent Index section in README.md, with CI verification to catch drift on pull requests.

A draft implementation exists in #361 .

Design Options

Option A: Auto-generation only

• Script regenerates the full index in-place between markers
• CI checks that the generated section matches source files
• Pro: guaranteed consistency, zero drift
• Con: contributors cannot hand-edit the index section

Option B: Validation-only

• CI checks that README entries match agent source files
• Fails the build on drift, but does not auto-overwrite
• Contributors fix manually or run a helper script
• Pro: preserves all manual edits
• Con: more friction, drift still possible if warnings are ignored

Option C: Hybrid (my current preference)

• The index itself is auto-generated between <!-- BEGIN GENERATED AGENT INDEX --> and <!-- END GENERATED AGENT INDEX --> markers — the script only touches this region
• A separate notes section (<!-- BEGIN AGENT INDEX NOTES --> … <!-- END AGENT INDEX NOTES -->) sits after the generated index and is preserved across regenerations — contributors can add supplementary context, cross-references, or annotations there, or leave it empty
• CI only validates the generated portion; the notes section is completely untouched by the script

Why I lean toward Option C:

• The auto-generated index ensures consistency and makes it easy to add new categories — all driven from source files
• The notes section gives contributors an escape valve for anything the generator does not capture, without undermining the consistency of the main index
• Keeps the implementation simple (one pair of extra markers, a few lines of script logic)
• Low-risk: the existing roster tables in README are untouched; this only adds a new isolated section

Request for Feedback

• Does the hybrid approach (Option C) address the concern about contributors not being able to hand-edit?
• Should the notes section be a single global area, or per-category?
• Any other approaches I haven't considered?

Happy to adapt the implementation based on what the community prefers. Thanks!