/project-audit

Launch a comprehensive multi-agent audit of the entire project. Agents with diverse perspectives analyze the codebase in parallel, then findings are synthesized into a master assessment with actionable recommendations.

Unlike /swarm-audit (which audits a specific document or topic), this skill audits the whole project holistically — architecture, code quality, security, testing, and more — with agent selection automatically tuned to the project type.

Arguments

• $ARGUMENTS - Optional configuration. Space-separated tokens:
  • agents=N — Number of agents (default: 6, min: 4, max: 12)
  • focus=AREA[,AREA,...] — Comma-separated focus areas to emphasize (e.g., focus=security,performance)
  • output=DIR — Output directory for reports (default: docs/project-audit/)
  • verbosity=brief|standard|detailed — Report depth (default: standard)
  • skip=AGENT[,AGENT,...] — Comma-separated agent nicknames to exclude
  • include=AGENT[,AGENT,...] — Force-include specific optional agents by nickname

Examples:

/project-audit
/project-audit agents=8 focus=security,performance
/project-audit output=audits/pre-release verbosity=detailed
/project-audit agents=10 include=deployer,auditor
/project-audit focus=testing skip=scout

Instructions

1. Parse Arguments

AGENT_COUNT = extract from agents=N (default: 6, clamp to 4–12)
FOCUS_AREAS = extract from focus=X,Y (default: empty — auto-detect all)
OUTPUT_DIR  = extract from output=DIR (default: docs/project-audit/)
VERBOSITY   = extract from verbosity=X (default: standard)
SKIP_AGENTS = extract from skip=X,Y (default: empty)
INCLUDE_AGENTS = extract from include=X,Y (default: empty)

2. Auto-Discover Project Profile

Before selecting agents, build a project profile by scanning the repository. This determines which optional agents are relevant.

Scan these signals (read files, do NOT guess):

Build the profile object (mental model, not written):

PROJECT_PROFILE = {
  name: <from package.json, Cargo.toml, etc. or directory name>,
  languages: [...],
  frameworks: [...],
  has_frontend: bool,
  has_tests: bool,
  test_coverage_estimate: low|medium|high,
  has_ci: bool,
  has_docker: bool,
  dependency_count: approximate,
  has_docs: bool,
  has_api: bool,
  security_surface: low|medium|high,
  performance_critical: bool,
  project_size: small|medium|large,
  repo_age: <from git log --reverse>,
}

IMPORTANT: Spend real effort on discovery. Read package.json, README.md, config files, and sample source files. The better the profile, the more relevant the audit. Do NOT skip this step or guess from file names alone.

3. Select Agent Panel

Choose AGENT_COUNT agents. Always include all 5 core agents. Fill remaining slots from the optional roster based on the project profile, FOCUS_AREAS, INCLUDE_AGENTS, and SKIP_AGENTS.

Core Panel (always included)

Chroxy core-agent weighting:

• Sentinel weights the bearer-token authority model (primary / pairing-bound / hook-secret classes — see docs/security/bearer-token-authority.md), transport E2E encryption, and credentials.json at-rest encryption. Every new HTTP route or WS handler that touches session state is in scope.
• Inspector weights the two mandatory CI lints — test stateFilePath isolation (lint-tests-state-file-path.sh) and BaseSession opt-forwarding (lint-session-opt-forwarding.sh) — plus the three test layers: server/protocol node:test, dashboard/store-core vitest, and the visual/E2E smoke layer (Playwright dashboard smoke + Maestro mobile flows).
• Strategist weights mobile UX: reconnect/ConnectionPhase resilience, touch targets, plan-approval and AskUserQuestion flows, and offline behavior.

Optional Roster (auto-selected based on project profile)

Chroxy domain-specific optional agents:

Selection Algorithm

1. Start with 5 core agents
2. Remove any core agents in SKIP_AGENTS (minimum 3 core agents — refuse if user tries to skip more)
3. Force-add any agents in INCLUDE_AGENTS
4. For remaining slots (AGENT_COUNT - current count):
   a. Score each optional agent by relevance to PROJECT_PROFILE
   b. Boost score +2 for agents whose lens matches a FOCUS_AREA
   c. Select highest-scoring agents until slots are filled
5. Remove any optional agents in SKIP_AGENTS
6. Final panel size may be less than AGENT_COUNT if SKIP reduces it

Tell the user which agents were selected and why before launching the swarm.

4. Create Output Directory

mkdir -p "${OUTPUT_DIR}"

