| name | agent-ready |
| description | Audits a repository's readiness for agent-driven development against Lauren Tan's five enforcement layers (codebase, static analysis, rules/bugbot, skills, style guide), then generates repo-specific hardening artifacts such as CI checks, import-boundary lint rules, rules files, a feature map, and a verification skill. Use when asked to "make this repo agent-ready", "harden this repo for agents", "audit agent-readiness", or to add trust layers or enforcement for coding agents. |
Agent-ready
Turn an existing repo into one where coding agents ship software. Trust in agents is bought with enforcement, one layer at a time. This skill runs two phases inside the target repo. Audit scores the repo against the five enforcement layers and produces a prioritized report. Harden generates the artifacts the report calls for.
The output must fit the repo in front of you. Never emit an artifact for a problem you did not observe here. Different repos produce different reports and different artifacts; a generic rule dump is a failure of this skill.
The finding
All work in both phases reduces to one shape. A finding is:
- the invariant, one sentence stating what must stay true
- evidence, file paths or quoted comments or command output from this repo
- the layer enforcing it today, often layer 5 or nothing
- the strongest layer that could enforce it
- the artifact that moves it there
The method in one sentence: find every invariant the repo cares about and push it down to the strongest enforcement layer it can hold. Read references/enforcement-layers.md before scoring anything. It defines the layers, the hard/soft split, audit questions, and hardening moves per stack.
Phase A: audit
- Detect the stack. Languages, build system, test runner, CI config (
.github/workflows/, .gitlab-ci.yml, or equivalent), lint configs, and what kind of application this is (web, service, CLI, desktop, mobile, library). Record the exact commands that build, lint, and test, and confirm they run.
- Score the five layers. Answer the audit questions in references/enforcement-layers.md, score each layer 0 to 2, and keep the evidence. Score what actually runs, not what config files claim.
- Mine human feedback channels. Read
AGENTS.md, CLAUDE.md, .cursor/rules/, CONTRIBUTING.md, and style docs. Sample recent PR review comments, the issue tracker, and fix/revert churn in git history. Detect the tracker before asking (remotes, your tool list, repo files); if that is inconclusive, ask one compact question and continue auditing without blocking on the answer. No tracker is a valid answer, noted in the report. Every recurring instruction, comment, or bug category is a candidate finding. Ask the user what they keep repeating to agents. Detection, mining heuristics, and conversion patterns live in references/review-smells.md.
- Check agent-behavior hazards. Shared registry files that every PR touches, missing import-boundary checks, foot-gun APIs in wide use, comment noise, and a conventional path that takes more decisions than the shortcut. The audit lens is references/dune-contract.md.
- Check the verification loop. Can an agent launch the app, drive a feature, and capture evidence without a human? Is there a feature map? See references/verification.md.
- Write the report. Follow references/report-template.md, including the trust-curve position from references/trust-curve.md and the required "explicitly not doing" section. Present the report to the user.
Phase B: harden
Proceed after presenting the report unless the user asked for an audit only. The report is reviewable and every artifact is revertible, so do not stop to ask permission finding by finding.
- Work the plan in priority order. Mechanical wins first, then verification, then structure, as ordered in the report.
- Generate per layer.
- Layer 2: lint rules, import-boundary checks, banned-API rules, and CI jobs matching the detected stack (menu in references/enforcement-layers.md). Every rule's error message names the sanctioned alternative.
- Layer 3: rules files that state each invariant once, name its mechanical twin, and describe the conventional path for common tasks. Write the same content to
AGENTS.md, CLAUDE.md, and .cursor/rules/ so every tool sees it. A must-hold invariant appears in both a hard layer and a rules file, never in a rules file alone.
- Layer 4: the verification skill and feature map per references/verification.md. If pstack's
create-verification-skill is installed, invoke it instead of reimplementing.
- Layer 1: a written migration plan toward feature folders and registry removal, plus a boundary check that holds the line for new code now. Never a big-bang move.
- Prove every artifact. For each check or rule: introduce a real violation, run the check, watch it fail, revert the violation, watch it pass. For the verification skill: run it end to end once against one feature. An unproven artifact is a draft and does not ship.
- Commit small. One artifact (or one coherent finding) per commit, message naming the finding it resolves. Small atomic commits are themselves part of the methodology: git history is context for future agents, and reverts stay cheap.
- Hand over. State the trust-curve rung before and after, the single next step up, and how to maintain the soft artifacts over time with evals (references/eval-playbook.md).
Boundaries
- Tighten existing enforcement before adding parallel enforcement. A repo with ESLint gets new ESLint rules, not a second linter.
- Wait for recurrence. A comment made once is not yet a rule; encoding one-offs breeds rule sprawl that agents learn to ignore.
- Escape hatches from new boundaries are narrow allowlist entries reviewed as architecture changes, never disabled rules.
- Do not edit product behavior in either phase. Broken things you find are findings, not fixes.
References
