Repo Readiness Scan

---
name: repo-readiness-scan
description: >-
  Scores a repository's production readiness out of 10 across stack, hosting, CI/CD, environments,
  error tracking, docs, security, cost, integrations, LLM-readiness and code organisation, with
  the top 3 issues and which skills fix them. Use when the user asks how production-ready their
  repo is, wants a readiness score or repo scan, or asks what to fix first before launch. Not for
  a deep security review (use security-auditor).
---

# Repo Scanner

Scans any repository to build a complete picture of the current technical setup and scores production readiness.

## How It Works

1. Read the root directory tree to identify project type and structure
2. Detect the tech stack from config files
3. Check for production infrastructure (CI/CD, Docker, hosting)
4. Check for observability (monitoring, error tracking, logging)
5. Check for developer experience (documentation, agent config, tooling)
6. Output a structured scan report using the EXACT format below

## Step-by-Step Procedure

### Step 1: Read Directory Structure
```bash
find . -type f -not -path './.git/*' -not -path './node_modules/*' -not -path './.next/*' -not -path './dist/*' -not -path './__pycache__/*' -not -path './venv/*' | head -200
```

### Step 2: Detect Tech Stack

Check for these files to determine the stack:

| File | Stack |
|------|-------|
| `package.json` | Node.js / JavaScript / TypeScript |
| `tsconfig.json` | TypeScript |
| `next.config.*` | Next.js |
| `vite.config.*` | Vite |
| `requirements.txt` / `pyproject.toml` | Python |
| `go.mod` | Go |
| `Cargo.toml` | Rust |
| `Gemfile` | Ruby |

Read `package.json` or equivalent to understand dependencies and scripts.

### Step 3: Check Production Infrastructure

| Check | How |
|-------|-----|
| **CI/CD** | Look for `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile` |
| **Docker** | Look for `Dockerfile`, `docker-compose.yml`, `.dockerignore` |
| **Hosting** | Look for `vercel.json`, `railway.toml`, `fly.toml`, `render.yaml`, `serverless.yml` |
| **Environments** | Look for `.env.example`, `.env.local`, `.env.production` |
| **Build** | Check for build scripts in `package.json` or `Makefile` |

### Step 4: Check Observability

| Check | How |
|-------|-----|
| **Error tracking** | Grep for `sentry`, `@sentry/`, `posthog`, `datadog`, `bugsnag` in deps or code |
| **Analytics** | Grep for `gtag`, `analytics`, `mixpanel`, `amplitude` |
| **Logging** | Check for structured logging (winston, pino, structlog, loguru) |
| **Health checks** | Look for `/health`, `/healthz`, `/api/health` endpoints |

### Step 5: Check Developer Experience

| Check | How |
|-------|-----|
| **Root README** | Does `README.md` exist with setup instructions? |
| **Directory READMEs** | `find . -name "README.md" -not -path './node_modules/*' | wc -l` |
| **Agent config** | Look for `AGENTS.md`, `.cursorrules`, `.cursor/rules/`, `.claude/` |
| **Linting** | Look for `.eslintrc`, `.prettierrc`, `ruff.toml` |
| **Testing** | Look for `__tests__/`, `tests/`, `spec/`, test scripts |
| **Git hygiene** | Check `.gitignore` exists and covers common patterns |

### Step 6: Check Security

Return filenames only from credential detection. Never print matching source lines or values; verify candidates with redaction before declaring a leak.
```bash
grep -rl "sk-\|api_key\s*=\s*['\"].\+['\"]" --include="*.ts" --include="*.js" --include="*.py" --include="*.env" . 2>/dev/null | grep -v node_modules | grep -v '.env.example' | head -20
```

## MANDATORY Output Format

**You MUST use this exact markdown structure. Do not invent your own format.**

````markdown
## 🔍 Repo Scan: {project-name}

**Tech Stack:** {e.g. React 18 + TypeScript, Flask + Python 3.11}
**Hosting:** {e.g. Vercel, AWS, Railway, or "Not configured"}
**Framework:** {e.g. Next.js 14, Vite 5, FastAPI}

---

## 📊 Production Readiness Score: {X}/10

| # | Category | Status | Details |
|---|----------|--------|---------|
| 1 | Environment Setup | {✅/⚠️/❌} | {one-line detail} |
| 2 | CI/CD Pipeline | {✅/⚠️/❌} | {one-line detail} |
| 3 | Documentation | {✅/⚠️/❌} | {one-line detail} |
| 4 | Error Tracking | {✅/⚠️/❌} | {one-line detail} |
| 5 | Deployment | {✅/⚠️/❌} | {one-line detail} |
| 6 | Security | {✅/⚠️/❌} | {one-line detail} |
| 7 | Cost Awareness | {✅/⚠️/❌} | {one-line detail} |
| 8 | Integration Health | {✅/⚠️/❌} | {one-line detail} |
| 9 | LLM-Readiness | {✅/⚠️/❌} | {one-line detail} |
| 10 | Code Organization | {✅/⚠️/❌} | {one-line detail} |

**Scoring: ✅ = 1 point, ⚠️ = 0.5 points, ❌ = 0 points**

---

## 🚨 Top 3 Issues

1. **{Issue title}** — {Why it matters. File:line reference if applicable.}
2. **{Issue title}** — {Why it matters.}
3. **{Issue title}** — {Why it matters.}

---

## 🛠️ Recommended Next Steps

Run these skills to fix the issues above:

1. `{skill-name}` — {what it will fix}
2. `{skill-name}` — {what it will fix}
3. `{skill-name}` — {what it will fix}
````

**Rules for the output:**
- Use the EXACT table format above with ✅/⚠️/❌ status icons
- Score is X/10 where ✅=1, ⚠️=0.5, ❌=0
- Top 3 issues must include specific file:line references when possible
- Recommended next steps must name real skills from this set: `deployment-engineer` (CI/CD, Docker, environments), `deploy-to-vercel` or `railway` (hosting), `monitoring-setup` (errors, analytics, health), `security-auditor` (secrets, deps, auth), `cloud-cost-optimizer` (cloud spend), `dev-tool-integrations` (Slack/Linear/Sentry wiring), `agents-md-writer` (AGENTS.md / LLM-readiness), `repo-structurer` (READMEs, dead code, modularity)
- Keep the entire output under 100 lines
- Do NOT add extra sections, executive summaries, or risk assessments