feat(spec): AI-Friendly Repository Guidance & Readiness Audit

[bdfinst]

Intent Description

dev-team should carry a documented rubric of repo conventions known to improve
Claude Code's effectiveness — layered CLAUDE.md context, deterministic fast
verification loops, and navigable/colocated repo layout — as first-class
knowledge, and extend its existing readiness-scoring capability so any target
repository can be audited against that rubric and get concrete, evidence-backed
findings.

This is not a new parallel audit tool. agent-readiness's MVP scorecard
already stubs closely-related criteria as deferred placeholders
(D2_ai_instructions, B1_single_command_build, T4_single_command,
C3_architecture) — the three new recommendation categories fill in and
extend that scorecard rather than duplicating its purpose.

Goal: running the scanner against a repo (this one or a user's project)
reports concrete findings on context-window discipline, verification-loop
speed, and repo navigability — the three levers with the most direct effect
on agent coding quality — backed by a durable knowledge doc other dev-team
agents (e.g. claude-setup-review, setup/project-init) can cite later.

Architecture Specification

Components:

• New knowledge doc — plugins/dev-team/knowledge/ai-friendly-repo-guidelines.md.
  Canonical source of the rubric: one subsection per recommendation category
  (Layered Context Architecture; Deterministic Verification & Fast Feedback
  Loops; Navigable Repository Layout), each restating its sub-recommendations
  with rationale. scanner.py and SKILL.md reference this doc rather than
  re-describing the rubric inline.
• Extended plugins/dev-team/skills/agent-readiness/scorecard.yaml — at
  least one new criterion per recommendation category (≥3 total): a
  CLAUDE.md line-count ceiling; hierarchical CLAUDE.md / .claude/rules/
  presence; single-target test command detectability (refines the existing
  deferred T4_single_command); a fast composite check command (refines the
  existing deferred B1_single_command_build or adds a sibling); colocated
  test/source layout; max directory depth; a canonical-reference-implementation
  pointer in CLAUDE.md (manual_review: true, matching the existing
  C3/S3/D4 pattern for heuristic-weak judgment calls).
• Extended scanner.py — one heuristic analyzer per new mvp: true
  criterion, stdlib-only, same shape as existing analyzers (pure function,
  score + evidence string), with fixture-backed unit tests.
• Updated SKILL.md — new criteria in the existing evidence-table format;
  scope note updated; attribution to the source recommendations captured in
  the knowledge doc.
• Scanner's CLI contract (REPO_PATH [--json] [--markdown]) is unchanged —
  additive only.

Constraints:

• Stdlib-only Python 3.10+ (ADR 0014, 0015, 0031; repo-wide script rule).
• Backward compatible: existing MVP criteria, tier thresholds, and JSON output
  keys are unchanged; new criteria are additive keys only.
• No CI-platform API calls — stays file-presence/heuristic, matching the MVP
  scope boundary already documented in SKILL.md.
• Audit-only. No remediation/auto-fix of the target repo in this feature —
  matches the skill's current read-only tool grant (Bash(python3 *), Read, Glob — no Edit/Write).
• Weights/thresholds stay externalized in scorecard.yaml; no hardcoded
  scoring logic in scanner.py.
• Heuristic-weak new criteria (e.g. "is the canonical reference implementation
  well-chosen") use manual_review: true rather than false-precision scoring.

Dependencies: none new — no third-party packages; new checks parse repo
files (CLAUDE.md, build manifests, directory tree) the same way existing
criteria already do.

Acceptance Criteria

• plugins/dev-team/knowledge/ai-friendly-repo-guidelines.md exists and
  documents all three recommendation categories, each with its specific
  sub-recommendations from the source guidance.
• scorecard.yaml's version is bumped and lists ≥3 new criteria (at
  least one per recommendation category), each with an mvp flag and
  manual_review: true where heuristic-weak.
• scanner.py implements a heuristic for every new mvp: true criterion;
  each has a passing-case and failing-case fixture-backed unit test.
• Scanning a repo that follows none of the three conventions scores each
  new criterion at its lowest value with an evidence string naming the
  specific gap (e.g. "root CLAUDE.md is 412 lines, exceeds 200-line ceiling").
• Scanning a repo that follows all three conventions scores each new
  criterion at its highest value.
• All pre-existing MVP criteria, tier thresholds, and output JSON keys are
  unchanged in behavior — existing agent-readiness tests pass unmodified.
• SKILL.md's evidence table and scope section list the new criteria;
  manual_review_flags output surfaces the new heuristic-weak criteria
  alongside the existing C3/S3/D4 set.
• No Edit/Write tool is added to the skill's allowed-tools — the
  scanner stays read-only against the audited repo.
• knowledge/agent-registry.md / knowledge/skills-registry.md entries
  for agent-readiness are updated if the skill's description changes
  materially (registry drift fails /agent-audit).

Ambiguity Log

Decision	Classification	Resolved By	Rationale / Answer
Extend agent-readiness vs. create a new standalone audit skill	inferable	inference	agent-readiness's MVP scorecard already stubs deferred criteria matching exactly these three categories (T4_single_command, B1_single_command_build, C3_architecture, D2_ai_instructions); a second parallel "AI-friendliness" audit would duplicate its stated purpose and leave users unsure which score to trust.
Audit-only vs. also wiring the guidance into /setup//project-init to actively scaffold these conventions into new projects	inferable	inference	The request says "auditing," not generating. Active scaffolding is a second, independently-shippable feature and would violate the one-feature-per-spec rule (Scope Split Protocol). Left as a natural follow-up, not built here.
Where the guidance content itself lives	inferable	inference	plugins/dev-team/CLAUDE.md already reserves knowledge/ for "registries, rubrics, patterns (loaded on-demand by agents)" — a new knowledge doc matches this pattern and lets other agents cite the rubric later without re-describing it in the skill file.
New scorecard category vs. folding new criteria into existing categories (documentation/build_env/code_quality) with weight renormalization	inferable	inference	scorecard.yaml is explicitly documented as versioned and tunable "without code changes," and the scanner already renormalizes across categories with at least one MVP criterion — adding criteria is the scorecard's designed extension path, not a breaking change. Exact placement (new category vs. existing) is left to /plan.

No requires-stakeholder-input items — each ambiguity found had a reliable
inference basis from existing repo structure and documentation.

Consistency Gate

• Intent is unambiguous
• Every behavior/goal maps to an acceptance criterion
• Architecture constrains without over-engineering
• Terminology consistent across artifacts
• No contradictions between artifacts
• Every gap/ambiguity finding is logged — inferable with rationale or resolved by human