Project Audit

Skill: project-audit

Systematic project audit for any repository — with a three-layer depth model. Automatically detects the stack, loads relevant supplements, and performs structured checks — for management repos, CLI tools, libraries, backend services, monorepos, Python projects, and shell collections.

Distinction from /audit: No SEO, no accessibility, no privacy/GDPR, no Lighthouse. Instead, more thorough checking of Git, CI/CD, code quality, deployment, and maintenance.

Check Layers

Each phase has two check levels:

Rule: Source layer is mandatory. Runtime layer supplements with tool-based checks. Both layers are tracked in state per phase.

Runtime layer per phase:

Check Priorities + Completeness Tracking

See _shared/audit-patterns.md (MUST/SHOULD/COULD markers, completeness counting). Phase with <100% MUST-checks can NOT be marked as done.

Architecture: Three-Layer Model

Layer 1: Base Phase (phases/*.md)                    ~70-100 lines, universal
Layer 2: Stack Supplement (stacks/*.md §-sections)   ~10-15 lines per phase, stack-specific
Layer 3: Project Override (project-audit-context.md)  ~20-40 lines, project-specific

Per phase, only the relevant supplements are loaded. Result: ~100-150 lines of check instructions per phase — comparable to a dedicated skill.

5 Modes

Mode: start

Step 1 — Detect Project Type

Step 2 — Stack Detection

Scan files and detect stack:

Version detection: For each detected stack, extract version:

• Node: engines.node or .nvmrc / .node-version
• Python: python_requires or .python-version
• Docker: Base image tag in Dockerfile

Step 3 — Load Context

1. Project CLAUDE.md read (architecture, conventions)
2. project-audit-context.md load (if in project root) — project-specific context
3. README.md read (purpose, setup instructions)
4. Existing docs scan: TODO.md, STATUS.md, CHANGELOG.md
5. package.json / pyproject.toml analyze (if present)
6. Existing state file (.project-audit-state.json) check > auto-migrate if v1

Step 4 — User Query

Show detection result:

Project Detection:
+-------------+------------------+---------+
| Category    | Detected         | Version |
+-------------+------------------+---------+
| Project Type| management-repo  | —       |
| Stack       | Shell/Bash       | —       |
| Docker      | Yes              | —       |
| Monorepo    | No               | —       |
+-------------+------------------+---------+

Project context: project-audit-context.md found
Existing docs: TODO.md, STATUS.md

Ask user (AskUserQuestion):

• Audit scope: Complete (all 10 phases) vs. focused (specific phases)
• Phase order: Sequential (01>10, default) vs. Smart Order (Security>Dependencies>Code>Rest, recommended)

[CHECKPOINT: decision] — User selects audit scope and phase order.

Step 5 — Create state, start first 2 phases

Mode: continue

1. Read .project-audit-state.json
2. Identify next pending phase(s)
3. Generate smart recommendation (> logic in _shared/audit-patterns.md)
4. Show recommendation as first option in AskUserQuestion, user chooses
5. Write state immediately after each phase/fix

Fixing Findings

• Always fix highest severity first: CRITICAL > HIGH > MEDIUM > LOW
• Per fix: Show problem > Load fix template (from fix-templates.md) > User confirmation > Implement > Test
• Update fix status in state ("status": "fixed", "fixedIn": "Session N")
• No auto-fix — every fix requires user confirmation (except auto mode)

Mode: status

Read state file and display:

Project Audit: {{PROJECT_NAME}} (management-repo)
Stack: Shell/Bash, Docker

Phases:
  [done] 01 Structure & Architecture (Session 1, 2 Findings, MUST 100%)
  [done] 02 Dependencies & Ecosystem (Session 1, 1 Finding, MUST 100%)
  [wip]  03 Code Quality (in progress)
  [wait] 04 Git & Versioning
  [wait] 05 CI/CD & Automation
  [wait] 06 Documentation & Onboarding
  [wait] 07 Testing & QA
  [wait] 08 Security & Secrets
  [wait] 09 Deployment & Operations
  [wait] 10 Maintenance & Hygiene

Findings: 3 total
  CRITICAL: 0
  HIGH: 1 (open: 1)
  MEDIUM: 2 (open: 2)
  LOW: 0

Completeness: 2/10 phases completed
  Layer: Source done | Runtime done (2/2 phases)

Mode: report

Generate structured Markdown report based on templates/report.md.

1. Read state file
2. Group all findings by phase
3. Report with Executive Summary, Findings per Phase, Recommendations
4. Include trend analysis (if history available):

   Trend (recent audits):
     CRITICAL: 3 > 1 > 0  (resolved)
     HIGH:     5 > 3 > 2  (declining)
     Total:   12 > 8 > 5
   Assessment: Project is steadily improving.
   

5. Save report as PROJECT-AUDIT-REPORT-{YYYY-MM-DD}.md in project root
6. If previous reports exist: Diff section (new/resolved since last report)

Mode: auto

Fully autonomous project audit without prompts.

Flow

1. Check orchestrator context: If .audit-orchestrator-state.json exists:
   • Read phaseMapping.project-audit.delegated > skip delegated phases
   • Read sequencingReason > understand context
   • Example: If structure delegated to /audit > skip Phase 01
2. Auto-detection as in start
3. All 10 phases run through (no 2-phase limit, skip delegated phases)
4. Document findings with fix templates from fix-templates.md
5. Context management: When context is running low:
   • Write state immediately
   • Create task in .tasks.json with handoff note
   • Recommend: "New session with /project-audit continue"
6. At the end: automatically generate report

Context Protection in Auto Mode

• Findings are collected but not fixed immediately (documented only)
• Write state after EVERY phase immediately
• At context limit: clean abort with complete state
• Fixes in follow-up sessions with /project-audit continue

10 Phases

Details in the phase files under phases/.

Phase Execution

For each phase:

1. Load base: Read phases/{NN}-{name}.md — universal check items

2. Load supplements: For each detected stack, load the matching file, ONLY the section relevant to the current phase

   Phase	Supplement Section
   01-structure	§Structure
   02-dependencies	§Dependencies
   03-code-quality	§Code
   04-git	§Git
   05-cicd	§CICD
   06-documentation	§Documentation
   07-testing	§Testing
   08-security	§Security
   09-deployment	§Deployment
   10-maintenance	§Maintenance

3. Project override: If project-audit-context.md exists > include relevant section

4. Existing findings: Check previous audit docs, do not create duplicates

5. Source layer: Systematically execute all code/config-based checks

6. Runtime layer: Execute tool-based checks (when tools are available)

   • Unavailable tools: document, no error

7. Document findings: Each finding with ID, severity, description, location

8. Count completeness: MUST/SHOULD/COULD checks (executed vs. skipped)

   • Skipped MUST-checks with reason in checksSkipped[]
   • Phase with <100% MUST = NOT markable as done

9. Update state: Phase status + completeness + layer status

[CHECKPOINT: verify] — After each phase: show findings + completeness to user, get confirmation.

Supplement Loading Logic

Per phase, the skill loads only relevant stack supplements. Each stack file is structured by sections.

Example Phase 08-security:

> Always: phases/08-security.md (base)
> If node=true: + stacks/node.md §Security
> If docker=true: + stacks/docker.md §Security
> If python=true: + stacks/python.md §Security
> If project-audit-context.md exists: + relevant section

Supplement files:

If a stack is detected but no supplement exists > use base phase only, no error.

Finding-IDs

Severity Definitions

Prioritization: CRITICAL > HIGH > MEDIUM > LOW. Security before functional before cosmetic.

State Schema v2.1 (.project-audit-state.json)

Complete state schema (JSON example) + migrations v1>v2 and v2>v2.1: See state-schema.md

Phase Order

Sequential (Default)

01 > 02 > 03 > 04 > 05 > 06 > 07 > 08 > 09 > 10

Smart Order (Recommended)

Prioritized by impact: 08-security > 02-dependencies > 03-code-quality > 05-cicd > 09-deployment > 04-git > 07-testing > 01-structure > 06-documentation > 10-maintenance

Logic: Security and dependencies are most urgent (CVEs, secrets). Code quality and CI/CD have high impact. Structure/docs/maintenance are important but less time-critical.

User chooses at start. Store in state as "phaseOrder": "sequential" or "smart".

Fix Templates

For common findings there are ready-made fix templates in fix-templates.md. Per finding type: code snippet, config change, verify step.

Verification-Depth + Fix Protocol

See _shared/audit-patterns.md (4-Level Verification, Stub-Detection, 5-Step Fix-Protocol). Level 4 (Functional) is mandatory when runtime layer is available. READ + VERIFY never skip.

Context Protection (CRITICAL)

Base rules: See _shared/audit-patterns.md (Max 2 phases, state immediately, no auto-fix).

Project audit specific:

• Layer tracking: Document source layer and runtime layer status per phase

Smart Next Steps

After completing the project audit, recommend suitable follow-up skills to user:

Output in report: Replace {NEXT_STEPS} placeholder with concrete recommendation list.

Files in This Skill

project-audit/
├── SKILL.md                       <- This file
├── state-schema.md                # State Schema v2.1 + Migrations
├── fix-templates.md               # Quick-Fix templates for common findings
├── phases/
│   ├── 01-structure.md            # Folder structure, architecture, coupling
│   ├── 02-dependencies.md         # Packages, ecosystem, licenses
│   ├── 03-code-quality.md         # Patterns, complexity, dead code
│   ├── 04-git.md                  # .gitignore, commits, branches, tags
│   ├── 05-cicd.md                 # Workflows, actions security, pipelines
│   ├── 06-documentation.md        # README, ADRs, API docs, onboarding
│   ├── 07-testing.md              # Test pyramid, coverage, E2E
│   ├── 08-security.md             # Secrets, supply chain, SAST
│   ├── 09-deployment.md           # Docker, server, monitoring, rollback
│   └── 10-maintenance.md          # Tech debt, cleanup, deprecations
├── stacks/
│   ├── node.md                    # Node.js-specific checks
│   ├── python.md                  # Python-specific checks
│   ├── shell.md                   # Shell/Bash-specific checks
│   ├── docker.md                  # Docker-specific checks
│   ├── monorepo.md                # Monorepo-specific checks
│   ├── claude-code.md             # Claude Code config/skills/agents/hooks checks
│   ├── go.md                      # Go-specific checks
│   ├── terraform.md               # Terraform/IaC-specific checks
│   └── github.md                  # GitHub repo/org security checks
└── templates/
    └── report.md                  # Markdown report template