📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,201 @@
+---
+name: plugin-engineer
+description: Transforms external repositories (CLIs, libraries, MCP servers) into Claude Code plugins with skills. Use when "build plugin for", "create skills for CLI", "package as plugin", "repo to plugin", or "turn into plugin" are mentioned.
+metadata:
+  version: "1.0.0"
+  related-skills:
+    - research
+    - codebase-recon
+    - patterns
+    - codify
+    - skills-dev
+    - claude-skills
+    - claude-plugins
+    - claude-plugin-audit
+allowed-tools: Read Write Edit Grep Glob Bash TaskCreate TaskUpdate TaskList TaskGet AskUserQuestion Skill
+---
+
+# Plugin Engineer
+
+Transform external repositories into Claude Code plugins.
+
+```text
+External Repo → Research → Recon → Patterns → Codify → Author → Package → Audit → Plugin
+```
+
+## Steps
+
+1. Clarify target repo and plugin goals
+2. Load the `outfitter:research` skill for external discovery (docs, APIs, community patterns)
+3. Load the `outfitter:codebase-recon` skill for internal analysis of target repo
+4. Load the `outfitter:patterns` skill to extract repeatable patterns worth automating
+5. Load the `outfitter:codify` skill to map patterns to component types
+6. Author components using `outfitter:skills-dev` or `outfitter:claude-skills`
+7. Load the `outfitter:claude-plugins` skill to package into distributable plugin
+8. Delegate by loading the `outfitter:claude-plugin-audit` skill for validation
+
+<when_to_use>
+
+- Turning a CLI tool into a Claude Code plugin
+- Creating skills that wrap an external library or API
+- Building plugin companions for MCP servers
+- Extracting automation opportunities from a third-party repo
+- Packaging workflow patterns around external tools
+
+NOT for: plugins from scratch (use `claude-plugins`), single-skill creation (use `skills-dev`), existing Claude Code plugins (use `claude-plugin-audit`)
+
+</when_to_use>
+
+## Artifact Structure
+
+Track progress with artifacts in `artifacts/plugin-engineer/`:
+
+```text
+artifacts/plugin-engineer/
+├── discovery.md      # Research output (docs, APIs, community patterns)
+├── recon.md          # Codebase analysis (structure, conventions, key files)
+├── patterns.md       # Extracted patterns with automation value
+├── mapping.md        # Pattern → component mapping decisions
+├── components/       # Authored skills, agents, hooks, commands
+│   ├── skill-1/
+│   ├── skill-2/
+│   └── ...
+└── audit.md          # Plugin validation results
+```
+
+## Quick Mode
+
+For simple repos (single-purpose CLI, small API wrapper):
+
+1. Skip stages 3-4 — go direct from recon to authoring
+2. Create 1-2 skills covering primary use cases
+3. Package immediately
+
+Trigger: User says "quick", repo has < 5 main commands, or clear single purpose.
+
+## Stages
+
+Load the **maintain-tasks** skill for stage tracking. Stages advance only.
+
+| Stage | Skill | activeForm |
+|-------|-------|------------|
+| 1. Discovery | `outfitter:research` | "Researching external docs" |
+| 2. Recon | `outfitter:codebase-recon` | "Analyzing target repo" |
+| 3. Patterns | `outfitter:patterns` | "Extracting patterns" |
+| 4. Mapping | `outfitter:codify` | "Mapping to components" |
+| 5. Authoring | `outfitter:skills-dev` | "Creating components" |
+| 6. Packaging | `outfitter:claude-plugins` | "Packaging plugin" |
+| 7. Audit | `outfitter:claude-plugin-audit` | "Validating plugin" |
+
+<workflow>
+
+### Stage 1: Discovery
+
+Load `outfitter:research` skill. Gather external docs, community patterns, pain points.
+
+See [stage-1-discovery.md](references/stage-1-discovery.md) for details.
+
+### Stage 2: Recon
+
+Load `outfitter:codebase-recon` skill. Analyze structure, API surface, conventions.
+
+See [stage-2-recon.md](references/stage-2-recon.md) for details.
+
+### Stage 3: Patterns
+
+Load `outfitter:patterns` skill. Extract workflows, command sequences, decision points.
+
+See [stage-3-patterns.md](references/stage-3-patterns.md) for details.
+
+### Stage 4: Mapping
+
+Load `outfitter:codify` skill. Map patterns to component types (skill, command, hook, agent).
+
+See [stage-4-mapping.md](references/stage-4-mapping.md) for details.
+
+### Stage 5: Authoring
+
+Load appropriate skill per component type. Create in `artifacts/plugin-engineer/components/`.
+
+See [stage-5-authoring.md](references/stage-5-authoring.md) for details.
+
+### Stage 6: Packaging
+
+Load `outfitter:claude-plugins` skill. Create plugin structure with manifest and README.
+
+Ask: "Do you have an existing marketplace to add this plugin to?" If yes, prepare the marketplace entry.
+
+See [stage-6-packaging.md](references/stage-6-packaging.md) for details.
+
+### Stage 7: Audit
+
+Delegate by loading `outfitter:claude-plugin-audit` skill. Validate before distribution.
+
+See [stage-7-audit.md](references/stage-7-audit.md) for details.
+
+</workflow>
+
+<decision_points>
+
+Key decisions during engineering process:
+
+**Which patterns to automate?**
+- High frequency + medium complexity = best ROI
+- Low frequency + high complexity = consider if audience is technical
+- One-off patterns = skip
+
+**Skills vs Commands?**
+- Multi-step, needs guidance → Skill
+- Quick action, obvious usage → Command
+- User entry point to skill → Both (command loads skill)
+
+**Include agents?**
+- Only for complex repos with orchestration needs
+- Most plugins don't need custom agents
+- Consider if existing agents (analyst, engineer) suffice
+
+**Quick mode vs full pipeline?**
+- Single-purpose tool → Quick mode
+- Complex tool with many features → Full pipeline
+- Unclear → Start with recon, decide after
+
+</decision_points>
+
+<rules>
+
+ALWAYS:
+- Start with discovery before touching code
+- Track artifacts at each stage
+- Validate patterns have 3+ use cases before creating components
+- Use existing skills for authoring (don't reinvent)
+- Run audit before declaring complete
+
+NEVER:
+- Skip recon stage (even for familiar repos)
+- Create agents without clear orchestration need
+- Package without audit validation
+- Over-engineer (simpler plugin > feature-complete plugin)
+
+</rules>
+
+<references>
+
+Stage guides:
+- [overview.md](references/overview.md) — quick reference
+- [stage-1-discovery.md](references/stage-1-discovery.md) — external research
+- [stage-2-recon.md](references/stage-2-recon.md) — codebase analysis
+- [stage-3-patterns.md](references/stage-3-patterns.md) — pattern extraction
+- [stage-4-mapping.md](references/stage-4-mapping.md) — component selection
+- [stage-5-authoring.md](references/stage-5-authoring.md) — creating components
+- [stage-6-packaging.md](references/stage-6-packaging.md) — plugin structure
+- [stage-7-audit.md](references/stage-7-audit.md) — validation
+- [repo-types.md](references/repo-types.md) — CLI vs Library vs MCP patterns
+
+Skills loaded:
+- `outfitter:research` — external discovery methodology
+- `outfitter:codebase-recon` — repo analysis approach
+- `outfitter:patterns` — pattern extraction
+- `outfitter:codify` — pattern-to-component mapping
+- `outfitter:claude-plugins` — plugin packaging
+
+</references>
@@ -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" |
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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 |