Skip to main content

Plan a Deck

Plan a complete presentation with narrative structure, or add individual slides to an existing deck. This guide walks you through creating a full deck plan, planning a single slide, adding slides to an existing plan, and modifying your plan after generation.

Prerequisites

Before planning a deck, make sure you have:

  • A Pitch Smith workspace scaffolded in your project (run /pitchsmith if you have not set one up yet -- see Quickstart)
  • A brand theme configured for your workspace (see Brand Setup)
  • Claude Code running in your project directory
  • A topic or brief for the presentation you want to create

Plan a Full Deck​

Create a narrative-first deck plan that includes a storyline arc, audience context, and a slide-by-slide breakdown with template assignments.

  1. Open a Claude Code session in your project directory.

  2. Run the plan-deck command:

    /pitchsmith:plan-deck

    You can optionally provide a deck name to pre-fill:

    /pitchsmith:plan-deck "Q3 Sales Review"

  3. Pitch Smith verifies that your theme.json exists, then guides you through a series of prompts:

    • Purpose -- What is the presentation about?
    • Audience -- Who will be viewing this presentation?
    • Key points -- What are the main messages you want to convey?
    • Desired length -- How many slides do you want?

  4. Based on your answers, Pitch Smith generates a storyline arc (hook, tension, resolution, call to action) and creates a slide-by-slide breakdown. Each slide entry includes a number, intent, template assignment, and storyline role.

  5. Review the plan and make any adjustments. Once you approve, Pitch Smith saves the plan to output/<deck-slug>/plan.yaml and updates status.yaml to track the new deck.

Verify: Deck plan created successfully

Check that the plan file was created:

ls output/<your-deck-slug>/plan.yaml

Expected: The file exists and contains a YAML structure with a slides array. Each slide entry should have number, intent, template, and storyline_role fields.

You can inspect the plan:

cat output/<your-deck-slug>/plan.yaml

Expected: A complete plan with your presentation's purpose, audience, and a numbered list of slides, each with status: pending.

Plan a Single Slide​

Plan a standalone slide when you need one slide for a specific purpose rather than a full deck. Use this for quick one-off slides or when adding to an existing presentation outside of deck mode.

  1. Open a Claude Code session in your project directory.

  2. Run the plan-one command:

    /pitchsmith:plan-one

  3. Pitch Smith verifies your theme and then asks you to describe the slide you need. Explain the purpose of the slide, such as:

    • "A title slide introducing our Q3 results"
    • "A comparison of before and after performance metrics"
    • "A process flow showing our onboarding steps"

  4. Pitch Smith matches your intent to the best template from your catalog (or selects "custom" if no template fits) and presents a summary for your approval.

  5. Once confirmed, the plan is saved to output/singles/plan.yaml with status: pending, ready for building.

Verify: Single slide plan created

Check the singles plan file:

cat output/singles/plan.yaml

Expected: A plan entry with your slide's intent, matched template, key points, and status: pending.

When to use plan-one vs. plan-deck
  • Use /pitchsmith:plan-deck when you are creating a full presentation with multiple slides that follow a narrative arc.
  • Use /pitchsmith:plan-one when you need a single standalone slide for a specific purpose -- for example, a quick title card, a data visualization, or a one-off callout.

Add a Slide to an Existing Plan​

Append a new slide to a deck that has already been planned. Use this when you want to expand an existing presentation without re-planning the entire deck.

  1. Open a Claude Code session in your project directory.

  2. Run the add-slide command:

    /pitchsmith:add-slide

    If you have multiple decks, you can specify which one:

    /pitchsmith:add-slide my-deck-slug

  3. Pitch Smith loads your existing deck plan and displays the current slides. You are asked where the new slide should go:

    • "after 3" -- Insert after slide 3
    • "at end" -- Add to the end of the deck

  4. Describe the new slide: its intent, key points, tone, and any visual guidance. Pitch Smith suggests a template from your catalog.

  5. If your deck uses agenda sections, Pitch Smith asks which section the new slide belongs to.

  6. The new slide is inserted at the specified position, subsequent slides are renumbered, and the updated plan is saved. Pitch Smith optionally offers to build the new slide immediately.

Verify: Slide added to plan

Open your deck plan:

cat output/<your-deck-slug>/plan.yaml

Expected: The slides array includes the new slide at the position you specified. Subsequent slides have been renumbered. The new slide has status: pending.

Modify Your Plan​

After generating a plan, you can refine it by editing the YAML directly, using the edit-plan command for natural language edits, or using the Plan Editor for visual editing.

Edit the YAML Directly​

Open your plan file in any text editor:

code output/<your-deck-slug>/plan.yaml

Common modifications include:

  • Change slide order -- Move slide entries up or down in the slides array and update their number fields.
  • Update key points -- Edit the key_points list for any slide to refine the content that will be generated.
  • Change template assignments -- Update the template field to switch a slide to a different layout.
  • Modify section groupings -- Adjust the agenda_section_id to reorganize slides into different narrative sections.
  • Reset a slide for rebuilding -- Change status: built back to status: pending so the next build command regenerates it with your changes.

Edit with Natural Language​

Use the edit-plan command to modify your plan by describing the change you want:

/pitchsmith:edit-plan Make the opening more compelling
/pitchsmith:edit-plan Add a slide about ROI after slide 3
/pitchsmith:edit-plan Change the audience to technical decision-makers

Pitch Smith reads your current plan, classifies the type of edit (field update, structural change, or narrative adjustment), applies the modification, and saves the updated plan.

Use the Plan Editor​

If you have the Pitch Smith VS Code extension installed, you can use the Plan Editor -- a visual interface for editing your deck plan. The Plan Editor opens when you click on a plan YAML file and provides drag-and-drop reordering, inline field editing, and section management without editing YAML directly.

Plan Editor documentation

The Plan Editor is a VS Code custom editor with its own set of features. This guide covers the basics -- for full Plan Editor documentation, see the VS Code extension help.

Verify: Plan modifications saved

After making changes, verify the plan file reflects your edits:

cat output/<your-deck-slug>/plan.yaml

Expected: Your modifications are saved. If you changed a slide's status to "pending", running /pitchsmith:build-one or /pitchsmith:build-all will regenerate that slide with the updated plan content.

See Also​

Related documentation

The following pages provide deeper context on the concepts and references used in this guide: