How the Plan Checkpoint Works in the Beautiful-Article Skill: Complete Technical Guide

The Plan Checkpoint is Phase 3 of the beautiful-article skill that pauses the generation pipeline to collect five independent user decisions—article type, theme, layout width, image mode, and cover toggle—before any content scaffolding begins.

The Plan Checkpoint serves as the critical control gate in the ConardLi/garden-skills repository's beautiful-article skill, ensuring user agency over the final article structure. This mandatory pause point prevents silent defaults by requiring explicit confirmation of five high-level parameters that drive downstream scaffolding, component selection, and rendering behavior according to the specifications in skills/beautiful-article/SKILL.md.

Workflow Position and Phase Structure

The Plan Checkpoint represents Checkpoint 1 within the six-phase workflow defined in the skill's master specification:

Phase 0 → Intake
Phase 1 → Source → Markdown
Phase 2 → Editorial Planning (produces plan/plan.md)
Phase 3 → Plan Checkpoint  ★Checkpoint 1 – must stop here
Phase 4 → First Spread
Phase 5 → Content Review

Located at Phase 3, this checkpoint follows the editorial planning phase that generates plan/plan.md and precedes the First Spread phase where actual content scaffolding begins. The checkpoint logic is implemented in skills/beautiful-article/SKILL.md (see the "Phase 3 — Plan Checkpoint" section), while the detailed verification criteria reside in skills/beautiful-article/references/review-checklist.md.

The Five Mandatory Decisions

The checkpoint gathers five specific decisions that determine the architectural foundation of the generated article. Each decision maps to a specific section in plan/plan.md and drives the behavior of scripts/scaffold.sh.

1. Article Type

Semantic tag defining content density and retention strategy. Options include longform·~100%, tutorial·~90%, and briefing·~50%, where the percentage indicates the default information retention ratio.

• Storage location: Brief section of plan/plan.md
• Reference file: skills/beautiful-article/references/article-types.md

2. Theme

Visual design system selection from the theme registry.

• Options: Pre-defined themes from theme-profiles/index.json (e.g., tufte, press)
• Storage location: Theme subsection of plan/plan.md

3. Layout Width

Page container sizing that affects text measure and component spanning.

• Options: narrow, regular (default), wide, full
• Storage location: Brief section (layout width parameter)
• Reference file: skills/beautiful-article/references/layout.md

4. Image Mode

Asset generation strategy for the article.

• Options: none, user-assets, placeholders, ai-generated
• Storage location: Assets subsection (image strategy)
• Reference file: skills/beautiful-article/references/asset-policy.md

5. Cover Toggle

Boolean flag for the book-cover style opening component.

• Options: on (default) or off
• Storage location: Brief section (cover toggle)
• Reference file: skills/beautiful-article/references/cover.md

Execution Flow and Implementation

The checkpoint executes a strict six-step sequence to ensure deterministic state management:

1. Plan Generation: The main agent populates plan/plan.md using the template defined in skills/beautiful-article/references/plan-template.md.

2. Inline Self-Check: The agent performs an inline self-review against the 5-item checklist in review-checklist.md without spawning sub-agents or creating review files.

3. Checkpoint Announcement: The agent posts the Plan Checkpoint opening template (SKILL.md lines 32-48), presenting automatically-generated recommendations while explicitly stating these are not defaults.

4. Decision Collection:

   • Primary method: If the environment provides the AskQuestion tool, the agent sends five separate question objects enabling UI choice cards.
   • Fallback method: When AskQuestion is unavailable, the agent posts a numbered plain-text list and waits for structured user replies.

5. Persistence: Each answer overwrites the corresponding placeholder in plan/plan.md within its designated section (Brief, Theme, or Assets).

6. Transition: After confirming all five answers are recorded, the pipeline advances to Phase 4 (First Spread).

Core Design Principles

The Plan Checkpoint adheres to four architectural principles that enforce user control:

• No Silent Defaults: Every decision must be asked independently. The agent may recommend options but never assumes choices.

• AskQuestion Preferred: The implementation prioritizes the AskQuestion tool for native UI integration, sending each decision as a separate question object.

• Plain Text Fallback: When advanced tooling is unavailable, the system degrades gracefully to numbered lists while maintaining the requirement for explicit answers.

• Immutable Order: The sequence of the five questions is fixed. The checkpoint will not proceed until each answer is recorded in plan/plan.md in the specified order.

Practical Code Examples

Initial Plan State Before Checkpoint

The agent generates plan/plan.md with placeholders that must be resolved:

## Brief

