name	checkpoint-approval
description	Manage user approval checkpoints with proper waiting and flag creation
allowed-tools	Bash, Write, Read

Checkpoint Approval Skill

Purpose: Enforce user approval checkpoints with proper presentation, waiting, flag creation, and state transitions.

Performance: Prevents checkpoint bypasses, ensures user control over critical transitions

When to Use This Skill

✅ Use checkpoint-approval When:

Transitioning from SYNTHESIS → IMPLEMENTATION (plan approval)
Transitioning from AWAITING_USER_APPROVAL → COMPLETE (change approval)
Need to present plan/changes and wait for explicit approval
Want to enforce mandatory checkpoint protocol

❌ Do NOT Use When:

User already approved (flag exists)
In bypass mode (user explicitly requested skip)
Simple clarification questions (use AskUserQuestion)
Not at a checkpoint transition

What This Skill Does

1. Presents Information

For Plan Approval (SYNTHESIS → IMPLEMENTATION):

## Implementation Plan

[Shows synthesized plan from task.md]

### Stakeholder Requirements Summary:
- Architect: [key points]
- Tester: [key points]
- Formatter: [key points]

### Implementation Approach:
[planned approach]

### Agents to Invoke:
- architect (code implementation)
- tester (test creation)
- formatter (documentation/style)

⚠️ **APPROVAL REQUIRED**: Please review and approve to proceed.

For Change Approval (AWAITING_USER_APPROVAL → COMPLETE):

## Changes Ready for Merge

### Commit SHA: abc1234

### Changes Summary:
```bash
git diff --stat main...{task-branch}

Files Modified:

[list of changed files]

Validation Results:

✅ Build: PASSED
✅ Tests: PASSED
✅ Checkstyle: PASSED
✅ PMD: PASSED

⚠️ APPROVAL REQUIRED: Please review changes and approve merge to main.


### 2. Waits for Approval

```bash
# Skill STOPS and waits for user to respond with:
- "approved"
- "proceed"
- "looks good"
- "LGTM"
- "merge it"

# Does NOT proceed on:
- Silence
- Ambiguous responses
- Questions

3. Creates Approval Flag

After explicit approval:

# For plan approval:
touch /workspace/tasks/{task-name}/user-approved-synthesis.flag

# For change approval:
touch /workspace/tasks/{task-name}/user-approved-changes.flag

4. Transitions State

# For plan approval:
jq '.state = "IMPLEMENTATION"' task.json > tmp.json
mv tmp.json task.json

# For change approval:
jq '.state = "COMPLETE"' task.json > tmp.json
mv tmp.json task.json

Usage

Plan Approval Checkpoint

# After SYNTHESIS phase completes
TASK_NAME="implement-formatter-api"

# Invoke checkpoint-approval skill with plan type
/workspace/main/.claude/scripts/checkpoint-approval.sh \
  --task "$TASK_NAME" \
  --type "plan" \
  --plan-file "/workspace/tasks/$TASK_NAME/task.md"

Change Approval Checkpoint

# After VALIDATION phase passes
TASK_NAME="implement-formatter-api"

# Invoke checkpoint-approval skill with changes type
/workspace/main/.claude/scripts/checkpoint-approval.sh \
  --task "$TASK_NAME" \
  --type "changes" \
  --branch "{task-name}"

Approval Detection

Valid Approval Phrases

Affirmative:

"approved"
"proceed"
"looks good"
"LGTM"
"merge it"
"go ahead"
"approve"
"yes"

NOT Valid:

Silence (no response)
"ok" (too ambiguous)
Questions about the plan
Requests for changes
Partial approval ("mostly good but...")

Safety Features

Prevents Bypass

✅ Blocks state transition without flag
✅ Hook enforces flag presence
✅ No timeout (waits indefinitely)
✅ No assumption of approval

Clear Communication

✅ Explicitly states "APPROVAL REQUIRED"
✅ Shows what user is approving
✅ Waits for clear affirmative response
✅ Confirms approval received

State Machine Integration

✅ Validates current state before checkpoint
✅ Creates flag before transition
✅ Transitions state after flag created
✅ Hook validates flag exists

