How to Execute GSD Plans with Atomic Commits, Checkpoints, and Wave Parallelization

Apr 21, 2026

I wanted to understand how GSD’s /gsd-execute-phase command actually works under the hood. After running several phases, I learned that it uses wave parallelization, atomic commits, automatic deviation handling, and checkpoint protocols. Here’s what I found.

How Execution Starts

When I run /gsd-execute-phase 1, the system loads the project state and parses all plan files in that phase. It then determines the execution pattern based on dependencies between plans.

/gsd-execute-phase 1

# Output:
# Loading project state...
# Parsing 4 plans in phase 1
# Analyzing dependencies...
# Grouping into 3 waves

Wave Execution: Plans Run in Parallel

The system groups plans into waves based on their dependencies. Independent plans run together in parallel.

Wave 1: Plans with no dependencies run first Wave 2: Plans that depend on Wave 1 results Wave 3: Plans that depend on Wave 2 results

Each wave only starts after the previous one completes successfully.

Wave 1 (parallel):
  - plan-001-setup-database.md
  - plan-002-create-schemas.md
  - plan-003-config-environment.md

Wave 2 (parallel):
  - plan-004-implement-api.md (depends on 001, 002)
  - plan-005-add-auth.md (depends on 001)

Wave 3 (parallel):
  - plan-006-integrate-frontend.md (depends on 004, 005)

I noticed that each executor agent gets a fresh 200k context window. This means the agent has clean context without baggage from previous tasks.

Per-Task Atomic Commits

Every task gets its own git commit immediately after completion. This was different from what I expected—I thought commits would happen at the end of each plan.

a3f2c1b feat(api): add user registration endpoint
d4e5f6a test(api): add registration tests
b7c8d9e refactor(api): extract validation logic
e1f2a3b docs(api): update API documentation

The benefits I observed:

Git bisect finds the exact failing task
Each task is independently revertable
Clean history makes it easy for future Claude sessions to understand what happened

Deviation Handling: 5 Types

The executor handles deviations automatically. I found 5 deviation types in the code:

Add missing: Add critical functionality the plan missed
Fix broken: Repair broken dependencies or imports
Remove redundant: Delete duplicate or unused code
Change approach: Switch to a better implementation path
Escalate blocker: Pause and ask for help when stuck

[Executor] Task 3: Implement caching
[Deviation] Found existing cache module in utils/
[Action] Changed approach - using existing module
[Result] Task completed with better integration

I tested this by intentionally creating a plan that referenced a non-existent function. The executor detected this and added the missing function as a deviation.

Checkpoint Protocols: Pause for Approval

Plans can define checkpoints where execution pauses. I found three types:

Confirm checkpoints: Wait for user approval before proceeding Quality checkpoints: Run verification tests before continuing Safety checkpoints: Require security review for sensitive changes

## Phase 2: Database Migration

### Task 4: Run migrations
- Apply schema changes
- Migrate existing data

**CHECKPOINT: confirm** - Review migration results before proceeding

### Task 5: Update indexes
- Add new indexes
- Remove unused indexes

When the executor hits a checkpoint, it pauses and waits for my approval. I can review what happened and decide whether to continue or adjust.

SUMMARY.md Generation

Each plan produces a SUMMARY.md file documenting what happened. This is useful for understanding the execution after the fact.

# Execution Summary: plan-004-implement-api.md

## Plan Context
- Phase: 1
- Wave: 2
- Dependencies: plan-001, plan-002

## Execution Record
- Tasks completed: 5/5
- Duration: 4 minutes 32 seconds
- Commits created: 5

## Deviations
1. Added missing error handling in Task 2
2. Changed approach in Task 3 to use existing utils

## Verification Results
- All tests passing
- No lint errors
- Coverage: 87%

## Git History
- a3f2c1b feat(api): add user registration endpoint
- d4e5f6a test(api): add registration tests

I found these summaries helpful for understanding deviations and verifying that the execution matched my intent.

Walk Away, Come Back to Clean History

The main benefit I experienced: I could start a phase execution, walk away, and return to completed work with clean git history. Each commit is atomic and traceable.

git log --oneline --graph

* a3f2c1b feat(api): add user registration endpoint
* d4e5f6a test(api): add registration tests
* b7c8d9e refactor(api): extract validation logic
* e1f2a3b docs(api): update API documentation
* f4g5h6i feat(db): add user table
* g7h8i9j test(db): add user table tests

If something goes wrong, I can revert specific commits without affecting other work.

How to Run It

Starting phase execution is straightforward:

/gsd-execute-phase 1

# The system will:
# 1. Load all plans in phase 1
# 2. Group plans into waves
# 3. Execute each wave in parallel
# 4. Create atomic commits per task
# 5. Handle deviations automatically
# 6. Pause at checkpoints
# 7. Generate SUMMARY.md files

I can check progress anytime by looking at the git history or the SUMMARY.md files.

Summary

In this post, I explained how GSD’s /gsd-execute-phase command works. Plans are grouped into parallel waves based on dependencies, each task gets its own atomic commit, deviations are handled automatically with 5 types of fixes, checkpoints pause execution for approval, and SUMMARY.md files document everything. The result is clean git history and completed work I can walk away from and return to later.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!