How GSD's XML Plan Structure Makes Claude Execute Without Guessing or Interpretation

Apr 21, 2026

When I first looked at GSD’s plan files, I noticed something unusual. They weren’t using markdown lists or numbered steps. They were using XML. Why would a plan format use XML when markdown is so much more readable?

The answer became clear when I understood how Claude executors work. XML structure eliminates interpretation. No guessing. No “I think this means…”

Why XML Not Markdown Lists

Markdown is great for humans. But for AI executors, it requires interpretation. When Claude sees “Step 1: Create login endpoint,” it has to understand that this is a task, parse what needs to be done, and figure out the details.

XML provides explicit boundaries. Each element has a clear purpose. Claude parses directly - no interpretation layer needed.

Here’s what a GSD task element looks like:

<task>
  <name>create-login-endpoint</name>
  <files>
    <file>src/auth/routes.py</file>
    <file>src/auth/handlers.py</file>
  </files>
  <action>
    Create POST /auth/login endpoint:
    - Accept email and password in request body
    - Validate credentials against database
    - Return JWT token on success
    - Return 401 on failure
  </action>
  <verify>
    pytest tests/auth/test_login.py -v
  </verify>
  <done>
    Login endpoint returns valid JWT for correct credentials
    Login endpoint returns 401 for invalid credentials
    All tests pass
  </done>
</task>

Notice what’s explicit:

name: Task identifier - no guessing what this task is called
files: Target files - Claude knows exactly where to write code
action: Implementation instructions - specific, not vague
verify: Automated command - run this to check work
done: Success definition - clear criteria for completion

Plan Frontmatter

Each plan starts with YAML frontmatter that tells the executor how to run it:

---
phase: implementation
plan: user-authentication
type: feature
autonomous: true
wave: 2
depends_on:
  - database-setup
  - user-model
---

The executor parses this to determine:

Which phase this plan belongs to
What other plans it depends on
Whether it can run autonomously
Which execution wave it’s in

No reading between lines. Just parse and execute.

Context References

Plans use @-references to load context. This keeps the executor lean:

## Context

@src/auth/models.py
@docs/api-spec.md

The executor loads only what’s referenced. No bloated context with irrelevant files. Fresh 200k context window stays focused.

Verification Built In

Every task has a <verify> element. After implementation, the executor runs this:

<verify>
  pytest tests/auth/test_login.py -v
</verify>

This isn’t optional. It’s part of the task definition. The executor implements, then verifies. If verification fails, it knows something went wrong.

No manual “Did this work?” questions. The plan includes the check.

2-3 Tasks Per Plan

GSD plans stay small. Two or three tasks maximum. Why?

Because large plans degrade in execution. As context fills up, responses get worse. The “I’ll be more concise now” problem appears.

Small plans mean:

Fresh context for each execution
No degradation
Complete focus on the task at hand

Here’s a complete plan example:

---
phase: implementation
plan: user-authentication
type: feature
autonomous: true
wave: 2
depends_on:
  - database-setup
---

## Objective

Implement user login with JWT authentication.

## Context

@src/auth/models.py
@src/database/connection.py

<task>
  <name>create-login-endpoint</name>
  <files>
    <file>src/auth/routes.py</file>
    <file>src/auth/handlers.py</file>
  </files>
  <action>
    Create POST /auth/login endpoint:
    - Accept email and password
    - Validate credentials
    - Return JWT on success
  </action>
  <verify>
    pytest tests/auth/test_login.py -v
  </verify>
  <done>
    Login returns valid JWT for correct credentials
    Login returns 401 for invalid credentials
  </done>
</task>

<task>
  <name>add-jwt-middleware</name>
  <files>
    <file>src/middleware/auth.py</file>
  </files>
  <action>
    Create JWT validation middleware:
    - Extract token from Authorization header
    - Verify token signature
    - Add user_id to request context
  </action>
  <verify>
    pytest tests/middleware/test_auth.py -v
  </verify>
  <done>
    Middleware validates valid tokens
    Middleware rejects invalid tokens
    Protected routes receive user_id
  </done>
</task>

## Verification

All tests pass:
- pytest tests/auth/ -v
- pytest tests/middleware/ -v

How Executors Parse Plans

From the GSD documentation, executors follow a specific parsing sequence:

Parse frontmatter: Extract phase, plan, type, autonomous, wave, depends_on
Parse objective: Understand what needs to be accomplished
Parse context: Load all @-referenced files
Parse tasks: Extract each task element with its components
Parse verification: Get success criteria

The executor then implements each task, running verification after each one. If a plan references CONTEXT.md, the executor honors the user’s vision throughout execution.

No interpretation. No guessing. Parse, implement, verify, done.

Summary

In this post, I explained how GSD’s XML plan structure enables precise execution without interpretation. Each task has explicit name, files, action, verify, and done sections. Plans include frontmatter for execution metadata. Context references keep executors lean. Verification is built into every task. Plans stay small with 2-3 tasks to avoid context degradation.

The key insight: GSD treats plans as prompts, not documents. XML structure lets Claude parse directly and execute precisely. No reading between lines required.

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!