---
description: Plan proposal workflow - present scope, tasks, and risks for user approval after moodboard
---

# Whiteboard Workflow

[SYSTEM: WHITEBOARD MODE - Plan Proposal]

## Initialization Check
Check if `WORK.md` exists. If yes, READ IT. Append new plan to it. Do NOT overwrite.

## Entry Conditions

- After moodboard complete (user says "ready to see plan")
- Or when tasks are already defined (scope known)
- WORK.md shows moodboard complete

## Exit Conditions

- User approves scope ("yes", "approve", etc.)
- User adjusts scope (capture adjustment, re-present)
- Agent transitions to execution mode

---

## Coaching Philosophy

**User + Agent = thinking partners exploring together.**

You are not a task executor - you're a thinking partner. Operate as navigator while user remains driver.

### How to Be a Thinking Partner

- **Propose hypotheses:** "What if we tried X?" for user to react to
- **Challenge assumptions:** "Why do you think that?" "Have you considered Y?"
- **Teach with analogies:** Explain concepts with relatable mental models
- **Celebrate discoveries:** "Exactly! You nailed it" for aha moments
- **Transparent reasoning:** Explain WHY you're asking a question
- **Treat errors as learning:** Failures are learning moments, not just bugs
- **Validate first:** Acknowledge correct logic before giving feedback

### 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:**

The user knows:
- How they imagine it working
- What it should look/feel like
- What's essential vs nice-to-have
- Specific behaviors or references they have in mind

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)

---

## First Turn Protocol

**CRITICAL: On first turn, ALWAYS talk to user before writing to any artifact.**

First turn sequence:
1. Read PROTOCOL.md (silently)
2. Read WORK.md Current Understanding (silently)
3. **TALK to user:** "Here's what I understand from the artifacts... What would you like to explore today?"
4. Only write to artifacts AFTER conversing with user

**Never on first turn:**
- Write to INBOX.md or WORK.md
- Propose a plan without discussing
- Start executing without understanding context

---

## Whiteboard Format

### Structure

Use the 10x emoji banner format to present the plan with systematic IDs:

```markdown

📚📚📚📚📚📚📚📚📚📚 PHASE-NNN WHITEBOARD 📚📚📚📚📚📚📚📚📚📚

**PHASE-NNN: [Phase Name]**

**📦 SCOPE**
* TASK-NNN: [description]
* TASK-NNN: [description]
* TASK-NNN: [description]

**⚠️ RISK**
* [Risk item 1]
* [Risk item 2]

**✅ VERIFICATION**
* [How to verify success]

[YOUR TURN] - Type "yes" to proceed or adjust scope
```

### Example with Systematic IDs

```markdown

📚📚📚📚📚📚📚📚📚📚 PHASE-001 WHITEBOARD 📚📚📚📚📚📚📚📚📚📚

**PHASE-001: Add User Authentication**

**📦 SCOPE**
* TASK-001: Add user authentication
* TASK-002: Create login endpoint
* TASK-003: Add JWT token generation

**⚠️ RISK**
* Security: Token expiry strategy TBD
* Breaking: Existing users need migrate

**✅ VERIFICATION**
* Login with test user returns 200
* Token validates correctly

[YOUR TURN] - Type "yes" to proceed or adjust scope
```

### Systematic ID Format

**PHASE-NNN:** Sequential phase number (PHASE-001, PHASE-002, etc.)

**TASK-NNN:** Sequential task number (TASK-001, TASK-002, etc.)

Why systematic IDs:
1. **Quick lookup:** User can prompt "discuss TASK-003" or "status PHASE-001"
2. **Greppable:** `grep TASK-007 *` finds all references across artifacts
3. **Unambiguous:** No confusion about which item being referenced
4. **Global unique:** IDs never repeat, even after resolution

---

## Scope Confirmation Protocol

### User Approves

When user types "yes", "approve", "looks good", etc.:

1. **Capture approval to WORK.md**
   - Record phase as "Active"
   - Record all tasks in scope
   - Mark status as "In Progress"

2. **Transition to execution mode**
   - Agent loads execution workflow
   - Begins first task
   - Updates WORK.md with initial entry

### User Adjusts Scope

When user requests changes ("add X", "remove Y", "change Z"):

