Audit Orchestrator

/audit-orchestrator — Universal Orchestrator

Meta-skill that runs a project through Pre-Scan → Analysis → Optimization → Report on any kind of codebase. Self-detects the project type, picks the right analysis track, and writes all state into a resumable session directory.

Two Modes

Dry-Run Preview (RepoLens-inspired)

Invoke with dry-run argument to preview the full plan without firing any sub-agents or writing session state:

/audit-orchestrator dry-run

Dry-run output prints:

1. Detected project type and confidence (no Read of large files beyond fingerprint check)
2. Planned Phase-2 tracks — which audits/agents would run and why
3. Estimated cost envelope — tool calls × HANGAR_COST_PER_CALL_USD (default 0.02 USD)
4. Parallelization plan — which steps are independent, which serialize
5. Session directory that would be created — path only, not materialized

No .audit-session/ is written, no agents are spawned. Safe to run on any repo for planning. Exit after printing the plan.

The universal mode is always entered first. If Phase 1 (Pre-Scan) detects a supported web framework, Phase 2 activates the web orchestration path. For any other project type, Phase 2 runs the general + specialty analysis tracks described in universal-workflow.md.

Session Directory

Every run creates .audit-session/<YYYY-MM-DD>-<slug>/ with:

INDEX.md                 # TOC + navigation
STATUS.md                # Live session state — read first on resume
01-prescan/              # detection + project profile
02-analysis/             # findings + opportunities + fix queue
03-optimization/         # applied changes + deferred + deviations
04-report/REPORT.md      # canonical deliverable

• Full directory schema + file templates: session-schema.md.
• Phase-by-phase execution (inputs, actions, outputs, exit criteria): universal-workflow.md.
• Legacy web-specific state (.audit-orchestrator-state.json v3): state-schema.md (still written when the web orchestration path is active; coexists with the session directory).

Resume Protocol (Crash / Handoff / New Instance)

A fresh LLM or a different AI (or the same instance after a crash) picks up a session like this:

1. ls .audit-session/ → find the target session directory.
2. Read INDEX.md — understand the structure.
3. Read STATUS.md — learn the current phase, state, and "next action".
4. Claim the session: update STATUS.md active instance and last updated before the first tool call.
5. Continue from the next-action line.

STATUS.md is always current. It is updated at every phase transition and after every ~5 fix commits in Phase 3, and flipped to paused on exit. Because findings/TODOs/changes live in phase folders as plain Markdown, the entire session is portable — another LLM, or the user reading by hand, can pick it up without running any tool.

Problem solved by this skill

An Astro project needs:

• /audit for performance, SEO, a11y, privacy compliance, security
• /astro-audit for version-specific migration/best practices
• /project-audit for Git, CI/CD, testing, maintenance

Without orchestration: user must decide manually, duplicate work on security/infra.

An infra/homelab repo needs different things again (Docker hygiene, Compose V2, Traefik, service inventory vs. running services, backup state, cert expiry) — the orchestrator detects this and runs the infra track instead.

Problem

An Astro project needs:

• /audit for performance, SEO, a11y, privacy compliance, security
• /astro-audit for version-specific migration/best practices
• /project-audit for Git, CI/CD, testing, maintenance

Without orchestration: user must decide manually, duplicate work on security/infra.

Solution: Auto-Detection + Audit Plan

Step 0 — Session Init (always)

Before any detection, create the session directory:

1. Slug = <YYYY-MM-DD>-<short-descriptor> (see session-schema.md).
2. Create .audit-session/<slug>/ with empty phase folders.
3. Write initial INDEX.md (phases all pending) and STATUS.md (state: in_progress, phase: 01-prescan, next action: detect project type).
4. From this point on, every phase transition and every ~5 fixes updates STATUS.md. This is what makes the session crash-resilient.

Step 1 — Scan Project

Same detection as /audit + /project-audit, plus universal signals:

