/scaffolding

name: scaffolding
description: "Use when generating project structure for new bundle-plugins, adding or removing platform support (Claude Code, Cursor, Codex, OpenCode, Gemini CLI, OpenClaw), updating platform manifests, or migrating hooks and configuration between platforms"
allowed-tools: Bash(bundles-forge bump-version *)

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