audit-workspace

name	audit-workspace
description	Audit CC project workspace against CAB v1.1.0 standards. Read-only 8-dimension scored assessment with YAML + markdown artifacts; Dimension 8 covers DP8 wrap-and-extend compliance. Triggers: audit workspace, check standards, cab audit, workspace health check, assess CC setup, dp8 compliance check.
argument-hint	Target path (default: cwd) and flags (e.g., '--changed-only')
agent	true
allowed-tools	Read, Grep, Glob, Bash

Workspace Audit

Audit a CC-integrated project workspace against CAB v1.1.0 architectural standards. This is a read-only assessment — no files are modified. The output is a scored gap report with remediation guidance, persisted as artifacts for iterative tracking.

When to Use

• User has an existing CC-integrated project and wants a quality check
• Before starting a major project phase (baseline audit)
• After a series of changes to verify standards alignment
• Periodic health checks on CC configuration quality
• When onboarding to an unfamiliar CC project

Instructions

Execute these phases sequentially. Never skip a phase or load all standard packs at once (token efficiency — process one dimension at a time).

Phase 0: Context Discovery

Understand the project before applying standards. This prevents false positives from applying team-level expectations to a solo project.

1. Detect project type (determines component location convention):

   ls CLAUDE.md .claude/ .claude-plugin/ 2>/dev/null
   

   • Plugin project: has .claude-plugin/plugin.json → components at ROOT (agents/, skills/, commands/)
   • Standalone project: has .claude/ or CLAUDE.md but NO .claude-plugin/ → components under .claude/
   • Not CC-integrated: neither present → ABORT — suggest /integrate-existing instead

   Set project_type = plugin | standalone — carry this through ALL subsequent phases.

   Architecture rule: Plugin components live at project root per CC convention. .claude/ retains project settings, rules, local overrides, and agent-memory regardless of project type. Only distributable components differ in location.

2. Read project context:

   • CLAUDE.md first paragraph for domain/purpose
   • plugin.json for metadata, component paths, and distribution info (if plugin)
   • Count components in the correct location per project_type:
     • Plugin: agents/, skills/, commands/, hooks/, knowledge/
     • Standalone: .claude/agents/, .claude/skills/, .claude/commands/, knowledge/

3. Determine complexity tier (governs which criteria apply):

   Tier	Signals
   Minimal	≤2 total components, no knowledge dir, solo project
   Standard	3-10 components, some knowledge, small team
   Advanced	10+ components, knowledge base, orchestration, team

4. Check for prior audit:

   ls notes/cab-audit-*.yaml 2>/dev/null | tail -1
   

   If found, load for delta comparison in Phase 3.

Phase 1: Structural Pre-Check

Run basic structural validation before attempting quality assessment. Auditing quality of files in the wrong location produces confusing results.

Critical checks (any failure blocks Phase 2):

• CLAUDE.md exists
• Components are in the correct location for project_type:
  • Plugin: agents/, skills/, commands/ at project root. Components found under .claude/ instead = ERROR (wrong convention for plugins — must be at root for CC plugin discovery)
  • Standalone: .claude/agents/, .claude/skills/, .claude/commands/. Root-level components without .claude-plugin/plugin.json = ERROR
• If plugin: .claude-plugin/plugin.json exists and is valid JSON
• If plugin: plugin.json does NOT have stale custom paths pointing to .claude/ (e.g., "agents": ".claude/agents/") — this is a non-standard workaround that masks the root-level convention. Severity: WARN

