ai-fob 1.1.3 → 1.2.1

package/assets/agents/meta-auditor-agent.md

@@ -0,0 +1,48 @@
+---
+name: meta-auditor-agent
+description: >
+  CC Documentation Auditor. Receives current CC documentation research and
+  asset inventory scan, cross-references each asset against current CC
+  conventions, and produces categorized findings (BREAKING/OUTDATED/MISSING)
+  with fix recommendations. Use when auditing CC assets against current
+  documentation.
+tools: Read, Grep, Glob
+model: opus
+color: yellow
+permissionMode: plan
+skills:
+  - claude-code-primitives
+  - audit-cc-assets
+---
+
+# Meta Auditor Agent
+
+## Purpose
+
+You are a CC documentation auditor. You analyze CC assets (skills, agents, commands, hooks, reference guides) against current Claude Code documentation to detect documentation drift. Your domain knowledge comes from two preloaded skills: `claude-code-primitives` provides the baseline for what correct CC assets look like, and `audit-cc-assets` provides the audit methodology, categorization framework, and report format.
+
+## Core Principle: Compare, Don't Assume
+
+Always verify against the documentation data provided in your delegation prompt. Never rely on pre-trained knowledge about what CC documentation says -- it changes frequently. If a value is not addressed by the provided documentation data, do not flag it. You report only what the evidence supports, nothing more.
+
+## Workflow
+
+When invoked, follow these steps:
+
+1. **Load the audit checklist.** Read `reference/audit-checklist.md` from the `audit-cc-assets` skill. This contains the exhaustive valid-value lists for every auditable dimension.
+2. **Load the report template.** Read `templates/audit-report.md` from the `audit-cc-assets` skill. This defines the output format.
+3. **Parse the delegation prompt.** Extract the documentation research data (current CC state) and the asset scan data (current asset state) provided by the calling command.
+4. **Audit each asset.** For every asset file in the scan data, read the file directly using the Read tool. Compare every auditable dimension (frontmatter fields, tool names, permission modes, model values, URLs, skill references, hook events) against the valid-value lists from the checklist and the current documentation data.
+5. **Classify findings.** For each discrepancy, classify it as BREAKING, OUTDATED, or MISSING using the categorization framework from the `audit-cc-assets` skill. Determine severity, auto-fixability, breaking change status, and the CC version that introduced the change (if known).
+6. **Include exact references.** Every finding must include the exact file path and line number where the issue occurs.
+7. **Produce the report.** Structure the output using the audit report template. Include the summary, categorized findings sections, and fix plan table.
+
+## Report
+
+Structure your output using the audit report template from the `audit-cc-assets` skill (`templates/audit-report.md`). The report must include:
+
+- **Summary**: File counts, finding counts by category, auto-fixable count
+- **BREAKING Findings**: Each with file, line, current value, recommended fix, severity, CC version, description
+- **OUTDATED Findings**: Each with file, line, current value, recommended fix, severity, CC version, description
+- **MISSING Findings**: Each with file, line, what is missing, severity, CC version, description, recommendation
+- **Fix Plan**: Table of BREAKING and OUTDATED fixes grouped by file

package/assets/commands/audit-cc-assets.md

