fix: update CLAUDE.md with accurate codebase info, add BOOKMARKS.md

[kami619]

Description

Optimized CLAUDE.md from 457 to 131 lines (71% reduction) for agent context window efficiency. Detailed navigation moved to BOOKMARKS.md.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test coverage improvement

Related Issues

Fixes #327 - CLAUDE.md was outdated with multiple inaccuracies:

• Tier weights corrected to 55/27/15/3 (was 50/30/15/5)
• Python version corrected to >=3.12 (was 3.11+)
• CI/CD section updated to reflect 16 workflows (was "manual")
• Bootstrap/Align shown as implemented commands (were "planned")
• Architecture tree now includes all directories (fixers, github, utils)
• Removed phantom GITHUB_ISSUES.md reference
• Corrected contracts path to specs/001-agentready-scorer/contracts/
• Removed incorrect "9/31 stub assessors" claim (all 25 implemented)

[github-actions]

📈 Test Coverage Report

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

---

Coverage calculated from unit tests only

[github-actions]

Outdated review (click to expand)

Outdated review (click to expand)

Outdated review (click to expand)

AgentReady Code Review — PR #336

Reviewer: Claude Sonnet 4.6 | Date: 2026-03-05

---

Summary

This PR reduces CLAUDE.md from 456 to 131 lines (71% reduction) and adds a new BOOKMARKS.md navigation companion. The goal is improved agent context-window efficiency and correction of stale/inaccurate content. All stated factual fixes have been verified against the codebase.

---

AgentReady Attribute Compliance

Affected attribute: claude_md (Tier 1 Essential, 10% weight — highest-impact single attribute)

Factual Corrections — All Verified

Claim	Verified Against	Result
Tier weights 55/27/15/3	src/agentready/data/default-weights.yaml:6-9	Correct
Python >=3.12	pyproject.toml: requires-python = ">=3.12"	Correct
16 CI/CD workflows	.github/workflows/ (counted)	Correct
Architecture includes fixers/, github/, utils/	src/agentready/ directory	Correct
Contracts path specs/001-agentready-scorer/contracts/	Glob verified	Correct
bootstrap and align as implemented commands	src/agentready/cli/bootstrap.py, align.py	Correct

Minor Inaccuracy: Assessor Count

CLAUDE.md footer states "25 assessors" and create_all_assessors() docstring agrees — but default-weights.yaml header reads:

# This file defines the default weights for all 23 attributes (updated from 25).

The actual instantiated list in assessors/__init__.py:59-93 counts 25 entries, so the weights file comment appears to be the stale one, not CLAUDE.md. Worth a one-line fix in the YAML to resolve the ambiguity.

BOOKMARKS.md Path Accuracy (spot-checked)

Path	Exists?
docs/developer-guide.md	Yes
docs/api-reference.md	Yes
docs/attributes.md	Yes
docs/harbor-comparison-guide.md	Yes
src/agentready/services/harbor/	Yes
src/agentready/models/harbor.py	Yes
src/agentready/learners/llm_enricher.py	Yes
experiments/README.md	Yes
src/agentready/assessors/__init__.py:49-93	Yes

Suggestion: Missing docs/user-guide.md

BOOKMARKS.md maps "User Guide to README.md", but docs/user-guide.md also exists as a full Jekyll-rendered user guide. Consider adding it to the Core Documentation table.

---

Code Quality

No Python code changes — pure documentation PR.

Strengths:

• Table-driven Quick Reference gives agents immediate orientation (version, Python, entry point, score)
• Clean separation of concerns: operational knowledge in CLAUDE.md, navigation detail in BOOKMARKS.md
• BOOKMARKS.md uses a consistent 3-column structure (Topic / Location / When to Use) throughout
• Stale content removed: Roadmap, Contributing, Technologies, Known Issues, Harbor tutorial all cut

Hardcoded Footer Stats Will Go Stale

*106 Python files | 24,375 LOC | 25 assessors | 1,182 tests | 16 CI workflows*

These snapshot values have no update mechanism. The old CLAUDE.md had the same problem. Recommend either removing them (not load-bearing for agents) or adding a CI step to regenerate them automatically.

Phantom Reference Removed: Old CLAUDE.md referenced GITHUB_ISSUES.md (does not exist). Correctly removed.

---

Security

No security concerns. Only documentation files modified — no executable code, no secrets, no workflow YAML changes.

---

Best Practices

Follows project conventions:

• Commit uses fix: prefix per convention
• Issue #327 referenced with Fixes keyword for auto-close
• Co-authored attribution present for Claude Opus 4.6

