Initial commit

commands/design-plugin.md

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