Initial commit

skills/build-assistant/templates/plugins/PLUGIN-JSON-GUIDE.md

@@ -0,0 +1,167 @@
+# Plugin.json Configuration Guide
+
+## Critical Rule: Auto-Discovery vs Custom Paths
+
+**Auto-Discovered (DO NOT list in plugin.json):**
+- `commands/` directory → All `.md` files auto-discovered
+- `agents/` directory → All `.md` files auto-discovered
+- `skills/` directory → All `SKILL.md` files auto-discovered
+
+**Only List in plugin.json IF using custom/non-standard locations**
+
+---
+
+## Example 1: Standard Structure (Most Common)
+
+**Directory structure:**
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── deploy.md
+│   └── validate.md
+├── agents/
+│   ├── orchestrator.md
+│   └── validator.md
+└── skills/
+    └── deployment-skill/
+        └── SKILL.md
+```
+
+**plugin.json (NO commands/agents/skills fields):**
+```json
+{
+  "name": "my-plugin"
+  "version": "1.0.0"
+  "description": "Deployment automation"
+  "author": {
+    "name": "Dev Team"
+    "email": "dev@example.com"
+  }
+  "license": "MIT"
+  "keywords": ["deployment"]
+}
+```
+
+**Why:** Everything is in default directories - auto-discovered automatically.
+
+---
+
+## Example 2: Custom Locations (Rare)
+
+**Directory structure:**
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/              ← Auto-discovered (default)
+│   └── deploy.md
+├── specialized/           ← Custom location
+│   └── advanced-deploy.md
+└── custom-agents/         ← Custom location
+    └── reviewer.md
+```
+
+**plugin.json (List ONLY custom paths):**
+```json
+{
+  "name": "my-plugin"
+  "version": "1.0.0"
+  "description": "Deployment automation"
+  "author": {
+    "name": "Dev Team"
+    "email": "dev@example.com"
+  }
+  "license": "MIT"
+  "keywords": ["deployment"]
+  "commands": ["./specialized/advanced-deploy.md"]
+  "agents": ["./custom-agents/reviewer.md"]
+}
+```
+
+**Result:**
+- `commands/deploy.md` loaded (auto-discovered)
+- `specialized/advanced-deploy.md` loaded (from plugin.json)
+- `custom-agents/reviewer.md` loaded (from plugin.json)
+
+---
+
+## ❌ WRONG: Duplication Error
+
+**Directory structure:**
+```
+my-plugin/
+├── commands/
+│   └── deploy.md
+└── agents/
+    └── orchestrator.md
+```
+
+**plugin.json (CAUSES DUPLICATION):**
+```json
+{
+  "name": "my-plugin"
+  "commands": ["./commands/deploy.md"],     ❌ WRONG
+  "agents": ["./agents/orchestrator.md"]    ❌ WRONG
+}
+```
+
+**Why wrong:**
+- `deploy.md` loaded from auto-discovery
+- `deploy.md` loaded AGAIN from plugin.json listing
+- **Result: Command appears TWICE**
+
+---
+
+## Template Default
+
+Our `plugin.json.template` defaults to:
+```json
+{
+  "name": "{{PLUGIN_NAME}}"
+  "version": "{{VERSION}}"
+  "description": "{{DESCRIPTION}}"
+  "author": {
+    "name": "{{AUTHOR_NAME}}"
+    "email": "{{AUTHOR_EMAIL}}"
+  }
+  "homepage": "{{HOMEPAGE_URL}}"
+  "repository": "{{REPOSITORY_URL}}"
+  "license": "{{LICENSE}}"
+  "keywords": {{KEYWORDS}}
+}
+```
+
+**No `commands`, `agents`, or `skills` fields** - assumes standard structure.
+
+---
+
+## When Building Plugins
+
+**For /build-lifecycle-plugin:**
+1. Creates standard structure (commands/, agents/, skills/)
+2. Generates plugin.json WITHOUT component fields
+3. Everything auto-discovered
+4. No duplication issues
+
+**Only add component fields manually if:**
+- You have scripts in non-standard locations
+- You're organizing differently for a specific reason
+- You understand the supplemental (not replacement) behavior
+
+---
+
+## Quick Reference
+
+| Scenario | Include in plugin.json? |
+|:---------|:------------------------|
+| Component in `commands/` | ❌ No (auto-discovered) |
+| Component in `agents/` | ❌ No (auto-discovered) |
+| Component in `skills/` | ❌ No (auto-discovered) |
+| Component in `custom-dir/` | ✅ Yes (must specify path) |
+| Both default AND custom | ✅ List only custom paths |
+
+---
+
+**Rule of thumb:** If you're using standard directories, leave `commands`, `agents`, `skills` out of plugin.json entirely.