---
phase: 01-foundation-templates
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - .planning/templates/LOOPS_TEMPLATE.md
  - .planning/templates/CONTEXT_TEMPLATE.md
  - .planning/templates/STATE_TEMPLATE.md
autonomous: true

must_haves:
  truths:
    - "User can read LOOPS_TEMPLATE.md and understand how to capture loops"
    - "User can read CONTEXT_TEMPLATE.md and understand token budget tracking"
    - "User can read STATE_TEMPLATE.md and understand session state structure"
    - "Templates explain both what to do and why (GSD mechanics + rationale)"
  artifacts:
    - path: ".planning/templates/LOOPS_TEMPLATE.md"
      provides: "Loop capture template with systematic ID format"
      min_lines: 80
      contains: "LOOP-NNN format, XML structure, status transitions"
    - path: ".planning/templates/CONTEXT_TEMPLATE.md"
      provides: "Token budget tracking template"
      min_lines: 60
      contains: "context_loaded XML, threshold phases, exclusion reasoning"
    - path: ".planning/templates/STATE_TEMPLATE.md"
      provides: "Session state template"
      min_lines: 70
      contains: "Active loops section, token budget, available actions"
  key_links:
    - from: "LOOPS_TEMPLATE.md"
      to: "systematic ID coding (LOOP-NNN)"
      via: "example loop structure"
      pattern: 'id="LOOP-\d{3}"'
    - from: "CONTEXT_TEMPLATE.md"
      to: "token budget thresholds (20/40/50%)"
      via: "threshold definitions"
      pattern: "threshold=\"(comfortable|deliberate|warning|stop)\""
    - from: "STATE_TEMPLATE.md"
      to: "available actions menu"
      via: "contextual action section"
      pattern: "/continue|/pause|/status"
---

<objective>
Create core artifact templates (LOOPS, CONTEXT, STATE) that enforce systematic protocol through structure and inline education.

Purpose: Enable any agent (Gemini, ChatGPT, Claude) to maintain discipline around loop capture, context scoping, and state tracking by following heavily-commented templates.

Output: Three production-ready templates in .planning/templates/ that teach through use.
</objective>

<execution_context>
@./.claude/get-shit-done/workflows/execute-plan.md
@./.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-foundation-templates/01-CONTEXT.md
@.planning/phases/01-foundation-templates/01-RESEARCH.md

# Reference implementations from gsd_lite testing
@gsd_lite/template_gsd_lite/02_STATE_TEMPLATE.md
@gsd_lite/template_gsd_lite/00_MANIFESTO.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create LOOPS_TEMPLATE.md with systematic ID structure</name>
  <files>.planning/templates/LOOPS_TEMPLATE.md</files>
  <action>
Create LOOPS template with:

1. **YAML frontmatter**: version, updated date, purpose statement
2. **Usage section**: When to use (open questions, parking lot), when NOT to use (clarified decisions → STATE/PROJECT)
3. **Structure section**: Loop lifecycle (open → clarifying → closed), systematic ID format (LOOP-NNN)
4. **XML format**: Full example loop with all fields:
   - `id="LOOP-NNN"` (systematic ID)
   - `status="open|clarifying|closed"`
   - `<title>` (brief description)
   - `<context>` (why this came up)
   - `<question>` (what needs clarification)
   - `<captured>` (ISO timestamp)
5. **Agent workflow**: How agent proposes loops (XML format → user approves → write to LOOPS.md)
6. **Status transitions**: open (initial) → clarifying (exploring) → closed (resolved with outcome)
7. **Examples**: 3 realistic loops from data engineering context (CB invoice assumption, lineage scope, test failure root cause)
8. **Educational inline comments**: Explain WHY systematic IDs (quick reference, artifact linking), WHY XML (semantic clarity, attributes), WHY status tracking (recovery from interruptions)

Reference RESEARCH.md "Loop Capture with XML Structure" section for proven patterns.
Reference CONTEXT.md decisions on systematic ID format and checkpoint visibility.

