Workflow Phase Details
Complete reference for the 4-phase optimization workflow.
Phase 1: Discovery & Validation
Path Resolution & Verification
- Use
realpath to resolve absolute path from $ARGUMENTS
- Verify the resolved path exists
Directory Structure Validation
- Check for
.claude-plugin/plugin.json manifest (required)
- Find component directories:
commands/, agents/, skills/, hooks/
- Report missing directories or files (MUST NOT create them)
Component Template Validation
- Read complete file (frontmatter + body) for each component
- Validate against templates in
${CLAUDE_PLUGIN_ROOT}/examples/
- See
./template-validation.md for detailed validation rules
- Cross-check
plugin.json declarations match component types
- Report ALL template violations as CRITICAL issues
Modern Architecture Assessment
If commands/ directory exists with .md files:
- Use
AskUserQuestion tool to ask about migrating to skills structure
- Record user decision for Phase 2
Validation Script
Run the unified validation script:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"
Options:
--check=structure,manifest,frontmatter,tools,tokens — Run specific validators
--json — Output results as JSON
-v, --verbose — Detailed output
Analysis
Compile issues by severity (Critical, Warnings, Info)
Phase 2: Agent-Based Optimization
Agent Context Requirements
Launch plugin-optimizer:plugin-optimizer agent with:
- Target plugin absolute path
- Validation issues from Phase 1 (organized by severity)
- Template validation results (component violations and recommended fixes)
- User decisions (migration choice if applicable)
Path Reference Rules
- Same directory: Use relative paths (
./reference.md)
- Outside directory: Use
${CLAUDE_PLUGIN_ROOT} paths
- Component templates: See
${CLAUDE_PLUGIN_ROOT}/examples/
Template Fix Requirements
- Agent MUST use
AskUserQuestion tool before applying template fixes
- Present detected violations with specific examples
- Show before/after comparison for structure fixes
Redundancy Analysis
- Allow strategic repetition of critical content (MUST/SHOULD requirements, templates, examples)
- Favor concise restatement over verbatim duplication
Post-Agent Actions
- Wait for agent to complete optimization tasks
- Receive fix report from agent
- Update plugin version in
.claude-plugin/plugin.json:
- Patch (x.y.Z+1): Bug fixes
- Minor (x.Y+1.0): New components
- Major (X+1.0.0): Breaking changes
Critical: Launch agent ONCE with all context. Orchestrator MUST NOT make fixes directly.
Phase 3: Final Verification
Re-run Validation
Execute the validation script again:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"
Results Analysis
- Compare results with Phase 1 findings
- Confirm critical issues resolved
- If issues remain, resume agent with remaining issues
- Document remaining issues (design decisions or optional improvements)
Phase 4: Final Deliverables
Comprehensive Report Generation
- Synthesize results from all validation and optimization phases
- Include: issues detected, fixes applied, verification outcomes, component inventory
- Provide overall assessment (PASS/FAIL) with clear reasoning
- See
./report-template.md for complete report format
README Documentation Update
- Read current README.md structure
- Generate updated content reflecting current plugin state:
- Plugin metadata from
plugin.json (name, version, description)
- Accurate directory structure and component inventory
- Installation instructions and usage examples
- Replace existing README.md with current documentation
- Ensure no version history is appended (users reference git log for history)