Hard Collaboration Checkpoints in Garden Skills: Enforcing Mandatory User Approval Gates

Hard collaboration checkpoints in Garden Skills are mandatory pause points embedded in skill contracts that require explicit user confirmation before LLM agents can proceed past critical decision phases, preventing silent defaults and bundled approvals.

Garden Skills implements a "skill-as-harness" architecture where hard collaboration checkpoints act as non-negotiable gates within AI-driven workflows. These checkpoints ensure that agents operating skills like beautiful-article and web-video-presentation never advance past critical phases without obtaining independent user confirmation for each decision, as strictly defined in the skill contracts and SKILL.md files.

What Defines a "Hard" Collaboration Checkpoint

A checkpoint is classified as "hard" when the skill contract explicitly annotates it with "★ Checkpoint X — must pause". This annotation creates a binding requirement that the agent must await a user response before generating any downstream artefacts or transitioning to the next phase.

The enforcement mechanism relies on two strict rules documented in the source contracts. First, the agent is prohibited from silently defaulting to any choice when a checkpoint is reached. Second, decisions must be gathered independently—bundling multiple yes/no questions into a single prompt is explicitly forbidden according to the skill contracts found in skills/beautiful-article/SKILL.md (lines 36-40) and skills/web-video-presentation/SKILL.md (lines 33-38).

Hard Checkpoints by Skill Module

Garden Skills implements phase-oriented workflows where checkpoints sit between numbered phases. The specific implementation varies by skill, with each defining its own critical gates.

beautiful-article Checkpoints

The beautiful-article skill defines three hard checkpoints that govern the article generation pipeline:

• Plan Checkpoint (Phase 2 → Checkpoint 1): Fires after the agent generates plan.md containing article type, theme, layout width, image policy, and cover settings. Users must approve five independent decisions one-by-one, as documented in skills/beautiful-article/README.md (lines 46-48).

• First-Spread Checkpoint (Phase 4 → Checkpoint 2): Activates after the first-spread proof (cover, hero, and first section) is built. The user must accept the visual proof and select the development mode (A/B) before proceeding, per lines 61-63 of the README.

• Delivery Checkpoint (Phase 8 → Checkpoint 3): Triggers before final HTML or PDF emission. The user decides between delivery formats (HTML only, HTML + PDF, or pause for revision) according to lines 71-73.

web-video-presentation Checkpoints

The web-video-presentation skill implements a similar gate system tailored for video production workflows:

• Script/Theme/Asset Plan (Phase 1.2 → Checkpoint A1): Fires after the script becomes an outline with a rough asset plan. Requires confirmation of script, chosen theme, and high-level asset strategy (lines 47-49 in README.md).

• Outline Approval & Development Mode (Phase 1.3 → Checkpoint A2): Activates when outline.md is ready. The user must approve the outline and choose a development mode (e.g., "dev-mode-A" vs "dev-mode-B") per lines 51-53.

• Audio Synthesis Decision (Phase 2 → Checkpoint B): Occurs after visual outline approval. The user decides whether to synthesize narration audio (yes/no) as specified in lines 55-57.

Architectural Implementation

Phase-Oriented State Management

The checkpoint system operates within a phase-oriented workflow where each skill is split into numbered phases. The agent's state machine reads the current phase, renders the appropriate artefacts, then checks for a pending checkpoint flag. This architecture ensures that checkpoints sit explicitly between processing phases rather than occurring mid-computation.

The runtime uses a checkpoint detection utility to determine when to pause. In utils/checkpoint.ts, the system maps phases to their corresponding checkpoint requirements:

// utils/checkpoint.ts
export enum Checkpoint {
  Plan = 'plan',
  FirstSpread = 'first-spread',
  Delivery = 'delivery',
  Audio = 'audio',
}

/** Returns true if the current phase requires a user‑confirmed checkpoint */
export function needsCheckpoint(phase: string): Checkpoint | null {
  switch (phase) {
    case 'Phase 2': return Checkpoint.Plan;
    case 'Phase 4': return Checkpoint.FirstSpread;
    case 'Phase 8': return Checkpoint.Delivery;
    case 'Phase 2 (web-video)': return Checkpoint.Audio;
    default: return null;
  }
}

Skill Contract Configuration

Each skill declares its hard checkpoints in its manifest file, allowing the runtime to enforce pause logic without hardcoding skill-specific logic. The beautiful-article skill defines its gates in manifest.json:

// skills/beautiful-article/manifest.json
{
  "name": "beautiful-article",
  "description": "Turn any source into a beautiful article",
  "hard_checkpoints": [
    "plan",          // ★ Checkpoint 1 – 5 independent decisions
    "first-spread", // ★ Checkpoint 2 – proof + dev‑mode
    "delivery"      // ★ Checkpoint 3 – final delivery format
  ]
}

Execution Patterns: Inline vs Sub-Agent

