codebase-readiness

What this skill does

# Codebase Readiness Assessment

Run an **Agent-Ready Codebase Assessment** — a scored evaluation of how well a codebase supports autonomous AI agent work, framed against the Stripe benchmark of 1,000+ AI-generated pull requests per week.

Work through the following phases sequentially.

---

## Phase 1: Codebase Reconnaissance

Execute the reconnaissance script to gather project metadata before launching assessment agents. Run directly — no agent needed.

```bash
bash scripts/recon.sh
```

The script is located at `scripts/recon.sh` relative to this skill's directory.

After reviewing the output, format a **Codebase Snapshot**:

```
## Codebase Snapshot: [Project Name]

- **Primary language/framework**: [detected]
- **Language tier**: [statically-typed | dynamically-typed | gradually-typed]
  - Statically-typed: TypeScript, Go, Java, Scala, Rust, C#, Kotlin
  - Dynamically-typed: Ruby, Python (unannotated), JavaScript/Node.js, PHP
  - Gradually-typed: Python with mypy/Pydantic, TypeScript with strict:false
- **Commit count**: [X]
- **Contributors**: [X]
- **Source files**: [X]
- **Test files**: [X] (ratio: X%)
- **CI/CD**: [platform(s) found or none]
- **CLAUDE.md**: [present at path, X lines / absent]
- **Linting config**: [tools found or none]
- **README**: [present, X lines / absent]
```

Determine `PRIMARY_LANGUAGE` and `LANGUAGE_TIER` from the snapshot. These values drive which language reference file to load.

**Supported languages:** ruby, python, php, typescript, javascript, go, java, scala, rust.

If the primary language is not in the supported list, inform the user which languages are supported. Offer to proceed with the closest supported language file if the user agrees, or assess dimensions generically without language-specific criteria.

---

## Phase 2: Launch 4 Assessment Agents in Parallel

### Prompt Composition

Each agent receives a composed prompt built from reference files:

1. **Read the language file** — `references/languages/{PRIMARY_LANGUAGE}.md`
2. **Read the dimension files** — each agent gets its relevant dimension files from `references/dimensions/`
3. **Compose the prompt** — role preamble + codebase snapshot + dimension content + language content + output instructions

Use the Read tool to load each reference file, then include the content inline in the agent prompts. When including the language file, instruct each agent to reference only the sections relevant to its assigned dimensions.

### Agent Prompts

Send a **single message** with **4 Agent tool calls** (subagent_type: `general-purpose`) to launch all agents simultaneously.

---

**Agent 1: Test & CI Agent**

Dimension files to read and include:
- `references/dimensions/test-foundation.md`
- `references/dimensions/feedback-loops.md`

Prompt:
```
You are a senior engineering consultant specializing in test infrastructure and developer feedback loops. Assess how well this codebase's testing and CI/CD setup supports autonomous AI agent work.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess two dimensions: **Test Foundation** and **Feedback Loops**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands, then apply any score modifiers.

Reference only the Test Foundation and Feedback Loops sections from the language file.

### Dimension Guide: Test Foundation

[INSERT CONTENT OF references/dimensions/test-foundation.md]

### Dimension Guide: Feedback Loops

[INSERT CONTENT OF references/dimensions/feedback-loops.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for both dimensions in the output format specified in each dimension guide. Be specific — reference actual files, counts, and statistics.
```

---

**Agent 2: Documentation Agent**

Dimension files to read and include:
- `references/dimensions/documentation.md`

Prompt:
```
You are a senior engineering consultant specializing in developer experience and knowledge management. Assess how well this codebase's documentation enables AI agents to work autonomously without constant human clarification.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guide and language-specific criteria below to assess one dimension: **Documentation & Context**. Run the evidence-gathering commands to collect data. Score 0-100 following the scoring bands.

Reference only the Documentation sections from the language file.

### Dimension Guide: Documentation & Context

[INSERT CONTENT OF references/dimensions/documentation.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment in the output format specified in the dimension guide. Be specific — reference actual files found. CLAUDE.md is the most important artifact for agent-readiness — give it special attention.
```

---

**Agent 3: Code Quality Agent**

Dimension files to read and include:
- `references/dimensions/code-clarity.md`
- `references/dimensions/consistency.md`

Prompt:
```
You are a senior engineering consultant specializing in code quality and developer tooling. Assess how navigable and consistent this codebase is for AI agents — agents perform better in codebases with small, focused files and enforced conventions.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess two dimensions: **Code Clarity** and **Consistency & Conventions**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands.

Reference only the Code Clarity and Consistency sections from the language file.

### Dimension Guide: Code Clarity

[INSERT CONTENT OF references/dimensions/code-clarity.md]

### Dimension Guide: Consistency & Conventions

[INSERT CONTENT OF references/dimensions/consistency.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for both dimensions in the output format specified in each dimension guide. Be specific — reference actual files and line counts.
```

---

**Agent 4: Architecture Agent**

Dimension files to read and include:
- `references/dimensions/type-safety.md`
- `references/dimensions/architecture-clarity.md`
- `references/dimensions/change-safety.md`

Prompt:
```
You are a senior engineering consultant specializing in software architecture and developer safety systems. Assess how safely and predictably AI agents can modify this codebase — guard rails vary by language: type systems for statically-typed languages, contract/test systems for dynamically-typed ones.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess three dimensions: **Type Safety**, **Architecture Clarity**, and **Change Safety**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands, then apply any score modifiers. Apply the language-appropriate Type Safety rubric based on LANGUAGE_TIER.

Reference only the Type Safety, Architecture, and Change Safety sections from the language file.

### D