@@ -0,0 +1,585 @@
+---
+description: Audit CC assets against current Claude Code documentation -- identifies breaking changes, outdated patterns, and missing features
+model: opus
+disable-model-invocation: true
+allowed-tools: Agent, Skill, Read, Write, Edit, Glob, Grep, Bash, MultiEdit
+---
+
+# Audit CC Assets
+
+Audit all CC assets (skills, agents, commands, hooks, reference guides) against current Claude Code documentation. Detects breaking changes, identifies outdated patterns, catalogs missing features, and applies fixes with user approval. Supports incremental audits by tracking state between runs.
+
+**Required Skill**: Before starting Step 1, invoke the `audit-cc-assets` skill using the Skill tool. This loads the audit methodology, categorization framework (BREAKING, OUTDATED, MISSING), per-asset-type audit dimensions, finding structure, source URLs, and audit state schema into the command agent's context. Keep this methodology in context throughout all 10 steps.
+
+### Step 1: Check State (Main Agent)
+
+You (the main agent) handle this step directly. The audit-cc-assets skill is already loaded from the Required Skill invocation above.
+
+1. **Determine the current CC version.** Run `claude --version` via the Bash tool. Parse the version string (e.g., "claude v2.1.76"). Store as CURRENT_CC_VERSION.
+   - If the Bash command fails (binary not found), ask the user: "Could not detect the CC version. What version of Claude Code is installed? (e.g., 2.1.76)"
+
+2. **Read the audit state file.** Use the Read tool to read `.claude/audit-state.json`.
+
+   **If the file exists:**
+   - Parse the JSON. Extract `lastAuditedCCVersion`, `lastAuditDate`, and `lastAuditSummary`.
+   - Determine the audit mode:
+     - If the CC version gap is more than 5 minor versions since `lastAuditedCCVersion`, set AUDIT_MODE to `full`.
+     - Otherwise, set AUDIT_MODE to `incremental`.
+   - Present to the user:
+     ```
+     AUDIT STATE
+     Current CC version: v{CURRENT_CC_VERSION}
+     Last audited: v{lastAuditedCCVersion} on {lastAuditDate}
+     Previous findings: {lastAuditSummary.totalFindings} total ({lastAuditSummary.breaking} breaking, {lastAuditSummary.outdated} outdated, {lastAuditSummary.missing} missing)
+     Fixes applied last time: {lastAuditSummary.fixesApplied}
+     Audit mode: {AUDIT_MODE}
+     ```
+
+   **If the file does NOT exist:**
+   - This is the first audit. Set AUDIT_MODE to `full`.
+   - Present to the user:
+     ```
+     AUDIT STATE
+     Current CC version: v{CURRENT_CC_VERSION}
+     No previous audit found. This will be a full audit.
+     The full CC documentation will be fetched and all assets will be scanned.
+     ```
+
+3. **Proceed automatically.** Do NOT wait for user confirmation. Move directly to Step 2.
+
+### Step 2: Research (Parallel agents via Agent tool)
+
+Spawn two agents **in parallel** (both Agent tool calls in the SAME message). Neither depends on the other's output. Make all Agent tool calls in a single response so they execute in parallel.
+
+#### 2a. Docs Researcher
+
+Delegate via the Agent tool (set `subagent_type` to `"docs-researcher-agent"`) with description "CC docs changelog research" and this prompt:
+
+```
+You are researching the current Claude Code documentation and changelog for a CC asset audit.
+
+## Audit Context
+- Current CC version: {CURRENT_CC_VERSION}
+- Last audited CC version: {lastAuditedCCVersion or "none (first audit)"}
+- Audit mode: {AUDIT_MODE}
+
+## Your Research Tasks
+
+### Task 1: Fetch the CC Changelog
+Fetch the CC changelog from https://code.claude.com/docs/en/changelog
+
+If this is an incremental audit (last audited version is known):
+- Extract all changes between v{lastAuditedCCVersion} (exclusive) and v{CURRENT_CC_VERSION} (inclusive)
+- For each version entry: note the version number, date, and each change with its category (new feature, improvement, bug fix, breaking change, deprecation)
+- Focus on audit-relevant changes: new frontmatter fields, tool name changes, hook event changes, permission mode changes, documentation URL changes, model changes, deprecated features
+
+If this is a full audit (first audit):
+- Extract the most recent 10 version entries for context
+- Focus on capturing the current state rather than historical changes
+
+### Task 2: Fetch Current CC Documentation
+Fetch each of these official documentation pages to establish the current ground truth:
+
+1. Skills documentation: https://code.claude.com/docs/en/skills
+2. Sub-agents documentation: https://code.claude.com/docs/en/sub-agents
+3. Tools reference: https://code.claude.com/docs/en/tools-reference
+4. Model configuration: https://code.claude.com/docs/en/model-config
+5. Permissions: https://code.claude.com/docs/en/permissions
+6. Hooks: https://code.claude.com/docs/en/hooks
+7. Agent teams: https://code.claude.com/docs/en/agent-teams
+8. Commands: https://code.claude.com/docs/en/commands
+
+For each page, extract:
+- All valid frontmatter fields per asset type
+- All valid tool names (complete canonical list)
+- All valid permission modes
+- All valid model values (aliases, full IDs, special values)
+- All valid hook events and handler types
+- Any deprecated patterns or migration guidance
+
+### Task 3: Compile Current CC State Summary
+Produce a structured summary of the current CC state:
+- Complete list of valid tool names
+- Complete list of valid hook events
+- Complete list of valid permission modes
+- Complete list of valid model aliases and model ID patterns
+- Complete list of frontmatter fields per asset type (skills, agents, commands)
+- Complete list of string substitution variables
+- Any recently deprecated patterns with replacement guidance
+
+## Output Format
+
+Structure your findings with these sections:
+
+### Changelog Entries (v{lastAuditedCCVersion} to v{CURRENT_CC_VERSION})
+[For each version: version, date, audit-relevant changes with category]
+
+### Current CC State
+[Complete valid-value lists for every auditable dimension]
+
+### Deprecated Patterns
+[Patterns that have been deprecated or renamed, with replacement guidance]
+
+### Documentation Observations
+[Anything unusual or noteworthy found during documentation research]
+
+Do NOT write your findings to a file. Return them directly.
+```
+
+#### 2b. Explorer (Asset Scanner)
+
+Delegate via the Agent tool (set `subagent_type` to `"explorer-agent"`) with description "CC asset inventory scan" and this prompt:
+
+```
+You are scanning ALL CC assets in this project for a comprehensive audit inventory.
+
+## Your Scan Tasks
+
+Scan the entire `.claude/` directory and catalog every CC asset. Be exhaustive -- the auditor needs to know exactly what exists and what each asset contains.
+
+### 1. Agent Files
+For each `.md` file in `.claude/agents/`:
+- File path
+- All frontmatter fields with their exact values (name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, isolation, color, and any other fields present)
+- Body content summary (purpose, workflow steps, key instructions)
+- Line count (total file lines)
+
+### 2. Skill Directories
+For each directory in `.claude/skills/`:
+- Directory path
+- SKILL.md: all frontmatter fields with exact values, line count
+- Reference files: list each file in `reference/` with line count
+- Template files: list each file in `templates/` with line count
+- Script files: list each file in `scripts/` with line count
+- Any non-standard subdirectories
+
+### 3. Command Files
+For each `.md` file in `.claude/commands/`:
+- File path
+- All frontmatter fields with their exact values (description, argument-hint, allowed-tools, model, disable-model-invocation, and any other fields present)
+- Agent references: every `subagent_type` value mentioned in the body
+- Skill references: every skill invoked via the Skill tool in the body
+- Line count (total file lines)
+
+### 4. Reference Guides in claude-code-primitives
+For each file in `.claude/skills/claude-code-primitives/reference/`:
+- File path
+- Tool names mentioned (search for tool name references)
+- Model values mentioned (search for model alias references)
+- Frontmatter field lists (extract any tables documenting frontmatter fields)
+- URL patterns (extract any documentation URLs)
+- Line count
+
+### 5. Settings and Hooks
+Read `.claude/settings.json` if it exists:
+- List all hook configurations with event names, handler types, and handler details
+- Note any other settings configured
+
+### 6. Summary Statistics
+At the end, provide:
+- Total agent files found
+- Total skill directories found
+- Total command files found
+- Total reference/template files found
+- Total files scanned
+
+## Output Format
+
+Structure your findings per-file, with exact values and line numbers for every item cataloged. Use this structure:
+
+### Agents ({count} files)
+[Per-file catalog]
+
+### Skills ({count} directories)
+[Per-directory catalog]
+
+### Commands ({count} files)
+[Per-file catalog]
+
+### Reference Guides ({count} files)
+[Per-file catalog]
+
+### Settings
+[Hook configurations and other settings]
+
+### Summary
+[Total counts]
+
+Do NOT write your findings to a file. Return them directly.
+```
+
+### Step 3: Analyze (meta-auditor-agent via Agent tool)
+
+After BOTH Step 2 agents return their findings, delegate the analysis to the meta-auditor-agent.
+
+Delegate via the Agent tool (set `subagent_type` to `"meta-auditor-agent"`) with description "CC asset audit analysis" and this prompt:
+
+```
+You are auditing all CC assets in this project against current Claude Code documentation.
+
+## Audit Context
+- Current CC version: {CURRENT_CC_VERSION}
+- Last audited CC version: {lastAuditedCCVersion or "none (first audit)"}
+- Audit mode: {AUDIT_MODE}
+- Date: {CURRENT_DATE}
+
+## Documentation Research Data (from docs-researcher-agent)
+
+{INSERT the complete output from the docs-researcher-agent (Step 2a) here -- this is the current CC state, changelog entries, and deprecated patterns}
+
+## Asset Scan Data (from explorer-agent)
+
+{INSERT the complete output from the explorer-agent (Step 2b) here -- this is the complete inventory of all CC assets with their frontmatter values, contents, and line counts}
+
+## Instructions
+
+1. Before beginning analysis, load the audit checklist reference file at `reference/audit-checklist.md` from the `audit-cc-assets` skill. This contains the exhaustive valid-value lists you need for comparison.
+
+2. For every asset file listed in the scan data, read the actual file using the Read tool. Do not rely solely on the scan summaries -- verify frontmatter values directly.
+
+3. Compare every auditable dimension of every asset against:
+   - The valid-value lists from the audit checklist
+   - The current CC state from the documentation research
+   - The changelog changes since the last audit
+
+4. For each discrepancy found, classify it using the categorization framework:
+   - BREAKING: Values that are invalid in current CC (asset will fail or behave unpredictably)
+   - OUTDATED: Values that still work but use deprecated identifiers
+   - MISSING: New features not reflected in assets or reference guides
+
+5. For each finding, produce the complete finding record with all 10 fields: file, line, category, currentValue, recommendedFix, severity, breakingChange, autoFixable, ccVersion, description
+
+6. Structure your output using the audit report template from `templates/audit-report.md` in the audit-cc-assets skill.
+
+## Constraints
+
+- Compare, Don't Assume. Only flag issues that are supported by the documentation research data. Do not rely on pre-trained knowledge about what CC documentation says.
+- Every finding must include the exact file path and line number.
+- BREAKING findings are listed first (most urgent).
+- The Fix Plan section must group proposed changes by file.
+- MISSING findings do NOT appear in the Fix Plan (they require user decisions, not automatic fixes).
+
+Do NOT write your report to a file. Return it directly.
+```
+
+### Step 4: Present Report (Main Agent, interactive)
+
+Receive the meta-auditor-agent's findings from Step 3. Parse the categorized findings and present them to the user organized by severity.
+
+Present:
+
+```
+AUDIT REPORT
+CC Version: v{CURRENT_CC_VERSION} (last audited: v{lastAuditedCCVersion or "none"})
+Audit Mode: {AUDIT_MODE}
+Assets Scanned: {count from meta-auditor report}
+Assets with Findings: {count}
+
+## BREAKING ({count})
+
+[For each BREAKING finding:]
+- {file path} (line {line}): `{currentValue}` -> `{recommendedFix}`
+  {description}
+  Auto-fixable: {yes/no}
+
+## OUTDATED ({count})
+
+[For each OUTDATED finding:]
+- {file path} (line {line}): `{currentValue}` -> `{recommendedFix}`
+  {description}
+  Auto-fixable: {yes/no}
+
+## MISSING ({count})
+
+[For each MISSING finding:]
+- {file path}: {description}
+  Recommendation: {recommendation -- marked as "User decision required"}
+
+## Summary
+Total findings: {count}
+Auto-fixable: {count of BREAKING + OUTDATED findings}
+Requires manual review: {count of MISSING findings}
+```
+
+Store the complete findings data in context for use in Steps 5, 6, 7, and 9. This includes the full finding records with all 10 fields, and the Fix Plan table from the meta-auditor's report.
+
+### Step 5: Persist Report (Main Agent)
+
+Write the full audit findings to a persistent report file. Determine the current date as CURRENT_DATE (YYYY-MM-DD format).
+
+1. Create the output directory if it does not exist. Use Bash:
+   ```
+   mkdir -p .claude/specs/audit/
+   ```
+
+2. Read the audit report template from the audit-cc-assets skill using the Read tool:
+   - File: `.claude/skills/audit-cc-assets/templates/audit-report.md`
+
+3. Fill the template with the meta-auditor-agent's complete findings from Step 3. Include:
+   - YAML frontmatter: type, date, cc-version, previous-audit-date, previous-cc-version, audit-mode, status
+   - Summary section with all counts
+   - BREAKING Findings section with all finding details
+   - OUTDATED Findings section with all finding details
+   - MISSING Findings section with all finding details
+   - Fix Plan section grouping BREAKING and OUTDATED fixes by file
+   - Changelog Changes section
+
+4. Write the filled template to: `.claude/specs/audit/audit-{CURRENT_DATE}.md`
+
+5. Confirm to the user: "Audit report saved to `.claude/specs/audit/audit-{CURRENT_DATE}.md`"
+
+Proceed directly to Step 6 -- do not wait for confirmation.
+
+### Step 6: Fix Approval (Main Agent, interactive)
+
+This is the CONFIRMATION GATE. Present the auto-fixable findings and ask the user what to do.
+
+Count the auto-fixable findings (all BREAKING + all OUTDATED findings where autoFixable is true).
+
+If there are zero auto-fixable findings, present:
+```
+No auto-fixable findings. All {MISSING count} findings require manual design decisions.
+The audit report has been saved to `.claude/specs/audit/audit-{CURRENT_DATE}.md`.
+```
+Skip Steps 7 and 8. Proceed directly to Step 9.
+
+If there are auto-fixable findings, present:
+
+```
+FIX APPROVAL
+
+The following {auto-fixable count} findings are auto-fixable:
+
+BREAKING ({count}):
+{For each BREAKING finding:}
+  - {file path}: `{currentValue}` -> `{recommendedFix}` ({description})
+
+OUTDATED ({count}):
+{For each OUTDATED finding:}
+  - {file path}: `{currentValue}` -> `{recommendedFix}` ({description})
+
+MISSING findings ({count}) require manual design decisions and cannot be auto-fixed.
+
+Options:
+  all      -- Apply all auto-fixable changes ({count} fixes)
+  breaking -- Apply only BREAKING fixes ({BREAKING count} fixes)
+  select   -- Choose individual fixes
+  none     -- Skip all fixes (report is saved)
+
+What would you like to do?
+```
+
+**CONFIRMATION GATE**: Do NOT proceed to Step 7 until the user responds.
+
+Handle the user's response:
+- **"all"**: Proceed to Step 7 with ALL auto-fixable findings (BREAKING + OUTDATED).
+- **"breaking"**: Proceed to Step 7 with only BREAKING findings.
+- **"select"**: Present each auto-fixable finding individually and ask "Apply this fix? (yes/no)" for each. Collect the user's selections. Proceed to Step 7 with the selected findings.
+- **"none"**: Skip Steps 7 and 8. Set FIXES_APPLIED to 0. Proceed directly to Step 9.
+
+Store the accepted fix list as ACCEPTED_FIXES for Step 7.
+
+### Step 7: Apply Fixes (meta-agent via Agent tool)
+
+Delegate the accepted fixes to the meta-agent for implementation.
+
+Delegate via the Agent tool (set `subagent_type` to `"meta-agent"`) with description "Apply CC asset fixes" and this prompt:
+
+```
+You are applying approved fixes to CC assets. Apply ONLY the fixes listed below. Do NOT make any additional changes.
+
+## Accepted Fixes
+
+{For each fix in ACCEPTED_FIXES, list:}
+
+### Fix {N}: {file path}
+- Line: {line number or section}
+- Category: {BREAKING or OUTDATED}
+- Current Value: `{currentValue}`
+- Fix To: `{recommendedFix}`
+- Description: {description}
+
+## Instructions
+
+1. For each fix listed above:
+   a. Read the current file content using the Read tool
+   b. Locate the current value at the specified line or section
+   c. Verify the current value matches what is listed above
+   d. If it matches: apply the change using Edit or MultiEdit tool
+   e. If it does NOT match: STOP for this fix and report the conflict (do not improvise a different change)
+
+2. After applying all changes, verify each modified file:
+   - YAML frontmatter parses correctly (no broken delimiters, no duplicate keys)
+   - Markdown structure is intact (headings, code blocks, lists properly formatted)
+
+3. Report your results
+
+## Constraints
+- Apply ONLY the fixes listed above -- no additional changes
+- If a fix requires changing multiple lines in the same file, use MultiEdit for efficiency
+- If a current value does not match what is listed, report the conflict rather than guessing
+- Do NOT use Write to overwrite entire files -- use Edit or MultiEdit for targeted changes
+
+## Output Format
+
+### Files Modified
+- {file path}: {what was changed}
+
+### Conflicts Encountered
+{List any fixes where the current value did not match, or "None"}
+
+### Verification
+- {file path}: frontmatter valid ({yes/no}), structure valid ({yes/no})
+
+### Summary
+Total fixes applied: {count}
+Total conflicts: {count}
+
+Do NOT write this report to a file. Return it directly.
+```
+
+### Step 8: Validate Fixes (Main Agent)
+
+VALIDATION_CYCLE = 1
+MAX_CYCLES = 3
+
+For each fix in ACCEPTED_FIXES that the meta-agent reported as applied (not conflicted):
+
+1. **Read the file** using the Read tool.
+2. **Grep for the old value** (the `currentValue` from the finding). The old value should NOT be present at the specified line. If the old value is a pattern that appears elsewhere in the file legitimately, check specifically at the reported line number.
+3. **Grep for the new value** (the `recommendedFix` from the finding). The new value SHOULD be present.
+4. **Verify frontmatter** (if the fix was in frontmatter): Check that the YAML frontmatter block has valid delimiters (`---`) and no obvious syntax errors.
+
+Record each fix as PASS or FAIL.
+
+**If ALL fixes PASS**: Proceed to Step 9. Set FIXES_APPLIED to the count of applied fixes.
+
+**If any fix FAILS and VALIDATION_CYCLE < MAX_CYCLES**:
+1. Increment VALIDATION_CYCLE
+2. Compile a list of the failed validations with details (which file, what was expected, what was found)
+3. Re-delegate to the meta-agent via the Agent tool (set `subagent_type` to `"meta-agent"`) with description "Re-apply failed fixes" and this prompt:
+
+   ```
+   The previous fix implementation failed validation. Apply corrections.
+
+   ## Failed Fixes
+
+   {For each failed fix:}
+   ### Fix {N}: {file path}
+   - Expected old value `{currentValue}` to be replaced with `{recommendedFix}`
+   - Validation result: {what was found -- e.g., "old value still present at line X" or "new value not found"}
+
+   ## Instructions
+   1. Read each affected file
+   2. Diagnose why the fix was not applied correctly
+   3. Apply the correct change
+   4. Verify the file structure after the change
+
+   ## Constraints
+   - Only modify what is needed to address the validation failures
+   - Do NOT make changes beyond the original fix specifications
+
+   Return: files modified, conflicts encountered, verification results.
+   ```
+
+4. Re-validate all previously-failed fixes
+5. Return to the PASS/FAIL check
+
+**If any fix FAILS after MAX_CYCLES (3 cycles)**:
+Present the persistent failures to the user:
+
+```
+VALIDATION INCOMPLETE
+
+{count} fixes could not be validated after {MAX_CYCLES} attempts:
+{For each persistent failure:}
+  - {file path}: {description of what failed}
+
+The remaining {passed count} fixes were applied and validated successfully.
+Proceeding to update audit state with partial results.
+```
+
+Set FIXES_APPLIED to the count of fixes that PASSED validation. Proceed to Step 9.
+
+### Step 9: Update State (Main Agent)
+
+Update the audit state file with the results of this audit.
+
+1. **Compute summary values:**
+   - TOTAL_FINDINGS: total count from the meta-auditor's report
+   - BREAKING_COUNT: count of BREAKING findings
+   - OUTDATED_COUNT: count of OUTDATED findings
+   - MISSING_COUNT: count of MISSING findings
+   - FILES_SCANNED: count from the explorer's scan
+   - FILES_WITH_FINDINGS: count from the meta-auditor's report
+   - FIXES_APPLIED: count from Steps 7-8 (validated fixes only), or 0 if user chose "none"
+
+2. **Build the new state object:**
+
+   ```json
+   {
+     "lastAuditDate": "{CURRENT_DATE}",
+     "lastAuditedCCVersion": "{CURRENT_CC_VERSION}",
+     "lastAuditSummary": {
+       "totalFindings": {TOTAL_FINDINGS},
+       "breaking": {BREAKING_COUNT},
+       "outdated": {OUTDATED_COUNT},
+       "missing": {MISSING_COUNT},
+       "filesScanned": {FILES_SCANNED},
+       "filesWithFindings": {FILES_WITH_FINDINGS},
+       "fixesApplied": {FIXES_APPLIED}
+     },
+     "auditHistory": [
+       {EXISTING_HISTORY_ENTRIES if any},
+       {
+         "date": "{CURRENT_DATE}",
+         "ccVersion": "{CURRENT_CC_VERSION}",
+         "findings": {TOTAL_FINDINGS},
+         "fixesApplied": {FIXES_APPLIED}
+       }
+     ]
+   }
+   ```
+
+   If this is the first audit (no previous state file), `auditHistory` starts as a single-element array.
+   If a previous state file existed, read it first, preserve the existing `auditHistory` entries, and append the new entry.
+
+3. **Write the state file** to `.claude/audit-state.json` using the Write tool.
+
+### Step 10: Final Report (Main Agent)
+
+Present the final audit summary to the user.
+
+## Report
+
+```
+AUDIT COMPLETE
+
+CC Version: v{CURRENT_CC_VERSION}
+Audit Mode: {AUDIT_MODE}
+Date: {CURRENT_DATE}
+
+Scan:
+  Assets scanned: {FILES_SCANNED}
+  Assets with findings: {FILES_WITH_FINDINGS}
+
+Findings:
+  BREAKING: {BREAKING_COUNT}
+  OUTDATED: {OUTDATED_COUNT}
+  MISSING: {MISSING_COUNT}
+  Total: {TOTAL_FINDINGS}
+
+Fixes:
+  Auto-fixable: {count of BREAKING + OUTDATED}
+  User-approved: {count of ACCEPTED_FIXES or 0}
+  Applied and validated: {FIXES_APPLIED}
+  Remaining (manual review): {MISSING_COUNT}
+
+Output:
+  Audit report: .claude/specs/audit/audit-{CURRENT_DATE}.md
+  Audit state: .claude/audit-state.json
+
+Next Steps:
+  - Review MISSING findings in the audit report for manual design decisions
+  - Run /audit-cc-assets again after the next CC update to check for new changes
+```