cc-os/plugins/cc-architect/workflows/audit-plugin.md

# Workflow: Audit Plugin

Comprehensive plugin evaluation against standards.

## Who should do this work

| Phase | Model | Why |
|-------|-------|-----|
| Research | Haiku | File gathering, structural validation |
| Deep analysis | Sonnet | Pattern matching, standards checking |
| Synthesis | Opus | Report writing, quality decisions |
| Cleanup | Haiku | File deletion |

## When to use

- Evaluating plugin from marketplace
- Checking plugin-architect standards compliance
- Comprehensive review

## Inputs required

- **plugin_path** - Path to plugin directory
- **audit_components** - `all` (default), `manifest-only`, `skills`, `agents`, `commands`

## Output

- `.claude/plugin-data/plugin-architect/audits/<plugin-name>-audit.md` (gitignored)
- Summary with verdict (Ready / Not Ready)
- Delete report after user acts on findings

---

## Phases

### Phase 1: Research and Setup (Haiku)

**Purpose:** Gather all inputs, validate requirements, perform initial structural checks.

**Tasks:**
1. Validate plugin path exists and is directory
2. Verify `.claude-plugin/plugin.json` exists
3. Extract plugin name and create scratch workspace
4. Inventory components: count skills, agents, commands
5. Check for reversion protection artifacts:
   - `invariants.md` in plugin root
   - `.decisions/` directory
   - `examples/golden/`
6. Check for config infrastructure:
   - `workflows/config.md` (config workflow for programmatic use)
   - `commands/config.md` (slash command for user invocation)
   - Run the Ruby config audit script for marketplace/installed/settings state:
     ```bash
     ruby ${CLAUDE_PLUGIN_ROOT}/scripts/plugin_config/plugin_config.rb audit \
       --plugin=<plugin-name> \
       --marketplace=<marketplace-id> \
       --project=<project-path> \
       --marketplace_file=<path-to-marketplace.json>
     ```
     Parse the JSON output and include check results (marketplace, installed, settings) in the research output. If the script is unavailable, fall back to manual file checks.
7. Read plugin manifest and validate structure
8. Check documentation existence (`CLAUDE.md`, `README.md`)
9. List all component entry files (SKILL.md, agent.md, command.md)

**References:**
- `${CLAUDE_PLUGIN_ROOT}/references/layout/plugin-structure.md`

**Output:** `scratch/research.md`
- Plugin metadata (name, version, component counts)
- Reversion protection inventory (invariants/decisions/golden examples)
- Config infrastructure status (workflows/config.md, commands/config.md)
- Manifest structure validation
- Documentation checklist
- Component file listing

---

### Phase 2: Deep Analysis (Sonnet)

**Purpose:** Perform detailed audits of manifest, documentation, and components.

**Tasks:**
1. Read `scratch/research.md` for context
2. Validate manifest fields:
   - Required fields: `name`, `version`, `description`
   - Name kebab-case format
   - Version semver compliance
   - Description non-empty and meaningful
3. Audit documentation quality:
   - `CLAUDE.md` meaningful (not boilerplate)
   - Documentation matches actual contents
   - README presence (optional but noted)
4. Audit config infrastructure:
   - Check if `workflows/config.md` exists -> flag as minor if missing
   - Check if `commands/config.md` exists -> flag as minor if missing
   - If either missing, add recommendation to create config infrastructure
5. If `audit_components != manifest-only`:
   - Check entry file naming (kebab-case)
   - Check description style consistency
   - Pattern analysis:
     - `workflows/` at plugin root -> Role-Workflow candidate
     - Skills dispatching 2+ subagent workflows -> Should use Role-Workflow
   - Optionally delegate to component-specific audit workflows:
     - Skills: `${CLAUDE_PLUGIN_ROOT}/workflows/audit-skill.md`
     - Workflows: `${CLAUDE_PLUGIN_ROOT}/workflows/audit-workflow.md`
     - Commands: `${CLAUDE_PLUGIN_ROOT}/workflows/audit-command.md`
6. Classify all findings by severity (significant/minor/polish)

**References:**
- `${CLAUDE_PLUGIN_ROOT}/references/tool-patterns/severity-guide.md`
- `references/tool-patterns/role-workflow-pattern.md`

**Severity for plugins:**
- **Significant:** Invalid manifest, missing CLAUDE.md, broken component refs
- **Minor:** Missing README, inconsistent patterns, missing config infrastructure
- **Polish:** Documentation wording, organization

**Output:** `scratch/findings.md`
- Manifest findings (with severity)
- Documentation findings (with severity)
- Config infrastructure findings (with severity and recommendations)
- Component findings (with severity)
- Pattern recommendations
- Delegated audit summaries (if any)

---

### Phase 3: Synthesis and Cleanup (Opus for report, Haiku for cleanup)

**Purpose:** Generate final audit report with verdict, act on findings, clean up artifacts.

**Tasks (Opus):**
1. Read `scratch/research.md` and `scratch/findings.md`
2. Synthesize findings into cohesive report:
   - Include reversion protection context
   - Group by severity (significant -> minor -> polish)
   - Include delegated audit summaries
   - Calculate verdict: Ready (0 significant) or Not Ready (1+ significant)
3. Write final report: `.claude/plugin-data/plugin-architect/audits/<plugin-name>-audit.md`
4. Present findings to user:
   - Walk through significant findings first
   - Offer to fix or let user handle
   - Prompt for decision recording if significant architectural decisions made

**Tasks (Haiku cleanup):**
1. After user acts on findings, delete audit report
2. Delete scratch workspace
3. If decision recording requested:
   - Template: `references/tool-patterns/templates/decision-record-template.md`
   - Write: `<plugin_path>/.decisions/YYYY-MM-DD-<topic>.md`

**Decision recording triggers:**
- Plugin-wide pattern decisions
- Exceptions to standards
- Component organization rationale