blueprint

name	blueprint
description	Transform feature descriptions into well-structured project plans
argument-hint	[feature description, bug report, or improvement idea]

Create a Blueprint

CRITICAL: This is a WORKFLOW SKILL, not Claude's built-in plan mode. Do NOT use EnterPlanMode or ExitPlanMode tools.

Task Tracking Setup

TASK_TRACKING = config_read("task_tracking.enabled", "false")

If TASK_TRACKING:
  BLUEPRINT_WORKFLOW_ID = "blueprint-{timestamp}"
  PHASE_TASKS = {}

  PHASES = [
    {num: 1, name: "Discovery", active: "Running discovery"},
    {num: 2, name: "Research", active: "Researching codebase"},
    {num: 3, name: "Research Validation", active: "Validating research"},
    {num: 4, name: "Architecture", active: "Designing architecture"},
    {num: 5, name: "Capture Learnings", active: "Capturing learnings"},
    {num: 6, name: "Write Plan", active: "Writing plan"},
    {num: 7, name: "Review Plan", active: "Reviewing plan"},
    {num: 8, name: "User Decision", active: "Awaiting user decision"},
    {num: 9, name: "Execution", active: "Executing plan"}
  ]

  For each P in PHASES:
    PHASE_TASKS[P.num] = TaskCreate(
      subject: "Phase {P.num}: {P.name}",
      activeForm: P.active,
      metadata: {workflow: BLUEPRINT_WORKFLOW_ID, phase: P.num}
    )

  # Dependencies: phase 4 blocked by 1-3, then sequential 5→6→7→8→9
  TaskUpdate(PHASE_TASKS[4], addBlockedBy: [PHASE_TASKS[1], PHASE_TASKS[2], PHASE_TASKS[3]])
  TaskUpdate(PHASE_TASKS[5], addBlockedBy: [PHASE_TASKS[4]])
  TaskUpdate(PHASE_TASKS[6], addBlockedBy: [PHASE_TASKS[5]])
  TaskUpdate(PHASE_TASKS[7], addBlockedBy: [PHASE_TASKS[6]])
  TaskUpdate(PHASE_TASKS[8], addBlockedBy: [PHASE_TASKS[7]])
  TaskUpdate(PHASE_TASKS[9], addBlockedBy: [PHASE_TASKS[8]])

Feature Description

<feature_description> $ARGUMENTS </feature_description>

If empty: Ask user to describe the feature, bug fix, or improvement.

Workflow

Phase 1: Discovery

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[1], status: "in_progress")

Skill("blueprint-discovery")

Handles: Idea Refinement, Interview decision, Acceptance Criteria, Feature Classification.

Wait for output: discovery_result

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[1], status: "completed")

Phase 2: Research

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[2], status: "in_progress")

Skill("blueprint-research") feature_description, discovery_result

Handles: Toolbox resolution, lessons discovery, parallel research agents, spec review.

Wait for output: research_result

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[2], status: "completed")

Phase 3: Research Validation

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[3], status: "in_progress")

Quick checkpoint before architecture. Catches misalignment early.

research_summary = summarize research_result:
  - Key patterns found (2-3 bullets)
  - Similar implementations discovered
  - Potential constraints/blockers

AskUserQuestion:
  question: "Research found: {research_summary}. Continue to planning?"
  header: "Validate"
  options:
    - label: "Looks good"
      description: "Proceed to architecture phase"
    - label: "Missing something"
      description: "Tell me what to research deeper"
    - label: "Wrong direction"
      description: "Let's revisit the requirements"

If "Missing something":

AskUserQuestion: "What should I dig into?"
→ Run targeted research agent
→ Append to research_result
→ Return to Phase 3

If "Wrong direction":

→ Return to Phase 1 (Discovery)

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[3], status: "completed")

Phase 4: Architecture

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[4], status: "in_progress")

Task(majestic-engineer:plan:architect):
  prompt: |
    Feature: {feature_description}
    Research: {research_result.research_findings}
    Spec: {research_result.spec_findings}
    Skills: {research_result.skill_content}
    Lessons: {research_result.lessons_context}

