audit-project

audit-project

Analyze a project's AI-readiness and produce a structured improvement report.

Announce at start: "Running AI-readiness audit on <current directory>..."

Usage

Run from within the project directory you want to audit:

/audit-project

The skill audits the current working directory.

Workflow

Steps 1 & 2: Parallel analysis

Dispatch both agents in a single message (two Agent tool calls simultaneously):

Agent 1 — claude-code-expert:

Analyze the project at <path> for AI-readiness. Read its CLAUDE.md, .claude/ structure, settings.json, and .mcp.json. Cross-reference against your knowledge of best practices. Return: (1) what's already good, (2) structure gaps, (3) anti-patterns found.

Agent 2 — automation-analyst:

Analyze the project at <path> for automation gaps. Detect language, framework, tooling, and CI patterns. Return the Recommended Automations section with top 1-2 picks per category.

Wait for both to complete before proceeding to Step 3.

Step 3: Compile report and save to file

Merge outputs and write the report to disk at:

<project-path>/.artifacts/specs/YYYY-MM-DD-ai-readiness-audit.md

Create .artifacts/specs/ if it doesn't exist. Use today's date for YYYY-MM-DD.

Report format:

# AI-Readiness Audit: <project-name>

> Generated by claude-audit on YYYY-MM-DD

## Project Profile
- **Type:** [detected stack — languages, frameworks, IaC tools]
- **Secrets management:** [how secrets are handled]
- **Existing Claude setup:** [summary of what's already configured]

## What's Already Good
| Area | Detail |
|------|--------|
| [area] | [what's well done] |

## Structure Gaps
| Gap | Recommended Fix | Priority |
|-----|----------------|----------|
| [gap] | [fix] | 🔴/🟡/🟢 |

## Recommended Automations
[Full output from automation-analyst — MCP servers, hooks, subagents, skills, plugins]

## Suggested Plugins to Install
| Plugin | Reason |
|--------|--------|
| [plugin] | [reason] |

## Priority Actions
| # | Action | Impact | Effort |
|---|--------|--------|--------|
| 1 | [highest impact first] | High/Med/Low | High/Med/Low |
| 2 | ... | | |

## Quick Wins (do today)
- [action that takes < 30 min and has high impact]

## Long-term Improvements
- [architectural or structural changes worth planning]

After writing, print a brief summary to the terminal only:

Audit saved to .artifacts/specs/YYYY-MM-DD-ai-readiness-audit.md

Key findings:
- [2-3 bullet points: most critical gaps or wins]

Priority Actions: [count] items — top action: [#1 action]

Step 4: Next steps prompt

Before asking, check if superpowers is available:

find ~/.claude/plugins/cache -name "SKILL.md" -path "*/writing-plans/*" 2>/dev/null | head -1 || echo "NOT FOUND"

Then ask:

Audit spec saved to .artifacts/specs/YYYY-MM-DD-ai-readiness-audit.md. What would you like to do next?

1. Write implementation plan — invoke superpowers:writing-plans with the audit spec as requirements; plan will be saved to .artifacts/plans/YYYY-MM-DD-ai-readiness-plan.md
2. Save to project memory — summarize findings into project memory for future sessions
3. Done

If superpowers is NOT found: show option 1 as unavailable and tell the user to install it first: claude plugin install superpowers@ccode-personal-plugins

If user selects option 1: invoke superpowers:writing-plans and pass this context explicitly:

Spec file: <project-path>/.artifacts/specs/YYYY-MM-DD-ai-readiness-audit.md Output plan to: <project-path>/.artifacts/plans/YYYY-MM-DD-ai-readiness-plan.md Use the Priority Actions table as the implementation steps.

This explicit path override ensures the plan lands in .artifacts/plans/ regardless of whether the target project has superpowers path overrides in its CLAUDE.md.