---
phase: 01-foundation-templates
plan: 03
type: execute
wave: 2
depends_on: [01-01, 01-02]
files_modified:
  - .planning/templates/PROTOCOL_REFERENCE.md
  - .planning/AGENTS.md
autonomous: true

must_haves:
  truths:
    - "User can read PROTOCOL_REFERENCE and understand all enforcement mechanisms"
    - "User can reference systematic ID formats without searching templates"
    - "User can understand checkpoint types and when to use each"
    - "AGENTS.md works across platforms (Claude Desktop, Cursor, ChatGPT with file access)"
  artifacts:
    - path: ".planning/templates/PROTOCOL_REFERENCE.md"
      provides: "Complete protocol documentation"
      min_lines: 120
      contains: "systematic IDs, checkpoint types, sticky note rules, visual conventions"
    - path: ".planning/AGENTS.md"
      provides: "Cross-platform agent configuration"
      min_lines: 80
      contains: "persona, commands, protocol summary, template references"
  key_links:
    - from: "PROTOCOL_REFERENCE.md"
      to: "all templates"
      via: "links to template files"
      pattern: "@\\.planning/templates/"
    - from: "AGENTS.md"
      to: "PROTOCOL_REFERENCE.md"
      via: "protocol section reference"
      pattern: "See: PROTOCOL_REFERENCE\\.md"
    - from: "AGENTS.md"
      to: "commands (/add-loop, /status, etc.)"
      via: "commands section"
      pattern: "/[a-z-]+"
---

<objective>
Create protocol reference documentation and cross-platform agent configuration that complete the foundation layer.

Purpose: Provide quick-reference protocol docs (IDs, checkpoints, sticky notes) and AGENTS.md for platform compatibility.

Output: Protocol reference consolidating all enforcement mechanisms, AGENTS.md for cross-platform 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

# Templates from Plan 01 and 02
@.planning/templates/LOOPS_TEMPLATE.md
@.planning/templates/CONTEXT_TEMPLATE.md
@.planning/templates/STATE_TEMPLATE.md
@.planning/templates/BOOTLOADER_TEMPLATE.md
@.planning/templates/SUMMARY_TEMPLATE.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create PROTOCOL_REFERENCE.md consolidating all enforcement mechanisms</name>
  <files>.planning/templates/PROTOCOL_REFERENCE.md</files>
  <action>
Create protocol reference with:

1. **Purpose**: Quick reference for protocol patterns used across all templates - the "why and how" without full template verbosity
2. **Systematic ID Coding**:
   - Format: TYPE-NNN (zero-padded 3 digits)
   - Types: LOOP, TASK, DECISION, HYPO, PLAN, MILESTONE, CHECKPOINT
   - Scope: Global unique (never reuse IDs)
   - Registry: All tracked in STATE.md
   - Examples: LOOP-003, TASK-017, DECISION-005
   - WHY: Quick reference, artifact linking, no ambiguity
