agent-readiness

What this does. An agent-first project lives or dies on a question no human-facing scorecard asks: can an autonomous coding agent that lands in the repo cold discover what fak is, want to adopt it, and build on it without tripping over a missing affordance or an undocumented guard? This pass turns that from a vibe ("we have an AGENTS.md, we're fine") into a repeatable, provable number — the way industry-score keeps the competitive story honest and repo-hygiene keeps the tree lean.

The shape: run the scorecard → add every missing affordance (HARD defect) → weigh every SOFT signal → re-measure to prove friction-debt dropped and the experience-frontier climbed → regenerate the snapshot → commit only the scorecard lane.

There are two headline numbers, because agent-readiness is two questions:

• friction-debt (the BASELINE gate, lower = better, floor 0): the count of concrete, re-derivable defects that make the expected affordances missing or broken. Zero means the current metric version detects none in the current corpus; keep discovering new failure classes rather than treating the ledger as complete. The shipped tree currently reads 0 / grade A for that named detector.
• experience-frontier (the HEADLINE, higher = better, unbounded): the weighted count of real, working agent affordances the tree actually provides — an integration recipe an agent follows, a zero-setup harness config, a kernel refusal an agent can recover from, a tool an agent drives via --json. It is deliberately NOT a 0-100 grade: agent experience is a never-done program (the same category as kernel- and cache-optimization), so it has no ceiling and is tracked as a frontier + a trend, never a completion %. It is the deliberate mirror of internal/heavinessscore's unbounded heaviness_pressure (the load an operator carries); this is the surface an agent gains. You move it by adding a real affordance (onboard a harness, map a refusal, expose a --json surface) — never by gaming a substring, the same rule the friction-debt gate enforces.

Drive friction-debt to zero and climb the frontier, and "attractive to agents" becomes a pair of numbers you moved, not a claim you made. (The stick any forked or adopting repo measures its own gap against.)

---

The one rule that overrides everything: add the affordance, never fake the check

The scorecard reads the real tracked tree. Every KPI is a genuine agent affordance — a file that must exist, a link that must resolve, a command that must be paste-able, a claim that must be tagged. So:

• Retire a defect by adding the real thing an agent reaches for, not by adding a keyword to satisfy a substring match. A first_command defect is fixed by a fenced, runnable no-key command an agent can actually paste — not by typing the words fak preflight into prose.
• Never weaken a claim or a guard to score. The honesty ledger, the trunk law, the leaf/ABI discipline are load-bearing; guardrails_surfaced wants them documented, never relaxed.
• It is read-only. The tool edits nothing; you make the edit, then re-run.

If "fixing" a defect would mean gaming the detector instead of adding the affordance, stop — that's not a real gap.

---

The three steps an agent walks (the groups, and the HARD defects each retires)

Twenty KPIs, each 0–100, grouped by the step they gate. Retire worst-step-first (the scorecard names the weakest step in group_scores). The presence KPIs ask does the affordance exist; the paste-and-run / executable-truth KPIs ask the question presence can't reach — does an agent who pastes the docs actually succeed (a bounded presence-only score can read 100 while a cold agent still trips on a stale cd fleet/fak, a /path/to/… placeholder, or a fak <verb> the binary never dispatches).

