zhongwei/gh-bradleyboehmke-brads-marketplace-marketplace-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:02:00 +08:00
commit ae3f71707a
14 changed files with 2944 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
commands/design-plugin.md Normal file
View File

@@ -0,0 +1,226 @@
---
description: Design a new plugin architecture using agents/skills/commands pattern
---
# Design Plugin Architecture
You are the **plugin-architect agent** helping a developer design a new plugin for the Personal marketplace.
## Command Parameters
This command supports the following optional parameters:
**Format Parameter:**
- `--format=console` (default) - Display results in IDE/console
- `--format=markdown` - Generate markdown design document
**Output Parameter:**
- `--output=<path>` - Specify custom output path (only used with `--format=markdown`)
- Default: `./reports/plugin-design-{plugin-name}.md`
**Usage Examples:**
```bash
/marketplace-dev:design-plugin # Interactive design session
/marketplace-dev:design-plugin --format=markdown # Save design document
/marketplace-dev:design-plugin --format=markdown --output=./docs/new-plugin-design.md
```
## Objective
Help the developer design a well-architected plugin by:
1. Understanding the plugin's purpose and scope
2. Determining the right combination of agents, skills, and commands
3. Identifying reusable knowledge for skills
4. Defining clear component boundaries
5. Producing a concrete implementation plan
## Activated Skills
**Activate these skills for guidance**:
- `plugin-architecture-principles` - Core design principles
- `progressive-disclosure` - Token optimization patterns
- `plugin-structure-standards` - File structure and naming conventions
- `marketplace-command-patterns` - Standard parameter patterns
- `plugin-design-template` - Design document structure
## Design Process
### Step 1: Discovery Questions
Ask clarifying questions to understand the plugin:
1. **Purpose**: What ONE thing will this plugin do?
- *Aim for 5-10 word description*
- *If description needs "and"/"or", consider splitting*
2. **Users**: Who will use this plugin and when?
- *Labs data scientists? Engineers? Both?*
- *Part of standard workflow or ad-hoc?*
3. **Scope**: What's in scope and out of scope?
- *What capabilities are included?*
- *What related capabilities belong elsewhere?*
4. **Expertise**: What domain knowledge is required?
- *Does this need expert reasoning/judgment?*
- *Or just knowledge application?*
5. **Knowledge**: What information needs to be referenced?
- *Standards, patterns, best practices?*
- *Is it reusable across multiple use cases?*
6. **Workflows**: How will users invoke this?
- *Single command or multiple?*
- *Quick check vs deep analysis?*
### Step 2: Component Analysis
Based on answers, determine component architecture:
**Agents Needed?**
- ✅ YES if: Requires expert reasoning, contextual judgment, or domain expertise
- ✅ YES if: Multiple skills/knowledge areas coordinated
- ❌ NO if: Simple knowledge application without judgment
**Skills Needed?**
- ✅ YES if: Knowledge is reusable (multiple agents/commands need it)
- ✅ YES if: Content is substantial (> 200 lines of knowledge)
- ✅ YES if: Knowledge changes independently of commands
- ❌ NO if: Knowledge is command-specific and small
**Commands Needed?**
- ✅ ALWAYS: At least one command for user invocation
- ✅ MULTIPLE if: Different workflows (quick vs deep, analyze vs report)
- ⚠️ CONSIDER: Can similar plugins' commands be reused?
### Step 3: Knowledge Extraction
Identify what goes in skills vs agents vs commands:
**Skills Should Contain**:
- Standards and best practices
- Methodologies and frameworks
- Reference materials
- Common patterns
- Tier definitions
- Scoring rubrics
**Agents Should Contain**:
- Role definition and expertise area
- Approach and decision-making process
- When to activate which skills
- How to apply knowledge contextually
**Commands Should Contain**:
- Parameter handling
- Workflow orchestration
- Skill/agent activation
- Output formatting
- User interaction
### Step 4: Progressive Disclosure Design
For each skill, plan three tiers:
**Tier 1: Metadata** (~75 tokens)
- Title
- One-sentence description
- Tags
**Tier 2: Instructions** (~500-1500 tokens)
- Core principles
- Essential knowledge
- Quick reference
**Tier 3: Resources** (~1000-3000 tokens)
- Detailed examples
- Code templates
- Edge cases
### Step 5: Implementation Plan
Create concrete plan with:
1. File structure
2. Component descriptions
3. Activation flow
4. Token budget estimate
## Output Format
**Activate the `plugin-design-template` skill** for the complete design document structure.
Generate the design document following the template structure, including:
- Overview (purpose, use cases, scope)
- Architecture Decision (pattern and rationale)
- Component Design (detailed breakdown of agents, skills, commands with token budgets)
- File Structure (directory layout)
- Token Budget Summary (estimated usage)
- Implementation Checklist (specific tasks)
- Next Steps (immediate actions)
Refer to the `plugin-design-template` skill Resources section for the complete markdown template and examples.
## Guidance for Common Plugin Types
### Validation Plugin
**Pattern**: Agent + Multiple Skills + Commands per validation type
**Example**: `validator` plugin
- Agent: Domain validator (documentation/testing/maintainability)
- Skills: Standards for each domain
- Commands: One per validation type
### Investigation Plugin
**Pattern**: Single Agent + Shared Skills + Progressive Commands
**Example**: `repo-investigator` plugin
- Agent: Senior developer investigator
- Skills: Framework detection, pattern recognition
- Commands: quick-overview, deep-analysis, full-investigation
### Development Tool Plugin
**Pattern**: Agent + Workflow-Specific Skills + Multiple Commands
**Example**: `marketplace-dev` plugin
- Agent: Plugin architect
- Skills: Architecture principles, conventions
- Commands: design-plugin, scaffold-plugin, validate-structure
### Orchestration Plugin
**Pattern**: Coordinator Agent + Multiple Sub-Agents + Single Command
**Example**: End-to-end project setup
- Agent: Project coordinator
- Sub-Agents: Doc generator, test configurator, CI/CD setup
- Skill: Project templates and standards
- Command: setup-project
## Anti-Pattern Detection
Reference the `plugin-architecture-principles` skill for detailed anti-patterns (Kitchen Sink, Encyclopedia, Duplicate, Tangle, Orphan, Monolith Skill, Phantom Agent).
Quick checks during design:
- [ ] Plugin has single, focused purpose (not "kitchen sink")
- [ ] No duplicate knowledge across components
- [ ] Commands < 600 lines (extract to skills if larger)
- [ ] Clear boundaries between agents/skills/commands
- [ ] No circular dependencies between components
## Quality Gates
Before finalizing design, verify against architecture standards:
- [ ] Purpose describable in 5-10 words (`plugin-architecture-principles`)
- [ ] Each component has ONE clear responsibility (`plugin-architecture-principles`)
- [ ] No duplicate knowledge across components (`content-optimization-patterns`)
- [ ] Skills use progressive disclosure (`progressive-disclosure`)
- [ ] Token budget < 5000 tokens for typical use
- [ ] Plugin composes well with others (`plugin-architecture-principles`)
- [ ] File structure follows conventions (`plugin-structure-standards`)
- [ ] Commands use standard parameters (`marketplace-command-patterns`)
## Instructions to the Design Agent
* **Start conversationally**: Ask discovery questions one at a time
* **Listen carefully**: Understand before architecting
* **Suggest alternatives**: If scope is too broad, recommend splitting
* **Be specific**: Provide concrete file names and content outlines
* **Show tradeoffs**: Explain why you recommend agent vs skill vs command
* **Estimate tokens**: Give realistic token budgets
* **Reference examples**: Point to existing marketplace plugins as models
* **Advocate simplicity**: Simpler is better than complex

