> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gsd-build/get-shit-done/llms.txt
> Use this file to discover all available pages before exploring further.
# PLAN.xml Structure
> XML structure for executable plans with examples and tag explanations
Every GSD plan uses structured XML optimized for Claude to parse and execute. This format ensures precise instructions, clear verification steps, and deterministic execution.
## Why XML?
From the README:
> Every plan is structured XML optimized for Claude:
>
> * Precise instructions
> * No guessing
> * Verification built in
Claude excels at parsing and following XML-structured instructions. The format makes it impossible to miss required steps or skip verification.
## Plan File Structure
Plans live in `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` with YAML frontmatter and XML body.
### Complete Example
```markdown theme={null}
---
phase: 03-features
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [src/models/user.ts, src/api/users.ts]
autonomous: true
requirements: [AUTH-01, AUTH-02]
must_haves:
truths:
- "User can create account with email/password"
- "User session persists across browser refresh"
artifacts:
- path: "src/models/user.ts"
provides: "User model and types"
min_lines: 20
- path: "src/api/users.ts"
provides: "User CRUD endpoints"
exports: ["GET", "POST"]
key_links:
- from: "src/api/users.ts"
to: "src/models/user.ts"
via: "imports User type"
pattern: "import.*User.*from.*models/user"
---
Create user authentication system with signup and login.
Purpose: Enable users to create accounts and authenticate.
Output: User model, signup/login endpoints, session management.
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
Create User model
src/models/user.ts
Define User type with id, email, password (hashed), createdAt.
Use jose for JWT (not jsonwebtoken - CommonJS issues).
Export TypeScript interface and Zod schema for validation.
tsc --noEmit passes without errors
User type exported and usable
Create signup endpoint
src/app/api/auth/signup/route.ts
POST endpoint that:
1. Validates email format and password strength
2. Hashes password with bcrypt (cost factor 12)
3. Creates user in database
4. Returns JWT token in httpOnly cookie
Error handling:
- 400 if validation fails
- 409 if email already exists
- 500 for database errors
curl -X POST localhost:3000/api/auth/signup -d '{"email":"test@example.com","password":"Test123!"}' returns 201 + Set-Cookie
Signup works with valid input, rejects invalid input
Create login endpoint
src/app/api/auth/login/route.ts
POST endpoint that:
1. Validates credentials against users table
2. Compares password with bcrypt.compare
3. Returns JWT token in httpOnly cookie on success
4. Returns 401 on invalid credentials
Avoid timing attacks: use constant-time comparison.
curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie with valid creds, 401 with invalid
Valid credentials return cookie, invalid return 401
Before declaring plan complete:
- [ ] npm run build succeeds
- [ ] All endpoints respond correctly
- [ ] TypeScript types are properly exported
- [ ] No console errors or warnings
- All tasks completed
- All verification checks pass
- No errors or warnings introduced
- JWT authentication working end-to-end
```
## Frontmatter Fields
YAML frontmatter provides metadata for the orchestrator:
```yaml theme={null}
phase: 03-features # Phase identifier
plan: 01 # Plan number within phase
type: execute # Plan type (execute or tdd)
wave: 1 # Execution wave (1, 2, 3...)
depends_on: [] # Plan IDs this requires (e.g., ["01-01"])
files_modified: [...] # Files this plan touches
autonomous: true # false if has checkpoints
requirements: [AUTH-01] # Requirement IDs from ROADMAP
must_haves: # Goal-backward verification
truths: [...] # Observable behaviors
artifacts: [...] # Files that must exist
key_links: [...] # Critical connections
```
### Key Fields Explained
**wave** - Pre-computed execution wave:
* Wave 1: Independent plans run in parallel
* Wave 2: Plans depending on Wave 1
* Wave 3+: Further dependencies
**depends\_on** - Explicit dependencies:
* `[]` - No dependencies, can run in Wave 1
* `["01-01"]` - Requires plan 01-01 complete
* `["01-01", "01-02"]` - Requires both plans
**autonomous** - Checkpoint indicator:
* `true` - Fully autonomous, no user interaction
* `false` - Has checkpoints requiring user input
**must\_haves** - Verification criteria:
* Used by verification subagent after execution
* Ensures goal achievement, not just task completion
## XML Tags
### ``
**Purpose:** What this plan accomplishes and why.
**Structure:**
```xml theme={null}
[One-line description of what gets built]
Purpose: [Why this matters for the project]
Output: [What artifacts will be created]
```
**Example:**
```xml theme={null}
Build responsive dashboard with user and product data.
Purpose: Provide unified view of system state for admin users.
Output: Dashboard component with data fetching and layout.
```
### ``
**Purpose:** Workflow and template references.
**Structure:**
```xml theme={null}
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
[If plan has checkpoints:]
@~/.claude/get-shit-done/references/checkpoints.md
```
These files guide Claude's execution behavior.
### ``
**Purpose:** Project files and prior work to read.
**Structure:**
```xml theme={null}
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
[Only include if genuinely needed:]
@.planning/phases/XX-name/XX-YY-SUMMARY.md
[Relevant source files:]
@src/path/to/relevant.ts
```
**Important:** Don't reflexively chain summaries. Only reference prior work if:
* This plan imports types/exports from prior plan
* Prior plan made decision affecting this plan
* Prior plan's output is input to this plan
### ``
**Purpose:** Container for all task elements.
**Structure:**
```xml theme={null}
...
...
...
```
### ``
**Purpose:** Fully autonomous task Claude executes.
**Structure:**
```xml theme={null}
[Action-oriented name]
[comma-separated file paths]
[Specific implementation details]
[What to do]
[How to do it]
[What to avoid and WHY]
[Command or check to prove it worked]
[Measurable acceptance criteria]
```
**Example from README:**
```xml theme={null}
Create login endpoint
src/app/api/auth/login/route.ts
Use jose for JWT (not jsonwebtoken - CommonJS issues).
Validate credentials against users table.
Return httpOnly cookie on success.
curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie
Valid credentials return cookie, invalid return 401
```
#### `` Tag
**Purpose:** Clear, action-oriented task name.
**Format:** `[Verb] [noun]` or `[Verb] [noun]: [specifics]`
**Good examples:**
* `Create User model`
* `Implement password hashing`
* `Add error handling to login endpoint`
**Bad examples:**
* `User model` (not action-oriented)
* `Authentication` (too vague)
* `Task 1` (meaningless)
#### `` Tag
**Purpose:** Which files this task creates or modifies.
**Format:** Comma-separated paths relative to project root.
**Examples:**
```xml theme={null}
src/models/user.ts
src/api/users.ts, src/api/auth.ts
src/components/Dashboard.tsx, src/styles/dashboard.css
```
#### `` Tag
**Purpose:** Specific implementation instructions.
**Include:**
* What to build
* How to build it
* What to avoid and WHY
* Technology choices
* Error handling requirements
**Example:**
```xml theme={null}
Create POST endpoint at /api/auth/signup that:
1. Validates email format with Zod schema
2. Checks password strength (min 8 chars, uppercase, number, symbol)
3. Hashes password with bcrypt (cost factor 12)
4. Creates user in database via Prisma
5. Returns JWT in httpOnly cookie
Error responses:
- 400 for validation failures (clear error message)
- 409 if email already exists
- 500 for database errors (log details, return generic message)
Use jose for JWT, NOT jsonwebtoken (CommonJS issues in Next.js).
```
#### `` Tag
**Purpose:** Command or check to prove the task worked.
**Format:** Executable command or manual check.
**Examples:**
```xml theme={null}
npm run build succeeds
tsc --noEmit passes without errors
curl -X POST localhost:3000/api/users returns 201
Open http://localhost:3000/dashboard and see user list
```
#### `` Tag
**Purpose:** Measurable acceptance criteria.
**Format:** Observable outcome that proves task complete.
**Examples:**
```xml theme={null}
User type exported and usable in other files
Valid credentials return JWT cookie, invalid return 401
Dashboard renders without errors and displays data
```
### Checkpoint Tasks
**Purpose:** Tasks requiring user interaction.
**Types:**
* `checkpoint:decision` - User makes implementation choice
* `checkpoint:human-verify` - User verifies visual/functional output
* `checkpoint:human-action` - User performs manual step
**Example:**
```xml theme={null}
Dashboard component - server running at http://localhost:3000
Visit http://localhost:3000/dashboard and verify:
- Desktop: 3-column grid layout
- Mobile: Single column stack
- No horizontal scroll
- Data loads without errors
Type "approved" or describe issues
```
**Important:** Claude starts dev server BEFORE human-verify checkpoints. User only visits URLs.
### ``
**Purpose:** Final checks before declaring plan complete.
**Structure:**
```xml theme={null}
Before declaring plan complete:
- [ ] [Specific test command]
- [ ] [Build/type check passes]
- [ ] [Behavior verification]
```
**Example:**
```xml theme={null}
Before declaring plan complete:
- [ ] npm run build succeeds
- [ ] npm test passes all tests
- [ ] TypeScript has no errors
- [ ] All endpoints return expected status codes
- [ ] No console errors or warnings
```
### ``
**Purpose:** Overall plan success definition.
**Structure:**
```xml theme={null}
- All tasks completed
- All verification checks pass
- No errors or warnings introduced
- [Plan-specific criteria]
```
### `