Clean up .claude/: two no-op hooks, 42 KB of files that never load, and 9 unused commands #526

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+b

It 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.

• Fix or remove both hooks in .claude/settings.json
• Remove .claude/agents/doubleagent.md
• Relocate .claude/skills/weekly-research-report-update.skill.md
• Decide on the nine speckit.* commands
• Trim the four mechanically-enforced blocks from AGENTS.md (coordinate with docs(AGENTS.md): test commands don't work, assessor checklist omits weights, and the languages coupling is undocumented #523)

Related

• docs(AGENTS.md): test commands don't work, assessor checklist omits weights, and the languages coupling is undocumented #523 — AGENTS.md test commands and assessor checklist gaps (overlapping edit surface)
• /review-agentready command is stale: wrong attribute count, tier weights, and a nonexistent CLI flag #522 — .claude/commands/review-agentready.md is stale (same directory, same class of drift)
• docs: remove stale directory listing from CLAUDE.md architecture section #434 — stale directory listing in the context file
• Add pre-commit config to enforce black/isort/ruff locally #422 — pre-commit config (now landed; this issue relies on it)