autonomous-agent-readiness

Autonomous Agent Readiness Assessment

Evaluate a codebase against proven patterns for autonomous agent execution and provide tailored recommendations.

Core Philosophy

Most agent failures are system design failures, not model failures. An agent that requires human approval at every step or depends on a developer's laptop being open is not autonomous. Autonomy is an infrastructure decision.

Assessment Workflow

Phase 1: Discovery

Gather information about the project's current state:

1. Examine project structure

   • Look for CI/CD configuration (.github/workflows/, Jenkinsfile, .gitlab-ci.yml)
   • Check for containerization (Dockerfile, docker-compose.yml, devcontainer.json)
   • Identify test infrastructure (tests/, __tests__/, test config files)
   • Find environment management (.env.example, requirements.txt, package.json)

2. Review development workflow

   • Read contributing guidelines, README, or developer docs
   • Check for sandbox/isolation patterns
   • Look for database setup scripts or fixtures
   • Identify how dependencies are managed

3. Assess current automation

   • Review existing CI/CD pipelines
   • Check for automated testing patterns
   • Look for environment provisioning scripts
   • Identify cleanup/teardown procedures

Phase 2: Evaluate Against Principles

Score the project (0-3) on each dimension. See references/assessment-criteria.md for detailed rubrics.

Dimension	What to Look For
Sandbox Isolation	Ephemeral environments, container support, clean state per run
Database Independence	Local DB setup, migrations in code, no external DB dependencies
Environment Reproducibility	Explicit dependencies, no hidden state, deterministic setup
Session Independence	Remote execution capability, no user session dependencies
Outcome-Oriented Design	Clear acceptance criteria, minimal procedural coupling
Direct Interfaces	CLI-first tools, OS primitives, minimal abstraction layers
Minimal Framework Overhead	Simple interfaces, no heavy orchestration, composable CLI tools
Explicit State	Workspace directories, file-based artifacts, inspectable logs
Benchmarking	Measurable quality criteria, automated verification
Cost Awareness	Resource limits, usage tracking, explicit provisioning
Verifiable Output	Automated validation, deterministic results, clear exit codes
Infrastructure-Bounded Permissions	System-enforced constraints, least-privilege, no runtime prompts

Phase 3: Generate Recommendations

For each dimension scoring below 2, provide:

1. Current state: What exists today
2. Gap: What's missing for autonomous execution
3. Recommendation: Specific, actionable improvement
4. Priority: High/Medium/Low based on impact and effort

Tailor recommendations to the project's:

• Technology stack
• Team size and workflow
• Existing infrastructure
• Deployment targets

Output Format

# Autonomous Agent Readiness Assessment

## Project: [name]
## Assessment Date: [date]

## Executive Summary

[1-2 paragraphs summarizing overall readiness and top priorities]

**Overall Readiness Score: X/36** (sum of dimension scores)

## Dimension Scores

| Dimension | Score | Status |
|-----------|-------|--------|
| Sandbox Isolation | X/3 | [emoji] |
| Database Independence | X/3 | [emoji] |
| ... | ... | ... |

Status: 0-1 = needs work, 2 = adequate, 3 = strong

## Detailed Findings

### [Dimension Name] (X/3)

**Current State:**
[What exists]

**Gap:**
[What's missing]

**Recommendation:**
[Specific action]

**Priority:** [High/Medium/Low]

[Repeat for each dimension]

## Prioritized Action Plan

### Immediate (This Week)
1. [Highest impact, lowest effort items]

### Short-term (This Month)
1. [Important foundational changes]

### Medium-term (This Quarter)
1. [Larger infrastructure investments]

## Quick Wins

[2-3 changes that can be made today with minimal effort]

Key Principles Reference

Sandbox Everything

Every agent run executes in its own ephemeral, isolated, disposable environment. Clean environment, writable filesystem, command execution, scoped network access. Environment destroyed after verified output.

No External Databases

Agents create their own databases inside the sandbox. Install packages on demand, spin up DBs locally, run migrations, seed data explicitly, tear down at end. Reproducible runs without shared state.

Environment Garbage Is Real

Long-lived environments accumulate stray files, half-installed packages, cached state, orphaned processes. Fresh environments surface correctness; persistent environments obscure it.

Run Independently of User Sessions

Agent loop decoupled from browser tabs, terminal sessions, developer machines. Start task, close laptop, return to completed artifacts. Control via wall-clock limits, resource limits, automatic cleanup.

Define Outcomes, Not Procedures

Avoid step-by-step plans and tool-level micromanagement. Define desired outcome, acceptance criteria, constraints. Planning and execution belong to the agent.

Direct, Low-Level Interfaces

Direct access to command execution, persistent files, network requests. OS primitives over abstraction layers. CLI-first systems are easier to debug and more capable than they look.

Persist State Explicitly

Writable workspace directory for intermediate results, logs, partial outputs, planning artifacts. Files are inspectable, deterministic, and enable post-run analysis.

Benchmarks Early

Introduce benchmarks as early as possible. Representative and repeatable metrics for quality. Even crude benchmarks beat none.

Minimal Framework Overhead

Most real-world agent workflows reduce to running commands, reading/writing files, and making network calls. CLI-first systems are easier to reason about, debug, and more capable than they look. When an abstraction layer is more complex than the task, it becomes the bottleneck.

Plan for Cost

Provision token usage, allocate compute explicitly, enforce limits by system. Autonomy shifts where costs appear, doesn't remove them.

Verifiable Output

Output must be verifiable without human review. Automated validation, deterministic results, clear success/failure exit codes. If quality cannot be measured, it cannot be trusted in autonomous operation.

Infrastructure-Bounded Permissions

Permissions are constrained by the environment, not by prompts or runtime decisions. Explicit capability grants, sandbox restrictions on dangerous operations, least-privilege by default. No runtime permission prompts required.