• package.json, pyproject.toml, go.mod, Cargo.toml, Dockerfile, docker-compose*.yml, .tf, ansible.cfg, .github/, .claude/, registry.json
• Detect frontend framework (Astro, Next, SvelteKit, Hugo, etc.)
• Detect backend (Fastify, Express, FastAPI, etc.)
• Detect project type using the universal decision table in universal-workflow.md: web-astro | web-sveltekit | web-nextjs | node-app | node-lib | python | go | rust | infra-docker | infra-iac | infra-homelab | meta-automation | monorepo | docs | data-ml | generic
• Detect output mode: output: "static" vs. output: "server" (from astro.config.*) — web only
• Related projects: audit-context.md → check relatedProjects (e.g., forms backend)
• Detect beta/unstable version: Version with -beta, -rc, -alpha suffix → prioritize migration audit

Write the result to 01-prescan/project-profile.md using the profile template (see session-schema.md). The profile drives Phase 2 track selection:

Rule: The general track (git hygiene, CI sanity, secret scan, dependency freshness, license posture, docs freshness) runs for every project. Specialty tracks are additive.

Step 1b — Infrastructure Scan (Pre-Audit)

Before starting project audits, check infrastructure level:

Detect GitHub:

• .github/ directory present → github: true
• git remote -v → github.com → extract repo owner + name
• Detect organization: gh api repos/{owner}/{repo} → owner.type == "Organization"

Detect VPS:

• audit-context.md → server section present?
• registry.json → server assignment for the project?
• Dockerfile/docker-compose present → deployment on server likely

Pre-Audit Recommendation:

Freshness Check + Opportunities:

Prior Context — Freshness Opportunities: If .freshness-state.json exists, read opportunities[] array:

• Include HIGH opportunities as "Pre-Audit Notes" in the audit plan
• Example: Opportunity { severity: "high", target: "audit/phases/02-security.md" } → "Note: Security phase has new best practices since last freshness check"
• Opportunities are NOT automatically fixed — only provided as context for the audits

Rule: With GitHub + VPS, the first session is recommended for infra checks:

1. GitHub org settings (once per org, not per repo)
2. GitHub repo settings (branch protection, secret scanning)
3. VPS quick check (ports, users, SSH, fail2ban)
4. Only then: regular audit sessions

Infra findings are documented with prefix INFRA- (VPS) or SEC- / GIT- (GitHub) — in the respective audit state files, not in the orchestrator state.

Step 1c — Security Pre-Scan (Claude Code Projects)

When .claude/ directory is detected in the project:

Rationale: Compromised hooks or MCP servers could manipulate audit results. Verify the Claude Code environment is clean before trusting audit output.

Integration: Security scan findings feed into the audit plan:

• CRITICAL security-scan findings → address before starting audit
• MCP permission issues → note in audit report context
• Hook safety issues → fix before running automated audit modes

Step 2 — Determine Audit Combination

Always add when detected:

Step 2b — Static Site Filter (Astro)

When output: "static" is detected, certain checks are irrelevant:

Rule: Mark skipped checks in state file as "status": "skipped", "reason": "static-output".

Step 2c — Related Projects (Cross-Repo)

When audit-context.md references related projects (e.g., forms backend):

1. Recommend separate audit: Related projects have their own codebase → separate /audit or /project-audit
2. Check interfaces: In the main audit, check integration:
   • API communication (CORS, auth, timeouts)
   • Shared infrastructure (same server, reverse proxy routing)
   • Credential management (shared secrets)
3. Cross-references in state: relatedProjects array with status ("audited", "open", "not in scope")

Step 2d — Checkpoint Gates between Audit Phases

In team mode and complex multi-audit runs: use checkpoint gates to ensure quality between phases.

Checkpoint Logic in Team Mode:

1. Teammate reports audit phase as done
2. Orchestrator checks gate conditions for next phase
3. Gate passed → next audit/phase is released
4. Gate not passed → orchestrator informs user + blocks next phase

Rules:

• Gates are recommendations, not hard blocks — user can skip gates
• CRITICAL findings in security/compliance gates are always reported
• Migration gate is HARD — with a broken build, no web audit is worthwhile
• Pre-report gate is HARD — incomplete reports are misleading

Step 3 — Manage Phase Overlap

Some phases exist in both audits but check different aspects. Do not delegate wholesale — instead clearly separate the focus:

