# Phase 1.3: Context Lifecycle, Coaching Model & Workflow Decomposition - Research

**Researched:** 2026-01-25
**Domain:** AI agent architecture, workflow design, and session management
**Confidence:** HIGH

## Summary

This phase addresses three architectural concerns discovered through evaluation with Claude Sonnet and Gemini 3.0 Pro:

1. **Context rot problem**: Monolithic PROTOCOL.md (930 lines) creates cognitive overload, leading agents to skip critical steps or hallucinate completion
2. **Missing coaching philosophy**: No explicit guidance on when agents should ask vs. decide, causing premature implementation and scope creep
3. **No context lifecycle**: Sessions accumulate bloat with no defined checkpoint/clear/resume strategy

**Key research findings:**

1. **Workflow decomposition** is the industry standard in 2026: specialized, single-purpose workflows coordinated through protocols replace monolithic instructions
2. **Context lifecycle management** (checkpoint → clear → resume) is essential for long-running agent sessions, with checkpointing mechanisms enabling graceful pause/resume
3. **Coaching model** represents a hybrid philosophy where user owns outcome but agent guides execution, with clear governance frameworks for autonomy levels
4. **OG GSD already implements these patterns**: workflows are modular (discuss-phase, execute-plan, verify-work), each self-contained with clear purpose

**Primary recommendation:** Decompose PROTOCOL.md into per-workflow files (moodboard, whiteboard, execution, checkpoint) with sticky note protocol as universal orientation mechanism across all workflows.

## Standard Stack

This is an architectural/documentation phase with no code dependencies.

### Core Patterns (from OG GSD analysis)

| Pattern | Source | Purpose | Why Standard |
|---------|--------|---------|--------------|
| Workflow decomposition | `.gsd_reference/workflows/*.md` | Single-purpose protocol files | Each workflow has clear entry/exit, reduces cognitive load |
| Sticky note checkpoints | `references/checkpoints.md` | Universal status/action menu | Provides orientation regardless of workflow |
| Context layering | PROJECT → STATE → WORK | Stable → ephemeral separation | Prevents context accumulation, enables fresh sessions |
| Checkpoint types | `checkpoint:human-verify`, `decision`, `human-action` | Formalized interaction points | Makes human-in-loop explicit vs implicit |

### Supporting Concepts (from 2026 industry research)

| Pattern | Source | Purpose | When to Use |
|---------|--------|---------|-------------|
| Agent Communication Protocol (ACP) | Multi-agent systems research | Standardized messaging between agents | When coordinating multiple specialized agents |
| Model Context Protocol (MCP) | OpenAI Agents SDK | Structured contexts to LLMs | When managing session state and continuity |
| Session management | Context lifecycle research | Pause/resume capability | Long-running tasks spanning multiple sessions |

### Alternatives Considered

| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| Per-workflow files | Keep monolithic PROTOCOL.md | Simpler to maintain, but evaluation shows agents skip critical sections in long protocols |
| Explicit coaching philosophy | Let agents infer from examples | Less documentation, but evaluation shows inconsistent behavior without explicit guidance |
| Checkpoint lifecycle | Just tell agents to "save progress" | Simpler, but no formalized resume mechanism |

**Installation:** None (documentation-only phase)

## Architecture Patterns

### Recommended Project Structure

```
gsd-lite/
├── workflows/
│   ├── moodboard.md       # Dream extraction (planning mode - questioning)
│   ├── whiteboard.md      # Plan proposal (planning mode - confirmation)
│   ├── execution.md       # Task execution (work mode)
│   └── checkpoint.md      # Promotion/handoff (meta mode)
├── PROTOCOL.md            # Minimal entrypoint (which workflow to load)
├── STATE.md               # Current position, decisions
├── WORK.md                # Ephemeral execution log
├── INBOX.md               # Loop capture
└── HISTORY.md             # Completed phases
```

### Pattern 1: Workflow Decomposition

**What:** Split monolithic protocol into specialized workflow files, each with clear entry/exit conditions.

**When to use:** When protocol exceeds ~300 lines or serves multiple distinct modes (planning vs execution vs handoff).

**Example from OG GSD:**

```
discuss-phase.md     → Entry: /gsd:discuss-phase {N}
                     → Purpose: Extract implementation decisions
                     → Exit: CONTEXT.md created

execute-plan.md      → Entry: /gsd:execute-plan or auto-continuation
                     → Purpose: Execute tasks from PLAN.md
                     → Exit: SUMMARY.md created, all tasks complete

verify-work.md       → Entry: /gsd:verify-work {phase}
                     → Purpose: User acceptance testing
                     → Exit: UAT.md created
```

