Scaffolding Bundle-Plugins

Overview

Generate new bundle-plugin projects and manage platform support across their lifecycle. Handles initial project generation (greenfield) and ongoing platform adaptation (add, fix, migrate, remove).

Core principle: Generate only what's needed. Every platform, every file has a reason to exist. This skill generates structure only — it does not run its own scripts. Validation is delegated to bundles-forge:auditing; version checks to bundles-forge bump-version.

Skill type: Hybrid — follow the generation/adaptation process rigidly, but mode selection and component choices are flexible based on user context.

Announce at start: "I'm using the scaffolding skill to [generate your project / add <platform> support / remove <platform> support / add <component> / remove <component>]."

Entry Detection

Determine the operation based on context:

1. Design document provided (from bundles-forge:blueprinting) → New Project flow
2. User request + no existing project → New Project flow
3. User request + existing project → Platform Adaptation flow (add / fix / migrate / remove)

New Project: Scaffold Layers

For new projects, first select a mode:

• Design document specifies the mode (minimal or intelligent)
• Direct invocation — choose between:
  • intelligent — recommend architecture based on user description, avoid unnecessary components
  • custom — present the full architecture option set, ask the user about each component

Minimal Mode (quick packaging)

Lean plugin for marketplace distribution:

No hooks, no bootstrap, no version infrastructure. Add these later by re-running scaffolding in platform adaptation mode.

Intelligent Mode

Core

Generated for all intelligent-mode projects regardless of platform selection:

Platform Adapters (selected platforms only)

For platform-specific wiring details, read references/platform-adapters.md.

Bootstrap (if requested)

Optional Components (only if specified)

New Project: Generation Process

Minimal mode:

1. Create plugin manifest from assets/platforms/claude-code/plugin.json template
2. Generate skill directories — one per skill
3. Generate README + LICENSE
4. git init + initial commit; validate manifest JSON

Intelligent mode:

Phase 1 — Load context:

1. Read template index — load references/scaffold-templates.md
2. Read templates — load from assets/ (infrastructure, docs, bootstrap)
3. Read platform templates — load from assets/platforms/<platform>/
4. Read anatomy — load references/project-anatomy.md

Phase 2 — Generate: 5. Replace placeholders — substitute <project-name>, <author-name>, etc. 6. Generate per-platform — only create files for target platforms 7. Generate skill stubs — one directory per skill 8. Generate bootstrap — if requested, create meta-skill with routing table 10. Generate optional components — only what the design specifies. For MCP servers, use assets/mcp-json.md template and consult references/external-integration.md for transport selection and platform differences. When userConfig is specified, add the userConfig field to plugin.json with appropriate sensitive flags. When marketplace distribution is specified, generate .claude-plugin/marketplace.json with plugin metadata. When CI validation is specified, generate .github/workflows/validate-plugin.yml from template

Phase 3 — Finalize: 11. git init + initial commit; run bundles-forge bump-version --check

Platform Adaptation: Existing Projects

Adding a Platform

1. Detect current platforms — scan for existing manifests (see detection table in references/platform-adapters.md)
2. Identify target — read references/platform-adapters.md for wiring details
3. Generate adapter files — from assets/platforms/<platform>/, replace <project-name> placeholders
4. Update version sync — add version-bearing manifests to .version-bump.json
5. Update hooks — if platform uses session hooks, ensure session-start (Bash) handles its JSON format via run-hook.cmd. For custom hooks beyond SessionStart, read references/hooks-configuration.md
6. Update documentation — add install section to README; create platform-specific docs if needed
7. Verify — validate manifests, bundles-forge bump-version --check, test hooks

Removing a Platform

1. Delete manifest files — remove the platform's manifest directory or file
2. Update .version-bump.json — remove entries for deleted manifests
3. Clean hooks — delete platform-specific hook files; simplify session-start if branches removed
4. Update documentation — remove install section from README and platform-specific docs
5. Verify — bundles-forge bump-version --check; run inspector validation

Adding Optional Components

Add MCP servers, CLI executables, LSP servers, userConfig, output styles, or default settings to an existing project:

1. Determine component type — read references/external-integration.md decision tree to choose the right integration level
2. Generate component files — create the corresponding file(s) at their default location (.mcp.json, .lsp.json, output-styles/, settings.json, or userConfig in plugin.json)
3. Update plugin manifests — add component declarations to plugin.json for platforms that require explicit paths (Cursor). For Claude Code, convention-based discovery handles most components automatically
4. Update skill references — add allowed-tools frontmatter for new CL