plugin-packaging

Purpose: Create professional PKG installers for sharing plugins with others.

Overview

Generates macOS PKG installers with branded UI, automated plugin installation, and Gatekeeper bypass instructions.

Workflow

<critical_sequence enforcement="strict" blocking="true">

Track your progress:

Plugin Packaging Progress:
- [ ] 1. Prerequisites verified (plugin installed, binaries exist)
- [ ] 2. Metadata extracted (contracts read, version/description/parameters)
- [ ] 3. Branding files created (Welcome, ReadMe, Conclusion)
- [ ] 4. Base package built (pkgbuild complete)
- [ ] 5. Branded installer created (productbuild complete)
- [ ] 6. Distribution package output (dist/ created, committed, PLUGINS.md updated)

---

1. Verify Prerequisites

Check plugin is ready for packaging:

• Read PLUGINS.md, verify status is 📦 Installed
• Verify VST3 exists: ~/Library/Audio/Plug-Ins/VST3/[ProductName].vst3
• Verify AU exists: ~/Library/Audio/Plug-Ins/Components/[ProductName].component

Blocking: If not installed, guide user to run /install-plugin [PluginName] first.

Preconditions verified in this step:

• Plugin status is 📦 Installed
• VST3 and AU binaries exist in system folders

2. Extract Plugin Metadata

Read multiple files in parallel using multiple Read tool calls:

• PLUGINS.md entry for plugin (version, description, parameter list, use cases)
• plugins/[PluginName]/CMakeLists.txt (for PRODUCT_NAME extraction)
• plugins/[PluginName]/.ideas/parameter-spec.md (detailed parameter descriptions)
• plugins/[PluginName]/.ideas/creative-brief.md (features, use cases, design rationale)

Extract PRODUCT_NAME using grep + sed (see Section 1.2 in references/pkg-creation.md).

Template variables to extract:

• {{PLUGIN_NAME}}, {{VERSION}}, {{DESCRIPTION}}
• {{PRODUCT_NAME}}, {{PARAM_COUNT}}, {{PARAMETERS}}
• {{FEATURES}}, {{QUICK_START_PRESETS}}

3. Create Branding Files

Generate Welcome.txt, ReadMe.txt, and Conclusion.txt by reading templates from assets/ and replacing {{VARIABLE}} placeholders with metadata from contracts (.ideas/parameter-spec.md and creative-brief.md provide richer content than PLUGINS.md).

See Section 3 in references/pkg-creation.md for complete bash implementation.

4. Build Base Package

Create foundational PKG with installation logic:

4a. Create temp directory structure (see Section 4a in references/pkg-creation.md)

4b. Copy binaries to payload (see Section 4a in references/pkg-creation.md)

Validation: Verify binaries copied successfully. ONLY proceed to 4c when both files are present.

4c. Create postinstall script (see Section 4b in references/pkg-creation.md for complete script)

4d. Run pkgbuild (see Section 4c in references/pkg-creation.md for complete command)

Validation: Verify base PKG created. ONLY proceed to step 5 when PKG file exists.

5. Build Branded Installer

Wrap base package with branding:

5a. Create Distribution.xml (see Section 5a in references/pkg-creation.md for complete XML structure)

5b. Run productbuild (see Section 5b in references/pkg-creation.md for complete command)

Validation: Verify branded PKG created. ONLY proceed to step 6 when branded PKG exists.

6. Output Distribution Package

Finalize and present to user:

6a. Create dist directory (see Section 6a in references/pkg-creation.md)

6b. Copy installer (see Section 6b in references/pkg-creation.md)

6c. Generate install-readme.txt (see Section 6c in references/pkg-creation.md for complete template)

6d. Commit distribution package:

git add plugins/[PluginName]/dist/
git commit -m "feat([PluginName]): create v[X.Y.Z] distribution package"

6e. Update PLUGINS.md with packaging metadata:

**Last Packaged:** YYYY-MM-DD
**Distribution:** plugins/[PluginName]/dist/[PluginName]-by-TACHES.pkg (X.X MB)

6f. Display summary:

✓ [PluginName] packaged successfully

Created: plugins/[PluginName]/dist/[PluginName]-by-TACHES.pkg (X.X MB)

Distribution package includes:
- [PluginName]-by-TACHES.pkg (branded installer)
- install-readme.txt (installation guide)

Send both files to your friend.

</critical_sequence>

---

Integration Points

Invoked by:

• /package [PluginName] command
• Natural language: "Create installer for TapeAge", "Package GainKnob"

Invokes:

• None (terminal skill - does not invoke other skills)

Reads:

• PLUGINS.md → Plugin metadata
• plugins/[PluginName]/CMakeLists.txt → PRODUCT_NAME extraction
• ~/Library/Audio/Plug-Ins/VST3/[Product].vst3 → Source binary
• ~/Library/Audio/Plug-Ins/Components/[Product].component → Source binary

Creates:

• plugins/[PluginName]/dist/[PluginName]-by-TACHES.pkg → Branded installer
• plugins/[PluginName]/dist/install-readme.txt → Installation guide

Updates:

• PLUGINS.md → Add Last Packaged: timestamp and Distribution: package path/size
• Git repository → Commit dist/ folder with distribution package

---

Decision Menu

<decision_gate type="checkpoint" enforcement="strict">

After successful packaging, present this menu and WAIT for user response:

✓ [PluginName] packaged successfully

Created: plugins/[PluginName]/dist/[PluginName]-by-TACHES.pkg (X.X MB)

What's next?
1. Test installer (recommended) → Verify PKG works correctly
2. Package another plugin → /package [OtherPlugin]
3. View installation guide → Show install-readme.txt contents
4. Share distribution files → Instructions for sending to friend
5. Other

Choose (1-5): _

Option handlers:

1. Test installer → Provide testing checklist (see Testing Checklist in references/pkg-creation.md Section 6)
2. Package another → Prompt for plugin name, re-invoke skill
3. View guide → Display install-readme.txt with cat command
4. Share instructions → Explain what files to send, how to compress if needed
5. Other → Open-ended response

</decision_gate>

---

Error Handling

For error scenarios and troubleshooting, see references/pkg-creation.md Section 6 (Error Scenarios).

---

Success Criteria

Packaging succeeds when:

• ✅ Base PKG created with postinstall script
• ✅ Branded PKG created with Welcome/ReadMe/Conclusion screens
• ✅ Installer file copied to plugins/[PluginName]/dist/
• ✅ Installation guide generated
• ✅ File sizes reported (PKG should be 3-5 MB typically)
• ✅ User knows what files to share

NOT required for success:

• Actually testing installer (recommended but not blocking)
• Signing/notarization (future enhancement)
• Multi-format packages (DMG, ZIP - future modes)

---

Notes for Claude

When executing this skill:

1. Extract PRODUCT_NAME carefully (may contain spaces, use quotes)
2. Populate branding templates with actual plugin metadata (not placeholders)
3. Postinstall script must handle user detection (can't assume /Users/[name])
4. Clean up temp files after success (rm -rf /tmp/[PluginName]-installer)
5. Report file size to user (helpful for sharing over email/Dropbox)

Branding consistency:

• Always use "TÂCHES" in title, welcome, conclusion
• Format: "[PluginName] by TÂCHES"
• Include Gatekeeper steps in ReadMe (critical for unsigned plugins)