From a97c567b01c0f1c9e0323224e2fd205fb4eda522 Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Tue, 13 Jan 2026 15:23:21 -0600
Subject: [PATCH] feat: add .claude/rules/ for auto-loaded contribution rules

Split GSD style guidance into:
- .claude/rules/style.md - global style rules (always loaded)
- .claude/rules/commands.md - path-scoped for commands/gsd/
- .claude/rules/workflows.md - path-scoped for workflows/
- .claude/rules/templates.md - path-scoped for templates/
- .claude/rules/references.md - path-scoped for references/
- GSD-STYLE.md - comprehensive reference for deep dives

Rules auto-load via Claude Code's .claude/rules/ feature (v2.0.64+).
Path-scoped rules only activate when editing matching files.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/rules/commands.md   |  64 ++++++
 .claude/rules/references.md |  36 +++
 .claude/rules/style.md      |  87 ++++++++
 .claude/rules/templates.md  |  48 ++++
 .claude/rules/workflows.md  |  46 ++++
 GSD-STYLE.md                | 430 ++++++++++++++++++++++++++++++++++++
 6 files changed, 711 insertions(+)
 create mode 100644 .claude/rules/commands.md
 create mode 100644 .claude/rules/references.md
 create mode 100644 .claude/rules/style.md
 create mode 100644 .claude/rules/templates.md
 create mode 100644 .claude/rules/workflows.md
 create mode 100644 GSD-STYLE.md