Warning checks (noted but don't block):

• .gitignore exists
• README.md exists (plugins only)
• No components inside .claude-plugin/ directory (only plugin.json belongs there)
• If plugin: root settings.json exists with agent key (plugin-distributed default agent)

If critical checks fail: emit structural report and STOP. Recommend /validate --full to fix structural issues before re-running audit.

Phase 2: Standards Audit (8 Dimensions)

For each dimension, follow this protocol:

1. Read the standard pack from references/standards/<dimension>-standards.md
2. Read the target files from the project for this dimension
3. Evaluate each criterion against the scoring rubric
4. Score the dimension: 0 (ABSENT) / 1 (MINIMAL) / 2 (ADEQUATE) / 3 (EXEMPLARY)
5. Classify each finding: MISSING / STALE / ENHANCEMENT / CURRENT
6. Record evidence (specific files, line references, patterns found/missing)
7. Link remediation to specific KB docs

Process dimensions sequentially to manage token budget:

#	Dimension	Standard Pack	Target Files (plugin)	Target Files (standalone)
1	CLAUDE.md Quality	claudemd-standards.md	CLAUDE.md, CLAUDE.local.md	same
2	Agent Frontmatter	agent-standards.md	agents/*.md + shadow scan vs ~/.claude/agents/*.md	.claude/agents/*.md
3	Skill Frontmatter	skill-standards.md	skills/*/SKILL.md	.claude/skills/*/SKILL.md
4	Settings Configuration	settings-standards.md	.claude/settings.json + root settings.json	.claude/settings.json
5	Rules Coverage	rules-standards.md	.claude/rules/**/*.md	same
6	Knowledge Structure	knowledge-standards.md	knowledge/**	same
7	Hooks Configuration	hooks-standards.md	hooks/hooks.json	hooks in .claude/settings.json
8	DP8 Wrap-and-Extend Compliance	inline (see scan protocol below)	all skills/, agents/, commands/ cross-checked vs installed plugins	same

For dimensions with zero applicable components at the project's complexity tier, score as N/A rather than ABSENT. A minimal project with no agents is not penalized for lacking agent frontmatter.

Dimension 8 — DP8 Wrap-and-Extend Compliance Scan:

Two-layer scan:

1. Layer 1 (component-type fit): each project component is classified against the canonical decision framework — does the chosen component type match the asset's nature?
2. Layer 2 (overlap detection): each project component is cross-checked against installed plugins for substantial domain overlap.

Operational enforcement of DP8 — see knowledge/overview/design-principles.md §Principle 8 + notes/lessons-learned.md LL-30 for the recurrence pattern this scan prevents.

Layer 1 — Component-Type Fit (rubric: component-decision-framework.md)

Canonical reference: knowledge/components/component-decision-framework.md — Decision Tree + Component Type Matrix + per-component scope tests + anti-patterns. This audit consumes that card as its scoring rubric.

For each project skill / agent / command / hook / MCP server / KB card, traverse the decision tree from the framework:

1. Three-question screening (Q1 real demand / Q2 native CC alternative / Q3 hard-coding risk) — does the asset pass the screening test as currently authored?
2. Asset-kind branch — is the chosen component type the canonical type per the framework's tree? (e.g., a deterministic multi-step orchestration authored as an agent rather than skill = TYPE-MISMATCH.)
3. Per-component scope test — does the asset honor the component's stated scope test (per framework §Component Type Matrix)?
4. Anti-pattern check — does the asset violate any framework-documented anti-pattern (e.g., agent-as-skill, skill-as-rules, hook-as-skill)?

Layer 1 verdict per asset:

• TYPE-MATCH — asset's component type matches what the decision tree would prescribe; scope test passes; no anti-pattern detected. Full credit.
• TYPE-MISMATCH — asset's component type does NOT match canonical decision-tree prescription. ENHANCEMENT finding (refactor candidate). Cite the framework branch the asset should belong to.
• SCOPE-DRIFT — type-match but per-component scope test fails (e.g., skill bodies that read more like advisory rules). WARN finding.
• ANTI-PATTERN — asset matches a framework-documented anti-pattern. ERROR finding (refactor required, not optional).

Layer 1.5 — Intra-Project Orchestrator-Without-Skill-Wrapper Detection

What it catches: backend orchestrator functions (in src/<package>/**/*.py, lib/, etc.) that meet the orchestration.md skill-first criteria (multi-step orchestration OR deterministic logic + tailored knowledge OR verification contract) but have NO skill wrapping them. Layer 1 catches type-mismatches within authored CC components; Layer 1.5 catches the case where a skill SHOULD exist but doesn't.

