Sample audit report

Private Rails app readiness audit

This sample uses the same structure as a paid Agent-Ready audit: scanner evidence, human validation, risk boundaries, copy-ready remediation prompts, and reviewer prompts. Identifying details have been removed.

Repo score 68/100

Promising but brittle. Fix the top gaps before assigning broad agent tasks.

test files found

assertions ran

CI workflows found

agent action packets

Executive summary

The repository is close enough for narrow, well-briefed agent work, especially documentation and repo-readiness cleanup. It is not ready for broad autonomous product changes yet. The repo has root agent instructions, orientation docs, lockfiles, and a clean worktree, but the default validation command does not prove behavior.

The highest-leverage cleanup is to add a real smoke test, wire it into CI, document the exact runtime setup, and add a repeatable task brief for agent assignments. The action packets below are intentionally narrow: each one can be handed to a coding agent without asking it to infer the whole remediation plan.

Scorecard

Area	Score	Read	Recommended fix
Agent instructions	15/15	Pass	Keep the pattern; add validation commands once the commands are settled.
Validation commands	8/15	Partial	Add one canonical check command for tests, dependencies, and build smoke.
CI	0/12	Gap	Add GitHub Actions for the same command agents run locally.
Tests	0/12 audited	Hidden gap	Add at least one real smoke test around the highest-risk happy path.
Secret hygiene	5/10	Partial	Add an env example with variable names only and safe credential guidance.
Task intake	0/8	Gap	Add an agent task brief and a pull request template.

Immediate agent action packets

Each packet has a target, the evidence that triggered it, a prompt to paste into an agent, and the acceptance criteria a reviewer should use before merging the change.

P0 Tests

Prove the test suite runs real assertions

Evidence: the repo has 47 test files, but the audited test run completed with 0 assertions. Future agents can get false confidence from a green suite.

You are improving this repo's agent readiness.

Target gap:
- Tests exist, but the current test command does not prove behavior.

Goal:
- Add one real smoke test around the highest-risk happy path.
- Make the default test command fail if that path breaks.

Constraints:
- Keep the change narrow.
- Do not refactor application code unless the test cannot be written otherwise.
- Do not touch production credentials or deployment settings.

Validation:
- Run the repo's existing test command.
- Report the assertion count or equivalent proof that behavior was exercised.

At least one assertion or expectation runs.
The test fails against an intentionally broken happy path.
The final report names the exact command and result.

P0 Validation

Create one canonical check command

Evidence: validation is split across docs and scripts, so agents do not have one obvious command to run before claiming a task is done.

Create one repo-local command that agents and humans can run before final response.

Inspect package scripts, Makefiles, Justfiles, bin scripts, language version
files, CI config, and README setup docs first.

The command should:
- require no production credentials
- run tests plus the narrowest useful lint/type/build smoke checks
- exit nonzero when any required check fails
- be documented in AGENTS.md and README.md

Run it once and report the result.

A single command is documented in both human and agent docs.
The command has deterministic local behavior.
Failure modes are clear enough for an agent to act on.

P1 CI

Run the same check on every pull request

Evidence: no pull request CI workflow was found. Local validation can drift unless the same command runs in hosted review.

Add pull_request CI for the canonical validation command.

Match the repo's checked-in runtime versions and package manager.
Avoid deployment, release, secret-backed integration tests, and broad formatting.

If hosted CI cannot be fully verified locally, say so explicitly and include:
- workflow file changed
- command CI will run
- any required repository settings or secrets

The workflow runs only safe validation, not deployment.
The command matches local agent instructions.
The PR summary separates local proof from hosted proof.

P1 Secrets

Add safe environment documentation

Evidence: the repo uses environment variables but does not give agents a safe inventory of required names or missing-credential behavior.

Inspect environment-variable usage and create a safe .env.example.

Rules:
- Include variable names only.
- Do not print, copy, infer, or commit real secret values.
- Mark required versus optional variables in README.md.
- Add AGENTS.md guidance: report missing credentials by name only.

No secret values appear in the diff or final response.
Required variables are easy to distinguish from optional ones.
Agent instructions define what to do when credentials are absent.

P2 Task intake

Add a repeatable agent task brief

Evidence: the repo has agent instructions, but no structured way to give scope, validation, risk boundaries, and final-response expectations for one assignment.

Add docs/agent-task-brief.md with fields for:
- goal
- allowed files or modules
- out-of-scope areas
- validation commands
- data and credential boundaries
- expected final report
- reviewer checklist

Link it from AGENTS.md and README.md.

A future agent can start from the brief without rediscovery.
Review criteria are explicit before implementation begins.
The template does not create process-heavy overhead.

Reviewer prompt

The review pass is separate from implementation. It should verify that the change genuinely improves agent readiness instead of just adding files that look useful.

Review only this change set.

Prioritize:
- bugs or behavioral regressions
- security or credential-handling risks
- missing validation
- whether the claimed readiness improvement is actually proven

Verify the documented command exists and was run. If there are no findings,
say that clearly and list residual risk. Do not expand into unrelated baseline
cleanup.

What an agent can safely do today

Good first tasks

Improve repo instructions, add validation docs, create a task brief, draft CI, and add a minimal smoke test with clear human review.

Avoid for now

Broad feature work, production deployment changes, credential-touching code, payment flows, migrations, or anything requiring trust in the current test suite.

Validation matrix

Before merge

Run the canonical check command, prove at least one behavioral test executed, and confirm no secret values entered the diff.

Before broad agent work

Confirm PR CI is green from the hosted provider and run one agent task using the new brief with a separate reviewer pass.

Still human-owned

Production deployment settings, credentials, payment flows, database migrations, and destructive data changes.

Want this for your repo?

Buy the kit for a self-serve cleanup pass, or book a focused audit sprint for one repo.

See pricing