gh-bradleyboehmke-brads-marketplace-marketplace-dev/commands/design-plugin.md

---
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