**Application to GSD-lite:**

```
moodboard.md         → Entry: New phase starts, no WHITEBOARD.md
                     → Purpose: Collaborative questioning (10x emoji banners)
                     → Exit: User signals "ready to see plan"

whiteboard.md        → Entry: After moodboard, or when tasks defined
                     → Purpose: Present scope/risk/verification (📚 banner)
                     → Exit: User approves or adjusts scope

execution.md         → Entry: After whiteboard approval
                     → Purpose: Execute tasks, log to WORK.md, capture loops
                     → Exit: All tasks complete, agent signals ready for promotion

checkpoint.md        → Entry: User requests "complete phase" or "promote"
                     → Purpose: Extract to external artifact, trim WORK.md
                     → Exit: HISTORY.md updated, STATE.md cleared
```

**Benefit:** Agent loads only relevant protocol (200-300 lines) vs entire 930-line file.

### Pattern 2: Sticky Note Protocol (Universal Orientation)

**What:** Every workflow includes the same sticky note format at end of turn, providing universal orientation.

**When to use:** End of EVERY agent response across ALL workflows.

**Structure:**

```markdown
```gsd-status
📋 UPDATED: [artifact] ([change])

CURRENT STATE:
- Phase: PHASE-NNN ([name]) - [X/Y tasks]
- Task: TASK-NNN ([name]) - [status]
- Active loops: [count] ([IDs])

AVAILABLE ACTIONS:
📋 /continue | /pause | /status | /add-loop | /discuss
[Workflow-specific actions]

NEXT: [What agent expects from user]
SELF-CHECK:
- [ ] STATE.md update
- [ ] WORK.md update
- [ ] INBOX.md update
- [ ] HISTORY.md update

---
📊 PROGRESS: PHASE-NNN [██░░░] 60% (3/5 tasks)
---
```
```

**Why universal:** User always knows:
1. What just changed (UPDATED)
2. Where they are (CURRENT STATE)
3. What they can do (AVAILABLE ACTIONS)
4. What agent expects (NEXT)
5. What was updated (SELF-CHECK)

**Evaluation insight:** Gemini eval showed agent lost track of which files to update. Self-check prevents phantom state.

### Pattern 3: Context Lifecycle (Checkpoint → Clear → Resume)

**What:** Formalized three-phase lifecycle for context management.

**When to use:** Sessions that span multiple days or accumulate >50% context usage.

**Phases:**

1. **Checkpoint (end of session)**
   - Agent signals completion readiness
   - User triggers promotion workflow
   - STATE.md captures: current phase, decisions made, session log
   - WORK.md trimmed after extraction to external artifact
   - Result: Clean slate for next session

2. **Clear (between sessions)**
   - User starts fresh chat (NEW context window)
   - OR orchestrator spawns fresh agent
   - 0% context usage at start
   - No accumulated chat history

3. **Resume (start of new session)**
   - Agent reads PROTOCOL.md (which workflow to load)
   - Reads STATE.md (where were we? what decisions made?)
   - If mid-task: reads WORK.md (what's in progress?)
   - Reconstructs context from artifacts, not chat history

**Example flow:**

```
Session 1 (Chat A, Monday):
→ Execute TASK-001, TASK-002
→ WORK.md logs progress
→ User: "let's continue tomorrow"
→ Agent: Updates STATE.md, doesn't promote yet
→ Context: 45% used

Session 2 (Chat B, Tuesday - FRESH):
→ Agent reads PROTOCOL.md → loads execution.md workflow
→ Reads STATE.md → sees PHASE-001, TASK-002 in progress
→ Reads WORK.md → gets latest progress
→ Continues TASK-002, executes TASK-003
→ Context: 0% → 35% (fresh window)
```

**Industry validation (2026):** LangGraph's checkpointing saves state at each node enabling pause/resume. OpenAI Agents SDK manages session continuity. Temporal engine enables pause/resume for long-running workflows.

### Pattern 4: Coaching Philosophy (User Owns Outcome, Agent Guides)

**What:** Explicit governance model for autonomy levels.

**When to use:** Throughout all workflows, defines when to ask vs when to decide.

**Governance Framework:**

| Decision Type | Owner | Agent Role | Example |
|---------------|-------|------------|---------|
| Vision/Outcome | User | Extract via questioning | "What should this feel like when done?" |
| Scope boundary | User | Clarify, redirect creep | "That's a new capability - note for roadmap?" |
| Implementation choice | User (if affects UX) | Present options with pros/cons | "Cards vs timeline layout?" |
| Technical detail | Agent | Auto-fix with deviation log | "Missing null check - adding" |
| Architectural change | User | Pause, present decision | "This requires new database table" |
| Critical security | Agent | Auto-fix immediately | "SQL injection risk - sanitizing input" |

**Key principle from OG GSD discuss-phase.md:**

> "The user knows:
> - How they imagine it working
> - What it should look/feel like
> - What's essential vs nice-to-have
>
> The user doesn't know (and shouldn't be asked):
> - Codebase patterns (researcher reads the code)
> - Technical risks (researcher identifies these)
> - Implementation approach (planner figures this out)"