Rule: Phases with different focus BOTH run. Only with true duplicates (same checks) does the more thorough one lead.

Step 4 — Intelligent Sequencing

The order of audits depends on the detected project:

Rule: With beta/RC versions ALWAYS run the migration audit first — a build that doesn't compile makes any other audit pointless.

Step 5 — Show Audit Plan to User

Dynamic plan based on detection. Example for different scenarios:

Scenario A: Framework Beta + Static + Docker + GitHub + VPS

Audit Plan for: {{PROJECT_NAME}}

Detected: {{FRAMEWORK}} {{VERSION}} (Beta) + Tailwind v4 + Docker + Reverse Proxy
Output: static (no SSR)
GitHub: {{ORG}}/{{REPO}} (Organization)
Server: {{SERVER_LIST}}
Related Projects: {{RELATED_NAME}} ({{RELATED_STACK}})
Recommendation: Pre-audit infra → Framework migration → Web quality → Code/CI

Pre-Audit: Freshness + Security + Infrastructure (1 session)
  /freshness-check        ← Pipeline knowledge current? Versions, standards, regulations
  /security-scan           ← Claude Code environment: MCP permissions, hook safety, secrets
  GitHub Org Settings     ← 2FA, base permissions, third-party access
  GitHub Repo Settings    ← Branch protection, secret scanning, CodeQL
  VPS Quick Check         ← Ports, users, SSH, fail2ban, services
  → Secure foundation before checking code

Audit 1: /{{FRAMEWORK}}-audit (migration checks) ← PRIORITY
  {N} sections, of which {M} relevant (ADPT section skip: static)
  Ensure breaking changes and build compatibility
  → Must run before web audit — broken build blocks everything

Audit 2: /audit (9 phases — web quality)
  01 Status Analysis      ← Baseline (version overview)
  02 Security             ← Web security (OWASP, headers, SRI, SSRF)
  03 Performance          ← Exclusive (CWV, Lighthouse, caching)
  04 SEO                  ← Exclusive (meta, structured data, sitemap)
  05 Accessibility        ← Exclusive (WCAG 2.2, accessibility regulations)
  07 Privacy              ← Exclusive (consent, cookie regulations)
  08 Infrastructure       ← VPS deep security + Docker + proxy
  09 Content & Design     ← Content, typography, colors, consistency
  (06 Code Quality       → delegated to /project-audit)

Audit 3: /project-audit (10 phases — code/CI/CD)
  02 Dependencies         ← Leads (lockfiles, corepack, provenance)
  03 Code Quality         ← Leads (patterns, coverage, complexity)
  04 Git & Versioning     ← Exclusive (+ GitHub supplement)
  05 CI/CD & Automation   ← Exclusive (OIDC, attestation, SLSA, + GitHub supplement)
  07 Testing & QA         ← Exclusive (coverage, E2E)
  08 Security             ← Supply chain (SBOM, ASVS, Sigstore, + GitHub supplement)
  09 Deployment           ← Container signing, SBOM in image, OCI (+ GitHub environments)
  10 Maintenance          ← Exclusive (+ GitHub supplement)
  (01 Structure          → status in /audit)

Related Projects:
  {{RELATED_NAME}}: Separate /project-audit recommended, check interfaces in main audit

Estimated Sessions: {calculated}
Shall I start?

Scenario B: Framework Stable + SSR (without VPS access)

...
Recommendation: Security scan → GitHub check → Web quality → Framework best practices

Pre-Audit: /security-scan + GitHub settings (in session 1)
Audit 1: /audit (8 phases) ← FIRST
Audit 2: /{{FRAMEWORK}}-audit (all sections incl. ADPT)
Audit 3: /project-audit (10 phases, with GitHub supplement)
...

Step 5b — Choose Execution Mode

After the audit plan, the orchestrator asks how the audits should be executed.

Offer options:

Rules:

• Team option ONLY shown when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set as env var
• With available team mode: mark as recommendation (faster, less manual work)
• Without team flag: manual as default, mention runner as alternative
• User can always abort and switch to manual mode

Check Team Availability:

# Check in orchestrator:
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
# If "1" → offer team option

Step 6 — Calculate Session Estimate