If the directory already contains a previous audit, warn the user and ask whether to overwrite or create a timestamped subdirectory (e.g., docs/project-audit/YYYY-MM-DD/).

5. Launch Agent Swarm

Launch ALL agents in parallel using the Task tool. Each agent receives:

1. The full project profile (languages, frameworks, size, etc.)
2. Their specific persona, lens, and evaluation criteria
3. Instructions to explore the actual codebase thoroughly
4. A structured report format to follow

Agent prompt template:

You are **"{NICKNAME}"** — {PERSONALITY}

You are auditing a project from the lens of **{LENS}**.

## Project Profile
{PROJECT_PROFILE_SUMMARY}

## Your Audit Scope

You MUST explore the codebase thoroughly. Read source files, configuration, tests, and documentation. Do NOT base your audit on file names alone.

### Exploration Strategy
0. **Use repo-memory first to save tokens** (this repo has it, ~1,500 files pre-indexed): `get_project_map` for structure, `get_file_summary`/`batch_file_summaries` to scan files (a fraction of a full Read each), `search_by_purpose` to find files by concept, `get_dependency_graph` to trace impact. `Read` files in full only for exact implementation/control flow or when a summary returns `suggestFullRead: true`.
1. Start with entry points: main files, index files, app entry, CLI entry
2. Trace key flows end-to-end (at least 2-3 major flows)
3. Read configuration and build files
4. Sample at least 5-10 source files across different modules
5. Read test files to understand what IS and ISN'T tested
6. Check for patterns: are conventions consistent across the codebase?

### Report Structure

#### Executive Summary
2-3 sentences: overall assessment from your lens.

#### Ratings

Rate each area on your lens (1-5 scale):

| Area | Rating | Evidence |
|------|--------|----------|
| {area relevant to lens} | X/5 | Specific file:line references |
| ... | ... | ... |

#### Top Findings
Rank your top 5-8 findings by severity. Each finding MUST include:
1. **Severity**: Critical / Major / Minor / Nitpick
2. **Finding**: Clear description
3. **Evidence**: Specific file paths and line numbers. Quote relevant code.
4. **Impact**: What goes wrong if this isn't fixed
5. **Recommendation**: Concrete fix (not "consider improving")

#### Strengths
What this project does WELL from your lens. Be specific — cite files and patterns.

#### Actionable Recommendations
Ordered list of concrete next steps. Each item must be specific enough to become a GitHub issue. Include:
- What to do (imperative verb)
- Where to do it (file paths)
- Why it matters (impact)
- Effort estimate: S (< 1 hour) / M (1-4 hours) / L (4-16 hours) / XL (> 16 hours)

#### Overall Rating
Single rating X.X/5 with one-paragraph justification.

## Rules
- READ actual source code. Verify everything against the codebase.
- Be specific. "This might be a problem" is worthless. "src/auth.js:42 uses MD5 for password hashing" is useful.
- Rate honestly. 3/5 means "adequate." 5/5 means "exemplary — I would showcase this." 1/5 means "actively harmful."
- Be opinionated. Strong views, loosely held. Do not hedge everything.
- Your recommendations must be actionable enough to become GitHub issues.

## Verbosity: {VERBOSITY}
- brief: Top 5 findings only, minimal evidence, skip Strengths section
- standard: Full report as described above
- detailed: Full report plus additional deep-dives into any area rated <= 2/5. Include code snippets for every finding.

Batching: Launch agents in parallel batches. First batch of up to 5 agents, then remaining agents in a second batch. Do NOT run agents in the background — use foreground Task calls so output returns directly.

Delegation tiers (cost discipline — do not strip):

Roles per /tiered-delegation: workhorse = one tier below the session ceiling, mechanical = cheapest available tier. Concrete model names live only in that skill's CUSTOMIZE-marker ladder — never here.

• Audit agents run at the workhorse tier by default. Codebase exploration and per-lens reporting are workhorse work; do not spawn panel agents at the ceiling. The orchestrator's master assessment (step 7) is where the expensive judgment lives.
• Discovery pre-pass at the mechanical tier. The step-2 profile scan's mechanical parts (file inventories, signal detection, dependency counts) run at the mechanical tier at low effort; the orchestrator interprets the results.
• Sample-verify instead of up-tiering. Before filing issues from agent recommendations (step 8), re-check a ~10% sample of the load-bearing findings with a stronger tier rather than re-running agents up-tier.
• Fan-out budget: ~12 workhorse/ceiling subagents per run. The budget counts workhorse- and ceiling-tier agents — a full 12-persona panel fills it exactly, and stays legal because the mechanical discovery pre-pass and the ~10% sample-verify checks do not count against it. Exceeding 12 requires an explicit one-line justification in the master assessment; 20 is a hard ceiling that includes every refute/verify agent, and no justification lifts it (≤3 refuters per finding — queue rounds rather than widen).

