| name | comprehensive-ecosystem-audit |
| description | Orchestrates all 7 ecosystem audits in staged waves with 4-concurrent-agent
limit, aggregates results into a unified health report with cross-audit
insights, domain heat maps, and priority-ranked findings.
|
| supports_parallel | true |
| fallback_available | false |
| estimated_time_parallel | 30 min |
| estimated_time_sequential | 90 min |
Document Version: 1.1
Last Updated: 2026-02-24
Status: ACTIVE
Comprehensive Ecosystem Audit
Orchestrates all 7 ecosystem audits (hook, session, TDMS, PR, skill, doc,
script) in 2 staged waves, aggregates results into a unified health report.
Invocation: /comprehensive-ecosystem-audit
Output: COMPREHENSIVE_ECOSYSTEM_AUDIT_REPORT.md in the project root.
CRITICAL RULES
- CHECK for saved progress first -- resume from
.claude/tmp/comprehensive-ecosystem-audit-progress.json if < 2 hours old.
- Run audits via npm scripts / node commands, not by reading checker code.
- CRITICAL RETURN PROTOCOL: Each agent saves JSON to
.claude/tmp/ecosystem-{name}-result.json and returns ONLY:
COMPLETE: {audit-name} grade {grade} score {score} errors {N} warnings {N} info {N}
- Check completion via
wc -l/wc -c on output files, never read full
output into context.
- Save progress after each stage to survive context compaction.
Compaction Guard
State file: .claude/tmp/comprehensive-ecosystem-audit-progress.json
Tracks stages (pending/completed), individual audit status
(pending/running/completed/failed), and result summaries (grade, score, counts).
| State | Resume Action |
|---|
| No file or > 2 hours old | Start fresh |
| Stage 1 partial | Re-run pending/failed Stage 1 audits |
| Stage 1 done, Stage 2 pending | Run Stage 2 |
| Stage 2 done, Stage 3 pending | Run Stage 3 (aggregation) |
| Stage 3 done | Display final report |
Details: See
reference/RECOVERY_PROCEDURES.md
Stage 1: Foundation Audits (4 parallel)
Dependencies: All 4 agents are independent. Stage 2 depends on Stage 1.
| Agent | Audit | Script | Result File |
|---|
| 1 | Hook | node .claude/skills/hook-ecosystem-audit/scripts/run-hook-ecosystem-audit.js --batch --summary | ecosystem-hook-result.json |
| 2 | Session | node .claude/skills/session-ecosystem-audit/scripts/run-session-ecosystem-audit.js --batch --summary | ecosystem-session-result.json |
| 3 | TDMS | node .claude/skills/tdms-ecosystem-audit/scripts/run-tdms-ecosystem-audit.js --batch --summary | ecosystem-tdms-result.json |
| 4 | PR | node .claude/skills/pr-ecosystem-audit/scripts/run-pr-ecosystem-audit.js --batch --summary | ecosystem-pr-result.json |
After completion: verify files exist, check sizes with wc -c, update progress.
Details: See reference/WAVE_DETAILS.md
Stage 2: Extended Audits (3 parallel)
| Agent | Audit | Script | Result File |
|---|
| 5 | Skill | node .claude/skills/skill-ecosystem-audit/scripts/run-skill-ecosystem-audit.js --batch --summary | ecosystem-skill-result.json |
| 6 | Doc | node .claude/skills/doc-ecosystem-audit/scripts/run-doc-ecosystem-audit.js --batch --summary | ecosystem-doc-result.json |
| 7 | Script | node .claude/skills/script-ecosystem-audit/scripts/run-script-ecosystem-audit.js --batch --summary | ecosystem-script-result.json |
Stage 3: Aggregation & Report Generation
Sequential. Read ONLY summary sections from each result file (first 50 lines or
summary key).
Weighted Health Grade
| Audit | Weight | Rationale |
|---|
| Hook | 15% | Core infrastructure |
| Session | 10% | Session management |
| TDMS | 15% | Debt tracking |
| PR | 15% | Review workflow quality gate |
| Skill | 20% | Largest surface area |
| Doc | 10% | Supporting infrastructure |
| Script | 15% | Build/test/deploy pipeline |
Formula: overallScore = sum(score * weight) / sum(completed_weights) Grades:
A=90+, B=80+, C=70+, D=60+, F=<60.
Cross-Audit Analysis
- Domain Heat Map -- bottom 10 category scores across all audits
- Shared File Hotspots -- files in findings from 3+ audits
- Common Pattern Violations -- anti-patterns in multiple audits
- Top 20 Findings -- top 3 from each audit, ranked by impact
Report Output
Write COMPREHENSIVE_ECOSYSTEM_AUDIT_REPORT.md: Executive Summary, Audit
Results table, Domain Heat Map, Top 20 Priority Findings, Cross-Audit Insights
(hotspots, patterns, gaps), Recommendations, Appendix (scripts, failed audits).
Cleanup
Update progress to completed, delete result files and progress file, present
summary.
Partial Failure Handling
If audit(s) fail: mark as "failed", log error, continue with remaining. Compute
weighted average using only completed audits. Note missing coverage in report.
Never block entire audit for one sub-audit failure.
When to Use
- Quarterly health check
- After major refactoring
- Before a release
- After adding new hooks/skills/scripts
When NOT to Use
- Quick single-domain check (use individual audit skills)
- Debugging specific issues (use
/systematic-debugging)
- When context budget is tight (7 agent launches)
Related Skills
Individual audits: /hook-ecosystem-audit, /session-ecosystem-audit,
/tdms-ecosystem-audit, /pr-ecosystem-audit, /skill-ecosystem-audit,
/doc-ecosystem-audit, /script-ecosystem-audit. Also: /audit-comprehensive
(9-domain code audit -- different scope).
Version History
| Version | Date | Description |
|---|
| 1.1 | 2026-02-24 | Trim to <500 lines: condense tables and agent prompts |
| 1.0 | 2026-02-24 | Initial -- 7 audits in 2 staged waves with aggregation |
