# Agent Readiness

> Audit and build the infrastructure a repo needs so agents can work autonomously — boot scripts, smoke tests, CI/CD gates, dev environment setup, observability, worktree isolation, and .worktreeinclude handling for Codex or Claude worktrees. Use when a repo can't boot, tests are broken or missing, there's no dev environment, agents can't verify their work, worktrees miss ignored local config, or a…

- **Type:** Skill
- **Install:** `agentstack add skill-uinaf-agents-agent-readiness`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [uinaf](https://agentstack.voostack.com/s/uinaf)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [uinaf](https://github.com/uinaf)
- **Source:** https://github.com/uinaf/agents/tree/main/skills/agent-readiness
- **Website:** https://tessl.io/registry/uinaf

## Install

```sh
agentstack add skill-uinaf-agents-agent-readiness
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agent-Readiness

Make a repo ready for autonomous agent work by adding mechanical proof: boot scripts, smoke checks, CI/hooks, observable signals, and isolation where needed. Add the smallest useful layer first; stop once the repo is reliably verifiable.

## Boundaries

- Existing code, diff, branch, or PR review is out of scope.
- Completed product changes need their own runtime proof pass.
- AGENTS.md, README.md, specs, or repo docs are documentation work unless they support readiness infrastructure.
- Mock-only tests, docs-only cleanup, and builder self-evaluation are not readiness proof.

## The 7-Layer Stack

1. **Boot** — single command starts the app
2. **Smoke** — a fast proof the app is alive
3. **Interact** — agent can exercise the real surface
4. **E2e** — key user flows work end to end
5. **Enforce** — one local gate plus hooks, CI gates, lint rules, or mechanical checks
6. **Observe** — logs, health endpoints, traces, machine-readable signals
7. **Isolate** — worktrees or containers do not collide; ignored local setup files are available where needed

Concrete examples:

- Boot: `pnpm dev`, `cargo run`, or `docker compose up`
- Smoke: `curl http://127.0.0.1:3000/health`
- Interact/E2e: `pnpm exec playwright test`
- Observe: structured logs or a machine-readable health endpoint

## Workflow

### 1. Audit

Grade the repo across these dimensions:

- **bootable**
- **testable**
- **observable**
- **verifiable**

For each, report:

- status: `pass` / `partial` / `fail`
- evidence: file, check outcome, or runtime surface
- gap: what is missing

Use [references/grading.md](references/grading.md). Lowest dimension sets the overall grade.

Also scan unattended-run constraints: session independence, explicit artifact paths, resource bounds, infrastructure-enforced permissions, and direct CLI/HTTP/file interfaces for dashboard-only flows. If these are not needed for the current task, keep them as remaining gaps instead of expanding the scope.

When the repo uses Codex or Claude worktrees, audit `.worktreeinclude` too:

- confirm required gitignored local config is present in managed worktrees
- keep patterns narrow and rooted to files the repo actually ignores
- do not list tracked files, broad secret directories, generated caches, or dependency folders
- prefer generated test config, Infisical/CI env, or setup scripts when copying secrets would broaden access
- note that custom worktree hooks and manual `git worktree add` flows need their own copy step

Example output:

```text
bootable: partial — `pnpm dev` starts the app after manual env setup
testable: fail — only mocked tests under test/
observable: partial — health endpoint exists, structured logs missing
verifiable: fail — no stable smoke or interaction script
overall grade: D
```

### 2. Setup

Build missing layers in this order:

**Boot → Smoke → Interact → E2e → Enforce → Observe → Isolate**

Each step should be independently useful. Stop once the repo is reliably verifiable.

Prioritize one canonical local gate (`make verify`, `just verify`, `./scripts/verify.sh`, or equivalent) that agents can run before push. It should mirror meaningful CI checks enough to catch routine failures without opening a dashboard.

When readiness work includes agent entrypoints, keep `AGENTS.md` as the canonical authored guide and place `CLAUDE.md` beside it as a symlink to `AGENTS.md` rather than maintaining two separate guidance files.

See [references/setup-patterns.md](references/setup-patterns.md) for local gates, boot scripts, e2e, observability, isolation, `.worktreeinclude`, containerized stacks, and tooling-version ownership.

### 3. Improve

Tighten weak or flaky layers:

- remove mock-only confidence theater
- replace one-off checks with a canonical local gate, then reuse it from hooks and CI
- add dead-code or unused-symbol enforcement where the stack supports it
- add logs and health signals agents can query
- make parallel work safe when agent collisions are real

### 4. Stop

When the repo reaches C+ and can be judged honestly, stop readiness work and report the next natural phase.
If changes created doc drift, report the documentation gap instead of expanding the scope.

## Output

After readiness work, report in this compact bullet shape:

- `- grade:` before → after
- `- evidence:` concise explanations of what readiness checks proved
- `- files changed:` changed readiness files
- `- remaining gaps:` highest-impact gaps only, or `none`
- `- next:` runtime proof, independent review, documentation cleanup, human review, or `none`

Keep details compact:

- Put dimension-by-dimension evidence in the audit table when useful, not again in the footer
- Name the command or file that proves the claim and summarize logs by signal
- Keep the footer to 5 labeled lines or fewer
- Omit unchanged dimensions unless they explain the final grade
- Summarize passing checks by intent and result; include full commands only when they failed, are needed for reproduction, or the user asks for them

## References

- [references/grading.md](references/grading.md) — agent-readiness grading scale with mechanical criteria
- [references/setup-patterns.md](references/setup-patterns.md) — local gates, boot, smoke, e2e, observability, isolation, and `.worktreeinclude` patterns
- [references/industry-examples.md](references/industry-examples.md) — external patterns and justification for readiness investment

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [uinaf](https://github.com/uinaf)
- **Source:** [uinaf/agents](https://github.com/uinaf/agents)
- **License:** MIT
- **Homepage:** https://tessl.io/registry/uinaf

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-uinaf-agents-agent-readiness
- Seller: https://agentstack.voostack.com/s/uinaf
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.