prime

name	prime
description	Evaluate an existing codebase to produce a detailed report on project purpose, health, status, and recommended next steps. Suggest when — new session project questions, encountering repo first time, resuming after break, health/quality/documentation inquiries, architectural decisions, or "overview"/"assess" requests.
effort	high
allowed-tools	Read, Glob, Grep, Agent, Bash(git:*), Bash(head:*), Bash(wc:*)

Prime

Perform a comprehensive evaluation of the current codebase/project and produce a structured report covering what the project is, where it stands, and what should happen next. This is the skill to use when encountering any project for the first time, resuming work after a break, or needing a full situational assessment before making decisions.

This skill is read-only. It NEVER modifies files, commits, or pushes.

Input

Arguments: $ARGUMENTS

Optional arguments:

• A specific focus area (e.g., "testing", "deployment readiness", "documentation")
• A path to a subdirectory to scope the analysis

If no arguments are provided, evaluate the entire project from the repository root.

Instructions

Execute ALL phases below using per-phase dispatch: Phases 1, 3, and 5 run via context: fork + agent: Explore (read-only analysis, isolated context). Dispatch all three simultaneously using the Agent tool — do NOT wait for one to finish before spawning the next. They are mutually independent; only Phase 6 needs their combined output. Phase 0 (lab notebook) and Phase 6 (recommendations) run inline in the main conversation — they require full prior-phase output visibility. Phase 2 runs its git commands itself (see that phase's note).

Phase 0: Lab Notebook (Mandatory First Read)

Before any other analysis, check for LAB_NOTEBOOK.md at the repository root (and within the scoped path if $ARGUMENTS specifies a subdirectory). If it exists, read it in full before proceeding to Phase 1.

The lab notebook typically contains the most current and authoritative context for the project — active decisions, open action items, recent experiment results, and current baselines — and often contradicts or supersedes what the README claims. Reading it first prevents Phase 1-5 from producing conclusions that the lab notebook has already invalidated.

Carry forward for use throughout the remaining phases:

• Decision Log entries — inform architecture, risk, and recommendation sections
• Open Action Items — feed into open work detection and recommended next steps
• Recent experiment entries (last 3-5) — reveal what was tried, what worked, what failed
• Current Baseline measurements — use these over README descriptions when they conflict

If no LAB_NOTEBOOK.md is present, note "Lab Notebook: Absent" and proceed.

Phase 1: Project Identity

Dispatch: This phase runs via context: fork + agent: Explore. Fork an isolated Explore subagent for all file scanning and manifest reading in this phase. Return findings to parent for report assembly.

Determine what this project IS.

1. Read project manifests -- Check for package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile, *.csproj, Makefile, docker-compose.yml, or similar. Extract: project name, version, description, language/runtime, declared dependencies.
2. Read documentation -- Check for README.md, CLAUDE.md, CONTRIBUTING.md, docs/, wiki/. Extract: stated purpose, architecture overview, setup instructions.
3. Scan entry points -- Identify main entry points (main.*, index.*, app.*, __main__.py, cli.*, server.*). Trace the top-level execution flow.
4. Identify project type -- Classify as: library, CLI tool, web application, API service, plugin/extension, monorepo, data pipeline, mobile app, infrastructure-as-code, or other.

Output for report: Project name, type, language(s), purpose (1-3 sentences), key dependencies.

Phase 2: Repository Health

Assess the project's current state and activity.

1. Git history analysis — run these yourself with Bash; the values are not pre-loaded. The `!`cmd `` spans below are inert under the harness pre-pass (see ADR-0011), so they render as literal text rather than expanding. They are kept in this inert form deliberately: rewriting them into the tidy double-backtick form — the live one, per ADR-0011's escaping table — would turn on seven shell executions that have never run, four of which Bash(git:*) alone would reject for piping into head/wc. Skip this whole item when not in a git repository (see Error Handling).

   • Recent commits: !git log --oneline -20``
   • Last commit date: !git log --format='%ai' -1``
   • First commit date: !git log --format='%ai' --reverse | head -1``
   • Top contributors: !git shortlog -sn --no-merges | head -10``
   • Activity last 30 days: !git log --since="30 days ago" --oneline | wc -l``

2. Branch status — likewise run yourself; the spans below are inert:

   • Active branches: !git branch -a --sort=-committerdate | head -10``
   • Working tree state: !git status -s``

3. Open work detection -- Check for: TODO, FIXME, HACK, XXX comments across source files. Check for IMPLEMENTATION_PLAN.md, PROGRESS.md, RECOMMENDATIONS.md, open GitHub issues/PRs if gh is available.

4. Lab notebook -- Check for LAB_NOTEBOOK.md. If present, read it thoroughly and extract:

   • Decision Log: Active decisions and their rationale — these reflect architectural and operational choices that shape what happens next
   • Open Action Items: Pending follow-ups with priority and source entry — these are the project's known TODO list beyond code comments
   • Recent experiment entries: Last 3-5 entries with status — reveals what was recently tried, what worked, what failed
   • System state measurements — more current and specific than README descriptions

Output for report: Repository age, activity level (active/maintained/stale/abandoned), contributor count, working tree status, open work items, lab notebook summary (if present).

Phase 3: Code Quality & Architecture

Dispatch: This phase runs via context: fork + agent: Explore. Fork an isolated Explore subagent for all codebase structure analysis, metric collection, and CI/CD inspection. Return findings to parent for report assembly.

Evaluate the codebase structure and quality.

1. Project structure -- Map the directory tree (top 3 levels). Identify the architectural pattern: monolith, microservices, plugin architecture, layered, hexagonal, MVC, etc.

2. Code metrics:

   • Total source files (by language)
   • Approximate lines of code (use wc -l on source files, exclude node_modules, venv, build artifacts)
   • Largest files (potential god classes/modules)
   • Circular dependency indicators

3. Test coverage:

   • Test directory presence and structure
   • Test count (if runnable without setup)
   • Coverage configuration (pytest-cov, jest --coverage, etc.)
   • Test-to-source ratio

4. CI/CD pipeline:

   • Check .github/workflows/, .gitlab-ci.yml, Jenkinsfile, Dockerfile, etc.
   • What does CI run? (lint, test, build, deploy)
   • Are there quality gates? (coverage thresholds, linting enforcement)

5. Configuration & secrets:

   • .env files (check .gitignore coverage)
   • Config files and their complexity
   • Secret management approach

6. Code quality signals:

   • Linter configuration (eslint, ruff, clippy, golangci-lint)
   • Type checking (TypeScript, mypy, pyright)
   • Pre-commit hooks
   • Code formatting enforcement

Output for report: Architecture pattern, code size, test coverage status, CI/CD maturity, quality tooling summary.

Phase 4: Documentation & Developer Experience

Assess how easy it is to understand and work with this project.

1. Documentation completeness:

   • README: Does it explain setup, usage, and contribution?
   • API documentation (if applicable)
   • Architecture Decision Records (ADRs)
   • LAB_NOTEBOOK.md (experiment log with decisions, action items, and baselines)
   • Inline code comments (density and quality)
   • CLAUDE.md or similar AI-context files

2. Developer onboarding:

   • Can a new developer set up the project from README alone?
   • Are there development scripts (make dev, npm run dev, docker-compose up)?
   • Is there a CONTRIBUTING.md?

3. Dependency documentation:

   • Are system dependencies documented?
   • Are environment variables documented?
   • Are third-party service requirements listed?

Output for report: Documentation grade (A-F), onboarding friction points, missing documentation.

Phase 5: Risk Assessment

Dispatch: This phase runs via context: fork + agent: Explore. Fork an isolated Explore subagent for all security posture checks, dependency scanning, and technical debt analysis. Return categorized risk items to parent for report assembly.

Identify potential problems and blockers.

1. Technical debt indicators:

   • Large files with high complexity
   • Duplicated code patterns
   • Deprecated dependency usage
   • TODO/FIXME density
   • Disabled tests

2. Security posture:

   • Hardcoded credentials or API keys
   • .env in git history
   • Dependency vulnerabilities (if audit tools available)
   • Input validation patterns

3. Operational risks:

   • Single points of failure
   • Missing error handling patterns
   • No monitoring/logging infrastructure
   • Missing backup/recovery procedures

Output for report: Risk items categorized as Critical/High/Medium/Low.

Phase 6: Recommended Next Steps

Based on ALL findings, produce a prioritized action plan.

Before constructing recommendations, review all findings from Phases 2-5 holistically. Identify shared root causes and interrelationships between issues. Group related findings into integrated corrective actions rather than listing isolated fixes. The goal is recommendations that, when executed together, produce architecturally coherent improvements — not a whack-a-mole list of patches where fixing one issue creates or worsens another.

1. Immediate actions (do now, < 1 hour each):

   • Critical security fixes
   • Broken CI/tests
   • Missing .gitignore entries

2. Short-term improvements (this week):

   • Documentation gaps
   • Test coverage gaps
   • Dependency updates
   • Code quality quick wins

3. Strategic initiatives (plan and schedule):

   • Architectural improvements
   • New feature opportunities
   • Performance optimizations
   • Scalability preparations

4. Suggested first task:

   • Based on the full analysis, recommend the single most impactful thing to do next
   • Explain WHY this is the highest-leverage action
   • If multiple issues share a root cause, recommend addressing that root cause rather than the individual symptoms

Output

Present findings as a structured in-conversation report with this format:

# Project Prime Report
**Project:** [name]
**Generated:** [date]
**Scope:** [full repo | specific path]

---

## 1. Project Identity

| Field | Value |
|-------|-------|
| Name | [name] |
| Type | [library/CLI/webapp/API/etc.] |
| Language(s) | [primary, secondary] |
| Version | [current version or "unversioned"] |
| Purpose | [1-3 sentence description] |

**Key Dependencies:** [top 5-10 dependencies with purpose]

---

## 2. Repository Health

| Metric | Value |
|--------|-------|
| Age | [first commit to now] |
| Last Activity | [last commit date] |
| Activity Level | [Active/Maintained/Stale/Abandoned] |
| Contributors | [count] |
| Working Tree | [Clean/Modified/Uncommitted changes] |
| Open Work | [IMPLEMENTATION_PLAN items, TODOs, issues] |
| Lab Notebook | [Present/Absent — if present: # entries, # active decisions, # open action items] |

---

## 3. Code Quality & Architecture

| Metric | Value |
|--------|-------|
| Architecture | [pattern] |
| Source Files | [count by language] |
| Lines of Code | [approximate] |
| Test Files | [count] |
| Test Coverage | [percentage or "not configured"] |
| CI/CD | [present/absent, what it runs] |
| Linting | [tool and status] |
| Type Checking | [tool and status] |

**Largest Modules:** [top 3-5 files by size]

---

## 4. Documentation

| Aspect | Grade | Notes |
|--------|-------|-------|
| README | [A-F] | [what's good/missing] |
| Setup Guide | [A-F] | [can you get running from docs alone?] |
| API Docs | [A-F or N/A] | [coverage level] |
| Architecture Docs | [A-F] | [ADRs, diagrams, etc.] |
| Code Comments | [A-F] | [density and quality] |
| **Overall** | **[A-F]** | |

---

## 5. Risk Assessment

### Critical
- [item or "None identified"]

### High
- [items]

### Medium
- [items]

### Low
- [items]

---

## 6. Recommended Next Steps

### Immediate (< 1 hour)
1. [action] -- [why]

### Short-term (this week)
1. [action] -- [why]
2. [action] -- [why]

### Strategic (plan & schedule)
1. [action] -- [why]

### Suggested First Task
> [Specific, actionable recommendation with rationale]

---

*Report generated by /prime on [date]*

Example

User: /prime

Claude: [Analyzes the codebase across all 6 phases]

# Project Prime Report
**Project:** claude-marketplace
**Generated:** 2026-02-16
...
[Full structured report]

User: /prime testing

Claude: [Focuses analysis on testing infrastructure and coverage]

# Project Prime Report (Focus: Testing)
...

User: /prime plugins/bpmn-plugin

Claude: [Scopes analysis to the bpmn-plugin subdirectory]

# Project Prime Report
**Project:** bpmn-plugin
**Scope:** plugins/bpmn-plugin
...

Error Handling

• If not in a git repository: Note this in the report, skip git-dependent analysis, proceed with file-based analysis
• If project is empty or near-empty: Produce abbreviated report noting the project appears to be in initial scaffolding phase
• If a specific tool (gh, npm, pip) is unavailable: Skip that check, note it as "unable to assess" in the report
• If the project is extremely large (>10,000 files): Use sampling -- analyze representative directories rather than exhaustive scan
• If arguments specify a path that doesn't exist: Report the error and fall back to full repository analysis

Performance

Project Size	Expected Duration
Small (< 50 files)	30-60 seconds
Medium (50-200 files)	1-3 minutes
Large (200-500 files)	3-5 minutes
Very Large (500+ files)	5-10 minutes