scaffolding

# 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:

| File | Purpose |
|------|---------|
| `.claude-plugin/plugin.json` | Plugin identity and metadata |
| `skills/<skill-name>/SKILL.md` | One directory per skill |
| `README.md` | Installation instructions and skill catalog |
| `LICENSE` | Default MIT unless specified |

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:

| File | Purpose |
|------|---------|
| `package.json` | Project identity and version |
| `README.md` | Installation per platform, skill catalog |
| `LICENSE` | Default MIT unless specified |
| `.gitignore` | node_modules, .worktrees, OS files |
| `.version-bump.json` | Version sync manifest |
| `skills/<skill-name>/SKILL.md` | One directory per skill |

#### Platform Adapters (selected platforms only)

| Platform | Files |
|----------|-------|
| Claude Code | `.claude-plugin/plugin.json`, `hooks/hooks.json`, `hooks/run-hook.cmd`, `hooks/session-start` |
| Cursor | `.cursor-plugin/plugin.json`, `hooks/hooks-cursor.json`, `hooks/session-start` |
| Codex | `.codex/INSTALL.md`, `AGENTS.md` |
| OpenCode | `.opencode/plugins/<name>.js`, `.opencode/INSTALL.md` |
| Gemini CLI | `gemini-extension.json`, `GEMINI.md` |

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

#### Bootstrap (if requested)

| File | Purpose |
|------|---------|
| `skills/using-<project>/SKILL.md` | Meta-skill: instruction priority, skill routing table |
| `skills/using-<project>/references/` | Per-platform tool mappings |

#### Optional Components (only if specified)

| Component | Files | When to Include |
|-----------|-------|-----------------|
| Executables | `bin/<tool-name>` | Skills reference CLI tools (see `references/external-integration.md` decision tree) |
| MCP servers | `.mcp.json` | Skills need external service integration (see `references/external-integration.md` decision tree) |
| LSP servers | `.lsp.json` | Skills involve language-specific code intelligence (see `references/external-integration.md` LSP section) |
| Output styles | `output-styles/<style>.md` | Custom output formatting (see `references/external-integration.md` Output Styles section) |
| Default settings | `settings.json` | Default agent activation (see `references/external-integration.md` Default Settings section) |
| User configuration | `userConfig` in `plugin.json` | Skills need user-provided API keys, endpoints, or tokens — Claude Code only (see `references/external-integration.md` userConfig section) |
| Marketplace entry | `.claude-plugin/marketplace.json` | Plugin targets marketplace distribution — declares plugin metadata for the marketplace index |

## 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 Platf