155 lines
5.7 KiB
Markdown
155 lines
5.7 KiB
Markdown
# 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
|