Wait for output: architect_output

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[4], status: "completed")

Phase 5: Capture Learnings

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[5], status: "in_progress")

PRIMARY_DIR = extract main folder from architect_output.file_recommendations
AGENTS_MD = walk up from PRIMARY_DIR until AGENTS.md found (default: root)

If new patterns or decisions discovered:
  Edit(AGENTS_MD, append patterns/decisions)

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[5], status: "completed")

Phase 6: Write Plan

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[6], status: "in_progress")

Apply plan-builder skill.

Select template based on complexity:

• Minimal: Single file changes, simple bugs
• Standard: Most features (default)
• Comprehensive: Major features, architectural changes

Output: Write to docs/plans/[YYYYMMDDHHMMSS]_<title>.md

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[6], status: "completed")

Phase 7: Review Plan

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[7], status: "in_progress")

Task(majestic-engineer:plan:plan-review):
  prompt: "Review plan at {plan_path}"

Incorporate feedback and update plan file.

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[7], status: "completed")

Phase 8: User Decision

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[8], status: "in_progress")

Check auto_preview: config_read("auto_preview", "false")

If true: Bash(command: "open {plan_path}")

AskUserQuestion:
  question: "Blueprint ready at `{plan_path}`. What next?"
  options:
    - "Build as single task" → Phase 9a
    - "Break into small tasks" → Phase 9b
    - "Create as single epic" → Phase 9c
    - "Deep dive into specifics" → Phase 8.1
    - "Preview plan" → Read and display, return to Phase 8
    - "Revise" → Ask what to change, return to Phase 6
    - "Review and refine" → Apply document-refinement skill, return to Phase 8

IMPORTANT: After user selects, EXECUTE that action.

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[8], status: "completed")

If "Review and refine":

Apply document-refinement skill to {plan_path}
→ Auto-fix minor issues in plan file
→ Present refinement report to user
→ Return to Phase 8

Phase 8.1: Deep Dive

AskUserQuestion: "What aspect needs deeper research?"

Run focused research:

Task(majestic-engineer:research:best-practices-researcher):
  prompt: "Deep dive: {aspect} for feature {feature}"
Task(majestic-engineer:research:web-research):
  prompt: "{aspect} - patterns, examples, gotchas"

Update plan with findings, return to Phase 8.

Phase 9: Execution

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[9], status: "in_progress")

Dispatch on user_choice from Phase 8:

9a. Single Task (user_choice == "Build as single task"):

Skill("build-task") "{plan_path}"

End workflow.

9b. Break Into Tasks (user_choice == "Break into small tasks"):

Task(majestic-engineer:plan:task-breakdown):
  prompt: "Plan: {plan_path}"

AskUserQuestion:
  question: "Tasks added to plan. Create in backlog?"
  options:
    - "Yes, create tasks" → For each task in plan: Skill("backlog-manager")
    - "No, just the plan" → Skip

Then offer build:

AskUserQuestion:
  question: "Start building?"
  options:
    - "Build all tasks now" → Skill("run-blueprint") "{plan_path}"
    - "Done for now" → End workflow

9c. Single Epic (user_choice == "Create as single epic"):

Skill("backlog-manager")

Update plan with task reference, then offer build:

AskUserQuestion:
  question: "Start building?"
  options:
    - "Build all tasks now" → Skill("run-blueprint") "{plan_path}"
    - "Done for now" → End workflow

If TASK_TRACKING: TaskUpdate(PHASE_TASKS[9], status: "completed")

Error Handling

Scenario	Action
Discovery skill fails	Ask user for AC manually, continue
Research skill fails	Continue with architect (degraded)
User skips validation	Continue to Phase 4
Architect fails	Log error, ask user to provide approach
Plan-review fails	Continue with original plan
Task creation fails	Report error, ask user to create manually
Config read fails	Use default value
User cancels	End workflow gracefully

Notes

• Blueprint-only skill - no implementation code
• Research and spec-review run in parallel (inside blueprint-research)
• Architect MUST wait for research completion
• All phases are mandatory except branches (8.1, 9a/9b/9c)
• Always execute user's selected option