**Industry validation (2026):** "Full automation isn't always the optimal goal" - hybrid human-agent systems produce better outcomes for decisions with significant business/ethical consequences. "Agentic AI shifts human involvement from routine execution to accountability and control."

### Anti-Patterns to Avoid

**Anti-Pattern 1: Monolithic Protocol**
- **Why it's bad:** Agents skip critical sections, hallucinate completion, lose track of requirements
- **Evidence:** Claude eval (eval_claude.md) - jumped directly to implementation without MOODBOARD
- **What to do instead:** Decompose into workflows, agent loads only what's needed

**Anti-Pattern 2: Implicit Coaching Model**
- **Why it's bad:** Inconsistent behavior - sometimes asks, sometimes assumes, sometimes implements prematurely
- **Evidence:** Gemini eval (eval_gemini.md) - T78 applied fix without discussion, T94 applied regex fix without user confirmation
- **What to do instead:** Explicit governance framework in PROTOCOL.md, repeated in each workflow

**Anti-Pattern 3: No Context Lifecycle**
- **Why it's bad:** Sessions accumulate bloat, agents lose orientation, no clear resume mechanism
- **Evidence:** Gemini eval - user had to manually prompt "/debug" to force systematic approach after multiple failed attempts
- **What to do instead:** Formalized checkpoint/clear/resume with STATE.md as source of truth

**Anti-Pattern 4: ASCII Art Diagrams**
- **Why it's bad:** Hard to maintain, not interactive, breaks in small viewports
- **Evidence:** Decision log in STATE.md (Quick 002 and 01-04): "Mermaid diagrams: Use Mermaid over ASCII for workflow/sequence diagrams (maintainability, interactivity)"
- **What to do instead:** Mermaid diagrams for workflows, plain markdown headers for sections

## Don't Hand-Roll

Problems that look simple but have existing solutions:

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Session state management | Custom JSON format | Follow OpenAI Agents SDK session pattern | Handles context length, history, continuity automatically |
| Checkpoint/resume | Custom save/load logic | LangGraph-style checkpointing | Saves state at each node, enables retry/debug/human-in-loop |
| Multi-agent coordination | Custom messaging | Model Context Protocol (MCP) | Standardized contexts, eliminates custom integration per LLM |
| Workflow orchestration | Ad-hoc task sequencing | Agent Communication Protocol (ACP) | Standardized messaging formats across agents |

**Key insight from OG GSD:** Don't reinvent workflow decomposition patterns. GSD already has proven patterns (discuss → plan → execute → verify). GSD-lite should adapt these, not create new ones.

## Common Pitfalls

### Pitfall 1: Workflow Files Too Large

**What goes wrong:** "Decomposed" workflows still 500+ lines each, defeating the purpose

**Why it happens:** Trying to document all edge cases, all variations, all examples in one file

**How to avoid:**
- Target 200-300 lines per workflow file
- Link to reference docs for deep-dives (checkpoints.md, questioning.md, etc.)
- Examples in templates, not protocols

**Warning signs:** Workflow file has >400 lines, multiple "mode switches" within same file

### Pitfall 2: Inconsistent Sticky Notes

**What goes wrong:** Some workflows omit sticky notes, or format differently

**Why it happens:** Each workflow written independently, no shared template

**How to avoid:**
- Include identical sticky note section in ALL workflows
- Use EXACT same format (gsd-status fenced block)
- Self-check section prevents phantom updates