3. **Sticky Note Protocol**:
   - Placement: End of every agent response when artifact updated OR state changed
   - Format: Fenced code block with ```gsd-status marker
   - Required fields: UPDATED, CURRENT STATE, AVAILABLE ACTIONS, NEXT
   - When to include: Artifact updated, state changed, available actions changed
   - When to omit: No changes, pure conversational turn
   - WHY: Protocol reminder (agent can't reference bootloader mid-session), visible compliance, parseable status
4. **Checkpoint Types** (reference CONTEXT.md decisions):
   - **📫 Loop captured**: Informational, loop proposed and approved
   - **⚡ Decision made**: Informational, user selected option
   - **✅ Task complete**: Informational, unit of work done
   - **🔮 Phase complete**: Informational, milestone reached
   - **🧪 Hypothesis validated/invalidated**: Informational, test result
   - **🛑 Blocking**: Requires explicit user action before proceeding (aggressive emoji wall: 🛑🛑🛑🛑🛑🛑🛑)
   - Structure: Emoji banner, what/context/action sections, clear resume signal
   - WHY: Visual interruption arrests attention, consistent format reduces cognitive load
5. **Visual Conventions**:
   - Emoji usage: Distinct per checkpoint type (see above)
   - Fenced blocks: ```gsd-status for sticky notes, ```xml for examples
   - Blocking barriers: 🛑🛑🛑 (7+ emojis) with horizontal rules
   - Action prompts: Always explicit (e.g., "Type 'approved' or describe issues")
6. **Available Actions Menu**:
   - Core actions (always): /continue, /pause, /status, /add-loop, /discuss
   - Contextual: /approve-plan, /reject-plan, /close-loop [ID], /explore-loop [ID], /complete-phase
   - Format: Single-line shortcut list: 📋 /continue | /pause | /discuss
   - WHY: Reduce user cognitive load, surface capabilities, prevent "what do I do now?" moments
7. **Context Stack** (for forking):
   - Single level: One fork at a time
   - Structure: "Return To" field in STATE.md
   - Behavior: Prompt before returning ("Ready to return to TASK-003?")
   - Example: Working TASK-003 → /discuss CB invoices → return to TASK-003
   - WHY: Support non-linear reasoning in linear chat, maintain primary focus
8. **Recovery Protocol**:
   - Trigger: User says "update artifacts" OR agent detects protocol drift
   - Action: Read STATE.md, show current state in sticky note, resume compliance
   - WHY: Long sessions cause drift, explicit reset mechanism prevents runaway degradation
9. **MCP vs Copy-Paste**:
   - MCP: Agent reads/writes files directly
   - Copy-paste: User provides file contents, agent proposes changes
   - Protocol identical: Both maintain same artifacts (STATE, LOOPS, CONTEXT)
   - WHY: Vendor agnostic - works with any agent
10. **Cross-references**: Link to each template for full details

Reference CONTEXT.md for all decisions (sticky notes, IDs, checkpoints, actions).
Reference RESEARCH.md for patterns (Pattern 1-4).

Do NOT include:
- Full template content (link to templates)
- Phase 2+ features (session handoff)
- Implementation tutorials (this is reference, not guide)
  </action>
  <verify>
1. File exists at .planning/templates/PROTOCOL_REFERENCE.md
2. Contains systematic ID format documentation (TYPE-NNN)
3. Contains sticky note protocol rules (when to include/omit)
4. Contains all checkpoint types with emojis and purposes
5. Contains visual conventions (emojis, fenced blocks, barriers)
6. Contains available actions menu (core + contextual)
7. Contains recovery protocol (update artifacts trigger)
8. Contains links to all 5 templates
  </verify>
  <done>
PROTOCOL_REFERENCE.md exists as quick reference for IDs, sticky notes, checkpoints, actions, and visual conventions
  </done>
</task>

<task type="auto">
  <name>Task 2: Create AGENTS.md for cross-platform agent configuration</name>
  <files>.planning/AGENTS.md</files>
  <action>
Create AGENTS.md following standard format (reference RESEARCH.md "AGENTS.md Template Structure"):

1. **YAML frontmatter** (AGENTS.md standard):
   ```yaml
   ---
   persona: Data Engineering Copilot
   domain: dbt, SQL, data modeling, token budget management
   project_structure: .planning/ (planning docs), .project/sessions/ (session artifacts)
   workflows:
     - loop_capture
     - context_scoping
     - session_state_tracking
   protocol_version: "1.0"
   ---
   ```
2. **Role section**:
   - Primary purpose: Assist with data engineering work while maintaining user ownership of reasoning
   - Key discipline: Loop capture, context scoping, artifact updates, checkpoint visibility
   - Educational focus: Explain WHY for decisions, teach patterns through use
3. **Commands section** (slash commands):
   - `/add-loop [description]` - Propose new loop capture
   - `/close-loop [ID]` - Mark loop as resolved
   - `/status` - Show current state (phase, loops, token budget)
   - `/pause` - Save session state for later resumption
   - `/continue` - Resume work after checkpoint
   - `/discuss [topic]` - Fork to exploratory discussion (maintain context stack)
   - `/export-summary` - Generate session summary for GTD export
4. **Protocol section** (summary, link to full reference):
   - Artifacts: STATE.md (session state), LOOPS.md (open questions), CONTEXT.md (token budget)
   - IDs: TYPE-NNN format for all trackable items
   - Sticky notes: End-of-response status blocks (when state changes)
   - Checkpoints: Visual barriers for blocking events, informational for progress
   - See: .planning/templates/PROTOCOL_REFERENCE.md for complete protocol. Add cross-reference to PROTOCOL_REFERENCE.md in protocol section.
5. **Templates section**:
   - Location: .planning/templates/
   - Entry point: README.md
   - Session artifacts: .project/sessions/YYYY-MM-DD-description/
6. **Workflows section** (high-level):
   - **Loop capture**: Agent proposes (XML) → user approves → write to LOOPS.md
   - **Context scoping**: Start narrow → track budget → exclude deliberately → document rationale
   - **Session state**: Update STATE.md after each turn → show in sticky note → recovery via "update artifacts"
7. **Token budget guidance**:
   - Target: 5000 tokens (adjustable)
   - Thresholds: 20% comfortable, 40% deliberate, 50% warning, 60%+ stop
   - See: CONTEXT_TEMPLATE.md for full budget protocol
8. **Educational note**: This configuration works across platforms that support AGENTS.md (Claude Desktop, Cursor). For platforms without AGENTS.md support, use BOOTLOADER_TEMPLATE.md.

Reference RESEARCH.md "AGENTS.md Template Structure" and "State of the Art" sections.
Reference agents.md standard (https://agents.md/).

Do NOT include:
- Full protocol documentation (link to PROTOCOL_REFERENCE)
- Template content (link to templates/)
- Phase 2+ features (multi-session handoff)
  </action>
  <verify>
1. File exists at .planning/AGENTS.md
2. Contains YAML frontmatter with persona, domain, workflows
3. Contains commands section with slash commands
4. Contains protocol summary with link to PROTOCOL_REFERENCE.md
5. Contains templates section with location
6. Contains token budget guidance
7. Valid AGENTS.md format (check against standard)
8. Contains cross-reference to PROTOCOL_REFERENCE.md in protocol section
  </verify>
  <done>
AGENTS.md exists with cross-platform configuration, commands, protocol summary, template references, and cross-reference to PROTOCOL_REFERENCE
  </done>
</task>

</tasks>

<verification>
After completion, verify:

1. PROTOCOL_REFERENCE.md: Systematic IDs documented, checkpoints typed, sticky note rules clear
2. AGENTS.md: Valid format, persona defined, commands listed, protocol linked
3. Cross-references: AGENTS.md → PROTOCOL_REFERENCE → Templates (full chain)
4. Documentation completeness: User can read PROTOCOL_REFERENCE and find any pattern
5. Platform compatibility: AGENTS.md follows standard format for cross-platform use
</verification>

<success_criteria>
Protocol documentation is production-ready when:
- User can reference systematic ID format without searching templates
- User can look up checkpoint types and visual conventions quickly
- AGENTS.md loads in Claude Desktop, Cursor, and other AGENTS.md-aware platforms
- Protocol reference consolidates all patterns from templates in one place
- Cross-references work: AGENTS.md → PROTOCOL_REFERENCE → Templates
</success_criteria>

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