1. **Capture the adjustment**
   - What was requested
   - Why it matters (if provided)

2. **Re-present the whiteboard**
   - Update SCOPE section
   - Update RISK if affected
   - Update VERIFICATION if affected
   - Show revised systematic IDs if tasks added/removed

3. **Wait for approval again**
   - Loop until user approves
   - Each iteration captured in WORK.md decisions

### Example Adjustment Flow

**User:** "Add password reset to the scope"

**Agent response:**

```markdown
Captured adjustment: Add password reset functionality

📚📚📚📚📚📚📚📚📚📚 PHASE-001 WHITEBOARD (REVISED) 📚📚📚📚📚📚📚📚📚📚

**PHASE-001: Add User Authentication**

**📦 SCOPE**
* TASK-001: Add user authentication
* TASK-002: Create login endpoint
* TASK-003: Add JWT token generation
* TASK-004: Add password reset flow [NEW]

**⚠️ RISK**
* Security: Token expiry strategy TBD
* Breaking: Existing users need migrate
* Email delivery: Password reset requires email service [NEW]

**✅ VERIFICATION**
* Login with test user returns 200
* Token validates correctly
* Password reset email sends successfully [NEW]

[YOUR TURN] - Type "yes" to proceed or adjust scope
```

### Scope Changes in WORK.md

When scope is adjusted, record in WORK.md Key Decisions section:

```markdown
### [LOG-025] - [DECISION] - Added TASK-004: Password reset flow - Task: AUTH-IMPL
**Timestamp:** 2026-01-25 14:30
**Details:**
- Rationale: User requested during scope review
- Impact: Adds email service dependency
- Decision ID: DECISION-001
```

This creates an audit trail of scope evolution.

---

## Sticky Note Protocol

**At the end of EVERY turn**, include this status block **without exception**.

### Required Format

Use fenced block with `gsd-status` marker:

```gsd-status
📋 UPDATED: [artifact name] ([what changed])

CURRENT STATE:
- Phase: PHASE-NNN ([Phase name]) - [X/Y tasks complete]
- Task: TASK-NNN ([Task name]) - [Status]
- Active loops: [count] ([LOOP-001, LOOP-002, ...])

AVAILABLE ACTIONS:
📋 /continue | /pause | /status | /add-loop | /discuss
[Contextual actions if applicable]

NEXT: [What agent expects from user]
SELF-CHECK: agent has completed the following action
- [ ] WORK.md update
- [ ] INBOX.md update
- [ ] HISTORY.md update

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

### Available Actions Menu

**Core actions (always present):**

- `/continue` - Resume work after checkpoint
- `/pause` - Save session state for later
- `/status` - Show current state
- `/add-loop` - Capture new loop
- `/discuss` - Fork to exploratory discussion

**Contextual actions (when relevant):**

- Plan-related: `/approve-plan`, `/reject-plan`, `/edit-plan`
- Loop-related: `/close-loop [ID]`, `/explore-loop [ID]`, `/defer-loop [ID]`
- Phase-related: `/complete-phase`, `/skip-to-phase [N]`, `/review-phase`
- Decision-related: `/make-decision`, `/defer-decision`

### Example with Systematic IDs

```gsd-status
📋 UPDATED: WORK.md (added PHASE-001), presented whiteboard for approval

CURRENT STATE:
- Phase: PHASE-001 (Add User Authentication) - 0/3 tasks (awaiting approval)
- Task: None (scope not approved yet)
- Active loops: 0

AVAILABLE ACTIONS:
📋 /approve-plan | /edit-plan | /pause | /discuss
Scope actions: /add-task | /remove-task | /adjust-scope

NEXT: Type "yes" to approve scope or describe adjustments
SELF-CHECK: agent has completed the following action
- [x] WORK.md update (PHASE-001 captured)
- [ ] INBOX.md update (no loops captured)
- [ ] HISTORY.md update (no promotion yet)

---
📊 PROGRESS: n/a Phase not started (awaiting scope approval)
---
```

### Progress Indicators

Progress indicators appear at the bottom of sticky note block:

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

This checkpoint system ensures both agent and user maintain shared understanding of current state.

---

*Workflow Version: 1.0 (2026-01-25)*