- 文章类型: <placeholder>
- 版式宽度: <placeholder>
- TOC: 开
- 配图模式: <placeholder>
- 封面: <placeholder>

## Outline

...

## Theme

<placeholder>

## Assets

...

Checkpoint Prompt Structure

The agent presents recommendations without applying them:

plan/plan.md 已经写好（自检通过）。我会逐项跟你确认 5 件事：文章类型 / 主题 / 版式宽度 / 配图模式 / 封面。

我的推荐先放在这里供参考（不会替你选）：
- 类型：longform（含标配信息保留 100%。理由：适合完整长文）
- 主题：tufte（理由：技术文档友好）
- 版式宽度：regular（默认值）
- 配图模式：placeholders（理由：无需用户自行准备图片）
- 封面：开（理由：默认提供书封式封面）

下面逐项请你确认。

AskQuestion Tool Schema

When available, the tool sends structured decision objects:

{
  "questions": [
    {
      "id": "article_type",
      "text": "请选择文章类型（包括默认信息保留比例）",
      "options": ["longform·~100%", "tutorial·~90%", "briefing·~50%"]
    },
    {
      "id": "theme",
      "text": "请选择主题",
      "options": ["tufte", "press", "custom"]
    },
    {
      "id": "layout_width",
      "text": "请选择版式宽度",
      "options": ["narrow", "regular", "wide", "full"]
    },
    {
      "id": "image_mode",
      "text": "请选择配图模式",
      "options": ["none", "user-assets", "placeholders", "ai-generated"]
    },
    {
      "id": "cover",
      "text": "是否开启封面？",
      "options": ["开", "关"]
    }
  ]
}

Updated Plan After Confirmation

Once decisions are collected, plan/plan.md contains concrete values:

## Brief

- 文章类型: tutorial·~90%
- 版式宽度: wide
- TOC: 开
- 配图模式: user-assets
- 封面: 关

## Outline

...

## Theme

press

## Assets

image_mode: user-assets
...

Key Source Files and References

The Plan Checkpoint implementation spans multiple reference files in the repository:

• skills/beautiful-article/SKILL.md: Master specification containing the full checkpoint description and opening template (lines 32-48).

• skills/beautiful-article/references/review-checklist.md: Contains the 5-item Plan self-check criteria used during the inline review step.

• skills/beautiful-article/references/plan-template.md: Template structure that the agent fills to produce plan/plan.md.

• skills/beautiful-article/references/article-types.md: Defines article type options and their default retention ratios.

• skills/beautiful-article/references/layout.md: Specifies layout width options and TOC handling rules.

• skills/beautiful-article/references/asset-policy.md: Documents the four image-mode options confirmed at the checkpoint.

• skills/beautiful-article/references/cover.md: Guidance for the optional cover component toggled during the checkpoint.

• scripts/scaffold.sh: CLI script executed in Phase 4 that reads the confirmed decisions from plan/plan.md to scaffold the project structure.

Summary

• The Plan Checkpoint is a mandatory stop at Phase 3 (Checkpoint 1) that prevents automated progression until user confirmation is received.

• It collects five specific decisions: article type, theme, layout width, image mode, and cover toggle, storing each in designated sections of plan/plan.md.

• The implementation supports both AskQuestion tool integration for rich UI experiences and plain-text fallback for compatibility.

• No silent defaults are permitted; the agent presents recommendations but requires explicit user selection for every parameter.

• These decisions drive the scaffold script (scripts/scaffold.sh) and determine component selection, layout behavior, and asset handling for all subsequent phases.

Frequently Asked Questions

What happens if the user doesn't answer all five questions?

The pipeline cannot proceed to Phase 4. The Plan Checkpoint enforces an immutable order and will not advance until all five answers are recorded in plan/plan.md. The agent remains in a waiting state, continuing to prompt for the remaining decisions.

Can decisions be changed after completing the checkpoint?

While the checkpoint itself validates completion before proceeding, modifications to plan/plan.md after Phase 3 would require restarting the workflow or manual editing. The checkpoint is designed as a commitment point to prevent scope drift during content generation.

What is the AskQuestion tool and why is it preferred?

AskQuestion is an environment-provided tool that enables structured question-answer flows with UI choice cards. It is preferred because it presents options natively within the interface rather than requiring users to parse plain-text lists, reducing input errors and improving the selection experience.

How do these five decisions affect the final article output?

The decisions act as configuration parameters for scripts/scaffold.sh and subsequent rendering phases. Article type determines content density and retention algorithms; theme controls CSS and typography; layout width sets the container constraints; image mode dictates asset sourcing; and the cover toggle determines whether to generate the book-cover style opening component.

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