Plan Schema

Plan files define the structure and content of your presentations. They are YAML files generated by the /pitchsmith:plan-deck and /pitchsmith:plan-one commands.

Deck plans are stored at .slide-builder/deck/{deck-name}/plan.yaml
Single slide plans are stored at .slide-builder/single/plan.yaml

This reference documents the complete schema for both plan types.

Last verified

March 2026 — verified against pitchsmith-plugin/reference/plan-schema.md in the Pitch Smith source.

Deck Plan Schema

A deck plan contains metadata about the presentation, audience context, storyline structure, agenda sections, and individual slide definitions.

Deck-Level Required Fields

Field	Type	Format / Options	Description
`deck_name`	string	Any non-empty string	Human-readable presentation title
`created`	string	ISO 8601 timestamp	Creation timestamp
`last_modified`	string	ISO 8601 timestamp	Last modification timestamp
`audience.description`	string	Free text	Who will view this presentation
`audience.knowledge_level`	enum	`beginner` \| `intermediate` \| `expert`	Audience expertise level
`audience.priorities`	string[]	Min 1 item	What the audience cares about
`purpose`	string	Free text	Presentation objective
`desired_outcome`	string	Free text	What should happen after the presentation
`key_message`	string	Free text	Core takeaway message
`slides`	array	Min 1 slide	Array of slide definitions

Deck-Level Optional Fields

Field	Type	Format / Options	Description
`presentation_setting`	enum	`live` \| `sent_as_deck` \| `recorded` \| `hybrid`	Delivery format — influences slide density and content style
`desired_length`	string	Range `"8-10"` or single `"12"`	Target slide count
`discovery_context`	object	Flexible key-value pairs	Context from adaptive follow-up questions
`planning_research`	array	Array of research objects	Web research findings
`storyline`	object	See below	Narrative structure
`recurring_themes`	string[]	Free text	Themes that recur across slides
`agenda`	object	See below	Agenda structure with sections

Storyline Fields

Field	Type	Description
`storyline.opening_hook`	string	Opening attention-grabber
`storyline.tension`	string	Challenge or pain point
`storyline.resolution`	string	Proposed approach
`storyline.call_to_action`	string	Desired next step

Agenda Fields

Field	Type	Description
`agenda.total_sections`	integer	Number of agenda sections
`agenda.sections`	array	Array of section definitions
`agenda.sections[].id`	string	Section identifier (e.g., `"agenda-1"`)
`agenda.sections[].title`	string	Section title
`agenda.sections[].narrative_role`	enum	`opening` \| `context` \| `problem` \| `solution` \| `evidence` \| `cta`
`agenda.sections[].estimated_slides`	integer	Estimated slides in this section
`agenda.sections[].description`	string	Section description

Discovery Context Common Keys

The discovery_context object is flexible — keys depend on what gaps were identified during planning. Common keys include:

Key	Type	Description
`known_objections`	string[]	Audience objections or concerns to address
`competitive_context`	string	Competitive landscape or incumbent being replaced
`audience_priorities`	string[]	What the audience cares about most
`audience_role`	string	Primary audience role (e.g., `"decision_maker"`)
`decision_timeline`	string	When the audience needs to make a decision

Slide Fields

Each slide in the slides array has the following fields.

Slide-Level Required Fields

Field	Type	Format / Options	Validation
`number`	integer	1-indexed	Must be sequential: 1, 2, 3...
`description`	string	One-line title	No newlines allowed
`suggested_template`	string	Template ID	Must exist in template catalog
`status`	enum	`pending` \| `built`	Exact match required
`storyline_role`	enum	`opening` \| `tension` \| `evidence` \| `resolution` \| `cta`	Exact match required
`agenda_section_id`	string	References agenda section	Must match an existing `agenda.sections[].id`
`key_points`	string[]	Talking points	Min 1 item
`design_plan`	string	Multi-line design notes	Must include layout, typography, color, spacing, animation

Slide-Level Optional Fields

Field	Type	Options	Description
`background_mode`	enum	`dark` \| `light`	Slide background mode
`tone`	enum	`professional` \| `bold` \| `warm` \| `technical` \| `urgent`	Slide tone

Single Slide Plan Schema

Single slide plans have a simpler structure with fewer required fields.