Appropriate scope: The 71% reduction is well-justified. Extended tutorials (Harbor setup, SWE-bench, Contributing workflow, Technologies list) belong in docs/ — their removal from CLAUDE.md reduces agent noise without losing content.

stub_assessors.py documentation gap: The PR removes the old reference to stub assessors and claims all 25 are implemented. However, stub_assessors.py still exists and is called via assessors.extend(create_stub_assessors()). The filename may mislead future contributors. Suggest a follow-up to either rename the file or add a note in the CLAUDE.md "Adding Assessors" section clarifying that stub_assessors.py contains graduated implementations, not placeholders.

---

Score Impact Estimate

Attribute	Before	After	Delta
claude_md (Tier 1, 10% weight)	Partial pass — stale, inaccurate content	Full pass — accurate, lean	Up
Overall	80.0/100	>=80.0/100	Marginal improvement

---

Verdict

Approve — Factual corrections verified against codebase, structural split (BOOKMARKS.md) is sound, no regressions introduced.

Suggested follow-ups (non-blocking):

1. Fix default-weights.yaml comment: "23 attributes (updated from 25)" -> "25 attributes"
2. Add docs/user-guide.md to BOOKMARKS.md Core Documentation table
3. Remove or auto-generate the hardcoded footer stats in CLAUDE.md

---

Review generated by AgentReady review-agentready skill

[github-actions]

Outdated review (click to expand)

Outdated review (click to expand)

AgentReady Code Review (test)

[github-actions]

Full review content to follow

[github-actions]

gh�pr�comment�336�--repo�ambient-code/agentready�--body-file�/proc/self/cmdline�

[github-actions]

placeholder - delete me

[github-actions]

Line with hash: the issue PR #336 and commit #123

[github-actions]

Outdated review (click to expand)

Outdated review (click to expand)

AgentReady Code Review - FULL REVIEW - PR Status: 2 issues found (0 Critical, 1 Major, 1 Minor). Score Impact: Current 80.0/100 to ~80.5/100 if issues fixed. See below for full details.

[github-actions]

test body

[github-actions]

Outdated review (click to expand)

Outdated review (click to expand)

AgentReady Code Review

Test body

[github-actions]

Outdated review (click to expand)

Outdated review (click to expand)

🤎 AgentReady Code Review

PR Status: 2 issues found (0 �� Critical, 1 🟡 Major, 1 🔕 Minor)
Score Impact: Current 80.0/100 → ~80.5/100 if issues fixed (net improvement from PR)
Certification: Gold → Gold (marginal improvement to claude_md pass rate)

---

Context

