--- 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/.md` Run these commands to gather plan state: ```bash esperkit plan list --dir pending --format json ``` ```bash esperkit plan list --dir active --format json ``` ```bash esperkit plan list --dir done --format json ``` Run these commands for git history and dependency health: ```bash git log --oneline -20 ``` ```bash git log --oneline --since="2 weeks ago" | wc -l ``` ```bash npm audit --json 2>/dev/null || true ``` ```bash 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/.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`.