Workflow Integration

Checkpoint 1: Plan Approval

CLASSIFIED state
  ↓
Requirements gathered (3 agent reports)
  ↓
SYNTHESIS state: Plan created in task.md
  ↓
[checkpoint-approval skill invoked] ← STOPS HERE
  ↓
Present plan to user
  ↓
Wait for explicit approval
  ↓
User says "approved"
  ↓
Create user-approved-synthesis.flag
  ↓
Transition to IMPLEMENTATION state
  ↓
Invoke implementation agents

Checkpoint 2: Change Approval

IMPLEMENTATION state
  ↓
Agents implement, merge to task branch
  ↓
VALIDATION state: Build and test
  ↓
All validation passes
  ↓
AWAITING_USER_APPROVAL state
  ↓
[checkpoint-approval skill invoked] ← STOPS HERE
  ↓
Present changes to user (diff, commit SHA)
  ↓
Wait for explicit approval
  ↓
User says "approved"
  ↓
Create user-approved-changes.flag
  ↓
Transition to COMPLETE state
  ↓
Squash and merge to main

Output Format

Skill returns JSON after approval received:

{
  "status": "approved",
  "checkpoint_type": "plan",
  "task_name": "implement-formatter-api",
  "flag_created": "/workspace/tasks/implement-formatter-api/user-approved-synthesis.flag",
  "state_transition": "SYNTHESIS → IMPLEMENTATION",
  "approval_phrase": "approved",
  "timestamp": "2025-11-11T12:34:56-05:00"
}

Related Skills

gather-requirements: Precedes plan approval checkpoint
task-cleanup: Follows change approval checkpoint
git-merge-linear: Executes after change approval

Troubleshooting

User Says "ok" Instead of "approved"

# "ok" is too ambiguous, re-prompt:
"I need explicit approval to proceed. Please respond with
'approved', 'proceed', or 'looks good' if you approve the plan."

User Asks Question Instead of Approving

# Answer question, then re-prompt for approval:
"[Answer to question]

Does this address your concern? If so, please approve with
'approved' or 'proceed' to continue."

User Silent (No Response)

# DO NOT proceed, wait indefinitely
# After reasonable time (5+ minutes), prompt:
"Waiting for approval to proceed. Please review the plan above
and respond with 'approved' if you'd like to proceed."

Hook Blocks Despite Flag Present

# Verify flag exists:
ls -la /workspace/tasks/{task-name}/*-flag

# Check flag permissions:
test -r /workspace/tasks/{task-name}/user-approved-synthesis.flag
echo $? # Should be 0

# Verify state matches:
jq -r '.state' /workspace/tasks/{task-name}/task.json

Common Mistakes to Avoid

❌ Assuming Silence = Approval

# WRONG:
"User hasn't objected, proceeding with implementation..."

# CORRECT:
"Waiting for user approval. No response yet, continuing to wait..."

❌ Proceeding on Ambiguous Response

# WRONG:
User: "sure"
Agent: [Creates flag and proceeds]

# CORRECT:
User: "sure"
Agent: "To confirm, are you approving the plan? Please respond
with 'approved' or 'proceed' to continue."

❌ Creating Flag Before Presenting

# WRONG:
1. Create flag
2. Transition state
3. Present plan to user

# CORRECT:
1. Present plan to user
2. Wait for approval
3. Create flag
4. Transition state

❌ Skipping Checkpoint for "Simple" Tasks

# WRONG:
"This is a straightforward task, skipping approval..."

# CORRECT:
"Presenting plan for approval (required for all tasks)..."

Implementation Notes

The checkpoint-approval script performs:

Presentation Phase
- Load plan/changes from appropriate source
- Format for user review
- Display with clear approval request
Waiting Phase
- Block execution (no timeout)
- Monitor for user response
- Validate response is affirmative
Approval Phase
- Create flag file
- Update task.json state
- Return success status
Verification Phase
- Confirm flag readable
- Confirm state updated
- Log approval event

checkpoint-approval

Install Skill

SKILL.md