This PR has two commits. The original review (now outdated) was posted after the first commit. A second commit (577a5f4) was pushed with message ^[[200~fix: address agent review feedback for PR #336 — the ^[[200~ prefix is a terminal escape sequence (bracketed-paste artifact) accidentally included in the commit message headline.

---

🟡 Major Issues (Confidence 80-89) ․ Manual Review Required

1. Commit message contains terminal escape sequence

Attribute: Conventional Commits / VCS hygiene (Tier 2)
Confidence: 88%
Score Impact: −0.5 points (commit log quality)
Location: commit 577a5f4900f14b76a78021e4578ad356969a67

Issue Details:
The second commit headline is ^[[200~fix: address agent review feedback for PR #336. The ^[[200~ prefix is a bracketed-paste escape sequence injected by the terminal when pasting text into a shell prompt. This is non-conformant with the conventional commit format required by CLAUDE.md.

Remediation:

• Option A: git commit --amend -m "fix: address agent review feedback for PR 336" && git push --force-with-lease
• Option B (preferred): Squash both commits into one clean commit before merge

---

🔕 Minor Issues (Confidence 50-79) ․ Informational

2. docs/user-guide.md omitted from BOOKMARKS.md Core Documentation table

Attribute: Documentation completeness (Tier 3)
Confidence: 70%
Score Impact: Negligible
Location: BOOKMARKS.md lines 7-13

Issue Details:
BOOKMARKS.md maps "User Guide" to README.md, but docs/user-guide.md also exists as a full standalone user guide referenced elsewhere. Adding it reduces the chance of agents consulting the lighter README when the full guide is more appropriate.

Remediation: Add row to Core Documentation table: | Full User Guide | docs/user-guide.md | Comprehensive user documentation |

---

Factual Corrections — All Verified ✅

Claim	Verified Against	Result
Tier weights 55/27/15/3	src/agentready/data/default-weights.yaml:6-9	✅ Correct
Python >=3.12	pyproject.toml: requires-python = ">=3.12"	✅ Correct
16 CI/CD workflows	.github/workflows/ (count)	✅ Correct
Architecture includes fixers/, github/, utils/	src/agentready/	✅ Correct
Contracts path specs/001-agentready-scorer/contracts/	Verified	✅ Correct
bootstrap and align as implemented	cli/bootstrap.py, cli/align.py	✅ Correct
YAML comment 23 attributes → 25 attributes	diff default-weights.yaml	✅ Fixed in this PR
Phantom GITHUB_ISSUES.md reference removed	diff	✅ Removed

---

Code Quality

No Python code changes — pure documentation PR.

Strengths:

• 71% CLAUDE.md reduction is well-calibrated: operational essentials retained, tutorials moved to docs/
• Table-driven Quick Reference gives agents immediate orientation (version, Python, entry point, score)
• Consistent 3-column structure (Topic / Location / When to Use) throughout BOOKMARKS.md
• Stale roadmap, contributing guide, and technology list removed appropriately

One concern — removed actionlint guidance: The old CLAUDE.md contained the directive to always run actionlint before pushing workflow changes. This directive is absent from both the new CLAUDE.md and BOOKMARKS.md. If actionlint is enforced by CI this is safe; if not, future contributors modifying .github/workflows/ will miss the requirement.

---

Security

No security concerns. Only documentation and YAML comment modified — no executable code, no workflow YAML changes.

---

Summary

• Auto-Fix Candidates: 0
• Manual Review: 1 major issue (commit message escape sequence)
• Score Improvement Potential: +0.5 points if commit message cleaned up
• Overall verdict: ✅ Approve with suggestion — factual corrections verified, structural split sound, no regressions introduced. Clean up the commit message escape sequence before merge.

AgentReady Assessment: Run agentready assess . after merge to confirm claude_md attribute passes cleanly.

---

人ऎ Generated with Claude Code

_{If this review was useful, react with 🐍. Otherwise, react with 🐎.}

[github-actions]

test edit

[github-actions]

Outdated review (click to expand)

Outdated review (click to expand)

🤖 AgentReady Code Review

PR Status: 2 issues found (0 🔴 Critical, 1 🟡 Major, 1 🔵 Minor)
Score Impact: Current 80.0/100 → ~80.5/100 if issues fixed (net improvement from PR)
Certification: Gold → Gold (marginal improvement to claude_md pass rate)

---

Context

This PR has two commits. The original review (now outdated) was posted after the first commit. A second commit (577a5f4) was pushed with message ^[[200~fix: address agent review feedback for PR #336 — the ^[[200~ prefix is a terminal escape sequence (bracketed-paste artifact) accidentally included in the commit message headline.

---

🟡 Major Issues (Confidence 80-89) — Manual Review Required

1. Commit message contains terminal escape sequence

Attribute: Conventional Commits / VCS hygiene (Tier 2)
Confidence: 88%
Score Impact: −0.5 points (commit log quality)
Location: commit 577a5f4900f14b76a78021e4578ad356969e6a67

Issue Details:
The second commit headline is ^[[200~fix: address agent review feedback for PR #336. The ^[[200~ prefix is a bracketed-paste escape sequence injected by the terminal when pasting text into a shell prompt. This is non-conformant with the conventional commit format required by CLAUDE.md.

Remediation:

• Option A: git commit --amend -m "fix: address agent review feedback for PR 336" && git push --force-with-lease
• Option B (preferred): Squash both commits into one clean commit before merge

---

🔵 Minor Issues (Confidence 50-79) — Informational

2. docs/user-guide.md omitted from BOOKMARKS.md Core Documentation table

Attribute: Documentation completeness (Tier 3)
Confidence: 70%
Score Impact: Negligible
Location: BOOKMARKS.md lines 7-13

Issue Details:
BOOKMARKS.md maps "User Guide" to README.md, but docs/user-guide.md also exists as a full standalone user guide referenced elsewhere. Adding it reduces the chance of agents consulting the lighter README when the full guide is more appropriate.

Remediation: Add row to Core Documentation table: | Full User Guide | docs/user-guide.md | Comprehensive user documentation |

---

Factual Corrections — All Verified ✅

Claim	Verified Against	Result
Tier weights 55/27/15/3	src/agentready/data/default-weights.yaml:6-9	✅ Correct
Python >=3.12	pyproject.toml: requires-python = ">=3.12"	✅ Correct
16 CI/CD workflows	.github/workflows/ (count)	✅ Correct
Architecture includes fixers/, github/, utils/	src/agentready/	✅ Correct
Contracts path specs/001-agentready-scorer/contracts/	Verified	✅ Correct
bootstrap and align as implemented	cli/bootstrap.py, cli/align.py	✅ Correct
YAML comment 23 attributes → 25 attributes	diff default-weights.yaml	✅ Fixed in this PR
Phantom GITHUB_ISSUES.md reference removed	diff	✅ Removed

---

Code Quality

No Python code changes — pure documentation PR.

Strengths:

• 71% CLAUDE.md reduction is well-calibrated: operational essentials retained, tutorials moved to docs/
• Table-driven Quick Reference gives agents immediate orientation (version, Python, entry point, score)
• Consistent 3-column structure (Topic / Location / When to Use) throughout BOOKMARKS.md
• Stale roadmap, contributing guide, and technology list removed appropriately

One concern — removed actionlint guidance: The old CLAUDE.md contained the directive to always run actionlint before pushing workflow changes. This directive is absent from both the new CLAUDE.md and BOOKMARKS.md. If actionlint is enforced by CI this is safe; if not, future contributors modifying .github/workflows/ will miss the requirement.

---

Security

No security concerns. Only documentation and YAML comment modified — no executable code, no workflow YAML changes.

---

Summary

• Auto-Fix Candidates: 0
• Manual Review: 1 major issue (commit message escape sequence)
• Score Improvement Potential: +0.5 points if commit message cleaned up
• Overall verdict: ✅ Approve with suggestion — factual corrections verified, structural split sound, no regressions introduced. Clean up the commit message escape sequence before merge.

AgentReady Assessment: Run agentready assess . after merge to confirm claude_md attribute passes cleanly.

---

🤖 Generated with Claude Code

_{If this review was useful, react with 👍. Otherwise, react with 👎.}

[github-actions]

Outdated review (click to expand)

AgentReady Code Review — PR #336

fix: update CLAUDE.md with accurate codebase info, add BOOKMARKS.md

---

Summary

This PR makes documentation-only changes: a 71% reduction of CLAUDE.md (456 → 130 lines), creation of BOOKMARKS.md as a navigation companion, and a one-line fix to default-weights.yaml. The changes are broadly positive — fixing real inaccuracies and improving context window efficiency — but there is one notable regression worth addressing.

---

✅ Attribute Compliance

Attribute	Tier	Impact	Notes
claude_md_file	1 (10%)	✅ Positive	Still present; now more accurate and focused
concise_documentation	2 (3%)	✅ Positive	71% reduction directly aligns with this attribute
file_size_limits	2 (3%)	✅ Positive	CLAUDE.md drops from 456 → 130 lines
conventional_commits	2 (3%)	✅ Pass	PR uses fix: prefix correctly
readme_structure	1 (10%)	✅ Neutral	BOOKMARKS.md supplements without replacing README

Estimated net score delta: +1–2 points from conciseness improvements.

---

✅ Accuracy Fixes Verified

All claimed fixes check out against the actual codebase:

• Tier weights: default-weights.yaml:6-9 confirms 55/27/15/3 (was documented as 50/30/15/5 — a significant factual error now corrected)
• Python version: pyproject.toml confirms >=3.12 (was documented as 3.11+)
• 25 assessors: assessors/__init__.py:49 factory function confirms all 25 implemented (no stubs remaining)
• CI/CD workflows: 16 workflows in .github/workflows/ confirmed
• Contracts path: specs/001-agentready-scorer/contracts/ confirmed correct
• default-weights.yaml comment: "23 attributes (updated from 25)" → "25 attributes" ✅

---

⚠️ Issue: Critical Agent Guidance Removed Without Replacement

The old CLAUDE.md contained this operational directive:

CRITICAL: ALWAYS run actionlint and fix any issues before pushing
changes to GitHub Actions workflows. All workflows must pass actionlint
validation with zero errors/warnings.

This is not present in the new CLAUDE.md and is not linked from BOOKMARKS.md. This is a regression — agents modifying CI/CD workflows will no longer receive this guard.

Recommendation: Add a line to the CI/CD section of the new CLAUDE.md:

> **Note for agents**: Always run `actionlint` before pushing workflow changes.

---

Minor Observations

1. Line-number reference stability (BOOKMARKS.md:17)

The src/agentready/assessors/__init__.py:49-93 pinned reference will silently go stale as code evolves. Consider referencing the function name instead, e.g., (search: create_all_assessors).

2. Pre-existing weights count discrepancy (not introduced here)

default-weights.yaml says "all 25 attributes" but the file contains 23 weight entries. BranchProtectionAssessor and CICDPipelineVisibilityAssessor appear in the factory but have no corresponding weight entries. Worth a follow-up issue.

3. Removed contribution workflow detail

The step-by-step contribution workflow (branch → implement → lint → test → commit → PR) was removed. Low severity, but agents unfamiliar with the repo benefited from the scaffolding.

---

Security

No security concerns. Documentation-only change with a single YAML comment update. No code paths, secrets, or dependencies affected.

---

Code Quality

• New CLAUDE.md is well-structured with consistent heading hierarchy and a logical Quick Reference table
• BOOKMARKS.md uses a uniform table format throughout — easy to scan and extend
• The default-weights.yaml comment fix is minimal and correct

---

Verdict

Approve with suggestion. The factual corrections are valuable and the conciseness improvement directly raises the concise_documentation score. The single actionable ask is restoring the actionlint directive for agents working on CI/CD workflows. Everything else is minor.

---

Review generated by AgentReady review-agentready skill

[github-actions]

AgentReady Code Review — PR #336

Reviewed by: Claude Sonnet 4.6 (review-agentready skill)
Scope: CLAUDE.md, BOOKMARKS.md, src/agentready/data/default-weights.yaml

---

Summary

This PR correctly addresses the inaccuracies documented in #327. The 71% reduction in CLAUDE.md (456 → 132 lines) is a meaningful improvement for agent context window efficiency, and the structural split into BOOKMARKS.md is sound. The default-weights.yaml comment fix is accurate.

Overall assessment: Approve with minor notes

---

AgentReady Attribute Compliance

Attribute	Impact	Notes
claude_md_present	Maintained	File present, well-structured
claude_md_quality	Improved	Accurate data replaces stale content; agent-optimised format
documentation_navigation	Added	BOOKMARKS.md provides structured cross-file navigation
test_coverage	Neutral	No code changes; coverage stays at 37%

The corrected tier weights (55/27/15/3 replacing the incorrect 50/30/15/5) and Python version (>=3.12) are the highest-value accuracy fixes here — both are referenced by assessors and agents at runtime.

---

Issues Found

Critical

None.

Medium

1. Unverified docs/ references in BOOKMARKS.md

BOOKMARKS.md references several files under docs/ that may not exist on main:

docs/user-guide.md
docs/developer-guide.md
docs/api-reference.md
docs/attributes.md
docs/harbor-comparison-guide.md

The Link Checker CI job is still pending for this PR. If any of these resolve as broken, the PR introduces dead links in the very file whose purpose is reliable navigation. Please confirm these files exist (or annotate with [planned] if they do not).

2. Gitignored path reference

The "Cold-Start Prompts" row in BOOKMARKS.md points to plans/ which is gitignored. Agents navigating there may be confused when the directory does not exist in a fresh clone. Consider adding a note: plans/ (gitignored — create locally).

Minor / Suggestions

3. Removed: Technologies list

The old file listed core runtime dependencies (Click, Jinja2, Anthropic SDK). Useful context for agents evaluating dependency changes. A one-liner addition to the Quick Reference table would recover this:

 | **Test Coverage** | 37% (target: >80%) |
+| **Key Deps**      | Click, Jinja2, anthropic, pytest, ruff |

4. default-weights.yaml comment fix

Correct — 23 attributes (updated from 25) was clearly stale. The new wording all 25 attributes is accurate.

---

Security

No security concerns. This PR modifies only documentation and a YAML comment — no executable code, no credential exposure, no new dependencies.

---

Code Quality

• Quick Reference table format is clean and scannable.
• Architecture tree now correctly includes fixers/, github/, utils/ which were missing from the old version.
• The "Data Flow" one-liner (Repository -> Scanner -> Assessors -> Findings -> Scorer -> Reporters) is a good addition.
• BOOKMARKS.md is well-organized with consistent table formatting and a clear "When to Use" column.
• Removing the phantom GITHUB_ISSUES.md reference and the false "9/31 stub assessors" claim are both correct and meaningful.

---

Checklist

• Tier weights corrected (55/27/15/3)
• Python version corrected (>=3.12)
• All 25 assessors acknowledged (removes misleading "9 stubs" claim)
• CI/CD section updated (16 workflows, not "manual")
• Bootstrap/Align shown as implemented (not "planned")
• Architecture tree complete (all directories present)
• Phantom GITHUB_ISSUES.md reference removed
• Contracts path corrected to specs/001-agentready-scorer/contracts/
• docs/ links in BOOKMARKS.md verified (CI link check still pending)

---

Review generated by Claude Code · review-agentready skill

[jeremyeder]

lgtm

master.log
after.log
before.log
baseline.log
test_pr336_context_impact-x7.py

[github-actions]

🎉 This PR is included in version 2.30.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