Project Health: AI-Agent Readiness Auditing

Overview

1. Understand the documentation without ambiguity
2. Execute workflows by following instructions literally
3. Resume work effectively with proper context handoff

When to Use

• Before handing off a project to another AI session
• When onboarding AI agents to contribute to a codebase
• After major refactors to ensure docs are still AI-executable
• When workflows fail because agents "didn't understand"
• Periodic health checks for AI-maintained projects

Agent Selection Guide

Key Principles

1. Literal Interpretation

"Update the config file with your settings"

"Edit

wrangler.jsonc

and set

account_id

to your Cloudflare account ID (find it at dash.cloudflare.com → Overview → Account ID)"

2. Explicit Over Implicit

• Which file you mean
• What "obvious" next steps are
• Environment state or prerequisites
• What success looks like

3. Verification at Every Step

• Expected output after each command
• How to check if a step succeeded
• What to do if it failed

Agents

context-auditor

• Instructions use imperative verbs (actionable)
• File paths are explicit (not "the config file")
• Success criteria are measurable
• No ambiguous references ("that thing", "as discussed")
• Code examples are complete (not fragments)
• Dependencies/prerequisites stated explicitly
• Error handling documented

workflow-validator

• Steps are discrete and ordered
• Each step has clear input/output
• No implicit knowledge required
• Environment assumptions documented
• Verification step after each action
• Failure modes and recovery documented
• No "obvious" steps omitted

handoff-checker

• SESSION.md or equivalent exists
• Current phase/status clear
• Next actions documented
• Blockers/decisions needed listed
• Context for future sessions preserved
• Git checkpoint pattern in use
• Architecture decisions documented with rationale

Templates

AI-Readable Documentation Template

templates/AI_READABLE_DOC.md

• Prerequisites (explicit environment/state requirements)
• Steps (numbered, discrete, with verification)
• Expected Output (what success looks like)
• Troubleshooting (common failures and fixes)

Handoff Checklist

templates/HANDOFF_CHECKLIST.md

Anti-Patterns

1. "See Above" References

# Bad
As mentioned above, configure the database.

# Good
Configure the database by running:
`npx wrangler d1 create my-db`

2. Implicit File Paths

# Bad
Update the config with your API key.

# Good
Add your API key to `.dev.vars`:

undefined

3. Missing Verification

# Bad
Run the migration.

# Good
Run the migration:
`npx wrangler d1 migrations apply my-db --local`

Verify with:
`npx wrangler d1 execute my-db --local --command "SELECT name FROM sqlite_master WHERE type='table'"`

Expected output: Should show your table names.

4. Assumed Context

# Bad
Now deploy (you know the drill).

# Good
Deploy to production:
`npx wrangler deploy`

Verify deployment at: https://your-worker.your-subdomain.workers.dev

Relationship to Other Tools

project-docs-auditor

project-health

docs-workflow

Quick Start

1. Full audit: "Run all project-health agents on this repo"
2. Check one aspect: "Use context-auditor to check AI-readability"
3. Before handoff: "Use handoff-checker before I end this session"

Success Metrics

• Context Auditor: 80+ (AI can understand without clarification)
• Workflow Validator: 90+ (steps execute literally without failure)
• Handoff Checker: 85+ (new session can resume immediately)