Do NOT include:
- Sticky note format (that's in BOOTLOADER)
- Token budget tracking (that's in CONTEXT)
- Cross-session handoff (that's Phase 2)
  </action>
  <verify>
1. File exists at .planning/templates/LOOPS_TEMPLATE.md
2. Contains YAML frontmatter with version and purpose
3. Contains XML example with id="LOOP-NNN" pattern
4. Contains at least 3 example loops from data engineering domain
5. Contains inline educational comments explaining WHY for each major section
6. grep -E 'LOOP-[0-9]{3}' matches systematic ID pattern
  </verify>
  <done>
LOOPS_TEMPLATE.md exists with systematic ID format, XML structure, lifecycle documentation, and inline education on GSD mechanics
  </done>
</task>

<task type="auto">
  <name>Task 2: Create CONTEXT_TEMPLATE.md with token budget tracking</name>
  <files>.planning/templates/CONTEXT_TEMPLATE.md</files>
  <action>
Create CONTEXT template with:

1. **YAML frontmatter**: version, updated date, purpose ("token budget management and context scoping")
2. **Purpose section**: Why context scoping matters (prevent overwhelming agent, deliberate inclusion/exclusion decisions)
3. **Token budget thresholds**: Define phases from RESEARCH.md Pattern 7:
   - comfortable: 0-20% (exploratory work)
   - deliberate: 20-40% (focused work)
   - warning: 40-50% (quality degradation zone)
   - stop: 50%+ (context must be reduced)
4. **XML structure**: Full example with all elements:
   - `<context_loaded>` wrapper
   - `<budget total="5000" used="2300" remaining="2700" threshold="warning" />`
   - `<phase>comfortable|deliberate|warning|stop</phase>`
   - `<included>` section (files loaded with token counts)
   - `<excluded>` sections (by reason: test_files, out_of_scope, etc. with rationale)
5. **Progressive loading strategy**: Start narrow → expand when needed (reference CONTEXT-03 requirement)
6. **Examples**: 3 realistic scenarios from dbt context:
   - Scenario 1: Model refactor (load model + direct deps, exclude tests/legacy)
   - Scenario 2: Test failure (load failing test + model, exclude unrelated models)
   - Scenario 3: Large lineage (use dbt-mp slim manifest, document exclusion rationale)
7. **Educational comments**: WHY token budgets (quality degradation curve), WHY exclusion rationale (future session context), WHY progressive loading (avoid premature context loading)

Reference RESEARCH.md "Context Budget Tracking" section.
Reference GSD_PATTERNS.md Pattern 7 (conservative budgets 20/40/50%).

Do NOT include:
- Loop capture format (that's in LOOPS)
- Session handoff mechanics (that's Phase 2)
- dbt-mp tool usage (that's Phase 3 - Context Engineering)
  </action>
  <verify>
1. File exists at .planning/templates/CONTEXT_TEMPLATE.md
2. Contains XML <context_loaded> structure with budget attributes
3. Contains threshold definitions (comfortable/deliberate/warning/stop)
4. Contains at least 3 examples from dbt/data engineering scenarios
5. Contains inline educational comments for each threshold
6. grep 'threshold="(comfortable|deliberate|warning|stop)"' matches pattern
  </verify>
  <done>
CONTEXT_TEMPLATE.md exists with token budget XML structure, threshold definitions, progressive loading strategy, and dbt-specific examples
  </done>
</task>

<task type="auto">
  <name>Task 3: Create STATE_TEMPLATE.md with session state structure</name>
  <files>.planning/templates/STATE_TEMPLATE.md</files>
  <action>
Create STATE template with:

1. **YAML frontmatter**: version, updated date, purpose ("session working memory")
2. **Purpose section**: Why STATE.md exists (single source of truth for current session, recovery from context drift)
3. **Structure sections**:
   - **Current context**: Phase, task, what's being worked on NOW
   - **Active loops**: List of open LOOP-NNN IDs with brief titles (links to LOOPS.md)
   - **Token budget snapshot**: Current usage from CONTEXT.md (used/total/percentage)
   - **Available actions**: Context-sensitive menu (core + contextual)
   - **Context stack**: Current activity, return-to location if forked
   - **Recent updates**: Last 3-5 artifact updates (what changed, when)
4. **Available actions menu** (from CONTEXT.md decisions):
   - Core (always present): /continue, /pause, /status, /add-loop, /discuss
   - Contextual examples: Plan-related (/approve-plan), Loop-related (/close-loop [ID]), Phase-related (/complete-phase)
5. **Context stack example**: Show forking (working on TASK-003 → user asks /discuss → return to TASK-003)
6. **Recovery protocol**: How agent uses STATE.md when protocol drift detected (user prompts "update artifacts")
7. **Examples**: 2 realistic STATE.md snapshots:
   - Mid-task state (loop open, 35% budget, actions: /continue | /close-loop 007)
   - Checkpoint state (awaiting approval, 45% budget, actions: /approve | /reject)
8. **Educational comments**: WHY single file (not scattered context), WHY available actions (reduce user cognitive load), WHY context stack (support non-linear reasoning), WHY recent updates (audit trail)

Reference gsd_lite/template_gsd_lite/02_STATE_TEMPLATE.md for structure inspiration.
Reference CONTEXT.md decisions on available actions menu and context stack.

Do NOT include:
- Loop XML structure (that's in LOOPS)
- Token budget XML (that's in CONTEXT)
- Sticky note format (that's in BOOTLOADER)
  </action>
  <verify>
1. File exists at .planning/templates/STATE_TEMPLATE.md
2. Contains sections: Current context, Active loops, Token budget, Available actions, Context stack
3. Contains core actions list (/continue, /pause, /status, /add-loop, /discuss)
4. Contains at least 2 example STATE.md snapshots
5. Contains inline educational comments explaining purpose of each section
6. grep '/continue|/pause|/status' matches action menu pattern
  </verify>
  <done>
STATE_TEMPLATE.md exists with session state structure, available actions menu, context stack support, and recovery protocol documentation
  </done>
</task>

</tasks>

<verification>
After completion, verify:

1. Directory structure: `.planning/templates/` exists with 3 files
2. LOOPS_TEMPLATE.md: Systematic ID format visible, XML examples present, lifecycle documented
3. CONTEXT_TEMPLATE.md: Token budget thresholds defined, XML structure complete, dbt examples included
4. STATE_TEMPLATE.md: Available actions menu, context stack example, recovery protocol documented
5. All templates: YAML frontmatter present, inline educational comments throughout
6. Cross-references: Templates reference each other appropriately (STATE points to LOOPS/CONTEXT)
</verification>

<success_criteria>
Templates are production-ready when:
- User can copy any template and understand what to fill in
- User can read inline comments and understand WHY each section exists
- Agent can follow template structure without additional instruction
- Templates work in both MCP (file access) and copy-paste workflows
- Educational value: Reading template teaches GSD mechanics
</success_criteria>

<output>
After completion, create `.planning/phases/01-foundation-templates/01-01-SUMMARY.md`
</output>
