--- name: harden-repo-for-coding-agents description: Use to ASSESS, HARDEN, SCAFFOLD, or DIAGNOSE a repository's agent-readiness for coding-agent harnesses such as Claude Code, Cursor, Codex, Copilot, Windsurf, and Aider. Covers AGENTS.md, SKILL.md, and MCP scaffolding, PreToolUse and other hooks, CI gates, sandbox and approval design, and repo-level agent failure modes; harness-agnostic and portable-first (AGENTS.md, MCP, OpenTelemetry); ships an opinionated checklist grounded in published research. Triggers on 'make this repo work with Claude Code / Cursor / Codex', 'scaffold our AGENTS.md', 'add an agent hook or gate', 'why did the agent trip on our repo', 'score our agent-readiness'. Do NOT use to design agent-facing products like SDKs or llms.txt docs (use design-for-agent-users), to promote recurring failures into rules from a feedback signal (use rules-from-coding-agent-failures), or to instrument an AI product's eval loops (use agent-evals). license: MIT --- # Agent Readiness Assess, harden, scaffold, and diagnose a repository's agent-readiness for coding-agent harnesses (Claude Code, Cursor, Codex, Copilot, Windsurf, Aider). Harness-agnostic and portable-first (AGENTS.md, SKILL.md, MCP, OpenTelemetry). Grounding lives in `skill.json`; this file is runtime routing only. This is the **repo-hardening arm** of the `design-for-agent-users` discipline, which routes here to harden a repo. **Produces:** an intent-specific report — `assess-report.md`, `harden-recommendation.md`, `scaffold-bundle.md`, or `diagnose-runbook.md`. Tracked assessments also emit `harden-repo-for-coding-agents-findings-ledger--.md` and `harden-repo-for-coding-agents-workflow-state--.json`. ## Core principle **Make the repository legible to a stateless, context-bound LLM that must rediscover the project on every turn** — through deterministic structure, hand-curated instructions (never autogenerated), executable boundaries, and replayable feedback loops. Three claims recur in every playbook: 1. **Don't `/init`.** Hand-curate from observed failures (W9: auto-init produces surface-plausible scaffolds with low fitness). 2. **Token budget is the dominant scarcity** (W6). Prefer on-demand → on-trigger → always-loaded. 3. **Hard gates beat soft prose** (W3). A hook holds at 100%; a sentence at ~70%. ## Quickstart The 90% case is `assess` × the `legibility` layer — "are AGENTS.md, specs, and the docs-index doing their jobs?": > `Assess the legibility layer of this repo.` The skill routes `assess`, scopes to the three legibility surfaces (instruction-surface, specs, docs-index), runs the four pre-write lenses against each, scores the layer 1–5 (layer score = the minimum across assessed surfaces), and renders the report in chat. Ask "save the report" to also write it to Markdown (per `templates/assess-report.md`, under `docs/audits/` or a path you give — never into `templates/`). With 7+ findings or any severity 3–4, the ledger + workflow-state pair is written automatically (step 9). For `harden`, `scaffold`, or `diagnose`, name the intent first. **Scope** — which repos this skill fits, and when to pair it with `rules-from-coding-agent-failures` — is in [`references/scope.md`](./references/scope.md). ## Activation - **Bare invocation** (`"agentify this repo"`, `"agent-readiness audit"`, `"use harden-repo-for-coding-agents"`): load `references/intent-router.csv`, show the intent menu, wait. No file inspection, network calls, or writes. - **Concrete invocation** with intent and surface inferable: skip to Workflow step 3. - **Concrete invocation with ambiguous scope**: ask one blocker question to fix the intent or surface; do not inspect private systems first. ## Workflow 1. **Pick intent.** Load `references/intent-router.csv`; match to `assess` / `harden` / `scaffold` / `diagnose`. Ambiguous → ask once. 2. **Pick surface(s).** Load `references/surface-router.csv`; match to one or more surfaces. For `assess`, `all` fans out across the full surface list. Ambiguous → ask once with the menu. 3. **Load grounded context.** Load the chosen playbook(s), `references/empirical-warnings.md`, and always `references/core/severity-rubric.md` (every finding carries a severity). For `assess`, also load `references/core/maturity-rubric.md`. These playbooks carry cross-harness implementation tables; static checks keep them bounded, not free-form dumps. 4. **Collect project knowledge and the harness inventory.** For `scaffold`, ask for (a) tech stack and runtimes, (b) repo layout and which directories the scaffold covers, (c) build / test / lint commands, and (d) invariants the agent must not break. For `scaffold`, **and for `harden` touching `instruction-surface` or `gates`**, also ask **(e) which harnesses are actually in use** (Claude Code, Cursor, Codex, Copilot, Aider, Windsurf, or AGENTS.md-only) — those surfaces emit per-harness output, so the set must be known, not guessed. **Do not infer the harness set from dotfiles** — `.claude/` proves Claude Code is used, not that it is the only one. Default to per-harness equivalents for every harness named. Hand-curate; the quality bar is "specific to this project, verifiable by reading the file," not "measured against a benchmark." 5. **Dispatch the four lenses in parallel** (`references/lenses.md`): cold-context-agent (does a fresh-context LLM trip here?), maintainer (is the agent surface drifting?), adversarial (injection, exfiltration, tool abuse, sandbox escape?), auditor (can a human reconstruct what the agent did and why?). Each loads the playbook(s) and applies its prompt. For `assess + all`, invert the topology: one agent per surface, four lenses inside. Hosts without a delegation primitive run the lenses sequentially in one head. Skip for tiny copy edits or deterministic command checks. 6. **Apply the playbook.** Use the intent's heuristics. For `assess`, score each layer 1–5 with the maturity rubric (layer score = min across assessed surfaces). For `harden` / `diagnose` / `scaffold`, rank hypotheses or recommendations before naming actions. Synthesize sub-agent findings here. 7. **Apply severity and IDs** to every finding (`references/core/severity-rubric.md`, `references/trackable-findings.md`); assessment findings use stable `AG--NNN` IDs. 8. **For `scaffold`, gate the writes, then audit them.** List `{path, action}` pairs and wait for the user (`all` / `none` / a specific list); write only what's confirmed. Then dispatch **one fresh-context auditor** (`references/lenses.md` §Post-write auditor) that reads the actual diff, enumerates every `harden` heuristic in the chosen playbook(s), and reports each as `applied | skipped-because-X | deferred`. This is external verification: the writer cannot rubber-stamp its own checklist, because the auditor never sees the writer's reasoning. Surface unapplied heuristics before calling the scaffold done. 9. **Emit, then track.** Default to a rendered, TUI-friendly view — fixed-width text or bullet lists, never Markdown pipe tables. If asked to save, also write the intent-specific template verbatim: `assess` → `templates/assess-report.md`, `harden` → `templates/harden-recommendation.md`, `scaffold` → `templates/scaffold-bundle.md`, `diagnose` → `templates/diagnose-runbook.md` (tables fine; single-line rows). **Create tracking state** for `assess` with 7+ findings, any severity 3–4, or a save/track/closeout request: write the ledger at `docs/audits/harden-repo-for-coding-agents-findings-ledger--.md` and workflow state at `docs/audits/harden-repo-for-coding-agents-workflow-state--.json` (fall back to `audit-artifacts/harden-repo-for-coding-agents-{findings-ledger|workflow-state}--.{md|json}` if `docs/audits/` is unwritable). Report both paths; check a box only after its verification rule passes. Never create roadmaps, external issues, or non-tracking edits without confirmation. ## Modes Guided Draft (default), Autopilot, Grill Me — contract in [`references/modes.md`](./references/modes.md). Offer the choice at bare invocation; default to Guided Draft on concrete invocations. ## Output requirements Every output names the intent, surface(s), and lenses dispatched; the playbook(s) applied; the intent's load-bearing section (maturity scores + gaps for `assess`, recommendation + verification for `harden`, file previews + confirmation gate for `scaffold`, hypothesis ranking + fix + prevention for `diagnose`); a severity per finding; stable IDs for assessment findings; and the `skill.json` sources cited. ## Empirical warnings W2–W10 live in `references/empirical-warnings.md` (symlink to the shared file); every playbook backlinks the ones it touches. The four most load-bearing here: **W2** (AGENTS.md ≤ 200 lines), **W3** (hard gates over soft prose), **W6** (token budget is the dominant scarcity), **W9** (auto-init lies; hand-curate). **W1** (≥3 observed failures before scaffolding) is the failure-driven floor and lives in `rules-from-coding-agent-failures` — it does not apply here, since most repos have no failure signal yet. If yours does, pair the two skills. ## Reference map - `references/intent-router.csv` — level-1 router (intent → template + rubric). - `references/surface-router.csv` — level-2 router (surface → playbook). - `references/playbooks/.md` — 11 surface playbooks across the legibility, action, and control layers (full list in `surface-router.csv`). - `references/lenses.md` — four pre-write lenses + post-write auditor + dispatch template (shared symlink). - `references/core/{maturity,severity}-rubric.md` — Levels 1–3 maturity (4–5 in `rules-from-coding-agent-failures`) and the 0–4 severity scale. - `references/empirical-warnings.md` — W2–W10 (shared symlink). - `references/trackable-findings.md` — ledger, roadmap, issue, workflow-state, and closeout rules. - `references/agent-friendly-architecture.md` — repo-structure + boundary note; points to `minimal-modular-code`. - `references/modes.md`, `references/scope.md`, `references/starter-scenarios.csv` — modes contract, fit guidance, worked examples. - `templates/*.md` — four intent output templates, plus the shared tracking artifacts (`findings-ledger`, `roadmap`, `github-issue`, `workflow-state.json`). - `templates/artifacts//` — skeletons for the files `scaffold` writes to the target repo (AGENTS.md, hooks, CODEOWNERS, …); every scaffold-bundle row cites one, and the post-write auditor enforces shape compliance. - `evals/` — activation cases, static checks, trigger evals. - `skill.json` — provenance, grounding sources, version, status.