Provenance: this layer addresses the GTA Iteration 1 finding (cab_philosophy_iteration_1.csv row 19) — Dimension 8 was scoped narrowly to plugin-overlap and missed intra-project orchestrator-without-skill-wrapper. GTA's cab_audit_dp8_scan.py demonstrates the scan logic.

Heuristic (per GTA playbook §Phase 1 Dim 8 deep-dive):

For each public-API entry point in the target project's source tree (language-agnostic; adapts to project structure):

1. Identify orchestrator-like top-level function defs by name prefix heuristics (Python: run_, fetch_, analyze_, compute_, process_, build_; JS/TS: similar verb-prefix patterns) PLUS export status (in __init__.py / index.ts / package public-API).
2. Count consumers by greping app/, pages/, tests/, cmd/, etc. for direct imports of the entry point.
3. Cross-reference against skill roster (.claude/skills/*/SKILL.md or plugin-root skills/*/SKILL.md): does any skill description name the entry point or its domain?
4. Classify each entry point:
   • WRAPPED — skill description names the entry point or domain. Full credit.
   • SKILL-CANDIDATE — no skill wraps it; entry point meets skill-first criteria (consumer count ≥ 2 OR consumer is a UI / Streamlit page; plus multi-step OR domain knowledge OR verification contract). ENHANCEMENT finding (refactor candidate). Cite consumer count + qualifying criteria in finding.
   • DOES-NOT-NEED-WRAP — one-shot helper, no orchestration, no domain knowledge worth packaging. Full credit.

Scoring impact (Layer 1.5 row added to dimension scoring table):

Layer 1.5 verdict	Dimension 8 score impact
WRAPPED	Full credit
DOES-NOT-NEED-WRAP	Full credit
SKILL-CANDIDATE	Cap at DEVELOPING (2) per detected candidate; ENHANCEMENT finding

Implementation: bundled script scripts/dp8-intra-project-scan.py (cross-platform Python; pathlib + stdlib only per .claude/rules/cross-platform.md). Auto-detects source roots (src/, lib/, pkg/, cmd/, internal/) + counts consumers across app/, pages/, tests/, cmd/, scripts/ plus cross-module within source roots + cross-references against skill roster description frontmatter (NOT body — mitigates the false-positive class where "When NOT to use" sections trigger spurious WRAPPED matches).

CLI usage:

# Scan current project
python skills/audit-workspace/scripts/dp8-intra-project-scan.py

# Scan a different project root
python skills/audit-workspace/scripts/dp8-intra-project-scan.py /path/to/project

Output: notes/audit-evidence/dp8-scan-<YYYY-MM-DD>.csv (machine-readable)

• console summary. Exit code 1 if SKILL-CANDIDATEs found, 0 otherwise (CI-gating ready). Iterations diff date-stamped CSVs to detect new SKILL-CANDIDATEs introduced by recent work.

Heuristic limitations (documented in script docstring):

• Python-only currently; JS/TS / Go support deferred until first non-Python audit demands it
• Name-prefix heuristic (run_, fetch_, analyze_, compute_, process_, build_) is a starting point; refinement iterations track in notes/audit-evidence/dp8-scan-<date>-review.md if authored alongside CSV
• Heuristic refinements promote to script logic when consensus stabilizes

Provenance: GTA Iteration 1 audit (cab_philosophy_iteration_1.csv row 19) surfaced the need; GTA's cab_audit_dp8_scan.py was the project-side reference implementation. CAB-canonical version diverges where CAB-strategic concerns (cross-platform discipline, plugin distribution) prevail over GTA-local choices.

Layer 2 — Overlap Detection (DP8 reactive enforcement)

For each project skill/agent/command, cross-check installed plugins:

