| name | project-audit |
| description | Project health audit with deterministic scoring. Use when: evaluating project quality, onboarding to new codebase, periodic health checks. Not for: runtime performance analysis, security-specific audits (use /codex-security). Output: 5-dimension score + actionable findings. |
Project Audit
When NOT to Use
- Security-specific review (use
/codex-security)
- Runtime performance profiling
- Mid-development review (use
/codex-review-fast)
Procedure
- Run
bash scripts/run-skill.sh project-audit audit.js --json to collect deterministic scores
- Parse the JSON output — overall_score, status, dimensions, checks, findings, next_actions
- If status = Blocked (P0 findings) — highlight critical gaps, suggest immediate fixes
- If status = Needs Work (P1 findings) — format improvement roadmap by dimension
- If status = Healthy — summarize strengths, note any P2 improvements
- Add qualitative interpretation beyond the scores (e.g., "test ratio is good but concentrated in unit tests")
Script Integration
The audit script runs 12 deterministic checks across 5 dimensions:
| Dimension | Checks | What It Measures |
|---|
| oss | 2 | LICENSE, README quality |
| robustness | 3 | CI config, lint/typecheck, test ratio |
| scope | 2 | Declared features vs implementation, AC completion |
| runnability | 3 | Package manifest, scripts, env/Docker setup |
| stability | 2 | Lock file + audit, type configuration |
Scoring Model
- Each check:
1 (pass) / 0.5 (partial) / 0 (fail) / N/A (skipped)
- Dimension score:
applicable_sum / applicable_count * 100
- Overall score: average of dimension scores
- Confidence:
applicable_checks / total_checks per dimension
Status Determination
| Status | Condition | Exit Code |
|---|
| Blocked | Any P0 finding | 2 |
| Needs Work | No P0, has P1 | 1 |
| Healthy | No P0/P1 | 0 |
Script Failure Fallback
If the script fails, report the error and suggest running manually:
bash scripts/run-skill.sh project-audit audit.js --json
Output Format
## Project Audit Report
| Field | Value |
|-------|-------|
| Repo | [name] |
| Score | **[N]/100** |
| Status | [icon] [status] |
### Dimensions
[table of dimension scores]
### Checks
[list of check results with suggestions]
### Next Actions
[prioritized action items]
## Gate: ✅/⛔
References
references/check-catalog.md — Check definitions, scoring criteria, ecosystem detection (read when investigating a specific check result)references/output-template.md — Report format examples and JSON schema (read when customizing output)
Verification