diff --git a/.claude/rules/commands.md b/.claude/rules/commands.md
new file mode 100644
index 000000000..d59a04e8e
--- /dev/null
+++ b/.claude/rules/commands.md
@@ -0,0 +1,64 @@
+---
+paths:
+  - "commands/gsd/**/*.md"
+---
+
+# Slash Command Rules
+
+Rules for editing files in `commands/gsd/`.
+
+## File Structure
+
+```yaml
+---
+name: gsd:command-name
+description: One-line description
+argument-hint: "<required>" or "[optional]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
+---
+```
+
+## Section Order
+
+1. `<objective>` — What/why/when (always present)
+2. `<execution_context>` — @-references to workflows, templates, references
+3. `<context>` — Dynamic content: `$ARGUMENTS`, bash output, @file refs
+4. `<process>` or `<step>` elements — Implementation steps
+5. `<success_criteria>` — Measurable completion checklist
+
+## Core Principle
+
+**Commands are thin wrappers.** Delegate detailed logic to workflows.
+
+Commands answer "what to do", workflows answer "how to do it".
+
+## @-Reference Patterns
+
+```markdown
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-phase.md
+@~/.claude/get-shit-done/templates/summary.md
+@~/.claude/get-shit-done/references/plan-format.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.planning/PROJECT.md
+@.planning/STATE.md
+</context>
+```
+
+- `execution_context`: Static resources (workflows, templates, references)
+- `context`: Dynamic project state and arguments
+
+## Success Criteria Format
+
+```xml
+<success_criteria>
+- [ ] Specific, measurable criterion
+- [ ] Another verifiable outcome
+</success_criteria>
+```
+
+Use checkbox format. Each criterion must be objectively verifiable.
diff --git a/.claude/rules/references.md b/.claude/rules/references.md
new file mode 100644
index 000000000..3a2cdabe7
--- /dev/null
+++ b/.claude/rules/references.md
@@ -0,0 +1,36 @@
+---
+paths:
+  - "get-shit-done/references/**/*.md"
+---
+
+# Reference File Rules
+
+Rules for editing files in `get-shit-done/references/`.
+
+## Outer Container Pattern
+
+References typically use an outer XML container related to the filename:
+
+- `principles.md` → `<principles>...</principles>`
+- `checkpoints.md` → `<overview>...</overview>` then `<checkpoint_types>...</checkpoint_types>`
+- `plan-format.md` → `<overview>...</overview>` then `<core_principle>...</core_principle>`
+
+Not a strict rule — check the file you're editing.
+
+## Internal Structure
+
+Internal organization varies. Common patterns:
+- Semantic sub-containers (`<solo_developer_claude>`, `<plans_are_prompts>`)
+- Markdown headers within XML
+- Code examples in fenced blocks
+
+## Teaching Patterns
+
+References often teach by contrast:
+- Show vague vs. specific examples
+- Explain WHY something is problematic
+- Provide concrete alternatives
+
+## Key Principle
+
+References explain concepts and patterns loaded by workflows/commands when relevant. Match the style of the specific reference you're editing.
diff --git a/.claude/rules/style.md b/.claude/rules/style.md
new file mode 100644
index 000000000..307ae9dc0
--- /dev/null
+++ b/.claude/rules/style.md
@@ -0,0 +1,87 @@
+# GSD Style Rules
+
+These rules apply to ALL files in this repository.
+
+## Language & Tone
+
+**Imperative voice.** "Execute tasks", "Create file" — not "Execution is performed"
+
+**No filler.** Absent: "Let me", "Just", "Simply", "Basically", "I'd be happy to"
+
+**No sycophancy.** Absent: "Great!", "Awesome!", "Excellent!", "I'd love to help"
+
+**Brevity with substance.** Good: "JWT auth with refresh rotation using jose library" Bad: "Phase complete"
+
+## Temporal Language Ban
+
+Never write: "We changed X to Y", "Previously", "No longer", "Instead of"
+
+Always: Describe current state only.
+
+Exception: CHANGELOG.md, git commits (their purpose IS tracking change)
+
+## Anti-Patterns
+
+### Enterprise Patterns (Banned)
+- Story points, sprint ceremonies, RACI matrices
+- Human dev time estimates (days/weeks)
+- Team coordination, knowledge transfer docs
+
+### Generic XML (Banned)
+Don't use: `<section>`, `<item>`, `<content>`
+
+Use semantic tags: `<objective>`, `<verification>`, `<action>`, `<process>`
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Files | kebab-case | `execute-phase.md` |
+| Commands | `gsd:kebab-case` | `gsd:execute-phase` |
+| Step names | snake_case | `name="load_project_state"` |
+| Bash variables | CAPS_UNDERSCORES | `PHASE_ARG` |
+| Type attributes | colon separator | `type="checkpoint:human-verify"` |
+
+## XML Conventions
+
+XML tags are semantic containers. Use Markdown headers for hierarchy within.
+
+```xml
+<!-- DO -->
+<objective>
+## Primary Goal
+Build authentication system
+
+## Success Criteria
+- Users can log in
+</objective>
+
+<!-- DON'T -->
+<section name="objective">
+  <subsection name="primary-goal">
+    <content>Build authentication</content>
+  </subsection>
+</section>
+```
+
+## @-References
+
+@-references are lazy loading signals — instructions to read, not pre-loaded content.
+
+```
+@~/.claude/get-shit-done/workflows/execute-phase.md  # Static (always load)
+@.planning/DISCOVERY.md (if exists)                   # Conditional
+```
+
+## Commit Format
+
+```
+{type}({phase}-{plan}): {description}
+```
+
+Types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`
+
+Rules:
+- One commit per task
+- Stage files individually (never `git add .`)
+- Include `Co-Authored-By: Claude` line
diff --git a/.claude/rules/templates.md b/.claude/rules/templates.md
new file mode 100644
index 000000000..1f7ab1050
--- /dev/null
+++ b/.claude/rules/templates.md
@@ -0,0 +1,48 @@
+---
+paths:
+  - "get-shit-done/templates/**/*.md"
+---
+
+# Template Rules
+
+Rules for editing files in `get-shit-done/templates/`.
+
+## Structure Varies
+
+Templates don't follow a uniform structure. Some patterns:
+
+- Most start with `# [Name] Template` header
+- Many include a `<template>` block containing the actual template content
+- Some include examples or guidelines sections
+
+## Placeholder Conventions
+
+**Square brackets** for human-fillable placeholders:
+```
+[Project Name]
+[Description]
+```
+
+**Curly braces** for variable interpolation:
+```
+{phase}-{plan}-PLAN.md
+.planning/phases/{phase}/
+```
+
+## YAML Frontmatter in Template Content
+
+Templates that define output documents often show example frontmatter:
+
+```yaml
+---
+phase: XX-name
+plan: YY
+type: execute
+---
+```
+
+This is content TO BE GENERATED, not frontmatter for the template file itself.
+
+## Key Principle
+
+Templates show structure for generated documents. Match the style of the specific template you're editing.
diff --git a/.claude/rules/workflows.md b/.claude/rules/workflows.md
new file mode 100644
index 000000000..4720f8a99
--- /dev/null
+++ b/.claude/rules/workflows.md
@@ -0,0 +1,46 @@
+---
+paths:
+  - "get-shit-done/workflows/**/*.md"
+---
+
+# Workflow Rules
+
+Rules for editing files in `get-shit-done/workflows/`.
+
+## No Frontmatter
+
+Workflows don't use YAML frontmatter. Content starts immediately.
+
+## Common XML Tags
+
+These tags appear across workflows, but not all workflows use all of them:
+
+- `<purpose>` — What this workflow accomplishes
+- `<when_to_use>` — Decision criteria (some workflows use `<trigger>` instead)
+- `<required_reading>` — Files to read before starting
+- `<process>` — Container for execution steps
+- `<step>` — Individual step within process
+
+Some workflows also use domain-specific tags like `<philosophy>`, `<references>`, `<planning_principles>`, `<decimal_phase_numbering>`.
+
+## Step Elements
+
+When using `<step>` elements:
+- `name` attribute: snake_case (e.g., `name="load_project_state"`)
+- `priority` attribute: Optional ("first", "second")
+
+## Conditional Logic
+
+```xml
+<if mode="yolo">
+  Content for yolo mode
+</if>
+```
+
+Conditions reference `.planning/config.json` values.
+
+## Key Principle
+
+Workflows contain detailed execution logic. Commands are thin wrappers that delegate to workflows.
+
+Match the style of the specific workflow you're editing — patterns vary across files.
diff --git a/GSD-STYLE.md b/GSD-STYLE.md
new file mode 100644
index 000000000..fba6e4ff1
--- /dev/null
+++ b/GSD-STYLE.md
@@ -0,0 +1,430 @@
+# GSD-STYLE.md
+
+> **Comprehensive reference.** Core rules auto-load from `.claude/rules/`. This document provides deep explanations and examples for when you need the full picture.
+
+This document explains how GSD is written so future Claude instances can contribute consistently.
+
+## Core Philosophy
+
+GSD is a **meta-prompting system** where every file is both implementation and specification. Files teach Claude how to build software systematically. The system optimizes for:
+
+- **Solo developer + Claude workflow** (no enterprise patterns)
+- **Context engineering** (manage Claude's context window deliberately)
+- **Plans as prompts** (PLAN.md files are executable, not documents to transform)
+
+---
+
+## File Structure Conventions
+
+### Slash Commands (`commands/gsd/*.md`)
+
+```yaml
+---
+name: gsd:command-name
+description: One-line description
+argument-hint: "<required>" or "[optional]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
+---
+```
+
+**Section order:**
+1. `<objective>` — What/why/when (always present)
+2. `<execution_context>` — @-references to workflows, templates, references
+3. `<context>` — Dynamic content: `$ARGUMENTS`, bash output, @file refs
+4. `<process>` or `<step>` elements — Implementation steps
+5. `<success_criteria>` — Measurable completion checklist
+
+**Commands are thin wrappers.** Delegate detailed logic to workflows.
+
+### Workflows (`get-shit-done/workflows/*.md`)
+
+No YAML frontmatter. Structure varies by workflow.
+
+**Common tags** (not all workflows use all of these):
+- `<purpose>` — What this workflow accomplishes
+- `<when_to_use>` or `<trigger>` — Decision criteria
+- `<required_reading>` — Prerequisite files
+- `<process>` — Container for steps
+- `<step>` — Individual execution step
+
+Some workflows use domain-specific tags like `<philosophy>`, `<references>`, `<planning_principles>`, `<decimal_phase_numbering>`.
+
+**When using `<step>` elements:**
+- `name` attribute: snake_case (e.g., `name="load_project_state"`)
+- `priority` attribute: Optional ("first", "second")
+
+**Key principle:** Match the style of the specific workflow you're editing.
+
+### Templates (`get-shit-done/templates/*.md`)
+
+Structure varies. Common patterns:
+- Most start with `# [Name] Template` header
+- Many include a `<template>` block with the actual template content
+- Some include examples or guidelines sections
+
+**Placeholder conventions:**
+- Square brackets: `[Project Name]`, `[Description]`
+- Curly braces: `{phase}-{plan}-PLAN.md`
+
+### References (`get-shit-done/references/*.md`)
+
+Typically use outer XML containers related to filename, but structure varies.
+
+Examples:
+- `principles.md` → `<principles>...</principles>`
+- `checkpoints.md` → `<overview>` then `<checkpoint_types>`
+- `plan-format.md` → `<overview>` then `<core_principle>`
+
+Internal organization varies — semantic sub-containers, markdown headers within XML, code examples.
+
+---
+
+## XML Tag Conventions
+
+### Semantic Containers Only
+
+XML tags serve semantic purposes. Use Markdown headers for hierarchy within.
+
+**DO:**
+```xml
+<objective>
+## Primary Goal
+Build authentication system
+
+## Success Criteria
+- Users can log in
+- Sessions persist
+</objective>
+```
+
+**DON'T:**
+```xml
+<section name="objective">
+  <subsection name="primary-goal">
+    <content>Build authentication system</content>
+  </subsection>
+</section>
+```
+
+### Task Structure
+
+```xml
+<task type="auto">
+  <name>Task N: Action-oriented name</name>
+  <files>src/path/file.ts, src/other/file.ts</files>
+  <action>What to do, what to avoid and WHY</action>
+  <verify>Command or check to prove completion</verify>
+  <done>Measurable acceptance criteria</done>
+</task>
+```
+
+**Task types:**
+- `type="auto"` — Claude executes autonomously
+- `type="checkpoint:human-verify"` — User must verify
+- `type="checkpoint:decision"` — User must choose
+
+### Checkpoint Structure
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Description of what was built</what-built>
+  <how-to-verify>Numbered steps for user</how-to-verify>
+  <resume-signal>Text telling user how to continue</resume-signal>
+</task>
+
+<task type="checkpoint:decision" gate="blocking">
+  <decision>What needs deciding</decision>
+  <context>Why this matters</context>
+  <options>
+    <option id="identifier">
+      <name>Option Name</name>
+      <pros>Benefits</pros>
+      <cons>Tradeoffs</cons>
+    </option>
+  </options>
+  <resume-signal>Selection instruction</resume-signal>
+</task>
+```
+
+### Conditional Logic
+
+```xml
+<if mode="yolo">
+  Content for yolo mode
+</if>
+
+<if mode="interactive" OR="custom with gates.execute_next_plan true">
+  Content for multiple conditions
+</if>
+```
+
+---
+
+## @-Reference Patterns
+
+**Static references** (always load):
+```
+@~/.claude/get-shit-done/workflows/execute-phase.md
+@.planning/PROJECT.md
+```
+
+**Conditional references** (based on existence):
+```
+@.planning/DISCOVERY.md (if exists)
+```
+
+**@-references are lazy loading signals.** They tell Claude what to read, not pre-loaded content.
+
+---
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Files | kebab-case | `execute-phase.md` |
+| Commands | `gsd:kebab-case` | `gsd:execute-phase` |
+| XML tags | kebab-case | `<execution_context>` |
+| Step names | snake_case | `name="load_project_state"` |
+| Bash variables | CAPS_UNDERSCORES | `PHASE_ARG`, `PLAN_START_TIME` |
+| Type attributes | colon separator | `type="checkpoint:human-verify"` |
+
+---
+
+## Language & Tone
+
+### Imperative Voice
+
+**DO:** "Execute tasks", "Create file", "Read STATE.md"
+
+**DON'T:** "Execution is performed", "The file should be created"
+
+### No Filler
+
+Absent: "Let me", "Just", "Simply", "Basically", "I'd be happy to"
+
+Present: Direct instructions, technical precision
+
+### No Sycophancy
+
+Absent: "Great!", "Awesome!", "Excellent!", "I'd love to help"
+
+Present: Factual statements, verification results, direct answers
+
+### Brevity with Substance
+
+**Good one-liner:** "JWT auth with refresh rotation using jose library"
+
+**Bad one-liner:** "Phase complete" or "Authentication implemented"
+
+---
+
+## Context Engineering
+
+### Size Constraints
+
+- **Plans:** 2-3 tasks maximum
+- **Quality curve:** 0-30% peak, 30-50% good, 50-70% degrading, 70%+ poor
+- **Split triggers:** >3 tasks, multiple subsystems, >5 files per task
+
+### Fresh Context Pattern
+
+Use subagents for autonomous work. Reserve main context for user interaction.
+
+### State Preservation
+
+- `STATE.md` — Living memory across sessions
+- `agent-history.json` — Subagent tracking for resume
+- SUMMARY.md frontmatter — Machine-readable for dependency graphs
+
+---
+
+## Anti-Patterns to Avoid
+
+### Enterprise Patterns (Banned)
+
+- Story points, sprint ceremonies, RACI matrices
+- Human dev time estimates (days/weeks)
+- Team coordination, knowledge transfer docs
+- Change management processes
+
+### Temporal Language (Banned in Implementation Docs)
+
+**DON'T:** "We changed X to Y", "Previously", "No longer", "Instead of"
+
+**DO:** Describe current state only
+
+**Exception:** CHANGELOG.md, MIGRATION.md, git commits
+
+### Generic XML (Banned)
+
+**DON'T:** `<section>`, `<item>`, `<content>`
+
+**DO:** Semantic purpose tags: `<objective>`, `<verification>`, `<action>`
+
+### Vague Tasks (Banned)
+
+```xml
+<!-- BAD -->
+<task type="auto">
+  <name>Add authentication</name>
+  <action>Implement auth</action>
+  <verify>???</verify>
+</task>
+
+<!-- GOOD -->
+<task type="auto">
+  <name>Create login endpoint with JWT</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie. Return 200. On mismatch, return 401.</action>
+  <verify>curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header</verify>
+  <done>Valid credentials → 200 + cookie. Invalid → 401.</done>
+</task>
+```
+
+---
+
+## Commit Conventions
+
+### Format
+
+```
+{type}({phase}-{plan}): {description}
+```
+
+### Types
+
+| Type | Use |
+|------|-----|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `test` | Tests only (TDD RED) |
+| `refactor` | Code cleanup (TDD REFACTOR) |
+| `docs` | Documentation/metadata |
+| `chore` | Config/dependencies |
+
+### Rules
+
+- One commit per task during execution
+- Stage files individually (never `git add .`)
+- Capture hash for SUMMARY.md
+- Include Co-Authored-By line
+
+---
+
+## UX Patterns
+
+### "Next Up" Format
+
+```markdown
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{copy-paste command}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Alternative option
+- Another option
+
+---
+```
+
+### Decision Gates
+
+Always use AskUserQuestion with concrete options. Never plain text prompts.
+
+Include escape hatch: "Something else", "Let me describe"
+
+---
+
+## Progressive Disclosure
+
+Information flows through layers:
+
+1. **Command** — High-level objective, delegates to workflow
+2. **Workflow** — Detailed process, references templates/references
+3. **Template** — Concrete structure with placeholders
+4. **Reference** — Deep dive on specific concept
+
+Each layer answers different questions:
+- Command: "Should I use this?"
+- Workflow: "What happens?"
+- Template: "What does output look like?"
+- Reference: "Why this design?"
+
+---
+
+## Depth & Compression
+
+Depth setting controls compression tolerance:
+
+- **Quick:** Compress aggressively (1-3 plans/phase)
+- **Standard:** Balanced (3-5 plans/phase)
+- **Comprehensive:** Resist compression (5-10 plans/phase)
+
+**Key principle:** Depth controls compression, not inflation. Never pad to hit a target number. Derive plans from actual work.
+
+---
+
+## TDD Plans
+
+### Detection Heuristic
+
+> Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+
+Yes → TDD plan (one feature per plan)
+No → Standard plan
+
+### TDD Plan Structure
+
+```yaml
+---
+type: tdd
+---
+```
+
+```xml
+<objective>
+Implement [feature] using TDD (RED → GREEN → REFACTOR)
+</objective>
+
+<behavior>
+Expected behavior specification
+</behavior>
+
+<implementation>
+How to make tests pass
+</implementation>
+```
+
+### TDD Commits
+
+- RED: `test({phase}-{plan}): add failing test for [feature]`
+- GREEN: `feat({phase}-{plan}): implement [feature]`
+- REFACTOR: `refactor({phase}-{plan}): clean up [feature]`
+
+---
+
+## Summary: Core Meta-Patterns
+
+1. **XML for semantic structure, Markdown for content**
+2. **@-references are lazy loading signals**
+3. **Commands delegate to workflows**
+4. **Progressive disclosure hierarchy**
+5. **Imperative, brief, technical** — no filler, no sycophancy
+6. **Solo developer + Claude** — no enterprise patterns
+7. **Context size as quality constraint** — split aggressively
+8. **Temporal language banned** — current state only
+9. **Plans ARE prompts** — executable, not documents
+10. **Atomic commits** — Git history as context source
+11. **AskUserQuestion for all exploration** — always options
+12. **Checkpoints post-automation** — automate first, verify after
+13. **Deviation rules are automatic** — no permission for bugs/critical
+14. **Depth controls compression** — derive from actual work
+15. **TDD gets dedicated plans** — cycle too heavy to embed