• CLEAR — no installed plugin covers the domain; build was justified
• WRAPS-EXISTING — project component documents a wrap relationship to a specific plugin component (e.g., "delegates to plugin-dev/agent-creator")
• DUPLICATES — substantial overlap with installed plugin, no wrap documented → ENHANCEMENT finding (refactor candidate)
• POTENTIAL OVERLAP — partial overlap, ambiguous; flag for human review

Scan protocol:

Cross-platform note: the bash protocol below uses jq + GNU find, which work on macOS / Linux / WSL / git-bash but fail on vanilla Windows. See .claude/rules/cross-platform.md for portability discipline. On vanilla Windows, use the Python fallback below the bash block.

# POSIX-assuming bash protocol (macOS / Linux / WSL / git-bash):
# 1. Enumerate enabled plugins
jq -r '.enabledPlugins | to_entries | map(select(.value == true)) | .[].key' \
  ~/.claude/settings.json

# 2. For each enabled plugin, list its skills/agents/commands
for plugin in $(jq -r '.enabledPlugins | to_entries | map(select(.value == true)) | .[].key' ~/.claude/settings.json); do
  cache_root=$(find ~/.claude/plugins/cache -maxdepth 4 -type d -name "${plugin%@*}" 2>/dev/null | head -1)
  if [ -n "$cache_root" ]; then
    find "$cache_root" -maxdepth 3 -name 'SKILL.md' -o -name '*.md' -path '*/agents/*' -o -name '*.md' -path '*/commands/*'
  fi
done

# 3. For each project component, name-match + tag-match against plugin components
# 4. Generate overlap report

# Python fallback (cross-platform; vanilla Windows + macOS + Linux):
# python -c "<paste below>" OR save as scripts/scan-plugins.py and invoke
import json, os, pathlib, sys
settings = pathlib.Path.home() / ".claude" / "settings.json"
with settings.open() as f:
    data = json.load(f)
enabled = [k for k, v in data.get("enabledPlugins", {}).items() if v]
print("Enabled plugins:", enabled)

cache_root = pathlib.Path.home() / ".claude" / "plugins" / "cache"
for plugin in enabled:
    plugin_name = plugin.split("@")[0]
    matches = list(cache_root.rglob(f"*/{plugin_name}/**/SKILL.md"))
    matches += list(cache_root.rglob(f"*/{plugin_name}/agents/*.md"))
    matches += list(cache_root.rglob(f"*/{plugin_name}/commands/*.md"))
    for m in matches[:50]:  # cap to avoid runaway
        print(m)

Scoring impact:

Layer 1 verdict	Layer 2 verdict	Dimension 8 score impact
TYPE-MATCH	CLEAR	Full credit
TYPE-MATCH	WRAPS-EXISTING	Full credit (wrap documented)
TYPE-MATCH	DUPLICATES	Cap at MINIMAL (1) — ENHANCEMENT finding
TYPE-MATCH	POTENTIAL OVERLAP	WARN (per-asset)
TYPE-MISMATCH	any	Cap at DEVELOPING (2) — ENHANCEMENT (cite canonical branch); compounds with Layer 2 if also DUPLICATES
SCOPE-DRIFT	any	WARN per-asset
ANTI-PATTERN	any	ERROR (blocks EXEMPLARY); refactor required

For projects with pre-existing TYPE-MISMATCH or DUPLICATES components (refactor debt), Layer 1 + Layer 2 findings surface them with concrete citations to the framework branch + plugin overlap (respectively), so the wrap-and-extend refactor can convert TYPE-MISMATCH → TYPE-MATCH and DUPLICATES → WRAPS-EXISTING.

Layer 1.5 contribution: SKILL-CANDIDATE findings cap dimension at DEVELOPING per detected candidate (compounds with Layer 1 / Layer 2). The three layers compose: Layer 1 catches type-mismatches in authored components; Layer 1.5 catches missing components (orchestrators without skill wrappers); Layer 2 catches duplications against installed plugins. A clean Dimension 8 requires all three layers to verdict TYPE-MATCH / WRAPPED-or-DOES-NOT-NEED / CLEAR-or-WRAPS-EXISTING.

