refactor: slim down context files, adopt AGENTS.md as canonical

[jwm4]

Summary

• Make CLAUDE.md a one-line @AGENTS.md reference
• Rewrite AGENTS.md to remove information agents can discover on their own
• AGENTS.md reduced from 136 lines to 58 lines

Removed (discoverable by agents via ls, find, grep, or reading config files):

• Directory tree (stale, redundant with ls)
• Attribute counts, self-score, test coverage percentages (stale instantly)
• Key Files table, reference implementation list (searchable)
• Tier weight percentages (in default-weights.yaml)
• CI workflow count and names (in .github/workflows/)
• Python version, entry point (in pyproject.toml)
• BOOKMARKS.md pointer

Kept (not discoverable or behavioral):

• Development commands (especially the PYTHONPATH trick)
• Data flow concept
• Certification level thresholds
• How to add assessors (workflow steps)
• Key patterns (proportional scoring, graceful degradation, Finding API)
• Commit conventions, linting commands, actionlint requirement
• Agent behavioral guidelines (self-assign, docs sync, etc.)

Test plan

• agentready assess . still reads CLAUDE.md via @AGENTS.md reference
• Linters pass

Posted by Bill Murdock with assistance from Claude Code.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guidelines documentation covering workflow commands, development practices, scoring patterns, and contributor conventions.
  • Reorganized and consolidated documentation structure for improved reference.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 0b20b8a7-935d-4f0e-aaa9-bae0d10265fe

📥 Commits

Reviewing files that changed from the base of the PR and between c5d9bef and eee3227.

📒 Files selected for processing (2)

• AGENTS.md
• CLAUDE.md

---

📝 Walkthrough

Walkthrough

PR consolidates contributor and operational documentation by creating a new AGENTS.md file with comprehensive agentready workflow guidance and reducing CLAUDE.md to a single reference pointer.

Changes

Documentation Consolidation

Layer / File(s)	Summary
Agent documentation and reference AGENTS.md, CLAUDE.md	AGENTS.md adds 67 lines of contributor/agent documentation covering agentready commands, data flow architecture, scoring thresholds, assessor creation guidelines, coding/testing/lint conventions, CI expectations, and agent behavior patterns. CLAUDE.md is consolidated from 136 lines to a single-line reference to AGENTS.md.

Possibly Related PRs

• ambient-code/agentready#393: Both PRs modify CLAUDE.md content—chore: remove version from CLAUDE.md #393 removes the "Version" row, while this PR consolidates the entire file into a reference to the new AGENTS.md.

Suggested Labels

released

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title follows Conventional Commits format with type 'refactor', includes a clear scope, and accurately describes the main change: consolidating documentation by slimming down context files and promoting AGENTS.md as canonical.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/agents-md-refactor

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch chore/agents-md-refactor

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

📈 Test Coverage Report

Branch	Coverage
This PR	73.1%
Main	73.1%
Diff	✅ +0%

---

Coverage calculated from unit tests only

[coderabbitai]

Actionable comments posted: 0

[github-actions]

🎉 This PR is included in version 2.44.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