esper-audit

name	esper:audit
description	Comprehensive project audit — health, architecture, phase retrospective, and codebase quality. Produces a scannable report with actionable recommendations.

You are performing a comprehensive project audit.

The user's initial prompt (if any): $ARGUMENTS

Step 1: Check setup

Run esperkit config check. If it exits non-zero, tell the user to run /esper:init first and stop.

Run esperkit config get current_phase to get the current phase slug.

Step 2: Gather project data

Read the following files:

• .esper/CONSTITUTION.md
• .esper/esper.json
• .esper/phases/<current_phase>.md

Run these commands to gather plan state:

esperkit plan list --dir pending --format json

esperkit plan list --dir active --format json

esperkit plan list --dir done --format json

Run these commands for git history and dependency health:

git log --oneline -20

git log --oneline --since="2 weeks ago" | wc -l

npm audit --json 2>/dev/null || true

npx npm-check-updates --errorLevel 0 2>/dev/null || true

Step 3: Project Health

Analyze the gathered data across four dimensions:

Constitution Alignment

• Cross-reference recent commits and shipped plans against the principles in CONSTITUTION.md
• Flag any drift — work that contradicts or ignores stated principles

Phase Progress

• Count plans: done vs total (pending + active + done) for the current phase
• Check acceptance criteria in the phase file — which are met, which are outstanding

Backlog State

• Count pending plans by priority
• Flag stale plans (created more than 2 weeks ago with no activity)
• Flag an empty backlog (no pending plans remaining)

Momentum

• Commit frequency from the 2-week count
• Plans shipped recently
• Stall detection: if no commits in the last 3 days or no plans shipped in the last week, flag it

Assign an overall health rating: HEALTHY, WATCH, or ATTENTION NEEDED.

Step 4: Phase Retrospective

Analyze the current phase file against shipped work:

Goals vs Accomplishments

• List each In Scope item from the phase file
• For each item, identify which done/active/pending plans cover it
• Mark status: covered, partially covered, or uncovered

Acceptance Criteria

• List each acceptance criterion from the phase file
• Assess whether shipped plans satisfy it: met, partially met, or not met

Shipped Plans Summary

• If the phase file has a ## Shipped Plans section, use it
• Otherwise, list done plans with their titles

Gaps and Risks

• In Scope items with no covering plan
• Acceptance criteria not yet met
• Active or pending plans that may not ship before phase end

Step 5: Dependency Health

Analyze the npm audit and npm-check-updates output from Step 2:

Vulnerabilities

• Count by severity (critical / high / moderate / low)
• List any critical or high vulnerabilities with affected packages

Outdated Packages

• Count packages with available major, minor, and patch updates
• Flag any packages more than 2 major versions behind

Redundancy

• Check package.json for packages that overlap in purpose (e.g. multiple HTTP clients, multiple test runners)

Assign a dependency health rating: CURRENT, WATCH, or OUTDATED.

Step 6: Architecture Review

Launch an Explore subagent using the Task tool with subagent_type: "Explore":

You are a senior software architect conducting an architecture review. You've been hired to evaluate this project's structural health before the team scales.

Review the codebase with these lenses:

1. Directory structure — is the layout intuitive? Would a new hire know where to add a new module?
2. Module boundaries — are concerns cleanly separated? Any circular dependencies or god modules that do too much?
3. Naming conventions — are file names, function names, and variable names consistent and predictable across the project?
4. Import/dependency patterns — are imports shallow and logical? Any files reaching deep into other modules' internals?
5. Configuration — are config files well-organized? Any duplication or drift between environments?
6. Principle adherence — does the code follow these project principles:

[Insert relevant principles from CONSTITUTION.md]

Rate each finding:
- observation: neutral architectural note
- warning: structural smell worth addressing
- concern: significant issue that will cause pain as the project grows

Return a structured list grouped by category. One line per finding with file paths. Skip categories with no findings.

Step 7: Codebase Quality Audit

Launch an Explore subagent using the Task tool with subagent_type: "Explore":

