AgentReady scores other repos on agent-readiness, but its own .claude/ directory carries ~42 KB of files that never load, two hooks that silently do nothing, and nine slash commands that have never been invoked. A /doctor context audit turned these up. Each is verified below.
1. Both hooks in .claude/settings.json are silent no-ops
.claude/settings.json (added in efe7507, #484) configures two hooks. Neither works, and both are engineered to fail silently — 2>/dev/null, ; true, and || true suppress every signal.
"PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command",
"command": "black --quiet \"$CLAUDE_FILE_PATH\" 2>/dev/null; isort --quiet \"$CLAUDE_FILE_PATH\" 2>/dev/null; true" }]}],
"PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command",
"command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE|--force' && echo 'BLOCK: destructive command' && exit 1 || true" }]}]Three independent failures:
a) $CLAUDE_FILE_PATH and $CLAUDE_TOOL_INPUT are not hook environment variables. Claude Code passes the tool payload to hooks as JSON on stdin. Both expand to the empty string.
b) The formatter binaries are not usable. On a current macOS dev box:
$ which black isort
/opt/homebrew/bin/black
isort not found
$ black --quiet probe.py
/opt/homebrew/bin/black: bad interpreter: /opt/homebrew/opt/python@3.10/bin/python3.10: no such file or directory
c) Confirmed empirically. Writing this file through the Edit tool, which matches Edit|Write:
import sys
import os
x = { 'a':1,'b':2 }
def f( a,b ):
return a+bIt came back byte-identical — no reformatting, no import sorting, no error. Likewise, running a Bash command containing --force was not blocked by the PreToolUse guard.
The PreToolUse hook is the more serious one: it reads as a destructive-command safety net and has never blocked anything.
Fix: either rewrite both to parse the JSON payload from stdin, or delete them. The formatting hook is redundant regardless — .pre-commit-config.yaml runs black/isort/ruff, and ci.yml:26-30 enforces them as a blocking check. My recommendation is to delete the PostToolUse hook and either fix or delete the PreToolUse one, since a guard that silently passes is worse than no guard.
2. .claude/agents/doubleagent.md (17 KB) never loads
Added in 0ab54cb (#30). The file has no YAML frontmatter — it opens with # AgentReady Development Agent. Agent definitions require frontmatter with name and description, so Claude Code skips it entirely; it has never been available as an agent.
It is also superseded: .claude/agents/agentready-dev.md has valid frontmatter and the same stated purpose ("Specialized agent with deep knowledge of the AgentReady codebase for development, testing, and maintenance").
Fix: delete it, or port anything still valuable into agentready-dev.md.
3. .claude/skills/weekly-research-report-update.skill.md (25 KB) never loads
Skills must live at .claude/skills/<name>/SKILL.md. This is a bare .md file directly under .claude/skills/, so it is not discovered as a skill. Its stated trigger is a GitHub Actions weekly schedule, which suggests it was never meant to be a skill at all.
Fix: move it to docs/ if it documents the workflow, or restructure it as .claude/skills/weekly-research-report-update/SKILL.md if it is meant to be invocable.
4. Nine speckit.* commands cost context every session, with zero uses ever
.claude/commands/speckit.{analyze,checklist,clarify,constitution,implement,plan,specify,tasks,taskstoissues}.md each contribute a name and description to the always-resident skill listing — roughly 1,240 characters (~310 est. tokens) in every session in this repo.
Usage counters in ~/.claude.json (skillUsage, a lifetime total since install) record zero invocations across 63 sessions, and no transcript hits. Note this is one contributor's local counter, so it is evidence rather than proof — but nine commands with no recorded use is worth a decision.
The skill listing is budgeted at ~1% of the context window; entries get truncated when it overflows, which degrades routing for the commands you do want found.
Fix: decide whether spec-kit is part of this repo's workflow. If yes, keep them and say so in AGENTS.md. If no, remove them — teammates who want them can install spec-kit themselves.
5. AGENTS.md restates rules that are already enforced mechanically
Four blocks duplicate checks that .pre-commit-config.yaml and ci.yml:26-30 already enforce:
black . && isort . && ruff check . # Lint
**Linting**: Run `black . && isort . && ruff check .` before commits
**CI changes**: Always run `actionlint` before pushing workflow changes.
1. **Read before modifying**: understand existing assessors first
3. **Test thoroughly**: unit tests required for all assessors
actionlint is a pre-commit hook; black/isort/ruff are both pre-commit hooks and blocking CI. Guideline 1 is a generic practice, and guideline 3 duplicates the **Tests** line directly above it. Cutting these saves ~70 est. tokens per session and removes maintenance surface.
Overlaps with #523 (which rewrites the same # Development block for a different reason — its test-command fixes should land first or together; note #523's diff keeps the black . && isort . && ruff check . line, which this issue proposes removing).
Why this matters beyond token count
DeterministicEnforcementAssessor penalizes repos whose enforcement is advisory rather than mechanical. This repo currently ships two hooks that look like mechanical enforcement and enforce nothing — the exact failure mode the assessor is meant to catch. There may be an assessor improvement hiding here: detecting hooks that reference undefined variables or unavailable binaries.
Scope
Docs and config only. No src/ changes, no assessor logic, no scoring impact.
Related
AgentReady scores other repos on agent-readiness, but its own
.claude/directory carries ~42 KB of files that never load, two hooks that silently do nothing, and nine slash commands that have never been invoked. A/doctorcontext audit turned these up. Each is verified below.1. Both hooks in
.claude/settings.jsonare silent no-ops.claude/settings.json(added in efe7507, #484) configures two hooks. Neither works, and both are engineered to fail silently —2>/dev/null,; true, and|| truesuppress every signal.Three independent failures:
a)
$CLAUDE_FILE_PATHand$CLAUDE_TOOL_INPUTare not hook environment variables. Claude Code passes the tool payload to hooks as JSON on stdin. Both expand to the empty string.b) The formatter binaries are not usable. On a current macOS dev box:
c) Confirmed empirically. Writing this file through the Edit tool, which matches
Edit|Write:It came back byte-identical — no reformatting, no import sorting, no error. Likewise, running a Bash command containing
--forcewas not blocked by thePreToolUseguard.The
PreToolUsehook is the more serious one: it reads as a destructive-command safety net and has never blocked anything.Fix: either rewrite both to parse the JSON payload from stdin, or delete them. The formatting hook is redundant regardless —
.pre-commit-config.yamlruns black/isort/ruff, andci.yml:26-30enforces them as a blocking check. My recommendation is to delete thePostToolUsehook and either fix or delete thePreToolUseone, since a guard that silently passes is worse than no guard.2.
.claude/agents/doubleagent.md(17 KB) never loadsAdded in 0ab54cb (#30). The file has no YAML frontmatter — it opens with
# AgentReady Development Agent. Agent definitions require frontmatter withnameanddescription, so Claude Code skips it entirely; it has never been available as an agent.It is also superseded:
.claude/agents/agentready-dev.mdhas valid frontmatter and the same stated purpose ("Specialized agent with deep knowledge of the AgentReady codebase for development, testing, and maintenance").Fix: delete it, or port anything still valuable into
agentready-dev.md.3.
.claude/skills/weekly-research-report-update.skill.md(25 KB) never loadsSkills must live at
.claude/skills/<name>/SKILL.md. This is a bare.mdfile directly under.claude/skills/, so it is not discovered as a skill. Its stated trigger is a GitHub Actions weekly schedule, which suggests it was never meant to be a skill at all.Fix: move it to
docs/if it documents the workflow, or restructure it as.claude/skills/weekly-research-report-update/SKILL.mdif it is meant to be invocable.4. Nine
speckit.*commands cost context every session, with zero uses ever.claude/commands/speckit.{analyze,checklist,clarify,constitution,implement,plan,specify,tasks,taskstoissues}.mdeach contribute a name and description to the always-resident skill listing — roughly 1,240 characters (~310 est. tokens) in every session in this repo.Usage counters in
~/.claude.json(skillUsage, a lifetime total since install) record zero invocations across 63 sessions, and no transcript hits. Note this is one contributor's local counter, so it is evidence rather than proof — but nine commands with no recorded use is worth a decision.The skill listing is budgeted at ~1% of the context window; entries get truncated when it overflows, which degrades routing for the commands you do want found.
Fix: decide whether spec-kit is part of this repo's workflow. If yes, keep them and say so in
AGENTS.md. If no, remove them — teammates who want them can install spec-kit themselves.5.
AGENTS.mdrestates rules that are already enforced mechanicallyFour blocks duplicate checks that
.pre-commit-config.yamlandci.yml:26-30already enforce:actionlintis a pre-commit hook; black/isort/ruff are both pre-commit hooks and blocking CI. Guideline 1 is a generic practice, and guideline 3 duplicates the**Tests**line directly above it. Cutting these saves ~70 est. tokens per session and removes maintenance surface.Overlaps with #523 (which rewrites the same
# Developmentblock for a different reason — its test-command fixes should land first or together; note #523's diff keeps theblack . && isort . && ruff check .line, which this issue proposes removing).Why this matters beyond token count
DeterministicEnforcementAssessorpenalizes repos whose enforcement is advisory rather than mechanical. This repo currently ships two hooks that look like mechanical enforcement and enforce nothing — the exact failure mode the assessor is meant to catch. There may be an assessor improvement hiding here: detecting hooks that reference undefined variables or unavailable binaries.Scope
Docs and config only. No
src/changes, no assessor logic, no scoring impact..claude/settings.json.claude/agents/doubleagent.md.claude/skills/weekly-research-report-update.skill.mdspeckit.*commandsAGENTS.md(coordinate with docs(AGENTS.md): test commands don't work, assessor checklist omits weights, and the languages coupling is undocumented #523)Related
AGENTS.mdtest commands and assessor checklist gaps (overlapping edit surface).claude/commands/review-agentready.mdis stale (same directory, same class of drift)