How the One-Shot Alignment Checkpoint Works in Web-Video-Presentation

The one-shot alignment checkpoint, named "Checkpoint Plan" in the ConardLi/garden-skills repository, is a mandatory hard-stop node that halts execution after Phase 1 to enforce user confirmation of five critical deliverables—script, outline, theme, assets, and development mode—before generating the presentation scaffold.

The web-video-presentation skill implements a one-shot alignment checkpoint to eliminate downstream rework by anchoring all creative decisions up front. This mechanism activates immediately after the initial content generation phase, requiring explicit validation of narrative structure, visual direction, and development workflow. Understanding this hard-stop node ensures you can efficiently navigate from automated draft generation to polished, web-based video presentations.

When the Checkpoint Triggers

The checkpoint activates automatically upon completion of Phase 1, the initial content generation stage. During this phase, the skill produces three key artifacts in the project folder:

• script.md – The narration script containing the full presentation text
• outline.md – The structural blueprint defining chapters and timing
• article.md (optional) – Supplementary source material

Once these files are written to disk, the workflow enters a suspended state. The skill cannot proceed to Phase 2 (webpage scaffolding) until the user explicitly reviews and confirms five specific items through the Checkpoint Plan interface defined in skills/web-video-presentation/SKILL.md.

The Five Critical Alignment Items

The checkpoint enforces a structured review of five mandatory items. Each item corresponds to a specific file or decision point that determines the downstream rendering pipeline.

1. Script Confirmation (script.md)

The user must verify or edit the script.md file containing the generated narration. This script serves as the audio timeline anchor for the entire presentation. Confirming this item locks the word count and estimated duration, which directly impacts animation timing and chapter segmentation.

2. Outline Verification (outline.md)

The outline.md file requires validation of chapter counts, step granularity, and the information pool. This verification ensures the logical flow from introduction to conclusion aligns with the script's narrative arc. The outline determines the minimum viable chapter structure before the scaffold script initializes the Vite + React project structure.

3. Theme Selection

The skill dynamically recommends two to three best-matching themes from the JSON theme catalog located in themes/*/theme.json. The recommendation engine analyzes the content of script.md and outline.md to suggest themes with compatible visual characteristics. The user selects a theme ID from the catalog defined in skills/web-video-presentation/references/THEMES.md, establishing the color palette, typography, and motion design tokens for the presentation.

4. Asset Inventory

Users must confirm the asset list—the collection of images, diagrams, logos, and media files required for the presentation. This inventory check prevents broken references during the chapter development phase by validating the availability of resources before coding begins.

5. Development Mode Selection

The checkpoint requires selection of a development mode that governs how subsequent chapters are built:

• Mode A: Sequential per-chapter review (default) – Each chapter requires individual validation before proceeding
• Mode B: Sequential without per-chapter review – Continuous generation with batch review
• Mode C: Parallel/sub-agent execution – Distributed processing across multiple agents for speed

This selection is stored in the checkpoint state and referenced by the chapter-crafting logic in skills/web-video-presentation/references/CHAPTER-CRAFT.md.

Implementation in SKILL.md

The checkpoint mechanism is formally specified in the Checkpoint Plan section of skills/web-video-presentation/SKILL.md. This definition establishes the node as a hard stop—the workflow graph cannot advance until the user replies with explicit confirmation or file edits.

The skill implements a self-check loop: if the user modifies script.md or outline.md during the checkpoint, the skill detects the filesystem changes, re-runs validation logic, and redisplays the checkpoint summary until all five items stabilize. The checkpoint summary template formats the current state into a structured prompt displaying word counts, file paths, and theme recommendations.

User Interaction Example

When the checkpoint activates, the skill presents a formatted summary block requiring structured input:

--- Phase 1 completed ---
Generated files:
 • script.md (1,200 words / ~6 min)
 • outline.md (4 chapters / 24 steps)

[Checkpoint Plan] – Please confirm the following 5 items:

1️⃣ Script – ok? (edit script.md or reply "keep")
2️⃣ Outline – ok? (edit outline.md or reply "keep")
3️⃣ Theme – I recommend "creative-voltage" (bestFor: talks). Choose? (reply theme id)
4️⃣ Assets – current list: [logo.svg, chart.png]. Add/remove?
5️⃣ Development mode – default A (per-chapter review). Change? (A/B/C)

> Your reply:
keep
keep
creative-voltage
keep
A

--- Proceeding to Phase 2 (scaffold) ---

If the user responds with "keep" for all items, the skill immediately triggers scripts/scaffold.sh to create the Vite + React project structure. If the user specifies edits, the checkpoint persists until the next validation cycle confirms alignment.

Transition to Phase 2 and Beyond

Upon checkpoint clearance, the skill initiates Phase 2, executing the scaffold script to generate the presentation boilerplate. The confirmed script.md anchors the narration files in presentation/src/chapters/*/narrations.ts, while the selected theme populates the design tokens.

The checkpoint also sets up the second hard node—Checkpoint Audio—which activates later if the user declines automatic audio synthesis. This secondary checkpoint mirrors the Plan checkpoint's validation pattern but focuses specifically on voice generation parameters.

Summary

• The one-shot alignment checkpoint is a hard-stop node named "Checkpoint Plan" defined in skills/web-video-presentation/SKILL.md.
• It triggers automatically after Phase 1 completes, pausing execution until the user confirms five items: script, outline, theme, assets, and development mode.
• The skill dynamically suggests themes from themes/*/theme.json based on content analysis of the generated files.
• Users select from three development modes (A/B/C) that determine how subsequent chapters are crafted according to CHAPTER-CRAFT.md.
• The checkpoint implements a self-check loop that detects file edits and re-prompts until all items are explicitly confirmed.
• Clearance triggers Phase 2 scaffolding via scripts/scaffold.sh, creating the foundation for the web-based presentation.

Frequently Asked Questions

What happens if I edit the script during the checkpoint?

If you modify script.md or outline.md while the checkpoint is active, the skill detects the filesystem change and re-runs its validation logic. It redisplays the Checkpoint Plan summary with updated word counts and chapter data, requiring you to confirm the revised content before proceeding. This ensures the narrative anchor remains synchronized with your edits.

Can I skip the theme selection and use a default?

No, theme selection is mandatory. The skill dynamically recommends two to three themes from the catalog in skills/web-video-presentation/references/THEMES.md based on your content analysis, but you must explicitly confirm or specify a theme ID. This prevents visual misalignment between the narrative tone and the presentation design system.

Where is the development mode stored after I select it?

The development mode (A, B, or C) selected at the checkpoint is stored in the session state and referenced by the chapter-crafting logic defined in skills/web-video-presentation/references/CHAPTER-CRAFT.md. This determines whether subsequent chapters undergo individual review (Mode A), batch processing (Mode B), or parallel sub-agent execution (Mode C).

What is the difference between Checkpoint Plan and Checkpoint Audio?

Checkpoint Plan activates after Phase 1 to confirm structural and creative decisions (script, outline, theme, assets, and mode). Checkpoint Audio is a secondary hard node that only appears later if you decline automatic audio synthesis, requiring explicit configuration of voice generation parameters before final rendering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}