You are a senior engineer conducting a pre-release codebase audit. Your job is to find the issues that would embarrass the team in production or slow down the next contributor. Be thorough but practical — only flag things that matter.

Audit the codebase for:

1. Dead code — unused exports, unreachable branches, commented-out code that should have been deleted
2. Test coverage gaps — important logic paths, edge cases, or error scenarios without tests
3. Error handling — silent failures, swallowed exceptions, missing try/catch around I/O, unhandled promise rejections
4. Inconsistencies — mixed patterns for the same task, style drift across files, conventions that aren't followed everywhere
5. Tech debt markers — TODO/FIXME/HACK comments, workarounds with no linked issue, shortcuts that became permanent

Rate each finding:
- low: cleanup item, no functional risk
- medium: should fix soon, potential for bugs or confusion
- high: real risk, fix before shipping

Return a structured list grouped by category. Include file paths and line numbers. One line per finding. Skip categories with no findings.

Step 8: Security Review

Launch an Explore subagent using the Task tool with subagent_type: "Explore":

You are a security engineer conducting a security audit before this project ships to production. Think like an attacker — find the weaknesses a penetration tester would exploit.

Audit the codebase for:

1. Injection risks — command injection, path traversal, template injection, SQL/NoSQL injection. Trace any user input or external data through to where it's used.
2. Authentication & authorization — missing auth checks, privilege escalation paths, insecure session handling
3. Secrets & credentials — hardcoded API keys, tokens, passwords, or connection strings. Check config files, env examples, and committed .env files.
4. Input validation — system boundaries (CLI args, API inputs, file reads, environment variables) where untrusted data enters without validation or sanitization
5. Dependency risk — known vulnerable patterns in how dependencies are used (e.g. unsafe deserialization, eval of user data, prototype pollution vectors)
6. Information leakage — verbose error messages exposing internals, stack traces in production, debug endpoints left enabled

Rate each finding:
- low: theoretical risk, low exploitability
- medium: exploitable under certain conditions, should fix
- high: directly exploitable, fix immediately

Return a structured list grouped by category. Include file paths and line numbers. One line per finding. Skip categories with no findings.

Step 9: Developer Experience Review

Launch an Explore subagent using the Task tool with subagent_type: "Explore":

You are a new team member on your first day. You've just cloned this repo and need to get productive. Evaluate how easy or painful that process is.

Review the project for:

1. Onboarding — is there a clear README with setup instructions? Can you go from clone to running in under 5 minutes? Are prerequisites documented?
2. Documentation accuracy — do the docs match the actual code? Are there outdated instructions, missing steps, or broken examples?
3. Dev tooling — are linting, formatting, and type checking configured and consistent? Are there dev scripts in package.json for common tasks?
4. Error messages — when things go wrong, are the error messages helpful? Do they tell you what happened AND what to do about it?
5. Contribution friction — is it clear how to add a new feature, fix, or test? Are there patterns to follow or is every file different?

Rate each finding:
- smooth: works well, no friction
- rough: workable but confusing or underdocumented
- broken: blocks productivity, needs fixing

Return a structured list grouped by category. One line per finding with file paths where relevant. Skip categories with no findings.

Step 10: API & Interface Consistency

Launch an Explore subagent using the Task tool with subagent_type: "Explore":

You are an API design reviewer evaluating the public interfaces of this project — CLI commands, exported functions, configuration schemas, and any external-facing contracts.

Review for:

1. Naming consistency — do CLI flags, config keys, function names, and file conventions follow a single naming pattern? Flag any that break the convention.
2. Parameter patterns — are similar operations invoked the same way? Flag inconsistent argument ordering, mixed flag styles (--kebab vs --camelCase), or unpredictable defaults.
3. Output consistency — do commands and functions return data in consistent formats? Flag mixed output styles (JSON in one place, plain text in another for similar operations).
4. Error contracts — do errors follow a consistent shape? Flag places where errors are strings in one module and objects in another, or where exit codes are inconsistent.
5. Breaking change risks — flag any public interfaces that are fragile or would be hard to change without breaking consumers.

Rate each finding:
- consistent: follows established patterns
- drift: minor deviation from the convention
- inconsistent: actively confusing, should be standardized

Return a structured list grouped by category. One line per finding with file paths. Skip categories with no findings.

Important: Launch Steps 6, 7, 8, 9, and 10 Explore subagents in parallel using separate Task tool calls in the same message.

Step 11: Report and Actions

Print a structured report:

## Project Audit Report

### 1. Project Health: [HEALTHY | WATCH | ATTENTION NEEDED]
- **Constitution Alignment:** [findings]
- **Phase Progress:** [X/Y plans complete, Z% of acceptance criteria met]
- **Backlog State:** [findings]
- **Momentum:** [findings]

### 2. Phase Retrospective: [phase name]

| In Scope Item | Status | Covered By |
|---|---|---|
| [item] | [covered/partial/uncovered] | [plan titles] |

**Acceptance Criteria:**
- [x] [met criterion]
- [ ] [unmet criterion]

**Gaps:** [uncovered items or unmet criteria]

### 3. Dependency Health: [CURRENT | WATCH | OUTDATED]
- **Vulnerabilities:** [count by severity]
- **Outdated Packages:** [findings]
- **Redundancy:** [findings]

### 4. Architecture Review: [SOLID | MINOR ISSUES | NEEDS WORK]
- **Directory Structure:** [findings]
- **Module Boundaries:** [findings]
- **Naming Conventions:** [findings]
- **Import Patterns:** [findings]
- **Configuration:** [findings]
- **Pattern Adherence:** [findings]

### 5. Codebase Quality: [CLEAN | MINOR DEBT | SIGNIFICANT DEBT]
- **Dead Code:** [findings with file paths]
- **Missing Tests:** [findings with file paths]
- **Error Handling:** [findings with file paths]
- **Inconsistencies:** [findings with file paths]
- **Tech Debt:** [findings with file paths]

### 6. Security: [SECURE | MINOR RISKS | VULNERABLE]
- **Injection Risks:** [findings with file paths]
- **Auth & Authorization:** [findings with file paths]
- **Secrets & Credentials:** [findings with file paths]
- **Input Validation:** [findings with file paths]
- **Dependency Risk:** [findings with file paths]
- **Information Leakage:** [findings with file paths]

### 7. Developer Experience: [SMOOTH | ROUGH EDGES | NEEDS WORK]
- **Onboarding:** [findings]
- **Documentation Accuracy:** [findings]
- **Dev Tooling:** [findings]
- **Error Messages:** [findings]
- **Contribution Friction:** [findings]

### 8. API & Interface Consistency: [CONSISTENT | MINOR DRIFT | INCONSISTENT]
- **Naming:** [findings]
- **Parameters:** [findings]
- **Output:** [findings]
- **Error Contracts:** [findings]
- **Breaking Change Risks:** [findings]

### Recommendations
1. [HIGH] [recommendation] — [related section]
2. [MEDIUM] [recommendation] — [related section]
3. [LOW] [recommendation] — [related section]

After printing the report, use AskUserQuestion with multi-select:

"What would you like to do with these findings?"

Options:

• Create fix plans — convert actionable findings into /esper:fix plans
• Create explorations — convert concerns into /esper:explore investigations
• Add phase notes — append key findings to the current phase file
• Export report — save the full report to .esper/audits/YYYY-MM-DD-audit.md
• Done — no follow-up action

For each selected action:

• Create fix plans: For each high/medium finding, invoke /esper:fix with the finding details pre-filled.
• Create explorations: For each concern or architectural issue, invoke /esper:explore with the question pre-filled.
• Add phase notes: Append a ## Audit Notes (YYYY-MM-DD) section to .esper/phases/<current_phase>.md with a summary of key findings and recommendations.
• Export report: Create the .esper/audits/ directory if needed, then write the full report to .esper/audits/YYYY-MM-DD-audit.md.