6. Write Individual Reports

After all agents return, write each report to its own file:

${OUTPUT_DIR}/
  00-master-assessment.md    <- You write this (step 7)
  01-craftsman.md            <- Code Quality
  02-architect.md            <- Architecture
  03-sentinel.md             <- Security
  04-inspector.md            <- Testing
  05-strategist.md           <- Feature Completeness
  06-{nickname}.md           <- Optional agents
  ...

Each file starts with:

# {Nickname}'s Audit: {Project Name}

**Agent**: {Nickname} — {one-line personality summary}
**Lens**: {lens description}
**Overall Rating**: X.X / 5
**Date**: {today}
**Verbosity**: {verbosity level}

---

7. Write Master Assessment

Create 00-master-assessment.md that synthesizes ALL agent findings into a unified assessment.

Required Sections

a. Project Profile Summary

Concise overview: name, languages, frameworks, size, what it does, project maturity.

b. Auditor Panel

Aggregate Rating: Weighted average (core agents 1.0x, optional agents 0.8x).

c. Risk Heatmap

ASCII grid mapping identified risks by likelihood vs. impact:

                    IMPACT
            Low      Medium     High     Critical
         ┌────────┬──────────┬────────┬──────────┐
  Likely  │        │          │ ██ R3  │ ██ R1    │
         ├────────┼──────────┼────────┼──────────┤
 Possible │        │ ░░ R5    │ ░░ R4  │ ██ R2    │
         ├────────┼──────────┼────────┼──────────┤
 Unlikely │ ·· R7  │ ·· R6    │        │ ░░ R8    │
         └────────┴──────────┴────────┴──────────┘

██ = Immediate action   ░░ = Plan to address   ·· = Monitor

Map each risk ID (R1, R2, ...) to a description below the grid.

d. Consensus Findings

Findings where 3+ agents independently identified the same issue. These are highest confidence. For each:

• What agents agree on
• Supporting evidence from multiple reports
• Recommended action
• Priority: P0 (fix now) / P1 (fix this sprint) / P2 (fix this quarter) / P3 (backlog)

e. Contested Points

Findings where agents disagree. Present each position with the agent's name. Include your synthesis of who is right and why — do not just list opinions.

f. Strengths

What the project does well, as identified across multiple agents. Grouped by theme.

g. Critical Path: Top 10 Recommendations

Synthesized and deduplicated from all agent recommendations. Ordered by priority, not by agent. Each recommendation includes:

h. Implementation Roadmap

Group the top 10 into a phased plan:

Phase 1 — Immediate (this week): P0 items, quick wins (S/M effort) Phase 2 — Short-term (this month): P1 items, medium effort Phase 3 — Medium-term (this quarter): P2 items, larger efforts Phase 4 — Long-term (backlog): P3 items, strategic improvements

For each phase, list:

• What to do (linked to recommendation #)
• Dependencies (which items unblock others)
• Expected outcome

i. Final Verdict

One of:

• Ship It — Project is solid. Address minor findings at your pace.
• Ship With Fixes — Project is good but has specific issues that should be fixed before/alongside the next release.
• Needs Work — Significant issues identified. Address Phase 1 items before expanding scope.
• Rethink — Fundamental concerns raised. Consider architectural changes before further investment.

One-paragraph justification with the aggregate rating.

j. Appendix: Agent Reports

Table linking to each individual report file.

8. Optionally Generate Issues

After writing the master assessment, ask the user:

"Would you like me to create GitHub issues for the top N recommendations? I can create them with appropriate labels and link them to the audit."

If yes, use this format for each issue:

gh issue create \
  --title "type(scope): recommendation title" \
  --label "enhancement" \
  --label "from-audit" \
  --body "$(cat <<'EOF'
## Context

Filed from: session {SESSION_ID}

Identified during project audit on {DATE}.
**Source:** {OUTPUT_DIR}/00-master-assessment.md — Recommendation #{N}
**Priority:** {P0-P3}
**Effort:** {S/M/L/XL}

## Agents Who Flagged This

{List of agents and their specific findings}

## Description

{Detailed description of what needs to change and why}

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Evidence

{File:line references from agent reports}
EOF
)"

