blueprinting

# Blueprinting Bundle-Plugins

## Overview

Turn a vague idea ("I want to package my skills") into a concrete project blueprint through needs exploration, architecture design, and structured review — then orchestrate the full creation pipeline: scaffolding, content authoring, workflow wiring, and initial quality check.

**Core principle:** Understand what you're building — and why — before generating anything. Five minutes of needs exploration saves hours of rework.

**Skill type:** Hybrid pattern — follow the three-phase process rigidly, but question selection, depth, and approach recommendations adapt to user context.

**Announce at start:** "I'm using the blueprinting skill to plan your bundle-plugin."

<HARD-GATE>
Do NOT invoke bundles-forge:scaffolding or any subsequent orchestration phase until the user has approved the design document. Every project — regardless of perceived simplicity — must pass through needs exploration → architecture design → design document review. Quick mode may shorten the process (needs exploration asks only 2 core questions), but it cannot skip it.
</HARD-GATE>

| Agent Reasoning | Reality |
|-----------------|---------|
| "The user's requirements are already clear" | Seemingly clear requirements often miss platform, workflow, and visibility architecture decisions |
| "This is just packaging a few existing skills" | Even simple packaging requires compatibility verification, cross-reference validation, and workflow chain mapping |
| "Moving fast through the process is more efficient" | Five minutes of exploration saves hours of rework from missing architecture decisions |

## Three Entry Points

This skill handles three scenarios. All three feed into the same three-phase interview — only the initial context differs.

- **Scenario A: New project from scratch** — Begin with Context Exploration, then the full interview
- **Scenario B: Splitting an existing complex skill** — Context Exploration reads the existing skill via `references/decomposition-analysis.md`, then enters the interview with richer context. Splitting produces a new project. To refactor skills within an existing project, use `bundles-forge:optimizing` (Skill & Workflow Restructuring target).
- **Scenario C: Composing multiple existing skills** — Context Exploration inventories candidates via `references/composition-analysis.md`, then enters the interview with richer context

If the user has an existing skill they want to break apart, start with Scenario B. If the user has multiple existing skills they want to combine into a **new** unified project, start with Scenario C. Otherwise, start with Scenario A.

> **Adding skills to an existing project?** That's optimization, not blueprinting. Use `bundles-forge:optimizing` (Skill & Workflow Restructuring target).

## Dialogue Strategy

Read `references/dialogue-strategies.md` for the full interview protocol. Core principles: ask 1-2 questions at a time, reject vague answers, propose approaches with trade-offs, challenge over-scoping, surface contradictions immediately, and confirm understanding after each phase.

## Context Exploration

Before asking any questions, gather available context:

### Scenario A (New Project)
1. **Scan the workspace** — look for scattered skill files, existing SKILL.md drafts, or relevant project files that hint at what the user is building
2. If user context is already rich from their initial message, proceed directly to Phase 1

### Scenario B (Decomposition)
1. **Read the existing skill** — follow `references/decomposition-analysis.md` to map responsibilities, identify split points, and propose a decomposition
2. Present the decomposition proposal to the user for approval
3. Proceed to Phase 1 with the decomposition as input context. In Phase 1, skip questions already answered by the decomposition analysis. Confirm those answers with the user rather than re-asking.

### Scenario C (Composition)
1. **Inventory candidate skills** — follow `references/composition-analysis.md` to check compatibility, detect conflicts, and design orchestration
2. Present the composition plan to the user for approval
3. Proceed to Phase 1 with the composition analysis as input context. In Phase 1, skip questions already answered by the composition analysis. Confirm those answers with the user rather than re-asking.

## Phase 1: Needs Exploration

Understand what the user wants to build and why, before making any architecture decisions. Ask these one at a time, adapting based on answers.

### 1. Problem Scenario

Ask: "What problem does this skill bundle solve? How are people solving it today?"

Understand the gap between the current state and what the user envisions. This is the foundation for all subsequent decisions.

### 2. Target Users

Ask: "Who will use this skill bundle? What's their background — what type of developers, what workflows, what platforms?"

The answer shapes platform selection, skill complexity, and documentation style.

### 3. Core Capabilities

Ask: "What capabilities must this skill bundle provide? If you had to remove one, which one would make it pointless?"

This identifies the non-negotiable skills vs nice-to-haves. The agent should actively propose a skill decomposition based on the answer — present 2-3 decomposition approaches with trade-offs when the boundaries aren't obvious.

### 4. Usage Flow

Ask: "Walk me through how someone would use this — from installing the plugin to completing their task."

This reveals workflow dependencies, entry points, and the natural sequence of operations.

### 5. Existing Alternatives (if relevant)

Ask: "Are there similar skill bundles or tools out there? What's different about yours?"

Skip this if the user has already addressed it or if the domain is clearly novel.

### Phase 1 Checkpoint

After collecting needs exploration answers, restate the understanding and verify completeness:

> "Let me confirm what I understand: You're building [one-sentence summary] for [target user