Plans

A plan in Pitch Smith is a YAML file that describes what your presentation should contain before any slides are built. Plans capture your audience, messaging, narrative structure, and slide-by-slide content requirements -- everything the AI needs to generate brand-consistent slides. Think of a plan as a blueprint: it defines the "what" and "why" of your presentation, while the build process handles the "how."

What is a deck plan?

A deck plan is a YAML file that describes an entire presentation from start to finish. It contains metadata about the deck (title, timestamps), audience context (who will see this, what they care about), messaging strategy (purpose, key message, desired outcome), a narrative storyline, an agenda structure with named sections, and an array of slide definitions.

Deck plans are created through the /pitchsmith:plan-deck command, which guides you through an adaptive discovery process. Rather than asking rigid sequential questions, the planning workflow analyzes the context you provide and identifies gaps that need clarification. The result is a plan that captures not just what you want to say, but who you are saying it to and why.

The power of a deck plan is that it front-loads the thinking. By the time you start building slides, every content decision has already been made -- which means the AI can focus entirely on visual design and brand application rather than guessing at your intent.

What is a slide plan?

A slide plan is a single entry within a deck plan's slides array. Each slide plan defines one slide's content: a description (short title), the suggested template to use, talking points (key_points), a detailed design plan for layout and visual treatment, the slide's role in the narrative, and which agenda section it belongs to.

Slide plans are intentionally detailed. The key_points field contains the actual content the audience will see, while the design_plan field provides multi-line instructions covering layout, typography, color choices, spacing, and animation hints. This level of detail gives the AI builder enough context to produce slides that match your vision without back-and-forth iteration.

Every slide plan also includes a status field (pending or built) that tracks build progress, and a storyline_role (opening, tension, evidence, resolution, or cta) that connects the slide to your narrative arc.

Plan YAML structure

Here is a simplified deck plan showing the major sections. Real plans include more detail; this example highlights the structure:

# Deck metadata
deck_name: "Product Launch"
created: "2026-02-16T10:00:00Z"
last_modified: "2026-02-16T10:00:00Z"

# Audience context
audience:
  description: "Sales team at annual kickoff"
  knowledge_level: "intermediate"
  priorities:
    - "Revenue impact"
    - "Competitive positioning"

# Messaging strategy
purpose: "Enable team to sell new product"
desired_outcome: "Team confident pitching ProductX"
key_message: "ProductX is the future of customer engagement"

# Narrative structure
storyline:
  opening_hook: "The future of customer engagement"
  tension: "Current limitations holding back growth"
  resolution: "ProductX capabilities address every gap"
  call_to_action: "Start selling today"

# Agenda sections
agenda:
  total_sections: 4
  sections:
    - id: "agenda-1"
      title: "Product Overview"
      narrative_role: "opening"
      estimated_slides: 2
    # ... additional sections omitted

# Slide definitions
slides:
  - number: 1
    description: "Title slide: ProductX Launch"
    suggested_template: "title"
    status: "pending"
    storyline_role: "opening"
    agenda_section_id: "agenda-1"
    key_points:
      - "ProductX launches Q1 2026"
      - "3x faster than competitors"
    design_plan: |
      Layout: Full-bleed hero typography, centered.
      Typography: Hero title in 72-80px bold.
      Color: Dark background, white text, brand accent.
      Spacing: Generous vertical centering.
      Animation: Title fades in, then subtitle.

  - number: 2
    description: "Session agenda overview"
    suggested_template: "agenda"
    status: "pending"
    storyline_role: "opening"
    agenda_section_id: "agenda-1"
    key_points:
      - "Product Overview"
      - "Key Features"
      - "Competitive Positioning"
      - "Q&A"
    design_plan: |
      Layout: Numbered list with section icons.
      Typography: Section titles in 28px semibold.
      Color: Light background, dark text, accent on active.
      Spacing: Even vertical distribution.
      Animation: Sections appear sequentially.

The deck-level fields (deck_name, audience, purpose, storyline, agenda) set the context that applies to the entire presentation. The slides array then defines each individual slide within that context. For the complete field-by-field reference of every plan field, types, and validation rules, see the Plan Schema reference (coming in Story 4.6).

How plans drive the build process

Plans are the input to Pitch Smith's AI slide generation pipeline. When you run a build command, the system reads your plan and combines it with your theme and a slide template to produce the final HTML/CSS slide. The flow works like this:

1. Plan provides content -- The slide plan's key_points, design_plan, and description tell the AI what the slide should contain and how it should look.
2. Theme provides brand tokens -- Your theme supplies the colors, fonts, shapes, and design rules that keep every slide on-brand.
3. Template provides structure -- A template gives the AI a starting layout pattern (title slide, content slide, comparison, etc.) to work from.
4. AI generates the slide -- The build process feeds the plan + theme + template to the AI, which produces a self-contained HTML file with embedded CSS. The result is a single index.html file per slide, styled with your brand's CSS variables.

This separation of concerns is what makes Pitch Smith's workflow powerful. Plans capture your intent without worrying about visual design. Themes encode your brand without worrying about content. Templates provide layout patterns without hardcoding either. The AI build step brings all three together.

Because the plan drives the build, changing your plan and rebuilding produces updated slides automatically. If you add a new slide to your plan, restructure your agenda, or update talking points, the next build reflects those changes -- your slides always match your latest thinking.

Single slide plans

Not every use case requires a full deck plan. The /pitchsmith:plan-one command creates a lightweight plan for a single slide, with a simpler structure:

created: "2026-02-16T10:00:00Z"
last_modified: "2026-02-16T10:00:00Z"
description: "Q4 Revenue Performance"
suggested_template: "content"
audience: "Executive leadership team"
key_points:
  - "Revenue grew 23% year-over-year"
  - "Three new enterprise accounts closed"
  - "Customer retention rate at 94%"
visual_guidance: "Clean data presentation with emphasis on growth metrics"
tone: "professional"

Single slide plans skip the deck-level fields (audience object, storyline, agenda) and focus on the essentials: what the slide should contain and how it should look. This makes them ideal for one-off slides -- a standalone chart, a quick summary, or a slide you want to build independently before deciding whether to include it in a larger deck.

Single slide plans fit naturally into the broader deck workflow. You can plan and build individual slides with /pitchsmith:plan-one, then incorporate them into a full deck plan later using /pitchsmith:add-slide.

Related resources

• Themes -- How brand identity is encoded as design tokens and applied to slides
• Templates -- Reusable slide layouts that combine with plans during the build process
• Plan Schema reference (coming in Story 4.6) -- Complete field-by-field documentation of every plan YAML field
• Build Slides guide (coming in Story 4.3) -- Step-by-step instructions for building slides from plans