Understanding the gsd-build XML Task Format: Why It's Optimized for Claude

The gsd-build XML task format uses strict XML markup inside PLAN.md files to define autonomous and human-in-the-loop steps, leveraging deterministic tokenization and schema enforcement to ensure Claude parses and executes tasks reliably without ambiguity.

The gsd-build system (also known as Get Shit Done) orchestrates complex software development workflows by describing every step in a machine-readable XML format. Unlike markdown or JSON plans that can introduce parsing ambiguities, the gsd-build XML task format is deliberately engineered to align with Claude's tokenization patterns, enabling deterministic execution of autonomous coding tasks and precise human checkpoint management.

What is the gsd-build XML Task Format?

At its core, the format lives within a PLAN.md file inside a <tasks> block that contains one or more <task> elements. Each task declares a type attribute that instructs Claude how to process the step—whether to execute autonomously or pause for human input.

The schema is defined in get-shit-done/templates/phase-prompt.md, which mandates that all task definitions use XML structure exclusively for Claude parsing【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/templates/phase-prompt.md#L60-L96】.

Task Types and Execution Semantics

The type attribute determines the execution mode:

• auto: Claude implements the code, runs verification commands, and marks the task complete without human intervention.
• checkpoint:decision: Claude presents options and pauses until the user selects a path and provides the resume signal.
• checkpoint:human-verify: Claude completes the implementation, starts any required servers, and waits for human approval before proceeding.
• checkpoint:human-action: Claude pauses for the user to perform a manual action (such as authentication) before resuming【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/references/checkpoints.md#L4-L10】.

Why XML is Optimized for Claude

The choice of XML over markdown or YAML is not arbitrary; it is a deliberate optimization for Claude's architecture and tokenization behavior.

Deterministic Tokenization

Claude's internal parser treats each XML tag as a distinct token, eliminating the ambiguities that markdown lists or code fences introduce. This deterministic tokenization ensures that the model's output remains stable and machine-readable, which is essential for automated plan execution【/cache/repos/github.com/gsd-build/get-shit-done/main/agents/gsd-planner.md#L77-L85】.

Strict Schema Enforcement

The <task> element defines a closed set of child tags such as <name>, <files>, <action>, <verify>, and <done>. Claude can verify that required fields are present before attempting execution, significantly reducing hallucinations and early-stage failures that often plague free-form text plans.

Hierarchical Nesting with Low Token Overhead

Checkpoint types are expressed as attribute values (e.g., type="checkpoint:decision"), allowing the executor to decide at runtime whether the plan is autonomous or must pause, without parsing free-form text. XML tags are short yet expressive, keeping the total token count low—a critical consideration for Claude's context window.

Human-Readable Yet Machine-Parseable

While optimized for Claude, the format remains legible to human team members who can read the plan in plain text. Simultaneously, Claude or any downstream tooling can reliably use standard XML parsing to extract structured data, bridging the gap between human planning and automated execution.

Practical Examples of gsd-build XML Tasks

The templates/phase-prompt.md file provides concrete examples of how tasks are structured in production plans.

Autonomous Implementation Task

<task type="auto">
  <name>Task 1: Add pagination to the users API</name>
  <files>src/api/users.ts, src/lib/pagination.ts</files>
  <action>Implement limit/offset parameters, update query builder, add tests.</action>
  <verify>Run `npm test src/api/users.test.ts` and ensure all pass.</verify>
  <done>Pagination works in the UI and test suite passes.</done>
</task>

Defined in get-shit-done/templates/phase-prompt.md lines 62-68【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/templates/phase-prompt.md#L60-L68】.

Decision Checkpoint

<task type="checkpoint:decision" gate="blocking">
  <decision>Which UI library should we use for the new dashboard?</decision>
  <context>We need a library that supports SSR and theming.</context>
  <options>
    <option id="option-a"><name>Chakra UI</name><pros>Simple theming</pros><cons>Large bundle</cons></option>
    <option id="option-b"><name>Radix + Tailwind</name><pros>Fine‑grained control</pros><cons>More setup</cons></option>
  </options>
  <resume-signal>Select: option-a or option-b</resume-signal>