Garden Skills employs two distinct execution patterns when handling checkpoints, optimized for latency versus complexity.

Inline Self-Checks: The Plan Checkpoint uses an inline self-check performed by the main agent to maintain low latency. According to skills/beautiful-article/README.md (lines 42-45), no extra sub-agent process is spawned at this stage.

Sub-Agent Reviews: Later checkpoints like First-Spread and Final Review spawn specialized sub-agents that write review files to disk. The presence of files like review/first-spread-review.md or review/final-review.md signals that the checkpoint has been satisfied, as detailed in skills/beautiful-article/references/review-checklist.md (lines 12-15).

User Interaction Templates

When a checkpoint fires, the agent renders structured prompts that enforce independent decision gathering. The Plan Checkpoint uses a template stored in references/plan-template.md:

🛑 **Checkpoint 1 – Plan**  
We need to lock down the following decisions before we continue:

1️⃣ Article type (retention ratio)  
2️⃣ Theme  
3️⃣ Layout width (regular / wide)  
4️⃣ Image policy (none / user‑assets / placeholders)  
5️⃣ Cover (on / off)

Please answer **one line per item**, e.g.:

type: longform  
theme: tufte  
width: regular  
images: user‑assets  
cover: on

For sub-agent checkpoints, the system invokes review scripts that handle the validation workflow:

# Inside the skill scaffold (scripts/scaffold.sh)

bash $SKILL_ROOT/scripts/review-first-spread.sh ./my-article

# The script writes review/first-spread-review.md and then

# signals the main agent to resume after the checkpoint.

Source File Reference Architecture

The checkpoint system is distributed across contract files, reference documentation, and runtime utilities:

• skills/beautiful-article/README.md — Documents the three hard checkpoints (Plan, First-Spread, Delivery) with line-specific implementation details
• skills/beautiful-article/SKILL.md — Contains the formal skill contract with checkpoint IDs and "must pause" enforcement annotations
• skills/beautiful-article/references/review-checklist.md — Maps checkpoint IDs to their corresponding review files and sub-agent triggers
• skills/web-video-presentation/README.md — Outlines the three checkpoints (A1, A2, B) specific to video presentation workflows
• skills/web-video-presentation/SKILL.md — Defines the skill contract with checkpoint enforcement rules for video production
• skills/web-video-presentation/references/THEMES.md — Provides theme metadata used during the Plan checkpoint selection process

Summary

• Hard collaboration checkpoints enforce mandatory user confirmation at critical workflow phases, preventing agents from proceeding with unapproved decisions
• Each checkpoint requires independent decision gathering—bundling multiple questions into a single prompt is explicitly prohibited by the skill contracts
• The system uses a phase-oriented architecture where checkpoints sit between numbered phases, detected via the needsCheckpoint() utility in utils/checkpoint.ts
• Skill manifests declare hard checkpoints in the hard_checkpoints array, separating configuration from runtime logic
• Execution strategies vary by checkpoint complexity: Plan Checkpoints use inline self-checks for low latency, while First-Spread and Delivery Checkpoints employ sub-agents that write review files to signal completion
• Contract enforcement relies on explicit "★ Checkpoint X — must pause" annotations in SKILL.md files, creating binding constraints on agent behavior

Frequently Asked Questions

What distinguishes a "hard" checkpoint from a soft confirmation in Garden Skills?

Hard collaboration checkpoints enforce a complete pause of the agent workflow and require explicit user input before any downstream artefacts are generated or state transitions occur. Soft confirmations, by contrast, might allow the agent to continue with logged assumptions or default values. The distinction is enforced by the skill contract's "★ must pause" annotation and the runtime's refusal to proceed without user file markers.

Can an LLM agent bypass hard collaboration checkpoints programmatically?

No, according to the skill contracts defined in files like skills/beautiful-article/SKILL.md and skills/web-video-presentation/SKILL.md, checkpoints marked with the "★" symbol are binding constraints. The agent architecture is designed to await specific user responses or the presence of review files (such as review/first-spread-review.md) before the state machine permits advancement to the next phase.

Why must decisions within a single checkpoint be asked independently?

Garden Skills mandates independent decision gathering to prevent user confusion and ensure explicit consent for each variable. Bundling questions—for example, asking the user to approve article type, theme, and layout width in a single combined prompt—violates the hard checkpoint specification found in the reference checklists and SKILL.md annotations, as each decision point represents a distinct contractual commitment.

How does the system determine whether to use an inline check or a sub-agent review?

The choice depends on checkpoint complexity and latency requirements. The Plan Checkpoint uses inline self-checks by the main agent to minimize latency, as noted in skills/beautiful-article/README.md. Complex validation checkpoints like First-Spread and Delivery spawn specialized sub-agents that perform detailed analysis and write their conclusions to disk (e.g., review/first-spread-review.md), with the main agent resuming only after detecting these completion markers.

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