**Warning signs:** User confusion about "where am I?" or "what changed?" - sticky note missing or incomplete

### Pitfall 3: No Entry/Exit Conditions

**What goes wrong:** Unclear when to load which workflow, workflows don't chain properly

**Why it happens:** Workflows written without considering the orchestration layer

**How to avoid:**
- Every workflow starts with entry condition (when to load this)
- Every workflow ends with exit condition (what triggers next workflow)
- PROTOCOL.md acts as router: "If X state, load Y workflow"

**Warning signs:** User has to manually tell agent which workflow to use, transitions are jarring

### Pitfall 4: Coaching Philosophy Only in One File

**What goes wrong:** Philosophy documented in PROTOCOL.md but workflows don't reference it

**Why it happens:** Assumption that agent will remember from initial read

**How to avoid:**
- Repeat key principles at top of each workflow file
- Reference governance table in decision points
- Moodboard/whiteboard explicitly state: "User owns outcome, you guide"

**Warning signs:** Eval shows agents making decisions that should be user's (layout choices, scope additions)

### Pitfall 5: Forgetting Weaker Models

**What goes wrong:** Protocols work for Claude Opus, fail for Gemini/Sonnet

**Why it happens:** Testing only with strongest model

**How to avoid:**
- Design for "weakest acceptable model" (Gemini 3.0 Pro, Claude Sonnet)
- Explicit, formulaic instructions (not "be thoughtful")
- Self-check sections catch hallucinated completion

**Warning signs:** Claude works, Gemini skips steps or hallucinates

## Code Examples

Not applicable - this is an architectural/documentation phase.

## State of the Art

### Context Management Evolution

| Old Approach (2024) | Current Approach (2026) | When Changed | Impact |
|---------------------|-------------------------|--------------|--------|
| Monolithic prompts | Modular workflow protocols | 2025 Q3 | Reduced cognitive load, agents can load only relevant protocol |
| Chat history as context | Session state in artifacts | 2025 Q4 | Enables fresh context windows, checkpoint/resume capability |
| Implicit autonomy | Explicit governance frameworks | 2026 Q1 | Clear accountability, user knows when they'll be asked |
| Single all-purpose agent | Orchestrated specialized agents | 2025 Q4 | Better quality, isolated failures, transparent reasoning |

### GSD-lite vs OG GSD Architectural Differences

| Dimension | OG GSD | GSD-lite | Rationale |
|-----------|--------|----------|-----------|
| **Orchestration** | Multi-agent (spawns subagents) | Single-agent sessions | GSD-lite targets weaker models in chat apps, no orchestration layer |
| **Context strategy** | Fresh windows via Task tool | Checkpoint → clear → resume manually | No programmatic agent spawning, relies on user starting fresh chat |
| **Workflow scope** | Project/milestone/phase level | Single phase only | GSD-lite for incremental work, not multi-month projects |
| **Protocol location** | `.claude/get-shit-done/workflows/` | `gsd-lite/workflows/` | Namespace separation |
| **Artifact depth** | Deep (RESEARCH, PLAN, SUMMARY, UAT) | Minimal (STATE, WORK, INBOX, HISTORY) | Aggressive trimming for weak agent resume |
| **Planning mode** | Separate discuss-phase workflow | Embedded in protocol (MOODBOARD/WHITEBOARD) | Simpler mental model |
| **Promotion** | Automatic after phase complete | User-controlled | Prevents premature WORK.md deletion |

**Key insight:** GSD-lite is NOT a simplified GSD. It's a single-session pattern optimized for weak agents in chat apps, using GSD's workflow decomposition principles but with different architectural constraints.

### Deprecated/Outdated

From eval findings and current protocol:

- **ASCII art diagrams**: Replaced with Mermaid (decision 01-04)
- **Automatic phase promotion**: Replaced with user-controlled promotion (decision 01.2-03)
- **BOOTLOADER.md, README.md**: Consolidated into PROTOCOL.md (Phase 1.2)
- **Generic "Discussion" workflow**: Replaced with MOODBOARD (questioning) + WHITEBOARD (proposal) split

## Open Questions

Things that couldn't be fully resolved:

### 1. **Mode tracking in STATE.md**

- **What we know:** STATE.md needs to track current workflow (moodboard, whiteboard, execution, checkpoint)
- **What's unclear:** Should this be explicit field, or inferred from task status?
- **Recommendation:** Add explicit `Current Mode:` field to STATE.md template. Prevents ambiguity when resuming.