</task>

See templates/phase-prompt.md lines 81-89【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/templates/phase-prompt.md#L81-L89】.

Human Verification Gate

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Dashboard UI is now live at http://localhost:3000/dashboard</what-built>
  <how-to-verify>Visit the URL and confirm the layout matches the mockup; no console errors.</how-to-verify>
  <resume-signal>Type "approved" or describe issues</resume-signal>
</task>

Defined in templates/phase-prompt.md lines 91-95【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/templates/phase-prompt.md#L91-L95】.

Key Implementation Files

The gsd-build XML task format is implemented across several critical files in the gsd-build/get-shit-done repository:

File	Role
get-shit-done/templates/phase-prompt.md	Defines the full XML task schema used in every PLAN.md. Contains the <tasks> block, example <task> elements, and the rule "Always use XML structure for Claude parsing"【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/templates/phase-prompt.md#L60-L96】【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/templates/phase-prompt.md#L461-L496】
agents/gsd-planner.md	Explains how the planner reads the XML, converts it into front-matter fields, and why the deterministic format is essential for Claude's planning logic【/cache/repos/github.com/gsd-build/get-shit-done/main/agents/gsd-planner.md#L77-L85】
references/checkpoints.md	Describes the semantics of each checkpoint type (human-verify, human-action, decision) and how Claude creates, pauses, and resumes around them【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/references/checkpoints.md#L4-L10】【/cache/repos/github.com/gsd-build/get-shit-done/main/get-shit-done/references/checkpoints.md#L31-L39】
agents/gsd-executor.md	Shows how the executor reads the XML tasks, runs the <action>/<verify> commands, and respects the gate="blocking" attribute.

Summary

• The gsd-build XML task format uses strict XML markup inside PLAN.md files to define autonomous and checkpoint-based workflow steps.
• The format leverages deterministic tokenization to ensure Claude parses each tag as a distinct token, eliminating the ambiguities of markdown or JSON.
• Four primary task types exist: auto for fully autonomous execution, and three checkpoint variants (checkpoint:decision, checkpoint:human-verify, checkpoint:human-action) for human-in-the-loop control.
• The schema is enforced through specific child tags like <name>, <files>, <action>, <verify>, and <done>, reducing hallucinations and execution failures.
• Implementation files including templates/phase-prompt.md, agents/gsd-planner.md, and references/checkpoints.md define the complete specification and execution semantics.

Frequently Asked Questions

What makes the gsd-build XML format more reliable than markdown for Claude?

The gsd-build XML format treats each tag as a distinct token during Claude's parsing phase, which eliminates the structural ambiguities that markdown lists or code fences can introduce. This deterministic tokenization ensures that Claude consistently interprets the plan structure without variation between runs, making the format both machine-readable and execution-stable.

How does Claude handle the different checkpoint types in the XML task format?

Claude processes checkpoint types by reading the type attribute and entering specific execution modes: for checkpoint:decision, Claude formats the <options> elements and waits for user selection; for checkpoint:human-verify, Claude starts any required services, displays the <what-built> description, and pauses for the <resume-signal>; and for checkpoint:human-action, Claude creates an authentication or setup gate and resumes only after the user reports successful completion of the manual step.

Can the gsd-build XML format be used with other AI models besides Claude?

While the gsd-build XML format is specifically optimized for Claude's tokenization patterns and planning logic as described in agents/gsd-planner.md, the structured XML schema is theoretically parseable by any system with XML capabilities. However, the deterministic execution guarantees and checkpoint semantics are specifically tuned to Claude's architecture, meaning other models would need custom adapters to achieve the same level of reliable orchestration.

Where is the formal schema for the gsd-build XML task format defined?

The formal schema and canonical examples are defined in get-shit-done/templates/phase-prompt.md, which specifies the required <tasks> block structure, valid <task> attributes like type and gate, and mandatory child elements such as <name>, <action>, and <verify>. Additional semantic details for checkpoint types are documented in references/checkpoints.md, while the planning logic that consumes this schema is described in agents/gsd-planner.md.

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