Agent Frontmatter dimension — mandatory shadow scan (LL-27 enforcement via UXL-013): for plugin projects, after the per-file frontmatter evaluation, execute the shadow scan documented in knowledge/operational-patterns/multi-agent/agent-resolution.md §Detection. For each plugin agent, check whether a same-named file exists at ~/.claude/agents/<name>.md — byte-identical match = WARN (future-drift risk); content-diverged match without documented intentional-override block = ERROR. Unresolved shadows gate EXEMPLARY score structurally (see agent-standards.md Scoring Guide). Pattern mirrors /cab:sync-check --shadow-only (UXL-011 commit 2185da9) — same detection logic, different trigger surface.

Read references/classification-schema.md before starting Phase 2 for the full scoring rubric, classification definitions, and contextual tier adjustments.

Phase 3: Synthesis + Artifact Generation

1. Aggregate scores: Sum dimension scores, compute percentage (0-21 scale)
2. Classify overall:
   • NEEDS WORK: 0-33%
   • DEVELOPING: 34-66%
   • ALIGNED: 67-89%
   • EXEMPLARY: 90-100%
3. Rank findings by severity (ERROR > WARN > INFO), then by dimension score (lowest first)
4. Compute delta if prior audit exists (per-dimension score change)
5. Generate YAML artifact: notes/cab-audit-YYYY-MM-DD.yaml
   • See references/audit-methodology.md for schema
6. Generate markdown summary: notes/cab-audit-YYYY-MM-DD.md
   • See references/audit-methodology.md for template
7. Present console summary: overall score, top 3 findings, artifact paths

Output Location

All artifacts go to the target project's notes/ directory (create if needed). This keeps audit history co-located with the project.

Flags

Flag	Behavior
(none)	Full 7-dimension audit
--changed-only	Re-audit only dimensions affected by files changed since last audit (uses git diff against last audit date)

--changed-only Behavior

# Get files changed since last audit
last_audit_date=$(grep "audit_date:" notes/cab-audit-latest.yaml | cut -d'"' -f2)
git diff --name-only --since="$last_audit_date" HEAD

Map changed files to dimensions (resolve paths per project_type):

Changed File Pattern (plugin)	Changed File Pattern (standalone)	Re-audit Dimension
CLAUDE.md	CLAUDE.md	CLAUDE.md Quality
agents/*	.claude/agents/*	Agent Frontmatter
skills/*	.claude/skills/*	Skill Frontmatter
.claude/settings* or settings.json	.claude/settings*	Settings Configuration
.claude/rules/*	.claude/rules/*	Rules Coverage
knowledge/**	knowledge/**	Knowledge Structure
hooks/hooks.json or hook scripts	hooks config or scripts	Hooks Configuration

Dimensions with no changed files retain their prior score.

Override Mechanism

Projects can suppress specific findings by adding a .cab-audit-ignore file:

# Findings to suppress (by criterion ID)
suppress:
  - agents.verification_section  # Intentionally omitted for lightweight agents
  - settings.sandbox             # Windows — sandbox not available

Suppressed findings appear in the report as "SUPPRESSED" with the reason, but don't affect the score.

Integration

• Upstream: /validate --cab-audit routes here (validate command dispatches)
• Downstream: Output YAML feeds into /execute-task for remediation planning
• Orchestrator: Recognizes "audit workspace" requests and invokes this skill
• Delta tracking: Each audit builds on prior runs for longitudinal health monitoring

See Also

• references/audit-methodology.md — Formalized PA-01 workflow, artifact schemas
• references/classification-schema.md — Scoring rubric, classification definitions
• references/standards/ — 7 modular standard packs (one per audit dimension)
• knowledge/components/ — Authoritative KB sources for each dimension