/review-agentready command is stale: wrong attribute count, tier weights, and a nonexistent CLI flag

[kami619]

The /review-agentready command (.claude/commands/review-agentready.md) has drifted from the repo it reviews. It hardcodes an attribute count, tier weights, a self-assessment score, a source doc that no longer exists, and a CLI flag that was never implemented. Because the command instructs reviewers to calculate score impact from these constants, every review it produces emits confidently wrong numbers.

It also predates several AGENTS.md conventions, so it silently skips the checks most relevant to this repo — notably the docs/attributes.md sync rule, which matters for essentially every assessor PR.

Stale facts

Line	Command claims	Repo reality
10	"the 25 agentready attributes"	30 — src/agentready/data/default-weights.yaml has 30 keys summing to 1.0
10	Source doc agent-ready-codebase-attributes.md	File does not exist. Actual sources: docs/attributes.md, RESEARCH_REPORT.md
11, 104	"current: 80.0/100 Gold"	Hardcoded, unverifiable — no self-assessment artifact is committed. Drives the "Score Impact" and "Certification" lines of every review
63	Tier weights "Tier 1: 50%, Tier 2: 30%, etc."	58% / 27% / 13% / 2%
61	Example attribute ID "2.3 Type Annotations"	2.3 is Architecture Decision Records; type_annotations is 3.3
64	Remediation command agentready bootstrap --fix	Flag does not exist. src/agentready/cli/bootstrap.py accepts only --dry-run and --language
2	allowed-tools: ... Bash(python:*)	Missing pytest, black, isort, ruff, uv permissions — yet step 3 (Agent #1) instructs the reviewer to verify all of them. Bare python also fails; the repo needs PYTHONPATH=src python -m agentready or the uv venv
throughout	"Link to relevant CLAUDE.md sections"	Root CLAUDE.md is a single @AGENTS.md include — all actual guidance lives in AGENTS.md

Missing AGENTS.md conventions

The command was written before these existed and checks none of them:

• Agent Guideline 7 — keep docs/attributes.md in sync when an assessor's scoring changes (thresholds, partial credit, recognized paths, pass/fail conditions). This is the highest-value check for an assessor repo and is entirely absent.
• Agent Guideline 6 — self-assign a GitHub issue before starting work on it.
• Agent Guideline 4 — schema version bump for model changes.
• CI changes — run actionlint before pushing workflow changes.
• Weight-conservation invariant — new attributes must be funded by reducing existing weights so default-weights.yaml still sums to 1.0. Nothing in the command verifies this.
• New-entry house style — docs/attributes.md entries follow a fixed shape (**ID** / **Tier** / **Weight** / **Category** / **Status** block, then #### Definition / #### Why It Matters / #### Measurable Criteria / #### Remediation, then **Tools** / **Citations**). Nothing checks conformance.

Proposed fix

1. Replace hardcoded constants with values read at review time — attribute count and tier weights from src/agentready/data/default-weights.yaml, the baseline score from a fresh agentready assess . rather than a frozen 80.0.
2. Fix the broken references: point at docs/attributes.md, drop agentready bootstrap --fix, correct the 2.3 example, retarget "CLAUDE.md" to AGENTS.md.
3. Widen allowed-tools to cover the commands the review process actually runs (pytest, black, isort, ruff, uv, actionlint).
4. Add the missing AGENTS.md checks above, with the docs/attributes.md sync rule and the weight-conservation invariant as first-class review criteria.
5. Add a guard against this recurring — e.g. a test or CI step asserting the attribute count and tier weights quoted in the command still match default-weights.yaml.

Related

README.md:156-159 is stale in the same way: it claims 55% / 27% / 14% / 4% and lists progressive_disclosure under Tier 4, but it moved to Tier 3. Worth fixing alongside, though it is independent of the command itself.

Verification

$ python3 -c "import yaml; d=yaml.safe_load(open('src/agentready/data/default-weights.yaml')); print(len(d), sum(d.values()))"
30 1.0

$ ls agent-ready-codebase-attributes.md docs/agent-ready-codebase-attributes.md
ls: agent-ready-codebase-attributes.md: No such file or directory
ls: docs/agent-ready-codebase-attributes.md: No such file or directory

$ grep -o '"--[a-z-]*"' src/agentready/cli/bootstrap.py | sort -u
"--dry-run"
"--language"