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

> Discover how the Plan Checkpoint in the beautiful-article skill works. This guide details Phase 3, explaining how user decisions shape content generation before scaffolding begins.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: deep-dive
- Published: 2026-08-28

---

**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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md) and drives the behavior of [`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md)
- **Reference file**: [`skills/beautiful-article/references/article-types.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/theme-profiles/index.json) (e.g., `tufte`, `press`)
- **Storage location**: **Theme** subsection of [`plan/plan.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md) using the template defined in [`skills/beautiful-article/references/plan-template.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md) in the specified order.

## Practical Code Examples

### Initial Plan State Before Checkpoint

The agent generates [`plan/plan.md`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md) with placeholders that must be resolved:

```markdown

## Brief

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

## Outline

...

## Theme

<placeholder>

## Assets

...

```

### Checkpoint Prompt Structure

The agent presents recommendations without applying them:

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

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

下面逐项请你确认。

```

### AskQuestion Tool Schema

When available, the tool sends structured decision objects:

```json
{
  "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`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md) contains concrete values:

```markdown

## 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/plan-template.md)**: Template structure that the agent fills to produce [`plan/plan.md`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md).

- **[`skills/beautiful-article/references/article-types.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/article-types.md)**: Defines article type options and their default retention ratios.

- **[`skills/beautiful-article/references/layout.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/layout.md)**: Specifies layout width options and TOC handling rules.

- **[`skills/beautiful-article/references/asset-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/asset-policy.md)**: Documents the four image-mode options confirmed at the checkpoint.

- **[`skills/beautiful-article/references/cover.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/cover.md)**: Guidance for the optional cover component toggled during the checkpoint.

- **[`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/scaffold.sh)**: CLI script executed in Phase 4 that reads the confirmed decisions from [`plan/plan.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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.