📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,44 @@
|
||||
# Plugin Engineer Overview
|
||||
|
||||
Quick reference for the repo-to-plugin transformation workflow.
|
||||
|
||||
## Stages
|
||||
|
||||
| Stage | Skill Loaded | Output |
|
||||
|-------|--------------|--------|
|
||||
| 1. Discovery | `outfitter:research` | `artifacts/plugin-engineer/discovery.md` |
|
||||
| 2. Recon | `outfitter:codebase-recon` | `artifacts/plugin-engineer/recon.md` |
|
||||
| 3. Patterns | `outfitter:patterns` | `artifacts/plugin-engineer/patterns.md` |
|
||||
| 4. Mapping | `outfitter:codify` | `artifacts/plugin-engineer/mapping.md` |
|
||||
| 5. Authoring | `outfitter:skills-dev` | `artifacts/plugin-engineer/components/` |
|
||||
| 6. Packaging | `outfitter:claude-plugins` | Plugin directory |
|
||||
| 7. Audit | `outfitter:claude-plugin-audit` | `artifacts/plugin-engineer/audit.md` |
|
||||
|
||||
## Quick Mode
|
||||
|
||||
Skip stages 3-4 for simple repos:
|
||||
|
||||
```
|
||||
Discovery → Recon → Authoring → Packaging → Audit
|
||||
```
|
||||
|
||||
Trigger: Single-purpose tool, < 5 commands, user requests speed.
|
||||
|
||||
## Stage References
|
||||
|
||||
- [stage-1-discovery.md](stage-1-discovery.md) — External research
|
||||
- [stage-2-recon.md](stage-2-recon.md) — Codebase analysis
|
||||
- [stage-3-patterns.md](stage-3-patterns.md) — Pattern extraction
|
||||
- [stage-4-mapping.md](stage-4-mapping.md) — Component selection
|
||||
- [stage-5-authoring.md](stage-5-authoring.md) — Creating components
|
||||
- [stage-6-packaging.md](stage-6-packaging.md) — Plugin structure
|
||||
- [stage-7-audit.md](stage-7-audit.md) — Validation
|
||||
- [repo-types.md](repo-types.md) — CLI vs Library vs MCP patterns
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
**Over-engineering**: Creating agents when skills suffice, multiple commands for related actions.
|
||||
|
||||
**Under-engineering**: Single skill doing everything, missing error handling, no documentation.
|
||||
|
||||
**Scope creep**: Adding "nice to have" features before core works.
|
||||
@@ -0,0 +1,163 @@
|
||||
# Repo Type Patterns
|
||||
|
||||
Guidance for different repository types.
|
||||
|
||||
## CLI Tool
|
||||
|
||||
Examples: git, docker, kubectl, gh, npm
|
||||
|
||||
### Discovery Focus
|
||||
- Command structure and subcommands
|
||||
- Common workflows users perform
|
||||
- Flags that are hard to remember
|
||||
- Error messages and recovery patterns
|
||||
|
||||
### Pattern Types
|
||||
- Command sequences (e.g., add → commit → push)
|
||||
- Option combinations (e.g., docker build with caching)
|
||||
- Error handling workflows
|
||||
|
||||
### Primary Components
|
||||
- **Skills**: For multi-step workflows
|
||||
- **Commands**: Entry points for common operations
|
||||
|
||||
### Example Plugin Structure
|
||||
|
||||
```
|
||||
kubectl-plugin/
|
||||
├── skills/
|
||||
│ ├── deploy-workflow/ # Rolling deployment process
|
||||
│ ├── debug-pod/ # Pod debugging methodology
|
||||
│ └── resource-management/ # Resource lifecycle
|
||||
├── commands/
|
||||
│ ├── quick-deploy.md # Fast deployment entry
|
||||
│ └── pod-shell.md # Quick shell access
|
||||
└── hooks/
|
||||
└── hooks.json # Validate before apply
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Library/SDK
|
||||
|
||||
Examples: Stripe, OpenAI, AWS SDK, Prisma
|
||||
|
||||
### Discovery Focus
|
||||
- API surface and key methods
|
||||
- Authentication patterns
|
||||
- Common integration scenarios
|
||||
- Error handling conventions
|
||||
|
||||
### Pattern Types
|
||||
- Request/response patterns
|
||||
- Error handling and retry logic
|
||||
- Configuration and initialization
|
||||
|
||||
### Primary Components
|
||||
- **Skills**: Integration patterns and best practices
|
||||
- **Commands**: Quick API calls
|
||||
|
||||
### Example Plugin Structure
|
||||
|
||||
```
|
||||
stripe-plugin/
|
||||
├── skills/
|
||||
│ ├── payment-flow/ # Checkout implementation
|
||||
│ ├── subscription-mgmt/ # Subscription lifecycle
|
||||
│ └── webhook-handling/ # Webhook verification
|
||||
├── commands/
|
||||
│ ├── test-webhook.md # Trigger test webhooks
|
||||
│ └── list-products.md # Quick product listing
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server
|
||||
|
||||
Examples: filesystem, database, memory, linear
|
||||
|
||||
### Discovery Focus
|
||||
- Tool manifest and capabilities
|
||||
- Common operation sequences
|
||||
- State management patterns
|
||||
- Error modes and recovery
|
||||
|
||||
### Pattern Types
|
||||
- Tool combinations (read → transform → write)
|
||||
- State management across calls
|
||||
- Coordination patterns
|
||||
|
||||
### Primary Components
|
||||
- **Skills**: Coordinated operations
|
||||
- **Hooks**: Automatic triggers based on state
|
||||
|
||||
### Example Plugin Structure
|
||||
|
||||
```
|
||||
database-mcp-plugin/
|
||||
├── skills/
|
||||
│ ├── migration-workflow/ # Schema migration process
|
||||
│ ├── backup-restore/ # Backup and recovery
|
||||
│ └── query-optimization/ # Performance tuning
|
||||
├── commands/
|
||||
│ ├── quick-backup.md # One-command backup
|
||||
│ └── schema-diff.md # Compare schemas
|
||||
└── hooks/
|
||||
└── hooks.json # Pre-migration validation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Tool
|
||||
|
||||
Examples: webpack, vite, esbuild, turbo
|
||||
|
||||
### Discovery Focus
|
||||
- Configuration options
|
||||
- Plugin/loader ecosystem
|
||||
- Build optimization patterns
|
||||
- Common troubleshooting
|
||||
|
||||
### Pattern Types
|
||||
- Configuration generation
|
||||
- Performance optimization sequences
|
||||
- Migration between tools
|
||||
|
||||
### Primary Components
|
||||
- **Skills**: Configuration and optimization
|
||||
- **Commands**: Quick actions (build, analyze)
|
||||
|
||||
---
|
||||
|
||||
## Testing Framework
|
||||
|
||||
Examples: jest, vitest, playwright, cypress
|
||||
|
||||
### Discovery Focus
|
||||
- Test patterns and best practices
|
||||
- Configuration options
|
||||
- Mocking and fixtures
|
||||
- CI integration
|
||||
|
||||
### Pattern Types
|
||||
- Test organization
|
||||
- Fixture management
|
||||
- Coverage optimization
|
||||
|
||||
### Primary Components
|
||||
- **Skills**: Testing methodology
|
||||
- **Hooks**: Pre-commit test runs
|
||||
|
||||
---
|
||||
|
||||
## Quick Mode Criteria
|
||||
|
||||
Use quick mode (skip Stages 3-4) when:
|
||||
|
||||
| Criterion | Quick Mode | Full Pipeline |
|
||||
|-----------|------------|---------------|
|
||||
| Commands | < 5 | 5+ |
|
||||
| Scope | Single purpose | Multi-purpose |
|
||||
| Patterns | Obvious | Needs discovery |
|
||||
| User request | "Just get it working" | "Comprehensive" |
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
# Stage 1: Discovery
|
||||
|
||||
External research before analyzing code.
|
||||
|
||||
**Goal**: Understand the tool from a user's perspective.
|
||||
|
||||
**Skill**: Load `outfitter:research`
|
||||
|
||||
## What to Gather
|
||||
|
||||
| Category | Sources | Questions |
|
||||
|----------|---------|-----------|
|
||||
| Official Docs | README, docs site, man pages | What's the intended workflow? |
|
||||
| API Reference | Function docs, CLI help | What's the public surface? |
|
||||
| Community | Tutorials, Stack Overflow, Discord | What do users struggle with? |
|
||||
| Integrations | Existing plugins, wrappers | What's already automated? |
|
||||
|
||||
## Research Patterns by Repo Type
|
||||
|
||||
**CLI Tool**:
|
||||
1. Start with `--help` output
|
||||
2. Find official docs or man pages
|
||||
3. Search GitHub issues for "workflow", "automation", "script"
|
||||
4. Look for shell scripts that wrap the tool
|
||||
|
||||
**Library/SDK**:
|
||||
1. API reference documentation
|
||||
2. Getting started guides
|
||||
3. Example repositories
|
||||
4. Community extensions
|
||||
|
||||
**MCP Server**:
|
||||
1. Protocol documentation
|
||||
2. Existing client implementations
|
||||
3. Tool manifest and capabilities
|
||||
4. Common integration patterns
|
||||
|
||||
## Red Flags
|
||||
|
||||
- No documentation → requires deep code analysis
|
||||
- Rapid version churn → watch for breaking changes
|
||||
- Abandoned project → consider maintenance burden
|
||||
|
||||
## Output
|
||||
|
||||
Create `artifacts/plugin-engineer/discovery.md`:
|
||||
|
||||
```markdown
|
||||
# Discovery: {REPO_NAME}
|
||||
|
||||
## Documentation
|
||||
- Official docs: {LINKS}
|
||||
- API reference: {LINKS}
|
||||
|
||||
## Community Patterns
|
||||
- {PATTERN}: {DESCRIPTION}
|
||||
|
||||
## Pain Points
|
||||
- {ISSUE}: {FREQUENCY}
|
||||
|
||||
## Existing Integrations
|
||||
- {NAME}: {PURPOSE}
|
||||
```
|
||||
|
||||
## Next Stage
|
||||
|
||||
Proceed to [Stage 2: Recon](stage-2-recon.md) when external research is complete.
|
||||
@@ -0,0 +1,59 @@
|
||||
# Stage 2: Recon
|
||||
|
||||
Codebase analysis to map internal structure.
|
||||
|
||||
**Goal**: Identify automation-worthy surfaces in the code.
|
||||
|
||||
**Skill**: Load `outfitter:codebase-recon`
|
||||
|
||||
## Analysis Checklist
|
||||
|
||||
**Structure**:
|
||||
- [ ] Identify entry points (main, CLI handlers, exports)
|
||||
- [ ] Map directory organization
|
||||
- [ ] Find configuration files and patterns
|
||||
- [ ] Locate test files (reveal intended usage)
|
||||
|
||||
**Public API**:
|
||||
- [ ] List exported functions/classes
|
||||
- [ ] Document CLI commands and subcommands
|
||||
- [ ] Note required vs optional parameters
|
||||
- [ ] Identify return types and error modes
|
||||
|
||||
**Conventions**:
|
||||
- [ ] Naming patterns (camelCase, snake_case)
|
||||
- [ ] Error handling approach
|
||||
- [ ] Configuration precedence (env, file, args)
|
||||
- [ ] Output formats (JSON, table, plain)
|
||||
|
||||
## Confidence Levels
|
||||
|
||||
| Level | Evidence | Action |
|
||||
|-------|----------|--------|
|
||||
| High | Tests + docs + clear structure | Proceed with confidence |
|
||||
| Medium | Tests OR docs, some structure | Note assumptions |
|
||||
| Low | Neither tests nor docs | Flag for user validation |
|
||||
|
||||
## Output
|
||||
|
||||
Create `artifacts/plugin-engineer/recon.md`:
|
||||
|
||||
```markdown
|
||||
# Recon: {REPO_NAME}
|
||||
|
||||
## Structure
|
||||
{KEY_DIRECTORIES}
|
||||
|
||||
## Public API
|
||||
- {COMMAND/FUNCTION}: {PURPOSE}
|
||||
|
||||
## Configuration
|
||||
- {CONFIG_FILE}: {OPTIONS}
|
||||
|
||||
## Conventions
|
||||
- {CONVENTION}: {EXAMPLE}
|
||||
```
|
||||
|
||||
## Next Stage
|
||||
|
||||
Proceed to [Stage 3: Patterns](stage-3-patterns.md) for full pipeline, or skip to [Stage 5: Authoring](stage-5-authoring.md) for quick mode.
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
# Stage 3: Patterns
|
||||
|
||||
Extract repeatable behaviors worth automating.
|
||||
|
||||
**Goal**: Identify patterns with automation value.
|
||||
|
||||
**Skill**: Load `outfitter:patterns`
|
||||
|
||||
## Pattern Categories
|
||||
|
||||
**Workflow Patterns**:
|
||||
Multi-step sequences users perform repeatedly.
|
||||
|
||||
```
|
||||
Example: Git release workflow
|
||||
1. Update version
|
||||
2. Generate changelog
|
||||
3. Create tag
|
||||
4. Push to remote
|
||||
5. Create GitHub release
|
||||
```
|
||||
|
||||
**Command Patterns**:
|
||||
Single actions with complex options.
|
||||
|
||||
```
|
||||
Example: Docker build with optimal caching
|
||||
docker build --cache-from=... --build-arg=... --tag=... .
|
||||
```
|
||||
|
||||
**Decision Patterns**:
|
||||
Conditional logic users apply manually.
|
||||
|
||||
```
|
||||
Example: Choose test runner based on project
|
||||
if package.json has "jest" → jest
|
||||
if package.json has "vitest" → vitest
|
||||
if bun.lockb exists → bun test
|
||||
else → error
|
||||
```
|
||||
|
||||
## Automation Value Assessment
|
||||
|
||||
| Signal | High Value | Low Value |
|
||||
|--------|------------|-----------|
|
||||
| Frequency | Daily/weekly | Monthly/rarely |
|
||||
| Complexity | 5+ steps or flags | 1-2 steps |
|
||||
| Error rate | Users often make mistakes | Straightforward |
|
||||
| Memorability | Hard to remember options | Obvious invocation |
|
||||
|
||||
## Evidence Threshold
|
||||
|
||||
Require 3+ instances before codifying:
|
||||
|
||||
- Documented in multiple tutorials
|
||||
- Appears in GitHub issues repeatedly
|
||||
- Found in multiple wrapper scripts
|
||||
- User explicitly mentions as pain point
|
||||
|
||||
## Output
|
||||
|
||||
Create `artifacts/plugin-engineer/patterns.md`:
|
||||
|
||||
```markdown
|
||||
# Patterns: {REPO_NAME}
|
||||
|
||||
## Workflows
|
||||
1. {WORKFLOW_NAME}
|
||||
- Steps: {STEP_LIST}
|
||||
- Frequency: {COMMON|OCCASIONAL|RARE}
|
||||
- Automation value: {HIGH|MEDIUM|LOW}
|
||||
|
||||
## Decision Points
|
||||
- {DECISION}: {OPTIONS}
|
||||
|
||||
## Boilerplate
|
||||
- {TEMPLATE}: {USE_CASE}
|
||||
```
|
||||
|
||||
## Next Stage
|
||||
|
||||
Proceed to [Stage 4: Mapping](stage-4-mapping.md) to select components.
|
||||
+79
@@ -0,0 +1,79 @@
|
||||
# Stage 4: Mapping
|
||||
|
||||
Choose the right component for each pattern.
|
||||
|
||||
**Goal**: Map patterns to Claude Code components.
|
||||
|
||||
**Skill**: Load `outfitter:codify`
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Is it a multi-step process with stages?
|
||||
├─ Yes → Does it need tool restrictions?
|
||||
│ ├─ Yes → Skill (with allowed-tools)
|
||||
│ └─ No → Skill
|
||||
└─ No → Is it a simple entry point?
|
||||
├─ Yes → Command (can load Skill)
|
||||
└─ No → Is it autonomous/long-running?
|
||||
├─ Yes → Agent
|
||||
└─ No → Is it reactive to events?
|
||||
├─ Yes → Hook
|
||||
└─ No → Probably doesn't need codifying
|
||||
```
|
||||
|
||||
## Component Comparison
|
||||
|
||||
| Aspect | Skill | Command | Hook | Agent |
|
||||
|--------|-------|---------|------|-------|
|
||||
| Invocation | Auto or `/skill` | `/command` | Event-triggered | Task tool |
|
||||
| Context | Inherit or fork | Main context | Script execution | Isolated |
|
||||
| Complexity | Medium-high | Low-medium | Low | High |
|
||||
| Use case | Methodology | Entry point | Automation | Orchestration |
|
||||
|
||||
## Common Combos
|
||||
|
||||
**Skill + Command**:
|
||||
Skill holds methodology, command provides entry point.
|
||||
|
||||
```
|
||||
commands/deploy.md → loads → skills/deployment/SKILL.md
|
||||
```
|
||||
|
||||
**Skill + Hook**:
|
||||
Skill defines process, hook triggers automatically.
|
||||
|
||||
```
|
||||
hooks/on-commit → loads → skills/commit-checks/SKILL.md
|
||||
```
|
||||
|
||||
**Agent + Skills**:
|
||||
Agent orchestrates, skills provide methodology.
|
||||
|
||||
```
|
||||
agents/developer.md → loads → skills/tdd/SKILL.md
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Create `artifacts/plugin-engineer/mapping.md`:
|
||||
|
||||
```markdown
|
||||
# Component Mapping: {REPO_NAME}
|
||||
|
||||
## Skills
|
||||
- {SKILL_NAME}: {PATTERN} → {RATIONALE}
|
||||
|
||||
## Commands
|
||||
- {COMMAND_NAME}: {PURPOSE}
|
||||
|
||||
## Hooks
|
||||
- {HOOK_TYPE}: {TRIGGER} → {ACTION}
|
||||
|
||||
## Agents
|
||||
- {AGENT_NAME}: {ORCHESTRATION_SCOPE}
|
||||
```
|
||||
|
||||
## Next Stage
|
||||
|
||||
Proceed to [Stage 5: Authoring](stage-5-authoring.md) to create components.
|
||||
+112
@@ -0,0 +1,112 @@
|
||||
# Stage 5: Authoring
|
||||
|
||||
Create high-quality components.
|
||||
|
||||
**Goal**: Build skills, commands, hooks, and agents.
|
||||
|
||||
**Skills**: Load per component type (see below).
|
||||
|
||||
## Skill Authoring
|
||||
|
||||
Load `outfitter:skills-dev` for base patterns, `outfitter:claude-skills` for Claude-specific features.
|
||||
|
||||
**Frontmatter Template**:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: tool-name-action
|
||||
description: Does X when Y. Use when "trigger phrase", "another trigger".
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
source-repo: owner/repo
|
||||
allowed-tools: Read Grep Glob Bash(tool-name *)
|
||||
---
|
||||
```
|
||||
|
||||
**Body Structure**:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
Brief purpose statement.
|
||||
|
||||
## Steps
|
||||
|
||||
1. First action
|
||||
2. If condition, do X
|
||||
3. Final action
|
||||
|
||||
<when_to_use>
|
||||
Trigger conditions
|
||||
</when_to_use>
|
||||
|
||||
<workflow>
|
||||
Detailed process
|
||||
</workflow>
|
||||
|
||||
<rules>
|
||||
ALWAYS/NEVER constraints
|
||||
</rules>
|
||||
```
|
||||
|
||||
## Command Authoring
|
||||
|
||||
Load `outfitter:claude-commands`.
|
||||
|
||||
**Simple Command**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Run tool-name with common options
|
||||
argument-hint: [target]
|
||||
---
|
||||
|
||||
Run tool-name on $ARGUMENTS with sensible defaults.
|
||||
```
|
||||
|
||||
**Command Loading Skill**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy using deployment workflow
|
||||
---
|
||||
|
||||
Load the deployment skill and apply to current project.
|
||||
```
|
||||
|
||||
## Hook Authoring
|
||||
|
||||
Load `outfitter:claude-hooks`.
|
||||
|
||||
**Common Triggers**:
|
||||
|
||||
| Hook Type | Use Case |
|
||||
|-----------|----------|
|
||||
| PreToolUse | Validate before file changes |
|
||||
| PostToolUse | Run after successful operations |
|
||||
| Stop | Cleanup on session end |
|
||||
|
||||
## Agent Authoring
|
||||
|
||||
Load `outfitter:claude-agents`.
|
||||
|
||||
Only create agents for complex orchestration. Most plugins don't need custom agents.
|
||||
|
||||
## Output
|
||||
|
||||
Create components in `artifacts/plugin-engineer/components/`:
|
||||
|
||||
```
|
||||
components/
|
||||
├── skills/
|
||||
│ └── my-skill/
|
||||
│ └── SKILL.md
|
||||
├── commands/
|
||||
│ └── my-command.md
|
||||
└── hooks/
|
||||
└── hooks.json
|
||||
```
|
||||
|
||||
## Next Stage
|
||||
|
||||
Proceed to [Stage 6: Packaging](stage-6-packaging.md) when components are ready.
|
||||
+181
@@ -0,0 +1,181 @@
|
||||
# Stage 6: Packaging
|
||||
|
||||
Create distributable plugin structure.
|
||||
|
||||
**Goal**: Package components into a valid plugin.
|
||||
|
||||
**Skill**: Load `outfitter:claude-plugins`
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### Standalone Plugin (External Repo)
|
||||
|
||||
For plugins in their own repo that will be referenced by marketplaces, place `.claude-plugin/` at the **repo root**:
|
||||
|
||||
```
|
||||
my-plugin/ # Repo root
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # At repo root — required for external reference
|
||||
├── README.md
|
||||
├── commands/
|
||||
│ └── main-command.md
|
||||
├── skills/
|
||||
│ ├── primary-skill/
|
||||
│ │ └── SKILL.md
|
||||
│ └── secondary-skill/
|
||||
│ ├── SKILL.md
|
||||
│ └── references/
|
||||
└── hooks/
|
||||
└── hooks.json
|
||||
```
|
||||
|
||||
When a marketplace references this via `{"source": {"source": "github", "repo": "owner/my-plugin"}}`, Claude Code looks for `.claude-plugin/plugin.json` at the repo root.
|
||||
|
||||
### Plugin in a Marketplace (Consolidated)
|
||||
|
||||
When adding to a marketplace with `strict: false`, skip `.claude-plugin/`:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── README.md
|
||||
├── commands/
|
||||
│ └── main-command.md
|
||||
├── skills/
|
||||
│ └── primary-skill/
|
||||
│ └── SKILL.md
|
||||
└── hooks/
|
||||
└── hooks.json
|
||||
```
|
||||
|
||||
Metadata goes in the marketplace's `marketplace.json` instead.
|
||||
|
||||
### Plugin in a Monorepo
|
||||
|
||||
When the plugin lives alongside application code, place it in a conventional location:
|
||||
|
||||
```
|
||||
my-project/ # Monorepo root
|
||||
├── packages/
|
||||
│ └── claude-plugin/ # Plugin subdirectory
|
||||
│ ├── .claude-plugin/
|
||||
│ │ └── plugin.json # Required — plugin owns its manifest
|
||||
│ ├── README.md
|
||||
│ ├── commands/
|
||||
│ └── skills/
|
||||
├── src/ # Application code
|
||||
└── package.json
|
||||
```
|
||||
|
||||
Marketplaces reference this with the `path` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "owner/my-project",
|
||||
"path": "./packages/claude-plugin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Common monorepo locations: `packages/claude-plugin/`, `tools/claude-plugin/`, `.claude/plugin/`
|
||||
|
||||
## plugin.json (Standalone Only)
|
||||
|
||||
Only needed for standalone plugins or those distributed outside a marketplace:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "Brief description of plugin purpose",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
},
|
||||
"license": "MIT"
|
||||
}
|
||||
```
|
||||
|
||||
## README Template
|
||||
|
||||
```markdown
|
||||
# Plugin Name
|
||||
|
||||
Brief description.
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
/plugin marketplace add owner/repo
|
||||
/plugin install plugin-name@owner
|
||||
\`\`\`
|
||||
|
||||
## Commands
|
||||
|
||||
- `/command-name` — what it does
|
||||
|
||||
## Skills
|
||||
|
||||
- `plugin:skill-name` — when to use
|
||||
|
||||
## Requirements
|
||||
|
||||
- List prerequisites
|
||||
```
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Move components from `artifacts/plugin-engineer/components/` to plugin directory
|
||||
- [ ] If standalone: Create `.claude-plugin/plugin.json`
|
||||
- [ ] If marketplace: Add entry to `marketplace.json` (skip plugin.json with `strict: false`)
|
||||
- [ ] Write README.md with installation instructions
|
||||
- [ ] Add LICENSE file
|
||||
- [ ] Verify all paths and references
|
||||
- [ ] Ask about marketplace integration (see below)
|
||||
|
||||
## Marketplace Integration
|
||||
|
||||
Ask: "Do you have an existing marketplace to add this plugin to?"
|
||||
|
||||
**If yes:**
|
||||
|
||||
1. Ask: "Do you have the marketplace repo cloned locally?"
|
||||
|
||||
2. **If local**: Get the path and update `marketplace.json` directly:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "new-plugin",
|
||||
"source": "./new-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
Or if the plugin lives in a separate repo:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "new-plugin",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "owner/new-plugin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **If remote only**: Provide the entry template for manual addition
|
||||
|
||||
**Avoid version pinning** — Omit `ref` and `sha` unless specifically requested. Pinned versions get stale quickly and require marketplace updates for every plugin release. Let the marketplace pull from default branch.
|
||||
|
||||
Only pin when:
|
||||
- Plugin has breaking changes between versions
|
||||
- Stability is critical (enterprise/production)
|
||||
- User explicitly requests it
|
||||
|
||||
**If no marketplace:**
|
||||
|
||||
- Plugin can be distributed standalone via GitHub
|
||||
- User can add to a marketplace later with the entry template above
|
||||
|
||||
## Next Stage
|
||||
|
||||
Proceed to [Stage 7: Audit](stage-7-audit.md) for validation.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Stage 7: Audit
|
||||
|
||||
Validate plugin before distribution.
|
||||
|
||||
**Goal**: Ensure plugin quality and completeness.
|
||||
|
||||
**Skill**: Delegate by loading `outfitter:claude-plugin-audit`
|
||||
|
||||
## Audit Checklist
|
||||
|
||||
**Structure**:
|
||||
- [ ] plugin.json exists and valid
|
||||
- [ ] Name matches directory
|
||||
- [ ] Version is semver
|
||||
|
||||
**Components**:
|
||||
- [ ] All skills have SKILL.md
|
||||
- [ ] All commands have descriptions
|
||||
- [ ] Hook scripts are executable
|
||||
- [ ] No broken references
|
||||
|
||||
**Documentation**:
|
||||
- [ ] README.md present
|
||||
- [ ] Installation instructions work
|
||||
- [ ] Usage examples accurate
|
||||
|
||||
## Severity Levels
|
||||
|
||||
| Level | Indicator | Meaning |
|
||||
|-------|-----------|---------|
|
||||
| Critical | `◆◆` | Blocks functionality, must fix |
|
||||
| Warning | `◆` | Best practice violation, should fix |
|
||||
| Info | `◇` | Suggestion, optional |
|
||||
|
||||
## Output
|
||||
|
||||
Create `artifacts/plugin-engineer/audit.md` with findings.
|
||||
|
||||
## Completion
|
||||
|
||||
When audit passes:
|
||||
|
||||
1. Plugin is ready for distribution
|
||||
2. Commit to version control
|
||||
3. Tag release with semver
|
||||
4. Push to marketplace or share repo
|
||||
|
||||
## Distribution Options
|
||||
|
||||
| Method | Best For | Setup |
|
||||
|--------|----------|-------|
|
||||
| GitHub repo | Public/team plugins | Push to GitHub |
|
||||
| Git URL | GitLab, Bitbucket | Full URL in source |
|
||||
| Local path | Development/testing | Relative path |
|
||||
Reference in New Issue
Block a user