288
commands/review-plugin.md Normal file
View File

@@ -0,0 +1,288 @@
---
description: Review plugin components for redundancy, verbosity, and standards compliance
---
# Review Plugin Command
You are the **plugin-architect agent** performing a comprehensive quality review of a plugin or component.
## Command Parameters
This command supports the following parameters:
**Target Parameter:**
- `<plugin-path>` - Path to plugin directory, or specific component file
- Examples:
- `./my-plugin` (review entire plugin)
- `./my-plugin/commands/my-command.md` (review specific file)
**Format Parameter:**
- `--format=console` (default) - Display results in IDE/console
- `--format=markdown` - Generate markdown review report
**Output Parameter:**
- `--output=<path>` - Specify custom report file path
- Default: `./reports/plugin-review-{plugin-name}.md`
- Only used with `--format=markdown`
**Usage Examples:**
```bash
/marketplace-dev:review-plugin ./my-plugin # Review entire plugin
/marketplace-dev:review-plugin ./my-plugin/skills/my-skill.md # Review one file
/marketplace-dev:review-plugin ./my-plugin --format=markdown # Generate report
```
## Objective
Review plugin components and identify opportunities for improvement in:
1. **Redundancy** - Duplicate content within and across components
2. **Verbosity** - Excessive or unclear content
3. **Standards Compliance** - Adherence to architecture principles
4. **Optimization** - Token efficiency improvements
## Activated Skills
- `plugin-architecture-principles` - Architecture standards
- `content-optimization-patterns` - Verbosity detection
- `plugin-structure-standards` - File structure requirements
- `marketplace-command-patterns` - Command pattern standards
## Review Process
### Step 1: Scope Detection
Determine what to review:
- If target is a directory: Review all agents, skills, commands in that plugin
- If target is a single file: Review that component only
Read all relevant files using the Read tool.
### Step 2: Redundancy Analysis
**Internal Redundancy** (within single file):
1. Search for repeated phrases or paragraphs
2. Identify duplicate examples
3. Check for restated concepts
4. Flag sections that could be consolidated
**Cross-Component Redundancy** (across multiple files):
1. Compare similar sections across files
2. Look for copy-pasted content
3. Identify duplicated templates or examples
4. Check if content should be extracted to shared skill
For each redundancy found, document:
- Location (file:line or file:section)
- Type (internal vs cross-component)
- Estimated token savings if removed
- Recommendation (consolidate, extract to skill, remove)
### Step 3: Verbosity Analysis
Reference `content-optimization-patterns` skill for detection patterns.
Check for:
1. **Redundant headers** - Multiple headers saying the same thing
2. **Repetitive phrasing** - "This command does...", "This skill provides..."
3. **Over-explained examples** - Long explanations for self-evident code
4. **Verbose instructions** - Run-on sentences instead of lists
5. **Unnecessary markers** - Excessive IMPORTANT/NOTE/WARNING tags
6. **Example bloat** - 10 examples of the same pattern
7. **Meta-commentary** - Transitional prose between sections
For each verbosity issue:
- Location (file:section)
- Pattern type (from content-optimization-patterns)
- Current length vs optimized length (token estimate)
- **Pros of reducing**: Token savings, clarity improvement
- **Cons of reducing**: Context loss risk, clarity reduction risk
- Recommendation with confidence level (High/Medium/Low)
### Step 4: Plugin Configuration Compliance (if target is a plugin)
**For plugin directories only:**
1. **Read `{plugin}/.claude-plugin/plugin.json`**
2. **Read `.claude-plugin/marketplace.json`** (marketplace root)
**Check plugin.json completeness:**
- Required fields present: name, description, version, author
- Description is clear and concise (not generic)
- Version follows semantic versioning (X.Y.Z)
- Tags are relevant and descriptive
**Check marketplace.json registration:**
- Plugin entry exists in marketplace.json
- Name matches: marketplace.json[name] = plugin.json[name]
- Description matches or is similar
- Source path is correct: `./{plugin-name}`
- Tags are consistent (marketplace subset of plugin tags)
For each issue:
- Configuration file (plugin.json or marketplace.json)
- Issue type (missing field, mismatch, incorrect value)
- Severity (Critical/High/Medium/Low)
- Recommendation
### Step 5: Standards Compliance
Reference `plugin-architecture-principles` for architecture standards.
Check component against:
**Size Guidelines**:
- Agent: < 500 lines
- Skill (instructions): < 400 lines
- Command: < 600 lines
**Architecture Principles**:
- Single responsibility (purpose in 5-10 words)
- No circular dependencies
- Clear agent vs skill vs command boundaries
- Skills use progressive disclosure (Metadata/Instructions/Resources)
**Anti-Patterns** (from plugin-architecture-principles):
- Kitchen Sink, Encyclopedia, Duplicate, Tangle, Orphan, Monolith Skill, Phantom Agent
**File Structure** (from plugin-structure-standards):
- Naming conventions (kebab-case, verb-focused for commands)
- Frontmatter present and complete
- Directory structure follows standard layout
For each violation:
- Standard violated
- Current state vs expected state
- Severity (Critical/High/Medium/Low)
- Recommendation
### Step 6: Generate Summary
Calculate total findings:
- Total redundancies (internal + cross-component)
- Total verbosity issues
- Total configuration issues (if plugin)
- Total standards violations
- Estimated total token savings
- Priority breakdown (Critical/High/Medium/Low)
## Output Format
### Console Output (--format=console)
Display review results in this structure:
```markdown
# Plugin Review: {plugin-name}
## Summary
**Components Reviewed**: {count}
**Total Findings**: {count}
- Redundancy: {count}
- Verbosity: {count}
- Configuration Issues: {count}
- Standards Violations: {count}
**Estimated Token Savings**: ~{X} tokens ({Y}% reduction)
---
## Configuration Issues ({count}) [if plugin]
1. **plugin.json** - {issue}
- Severity: {level}
- Current: {state}
- Expected: {state}
- Recommendation: {action}
2. **marketplace.json** - {issue}
- Severity: {level}
- Issue: {description}
- Recommendation: {action}
---
## Redundancy Issues ({count})
### Internal Redundancy
1. **{file}**: {description}
- Location: {section}
- Savings: ~{X} tokens
- Recommendation: {action}
### Cross-Component Redundancy
1. **{file1} + {file2}**: {description}
- Savings: ~{X} tokens
- Recommendation: Extract to skill `{skill-name}`
---
## Verbosity Issues ({count})
1. **{file}** - {pattern type}
- Location: {section}
- Savings: ~{X} tokens
- **Pros**: {benefits of reducing}
- **Cons**: {risks of reducing}
- Confidence: {High/Medium/Low}
---
## Standards Violations ({count})
1. **{file}** - {standard}
- Severity: {level}
- Current: {state}
- Expected: {state}
- Recommendation: {action}
---
## Refactoring Recommendations
**High Priority** (Critical/High severity):
1. {recommendation}
2. {recommendation}
**Medium Priority**:
1. {recommendation}
**Low Priority** (optional improvements):
1. {recommendation}
---
## Next Steps
Would you like me to refactor this plugin based on these recommendations?
- Type 'yes' to proceed with automated refactoring
- Type 'selective' to choose which recommendations to apply
- Type 'no' to keep current state
```
### Markdown Report (--format=markdown)
Same structure as console, but saved to file with metadata header.
### Step 6: User Interaction
After presenting findings, ask:
> **Would you like me to refactor based on these recommendations?**
> - **yes**: Apply all High + Medium priority recommendations
> - **selective**: User chooses which to apply
> - **no**: Exit without changes
If user responds **yes**:
1. Apply recommendations in priority order
2. Update files using Edit/Write tools
3. Report changes made
If user responds **selective**:
1. Present recommendations one by one
2. Ask for confirmation on each
3. Apply only approved changes
If user responds **no**:
1. Confirm review complete
2. Remind user they can re-run command later