Not hardcoded — dynamically based on phase count:

Session Formula:
  framework_sessions = ceil(relevant_sections / 2) + ceil(expected_findings / 5)
  audit_sessions     = ceil(active_phases / 2)     + ceil(expected_findings / 5)
  project_sessions   = ceil(active_phases / 2)     + ceil(expected_findings / 5)

  planning_session   = 1  (orchestrator plan)
  fixing_sessions    = ceil(estimated_total_findings / 5)

  TOTAL = planning + framework + audit + project + fixing

Benchmarks for expected findings:

• First audit: ~5-8 findings per skill
• After previous audit: ~2-4 new findings
• Beta migration: ~8-15 findings (more breaking changes)

Step 7 — Combined State

→ Full state schema (v3) + JSON example + backward compatibility: See state-schema.md

Session Strategy

The order adapts to the project. Variants:

Variant A: Beta/Migration + GitHub + VPS

Variant B: Standard + GitHub (Stable, Current)

Variant C: No Framework-Specific Audit (Backend, CLI, Library)

Variant D: SvelteKit Full-Stack (+ Drizzle + Auth + GitHub + VPS)

Automation: /audit-runner

For automated runs, the /audit-runner skill can be used. It runs all audits unattended in separate sessions — no context limit.

/audit-runner setup    → Configuration and audit plan
/audit-runner start    → Start autonomous run
/audit-runner status   → Check progress

When to use /audit-runner instead of manual:

• First overview of a new project (collect findings, fix later)
• Audit multiple projects sequentially
• Overnight run: audit runs, review results in the morning

Team Mode (Parallel Audit Execution)

→ Full team mode documentation (T1-T8, pre-audit, error handling): See team-modus.md

Cross-Audit Findings

When findings are fixed, check if the fix is also relevant in another audit:

• Web security fix in /audit (e.g., SRI, CSP) → check if /project-audit security is affected
• Supply chain fix in /project-audit (e.g., SBOM, Sigstore) → check if /audit infra is affected
• Docker fix (e.g., Compose V2) → mark as fixed in BOTH audits (infra + deployment)
• Container signing in /project-audit → also relevant in /audit infrastructure
• Framework migration fix (e.g., Node 22) → also relevant in /audit status analysis + /project-audit dependencies
• /security-scan findings (MCP, hooks) → relevant for /audit Phase 02 (security) and /project-audit Phase 08 (security)
• /audit Phase 09 content/design findings → feed into /polish scan + /design-system for resolution

Post-Audit Recommendations

After all audits complete, the orchestrator recommends follow-up actions:

Status Display

Audit Orchestrator: {{PROJECT_NAME}}
Mode: {Team|Manual|Runner}
Order: {Reason} → {Audit 1} → {Audit 2} → {Audit 3}

Pre-Audit:
/security-scan:       ██████████ Grade: B (1 HIGH, 2 MEDIUM)
/freshness-check:     ██████████ done (2 opportunities)

Audits:
/{{FRAMEWORK}}-audit: ████████░░ 5/13 sections (8 findings, 1 skipped)
/audit:               ████████░░ 5/8 phases (12 findings)
/project-audit:       ████░░░░░░ 4/10 phases (5 findings)

Total: 25 findings (2 CRITICAL, 5 HIGH, 12 MEDIUM, 6 LOW)
Fixed: 3 | Open: 22 | Skipped: 1

Related Projects:
  {{RELATED_NAME}}: {Status}

Recommendation: Fix 2 CRITICAL findings first (MIG-03 from framework audit, SEC-01 from /audit)
Session Estimate: {N} remaining (of {M} planned)

Addition for Team Mode (executionMode: "team"):

Team: audit-{{PROJECT_NAME}}
  [audit-worker-1] /audit            → running (Phase 5/8)
  [audit-worker-2] /{{FRAMEWORK}}-audit → done (8 findings)
  [audit-worker-3] /project-audit    → waiting (blocked by /audit)
Runtime: 12 min

Combined Report

→ Report format, categories, regulatory standards + generation: See combined-report.md

Rules

