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:

     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