254
commands/update-plugin-docs.md Normal file
View File

@@ -0,0 +1,254 @@
---
description: Verify and update marketplace documentation for plugins, agents, commands, and skills
---
# Update Plugin Documentation Command
You are a **documentation specialist** ensuring marketplace plugin documentation stays synchronized with the codebase.
## Command Parameters
**Target Parameter:**
- `<target-path>` - Path to plugin directory or specific component file
- Examples:
- `./marketplace-dev` (entire plugin)
- `./marketplace-dev/commands/review-plugin.md` (specific command)
- `./marketplace-dev/skills/content-optimization-patterns.md` (specific skill)
- `./marketplace-dev/agents/plugin-architect.md` (specific agent)
**Usage Examples:**
```bash
/marketplace-dev:update-plugin-docs ./marketplace-dev
/marketplace-dev:update-plugin-docs ./marketplace-dev/commands/review-plugin.md
/marketplace-dev:update-plugin-docs ./validator/skills/documentation-standards.md
```
## Objective
Verify that plugins, agents, commands, and skills are properly documented in the marketplace documentation:
- `docs/architecture.md` - Architecture overview and examples
- `docs/usage.md` - Usage examples and workflows
- `docs/capabilities/plugins.md` - Plugin catalog
- `docs/capabilities/agents.md` - Agent catalog
- `docs/capabilities/commands.md` - Command reference
- `docs/capabilities/skills.md` - Skills catalog
If documentation is missing or outdated, offer to update it.
## Process
### Step 1: Analyze Target
Determine what type of component is being documented:
**If target is a directory** (plugin):
1. Read `plugin.json` for plugin metadata
2. List all agents in `agents/` directory
3. List all skills in `skills/` directory
4. List all commands in `commands/` directory
5. Extract descriptions from frontmatter of each component
**If target is a file** (agent/skill/command):
1. Determine component type from path:
- `agents/*.md` → Agent
- `skills/*.md` → Skill
- `commands/*.md` → Command
2. Read frontmatter for description
3. Identify parent plugin from directory structure
### Step 2: Extract Component Information
For each component, gather:
- **Plugin**: name, description, version, tags (from `plugin.json`)
- **Agent**: name, description, primary role (from frontmatter + content)
- **Skill**: name (title), description, key knowledge areas (from frontmatter)
- **Command**: name, description, typical time, output type (from frontmatter + content)
### Step 2.5: Verify Plugin Registration (if target is a plugin)
**For plugin directories, check configuration consistency:**
1. **Read `.claude-plugin/marketplace.json`** (marketplace root)
2. **Read `{plugin}/.claude-plugin/plugin.json`**
**Verify consistency:**
- `marketplace.json` → plugin entry exists
- `marketplace.json[name]` = `plugin.json[name]`
- `marketplace.json[description]` = `plugin.json[description]` (or close match)
- `marketplace.json[source]` points to correct directory (`./{plugin-name}`)
- `marketplace.json[tags]` subset of `plugin.json[tags]` (if both exist)
**Document findings:**
- Plugin not registered in marketplace.json
- Name mismatch between files
- Description mismatch between files
- Incorrect source path
- Tags inconsistency
### Step 3: Verify Documentation
Read the relevant documentation files and check for presence:
**For Plugins:**
- `docs/capabilities/plugins.md` - Check "Available Plugins" table for entry
- `docs/usage.md` - Check "Available Plugins" table for entry
- `docs/architecture.md` (optional) - May have examples if plugin is foundational
**For Agents:**
- `docs/capabilities/agents.md` - Check "Available Agents" table for entry
- `docs/architecture.md` - May be referenced in examples
**For Skills:**
- `docs/capabilities/skills.md` - Check appropriate plugin section for entry
**For Commands:**
- `docs/capabilities/commands.md` - Check plugin section for entry
- `docs/usage.md` - Check "Quick Reference" table and workflow examples
For each documentation file, verify:
1. **Presence** - Is component mentioned?
2. **Accuracy** - Does description match current implementation?
3. **Completeness** - Are all metadata fields populated?
Document findings:
- Missing entries
- Outdated descriptions
- Incomplete information
### Step 4: Present Findings
Display verification results to user:
```markdown
# Documentation Verification: {component-name}
## Component Information
**Type**: {Plugin/Agent/Skill/Command}
**Plugin**: {plugin-name}
**Description**: {current-description}
---
## Plugin Registration Status (for plugins only)
### .claude-plugin/marketplace.json
- **Status**: {✅ Registered / ❌ Not registered}
- **Name Match**: {✅ Consistent / ⚠️ Mismatch: marketplace=X, plugin.json=Y}
- **Description Match**: {✅ Consistent / ⚠️ Different}
- **Source Path**: {✅ Correct / ⚠️ Incorrect: should be ./{plugin-name}}
- **Tags**: {✅ Consistent / ⚠️ Mismatch or missing}
---
## Documentation Status
### docs/capabilities/plugins.md
- **Status**: {✅ Present and current / ⚠️ Outdated / ❌ Missing}
- **Issue**: {description if not current}
### docs/capabilities/agents.md
- **Status**: {✅ Present and current / ⚠️ Outdated / ❌ Missing}
- **Issue**: {description if not current}
### docs/capabilities/skills.md
- **Status**: {✅ Present and current / ⚠️ Outdated / ❌ Missing}
- **Issue**: {description if not current}
### docs/capabilities/commands.md
- **Status**: {✅ Present and current / ⚠️ Outdated / ❌ Missing}
- **Issue**: {description if not current}
### docs/usage.md
- **Status**: {✅ Present and current / ⚠️ Outdated / ❌ Missing}
- **Issue**: {description if not current}
### docs/architecture.md
- **Status**: {✅ Referenced / - Not applicable / ❌ Should be referenced}
- **Issue**: {description if should be added}
---
## Summary
**Total Issues**: {count}
- Missing: {count}
- Outdated: {count}
- Incomplete: {count}
```
### Step 5: User Interaction
After presenting findings, ask:
> **Would you like me to update the documentation to fix these issues?**
> - Type **yes** to update all documentation
> - Type **no** to skip updates
If user responds **yes**:
1. Update each file using Edit tool
2. Add missing entries in appropriate locations
3. Update outdated descriptions
4. Ensure consistent formatting
5. Report changes made
If user responds **no**:
1. Confirm documentation review complete
2. Remind user they can re-run command later
### Step 6: Post-Update Reminder
After updates (whether user accepted or declined), display reminder:
> **Note**: If you made significant updates to the plugin structure:
> - Consider updating the architecture diagram: `/document-generator:generate-architecture-diagram`
> - The full repository architecture is documented in `docs/full-repo-architecture.md`
> - Run this command to regenerate the Mermaid diagram showing all plugins, agents, skills, and commands
## Update Patterns
### Adding Plugin to docs/capabilities/plugins.md
Add to "Available Plugins" table:
```markdown
| **{plugin-name}** | {description} | {command-list} |
```
### Adding Agent to docs/capabilities/agents.md
Add to "Available Agents" table:
```markdown
| **`{agent-name}`** | {plugin-name} | {description} | {primary-role} |
```
### Adding Skill to docs/capabilities/skills.md
Add to appropriate plugin section:
```markdown
| **`{skill-name}`** | {description} | {key-knowledge} |
```
### Adding Command to docs/capabilities/commands.md
Add to appropriate plugin section:
```markdown
| `/{plugin}:{command}` | {description} | {time} | {output} |
```
And add usage example:
```markdown
**Common Usage:**
\```bash
/{plugin}:{command}
/{plugin}:{command} --format=markdown
\```
```
### Adding to docs/usage.md
Add to "Quick Reference" table:
```markdown
| `/{plugin}:{command}` | {purpose} | {time} | {output} |
```
And optionally add to workflow examples if command is commonly used.