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>

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 users] to solve [problem]. The core capabilities are [list]. The usage flow is [summary]. Does this match your intent?"

Must verify before proceeding:

• Problem scenario: expressible as "[user] needs to [action] because [reason]" in one sentence
• Target users: at least one concrete persona with platform + workflow identified

Wait for user confirmation before proceeding to Phase 2. If the user corrects anything, update the understanding and re-confirm.

Phase 2: Architecture Design

With a clear understanding of what and why, now decide how to build it. The agent should actively recommend answers based on Phase 1 context, rather than asking open-ended questions.

Before making architecture recommendations: Explicitly list key assumptions derived from Phase 1 and wait for user confirmation. Template:

"Based on our needs exploration, I'm operating on these assumptions:

1. [Complexity assumption — e.g., 'This is a straightforward packaging project']
2. [Platform assumption — e.g., 'Primary platform is Claude Code based on your workflow']
3. [Independence assumption — e.g., 'Skills appear independent with no workflow chain']

If any of these are wrong, correct me now — they will shape all architecture decisions."

1. Project Complexity

Based on Phase 1 answers, recommend quick or adaptive mode:

Quick mode (quick packaging):

• Target: bundle standalone skills into a plugin with minimal infrastructure
• Skip questions 5 (Workflow Chain), 6 (Bootstrap Strategy), and 4a (Skill Visibility)
• Defaults: no bootstrap, no hooks, Claude Code only
• Jump to a simplified design document after question 4

Adaptive mode (adaptive deep interview):

• Full interview with dynamic follow-ups based on answers
• After core questions, conditionally ask about advanced components

Present the recommendation with reasoning: "Based on what you've described — [reasoning] — I recommend [quick/adaptive] mode. [Quick explanation of what this means]."

Quick mode skips most Phase 1/2 questions and defaults to Claude Code only with independent skills. See references/dialogue-strategies.md for the full behavior summary table.

2. Project Name

Kebab-case identifier (e.g., my-dev-tools). This becomes the directory name, package name, and plugin ID across all platforms.

Validation: lowercase letters, numbers, hyphens only. No underscores, no spaces.

3. Target Platforms

Which platforms should the project support? See references/platform-reference.md for the full platform table and selection strategies.

Based on the target users identified in Phase 1, recommend a platform combination with reasoning. Start with what the user actually uses — others can be added later via bundles-forge:scaffolding.

4. Skill Inventory

Based on the core capabilities and usage flow from Phase 1, propose a skill decomposition rather than asking the user to list skills:

"Based on the capabilities you described, I recommend splitting into these skills: [proposed list with one-sentence purpose each]. Here's why this decomposition makes sense: [reasoning]."

When the decomposition isn't obvious, present 2-3 approaches:

• Approach A: [decomposition] — pros/cons
• Approach B: [decomposition] — pros/cons
• Recommended: [which and why]

For each skill, determine:

• Skill name (kebab-case)
• One-sentence purpose
• Rigid or flexible type

If the user isn't sure yet, scaffold with a single placeholder skill and the bootstrap.

4a–7. Adaptive Mode Questions

Questions 4a (Skill Visibility), 5 (Workflow Chain), 6 (Bootstrap Strategy), and 7 (Advanced Components) apply only in adaptive mode. Quick mode skips them. See references/adaptive-mode-questions.md for the full question set.