Step	KPI	The affordance to add when it's red
discover	agents_entrypoint	An AGENTS.md (the agents.md convention) that states what fak is and carries build + test + run commands.
discover	agent_config	The zero-setup configs a harness auto-loads: .mcp.json, .cursorrules, .github/copilot-instructions.md.
discover	agent_config_valid	SUCCESS — the auto-loaded config is well-formed, not just present: .mcp.json parses and every server names a launch command (else the harness silently fails to start it).
discover	llms_map	llms.txt (the answer-engine / agent doc-map).
discover	identity_statement	A one-sentence "fak is a/an …" near the top of AGENTS.md / llms.txt / README an agent can quote.
discover	entry_links_resolve	Fix any dead local link in AGENTS.md or the integration index — a 404 on the orientation path.
discover	recipe_links_resolve	SUCCESS — every local link INSIDE each per-agent recipe resolves (one hop past the index — the recipe an agent is actively following).
adopt	first_command	A copy-pasteable, fenced, no-key/no-model/no-GPU first command (the 30-second proof).
adopt	command_verbs_resolve	SUCCESS — every fak <verb> an agent pastes resolves to a real dispatched verb (parsed live from cmd/fak/main.go); a doc that says fak hooks when the verb is fak hook is an ambush.
adopt	first_command_runs	SUCCESS — the first command actually RUNS from a clean clone: the --policy it names exists on disk, and it's the no-key form (not a serve --api-key-env sold as step one).
adopt	fenced_paths_resolve	SUCCESS — every path an agent pastes from a fenced block resolves in a clean clone: no stale cd fleet/fak private-monorepo prefix, no non-existent repo-relative path, no /path/to/… literal in a runnable line.
adopt	install_oneliner	The go install …@latest one-liner (the module is at the repo root, so it resolves).
adopt	honesty_ledger	CLAIMS.md present, every - [ claim carrying exactly one status tag (the make claims-lint rule).
adopt	integration_recipes	A per-agent recipe under docs/integrations/ for each family (Claude, Codex/OpenAI, Cursor, MCP).
adopt	codex_recipe_current	The Codex recipe matches current Codex surfaces: MCP for the CLI/IDE path, codex exec --json, AGENTS.md discovery, and an honest Responses-vs-Chat-Completions fence.
build	extension_scaffold	The additive path: fak new-leaf + EXTENDING.md (add a leaf, don't edit core).
build	guardrails_surfaced	Document each enforced rule in AGENTS.md: trunk-only, commit-by-path, DCO sign-off, tagged claims, leaf/ABI, the out-of-tree write guard.
build	contributor_contract	CONTRIBUTING.md linked from the entry point + a one-command green gate (make ci).
build	platform_guidance_consistent	SUCCESS — if AGENTS.md sells make ci as the gate, it names the native-Windows bridge (scripts/ci.ps1 / ./test.ps1 under WSL) so a Windows agent isn't told to run a gate it can't.
build	machine_consumable	SOFT — how much of the measurement family speaks --json. Scores; never hard debt.

SOFT signals (a missing llms-full.txt, a tool without --json) lower the score but are never friction-debt; weigh them, don't grind on them.

---

Step 1 — Run the scorecard (it builds your work-list)

From the repo root:

fak score agent-readiness --json > agent-readiness.json

This machine-readable artifact is mandatory. Before choosing work, quote every non-zero corpus.breakdown row from it. When present, prioritize command_verbs_resolve and refusal_recovery_mapped before softer copy polish. Product defects exposed by those rows belong in dedicated issues rather than being silently fixed inside a skill-only pass.

It scores the three steps (discover · adopt · build) into a composite (0–100, A–F) and a friction-debt integer, and prints the work-list: every HARD defect with the affordance to add, then the SOFT signals. Read-only; it never edits the tree.

Step 2 — Retire friction-debt worst-step-first

Take the weakest measured step first (the captured JSON names it in group_scores and corpus.breakdown). Quote the exact non-zero rows in the work record. For each HARD defect, add the real affordance from the table above, using a dedicated product issue when the fix is outside this skill. After a batch, re-run the scorecard and watch the number fall; that loop (add, re-measure, add again) is the whole method. Capture a before/after baseline so you can prove the drop:

fak score agent-readiness --json > /tmp/before.json   # baseline before the pass
# … add the issue-authorized affordances …
fak score agent-readiness --compare /tmp/before.json  # experience-frontier delta (+35% goal) + friction-debt delta

--compare leads with the experience-frontier delta and a percentage: the goal is a frontier climb (the default target is +35%), because the friction-debt gate has already bottomed out at 0 — improvement now lives entirely on the unbounded frontier. It also still prints the friction-debt 2x gate (held at 0).

Step 3 — Weigh the SOFT signals, then stop

Read the SOFT list once; fix the cheap, real ones. Don't chase them to zero — a token added only to move a metric is the gaming this pass refuses.

Step 4 — Re-measure, confirm, regenerate the snapshot

Re-run fak score agent-readiness --json; compare and quote the before/after corpus.breakdown rows, then state the before/after on BOTH headlines (e.g. "friction-debt 6 → 0, adopt 67 → 100; experience-frontier 284 → 384, +35%"). Then regenerate the committed snapshot so the doc matches the tree:

go run ./cmd/fak score agent-readiness --markdown --stamp $(date +%F) > docs/AGENT-READINESS-SCORECARD.md

If you added or removed a scorecard surface, also re-fold the portfolio: python tools/scorecard_control_pane.py (agent-readiness reports friction_debt).

Step 5 — Commit only the scorecard lane, by explicit path

This is a shared trunk; commit your lane, never a peer's work:

fak sync reconcile --apply
fak commit \
  --path internal/agentreadinessscore/agentreadinessscore.go \
  --path internal/agentreadinessscore/agentreadinessscore_test.go \
  --path cmd/fak/agentreadinessscore.go \
  --path docs/AGENT-READINESS-SCORECARD.md \
  -F <msgfile> [--push]
fak sync push

• Stage by explicit path via fak commit --path, never git add -A — stage + commit in one shell call so a peer's bare commit can't sweep your files.
• Subject: a code change to the tool → feat(tools): … (fak tools); a docs-only snapshot regen → docs(scorecard): … (fak docs). End with the (fak <leaf>) trailer; lead with a verb.
• The control pane (tools/scorecard_control_pane.py), INDEX.md, and this skill are co-edited by peers adding sibling scorecards — if one shows in your diff and you didn't change it, exclude it; if a MERGE_HEAD is set, wait it out, then commit by explicit path.

---

When to run this

• After a change to any agent surface: AGENTS.md, llms.txt/llms-full.txt, CLAIMS.md, the docs/integrations/ recipes, the surfaced guardrails, fak new-leaf.
• When onboarding a new agent harness (add its agent_config + a recipe).
• On a /loop cadence to keep the front door agent-friendly as the repo grows.

The scorecard is fak's agent-experience checking layer, the way industry-score is its competitive layer and repo-hygiene is its structural one. Same discipline: a number you can move, and prove you moved.