### 2. **Workflow transition rules in PROTOCOL.md**

- **What we know:** PROTOCOL.md should route to appropriate workflow based on state
- **What's unclear:** How complex should the routing logic be? Simple if/else, or decision tree?
- **Recommendation:** Start simple (4 routes), expand if evaluation shows confusion. Too complex = hard to maintain.

### 3. **Sticky note self-check enforcement**

- **What we know:** Gemini eval showed phantom updates (claimed to write files without tool execution)
- **What's unclear:** Does self-check actually prevent this, or do we need verification step?
- **Recommendation:** Include self-check in ALL workflows, then re-evaluate with Gemini after Phase 1.3 implementation

### 4. **Eval findings integration**

- **What we know:** eval_claude.md and eval_gemini.md reveal specific failure modes
- **What's unclear:** Should ANALYSIS.md analyze these through "coaching lens" or "architectural lens"?
- **Recommendation:** Both. Coaching lens = when did agent overstep/undershoot autonomy. Architectural lens = what protocol gaps enabled failure.

## Sources

### Primary (HIGH confidence)

- `.gsd_reference/get-shit-done/workflows/discuss-phase.md` - OG GSD workflow pattern analysis
- `.gsd_reference/get-shit-done/workflows/execute-plan.md` - OG GSD execution pattern, checkpoint protocols
- `.gsd_reference/get-shit-done/references/checkpoints.md` - Checkpoint types and anti-patterns
- `gsd-lite/template/PROTOCOL.md` - Current monolithic protocol (930 lines)
- `eval/eval_claude.md` - Claude Sonnet 4 evaluation trace showing premature implementation
- `eval/eval_gemini.md` - Gemini 3.0 Pro evaluation trace showing protocol violations
- `eval/another_eval_gsd_gemini.md` - Additional Gemini eval findings on hallucination, missing research mode
- `.planning/GSD_PATTERNS.md` - GSD pattern analysis for this project

### Secondary (MEDIUM confidence - 2026 industry research)

Context lifecycle management:
- [OpenAI Agents SDK Session Memory](https://cookbook.openai.com/examples/agents_sdk/session_memory) - Session management patterns
- [AI Agents' Context Management Breakthroughs](https://bytebridge.medium.com/ai-agents-context-management-breakthroughs-and-long-running-task-execution-d5cee32aeaa4) - Checkpointing and long-running task execution
- [Agent Lifecycle Management 2026](https://onereach.ai/blog/agent-lifecycle-management-stages-governance-roi/) - Lifecycle stages and governance

Coaching philosophy / autonomy levels:
- [Copilot vs Agentic Intelligence 2026](https://www.ampcome.com/post/copilot-vs-agentic-intelligence-2026) - Assistance vs delegation paradigm
- [Levels of Autonomy for AI Agents](https://knightcolumbia.org/content/levels-of-autonomy-for-ai-agents-1) - Autonomy level frameworks
- [Agentic AI in Enterprise 2026](https://acmeminds.com/agentic-ai-for-enterprises-in-2026-a-practical-guide/) - Human-in-loop approaches and governance

Workflow decomposition:
- [Multi-Agent AI Systems: Orchestrating Workflows](https://www.v7labs.com/blog/multi-agent-ai) - Multi-agent orchestration and task decomposition
- [The 2026 Guide to AI Agent Workflows](https://www.vellum.ai/blog/agentic-workflows-emerging-architectures-and-design-patterns) - Modular, specialized agent architectures
- [Top 5 Open Protocols for Multi-Agent AI 2026](https://onereach.ai/blog/power-of-multi-agent-ai-open-protocols/) - MCP, ACP, A2A protocols

## Metadata

**Confidence breakdown:**
- Workflow decomposition patterns: HIGH - Directly observable in OG GSD reference, validated by 2026 industry research
- Context lifecycle (checkpoint/clear/resume): HIGH - Pattern exists in OG GSD, validated by OpenAI SDK and LangGraph approaches
- Coaching philosophy: MEDIUM - Inferred from OG GSD discuss-phase, supported by 2026 governance frameworks but not explicitly documented in GSD
- GSD-lite vs OG GSD differences: HIGH - Directly comparable from codebase analysis
- Eval findings analysis: HIGH - Primary source material (eval files) available

**Research date:** 2026-01-25
**Valid until:** 60 days (stable architectural patterns, minimal API churn risk)