Field	Type	Required	Description
`created`	string	No	ISO 8601 timestamp
`last_modified`	string	No	ISO 8601 timestamp
`description`	string	Yes	Short one-line slide title
`suggested_template`	string	Yes	Template ID or `"custom"`
`audience`	string	No	Who will view this slide
`key_points`	string[]	Yes	Detailed talking points
`visual_guidance`	string	No	Design hints
`tone`	enum	No	`professional` \| `bold` \| `warm` \| `technical`

Single Slide Plan Example

created: "2026-03-01T10:00:00Z"
last_modified: "2026-03-01T10:00:00Z"
description: "Q1 Revenue Dashboard"
suggested_template: "data"
audience: "Executive leadership team"
key_points:
  - "Revenue grew 23% quarter-over-quarter"
  - "Three product lines exceeded targets"
  - "Customer acquisition cost decreased by 15%"
visual_guidance: "Lead with the headline metric, use a chart for trends"
tone: "professional"

Backward Compatibility

Legacy plans may use older field names. Pitch Smith accepts both legacy and current names but normalizes to current names when saving.

Legacy Field	Current Field	Notes
`intent`	`description`	Read either, write as `description`
`template`	`suggested_template`	Read either, write as `suggested_template`
`visual_guidance`	`design_plan`	Read either, write as `design_plan`

Plans created before the adaptive discovery feature will not contain presentation_setting, desired_length, or discovery_context fields. Their absence does not cause errors.

Validation Rules

#	Requirement	Rule
1	Timestamps	`created` and `last_modified` must be ISO 8601 format
2	Minimum slides	Full deck: min 1 slide. Single slide: exactly 1
3	Sequential numbering	Slide numbers must be 1-indexed and sequential
4	Required arrays	`audience.priorities` and `key_points` must have at least 1 item
5	One-line descriptions	`description` field must be single-line (no newlines)
6	Multi-line design plans	`design_plan` must be multi-line with layout, typography, color, spacing, animation
7	Valid enums	`knowledge_level`, `status`, `storyline_role` must use exact values
8	Agenda linking	Every slide's `agenda_section_id` must reference an existing agenda section

Complete deck plan example

deck_name: "Product Launch"
created: "2026-03-01T10:00:00Z"
last_modified: "2026-03-01T10:00:00Z"

audience:
  description: "Sales team"
  knowledge_level: "intermediate"
  priorities:
    - "Revenue impact"
    - "Competitive positioning"

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

presentation_setting: "live"
desired_length: "8-10"

discovery_context:
  audience_role: "sales_representative"
  known_objections:
    - "Price is higher than Competitor Y"
    - "Requires training ramp-up"
  competitive_context: "Displacing Competitor Y in mid-market accounts"

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"

recurring_themes:
  - "Customer-centric innovation"
  - "Measurable results"

agenda:
  total_sections: 2
  sections:
    - id: "agenda-1"
      title: "Introduction"
      narrative_role: "opening"
      estimated_slides: 2
      description: "Set the stage and present agenda"
    - id: "agenda-2"
      title: "Product Overview"
      narrative_role: "solution"
      estimated_slides: 3
      description: "Present key features and differentiators"

slides:
  - number: 1
    status: pending
    storyline_role: "opening"
    agenda_section_id: "agenda-1"
    tone: "bold"
    background_mode: dark
    suggested_template: "title"
    description: "Title slide: ProductX Launch"
    design_plan: |
      **Layout:** Full-bleed hero typography, centered.
      **Typography:** Hero title in 72px bold. Subtitle in 32px medium.
      **Color:** Dark background, white text, brand accent highlights.
      **Spacing:** Generous vertical centering, title in upper-center third.
      **Animation hint:** Title fades in, then subtitle.
    key_points:
      - "ProductX launches Q1 2026"
      - "3x faster than competitors"

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

Deck Plan Schema​

Deck-Level Required Fields​

Deck-Level Optional Fields​

Storyline Fields​

Agenda Fields​

Discovery Context Common Keys​

Slide Fields​

Slide-Level Required Fields​

Slide-Level Optional Fields​

Single Slide Plan Schema​

Single Slide Plan Example​

Backward Compatibility​

Validation Rules​