Chroxy issue/commit conventions: create issues with a from-audit label. Title findings as type(scope): summary using chroxy's types (feat/fix/refactor/docs/test/chore/style/perf) and scopes (server/app/desktop/tunnel/ws/cli/ci/docs). Per the Zero Attribution Policy, never add any AI/Claude attribution to issues, commits, or PR bodies.

9. Commit Results

Stage and commit the audit files by name.

Stage explicit paths. git status --short first, then git add each report you just wrote. Never git add -A, git add ., git add -u, git add <dir>/, or git commit -a. A trailing-slash directory add is a bulk add: the working copy is shared with concurrent sessions, so ${OUTPUT_DIR}/ may also hold a stale report from another run or a file that is not yours. -u is not the safe one: it restages every tracked file whose worktree copy differs, including files a clean/smudge filter rewrote without you touching them — that is how git add -u turned a tracked 21KB .docx into a git-lfs pointer and committed it as an edit.

git status --short "${OUTPUT_DIR}"
git add "${OUTPUT_DIR}/<agent-1>.md" "${OUTPUT_DIR}/<agent-2>.md" "${OUTPUT_DIR}/master-assessment.md"
git commit -m "docs: project audit (${AGENT_COUNT} agents, aggregate ${AGGREGATE_RATING}/5)

Agents: ${AGENT_NICKNAMES_COMMA_SEPARATED}
Verdict: ${VERDICT}
Top finding: ${TOP_CONSENSUS_FINDING_SUMMARY}
"

Do NOT push unless explicitly asked.

10. Report to User

Output a concise summary:

## Project Audit Complete

| Metric | Value |
|--------|-------|
| Agents | ${AGENT_COUNT} (${CORE_COUNT} core + ${OPTIONAL_COUNT} optional) |
| Aggregate Rating | ${AGGREGATE_RATING} / 5 |
| Verdict | ${VERDICT} |
| Reports | ${OUTPUT_DIR}/ |

### Agent Ratings

| Agent | Rating | Top Finding |
|-------|--------|-------------|
| Craftsman | X.X/5 | ... |
| ... | ... | ... |

### Top 3 Consensus Findings
1. ...
2. ...
3. ...

### Top Contested Point
...

### Recommended Next Action
...

Configuration

Rating Scale

Chroxy grading criteria:

• Sentinel weights the bearer-token authority model, transport E2E encryption, and credentials.json at-rest encryption (OS-keychain key); any new endpoint touching session state must be checked against docs/security/bearer-token-authority.md.
• Profiler weights WebSocket streaming and large-output handling (stream parsing, background-shell reaping, message-id collisions).
• Inspector weights the mandatory CI lints (test stateFilePath isolation, BaseSession opt-forwarding) and gives extra weight to the visual-smoke / Maestro layers, which lag the unit layer.
• Advocate (if included) weights mobile reconnect resilience and touch ergonomics; Tunneler weights tunnel/WS reliability under drops.

Agent Behavior Rules

• Agents MUST read actual source code — at least 5-10 files across different modules
• Agents MUST provide file:line references for every finding
• Agents MUST rate each area independently with evidence
• Agents MUST end with actionable recommendations that could become GitHub issues
• Agents MUST include effort estimates (S/M/L/XL) for every recommendation
• Agents should be opinionated, not diplomatic — strong views, loosely held
• Agents should acknowledge strengths, not just problems — a balanced audit is more credible

Verbosity Levels

Customization

Adding Custom Agent Personas

To add a custom agent, include it in your INCLUDE_AGENTS with a description in the arguments. Or, to make it permanent, create a .claude/audit-agents.json file:

{
  "custom_agents": [
    {
      "nickname": "Regulator",
      "lens": "GDPR compliance, data privacy, consent flows, data retention",
      "personality": "Privacy lawyer turned engineer who reads every data flow for compliance violations.",
      "auto_include_when": "Project handles personal data or has EU users",
      "detect_signals": ["gdpr", "privacy", "consent", "personal data", "user data"]
    }
  ]
}

Project-Level Defaults

Create .claude/audit-config.json to set defaults for this project:

{
  "default_agents": 8,
  "default_focus": ["security", "performance"],
  "default_verbosity": "detailed",
  "always_include": ["deployer", "auditor"],
  "always_skip": ["scout"],
  "output_dir": "docs/audits/"
}

Examples

/project-audit
/project-audit agents=8
/project-audit focus=security
/project-audit agents=10 focus=security,performance verbosity=detailed
/project-audit output=audits/pre-launch agents=12
/project-audit skip=scout,chronicler
/project-audit include=deployer verbosity=brief