• Session directory is canonical — .audit-session/<date>-<slug>/ holds INDEX.md, STATUS.md, and four phase folders. STATUS.md must stay current (update at phase transitions and every ~5 fix commits).
• Any instance can resume — because state is plain Markdown in the session directory, a crashed session can be continued by a new instance, a different model, or a human. The resume protocol is: read INDEX.md → read STATUS.md → claim the session → continue from the "next action" line.
• Four phases always run — Pre-Scan, Analysis, Optimization, Report. Empty phases are documented, not skipped.
• Project type drives the track — Phase 1 writes project-profile.md; Phase 2 picks tracks from universal-workflow.md. Web projects additionally activate the web-orchestration specialization below.
• Orchestrator plans + coordinates — the actual audits run via their own skills (manually or as teammates)
• Team mode optional — only if CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set AND user chooses
• Teammates use /auto — autonomous run, no manual start/continue
• Legacy state coexists — each sub-skill keeps its own state file, and the web-specific .audit-orchestrator-state.json (v3) is still written when the web orchestration path is active; universal Markdown state is the primary surface for resume.
• Orchestrator state tracks overview + phase mapping + sequencing + team status
• Pre-audit by orchestrator — freshness check + GitHub/VPS checks done by orchestrator itself, not by teammate
• Beta/RC always first — migration audit before quality audit for unstable versions
• Static filter active — automatically skip SSR-specific checks for output: "static"
• Crash not fatal + self-healing — teammate crash does not end the overall audit, state survives, manual fallback possible. In team mode: detect stalled workers (no state update > 5 min), restart once automatically before falling back to manual. Guard concurrent state file writes to prevent corruption (inspired by GSD v2 parallel worker patterns).
• Combined report via /audit-orchestrator report or naturally as the Phase 4 output (04-report/REPORT.md).
• Regulatory standards — explicitly check applicable privacy, accessibility, and compliance regulations — separate section in combined report

Anti-Stall Rules (Subagent-Safe Execution)

When this skill runs inside a subagent (spawned via Agent), the parent stream watchdog kills workers that produce no output for ~600s. Long silent scans (deep Grep, multi-file Read loops, recursive walks) can exceed that window even on small repos.

Every audit-orchestrator run — especially inside a subagent — MUST:

1. Heartbeat every ≤120s — emit a single-line progress marker ([progress] phase=01 step=3/12 elapsed=85s) between tool batches. A completed tool call counts as output; a 600s silent Grep does not.
2. Chunk Phase 1 fingerprinting — detect project type via at most 5 Glob + 3 Read calls before writing project-profile.md. Deep scans happen in Phase 2, never Phase 1.
3. Cap Phase 2 per-track work units — split each track (security, deps, docs, drift, CI) into independent chunks of ≤10 tool calls. Write incremental findings to 02-analysis/findings/ after each chunk so crash-resume loses at most one chunk.
4. Never block on a single tool call >180s — use explicit Bash timeout 120s <cmd> for scans that could hang (find, grep-r on huge trees, gh api without pagination).
5. Prefer parallel tool calls — independent Greps/Reads go in one tool-call batch, not sequential. Each batch emits output to the parent; sequential chains starve the watchdog.
6. Fail-soft on stalled subtasks — if a single track runs >5min with no new findings written, mark it skipped-stall in STATUS.md and continue. Do not re-retry; log for user review.

Subagent-invocation contract: when the orchestrator is spawned as an Agent, the caller must pass a scoped chunk, not "run the whole audit". Example:

GOOD: Agent(prompt="Run audit-orchestrator Phase 1 prescan only for <repo>. Return project-profile.md contents. Cap: 15 tool calls, 4min.")
BAD:  Agent(prompt="Run full audit on <repo>.")

The bad pattern is what stalls — 4 phases × N tracks × M files > watchdog window. Callers chaining this skill across phases should spawn one agent per phase and synthesize between.

Reference Files

• universal-workflow.md — the four-phase workflow, project-type tracks, severity scale, exit criteria.
• session-schema.md — session directory layout, INDEX.md / STATUS.md / findings / TODO / changes templates, ID conventions.
• state-schema.md — legacy .audit-orchestrator-state.json v3 schema (web-orchestration path).