whiteport-design-studio 0.2.2 → 0.3.0

package/docs/tools/excalidraw.md

@@ -0,0 +1,384 @@
+# Excalidraw
+
+**Category:** Wireframing Tool
+**Purpose:** Agent + human collaborative wireframing with editable JSON format
+**Website:** <https://excalidraw.com>
+**VS Code Extension:** [Excalidraw Editor](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor)
+
+---
+
+## What It Is
+
+Excalidraw is a whiteboard-style drawing tool with a hand-drawn aesthetic. In WDS, its killer feature is that `.excalidraw` files are **plain JSON** — meaning agents can programmatically create, modify, and clean up wireframes while the user edits the same file visually in VS Code.
+
+This creates a genuine **two-way collaboration loop** that no other wireframing tool offers:
+
+1. Agent scaffolds wireframe from spec (JSON manipulation)
+2. User opens in VS Code, tweaks layout and positions visually
+3. Agent reads file back, updates spec to match
+4. Agent adds new elements or cleans up annotations
+5. User exports PNG for documentation
+
+**Output formats:**
+- `.excalidraw` — Editable JSON source (version controlled)
+- `.png` / `.svg` — Exported images for documentation and GitHub rendering
+
+---
+
+## Why WDS Recommends It
+
+**Agent-Human Collaboration:**
+- Agent writes JSON, user edits visually — same file, no handoff
+- The "sketchy" hand-drawn style signals "work in progress" — right tone for wireframes
+- JSON diffs are readable in git — fits the plain-text WDS philosophy
+- No account, no cloud service, no API keys required
+
+**Speed:**
+- Agent can scaffold a full page wireframe from a spec in one pass
+- User can drag elements, adjust sizes, add hand-drawn touches instantly
+- Cleanup scripts batch-remove annotations for clean exports
+- No export/import cycle between tools
+
+**Integration:**
+- Lives directly in the project repository alongside specs
+- VS Code extension opens files inline — no context switching
+- PNG export renders on GitHub for spec review
+- Object IDs and groupIds map directly to spec sections
+
+---
+
+## Setup Instructions
+
+### 1. VS Code Extension
+
+Install the Excalidraw Editor extension:
+
+1. Open VS Code Extensions (Ctrl+Shift+X)
+2. Search for "Excalidraw Editor" by pomdtr
+3. Install
+4. `.excalidraw` files now open as visual drawings in VS Code
+
+### 2. Folder Convention
+
+Place wireframe files in the page's Sketches folder:
+
+```
+C-UX-Scenarios/
+└── 01-about-pages/
+    └── 1.1-hem/
+        ├── 1.1-hem.md              # Spec (references wireframe)
+        └── Sketches/
+            ├── 1.1-hem-wireframe.excalidraw   # Editable source
+            └── 1.1-hem-wireframe.png           # Exported image
+```
+
+### 3. No Additional Setup Required
+
+Excalidraw requires no accounts, API keys, or cloud services. The VS Code extension is all you need.
+
+---
+
+## File Format Reference
+
+### Structure
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor",
+  "elements": [ ... ],
+  "appState": { ... }
+}
+```
+
+### Element Properties
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `id` | Unique identifier | `"elem_30"`, `"hero_badge_bg"` |
+| `type` | Element type | `"rectangle"`, `"text"`, `"line"`, `"ellipse"` |
+| `x`, `y` | Position | `211`, `400` |
+| `width`, `height` | Size | `1440`, `80` |
+| `strokeColor` | Stroke/text color | `"#1e1e1e"`, `"#ffffff"` |
+| `backgroundColor` | Fill color | `"#364fc7"`, `"transparent"` |
+| `groupIds` | Section membership | `["header"]`, `["hero"]` |
+| `text` | Text content (text elements) | `"Bilverkstad på\nnorra Öland"` |
+| `fontSize` | Font size (text elements) | `48`, `14` |
+| `fontFamily` | Font style | 1=handwritten, 2=sans-serif, 3=monospace |
+
+### GroupIds Convention
+
+Map groupIds to spec sections:
+
+| groupId | Spec Section |
+|---------|-------------|
+| `"header"` | Site Header |
+| `"service-menu"` | Service Menu |
+| `"hero"` | Hero Section |
+| `"vehicle-icons"` | Vehicle Icon Bar |
+| `"about"` | About Preview |
+| `"trust-card-0"` | Trust Card 1 |
+| `"seasons"` | Seasons Section |
+| `"season-0"` | Season Card (Spring) |
+| `"footer"` | Footer |
+
+---
+
+## WDS Workflows
+
+### Workflow A: Agent Scaffolds Wireframe from Spec
+
+When a page spec exists but has no wireframe yet:
+
+```
+1. Agent reads page spec (sections, objects, content)
+2. Agent creates .excalidraw JSON with elements for each section
+   - Rectangles for containers and image placeholders
+   - Text elements for headings, body, labels
+   - Lines for dividers and decorations
+   - groupIds matching spec sections
+3. Agent adds annotation layer (optional, for dev reference)
+4. User opens file, adjusts layout visually
+5. User exports PNG
+6. Agent updates spec header to reference wireframe + PNG
+```
+
+**Agent code pattern:**
+
+```javascript
+const fs = require('fs');
+
+const data = {
+  type: 'excalidraw',
+  version: 2,
+  source: 'https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor',
+  elements: []
+};
+
+// Add a section background
+data.elements.push({
+  type: 'rectangle',
+  id: 'hero_bg',
+  x: 100, y: 200, width: 1440, height: 600,
+  strokeColor: '#1e1e1e',
+  backgroundColor: '#343a40',
+  groupIds: ['hero'],
+  // ... other required properties
+});
+
+// Add a text element
+data.elements.push({
+  type: 'text',
+  id: 'hero_heading',
+  x: 200, y: 350, width: 500, height: 60,
+  strokeColor: '#ffffff',
+  text: 'Page Heading',
+  fontSize: 48,
+  fontFamily: 1,
+  groupIds: ['hero'],
+  // ... other required properties
+});
+
+fs.writeFileSync('wireframe.excalidraw', JSON.stringify(data, null, 2));
+```
+
+### Workflow B: Agent Updates Existing Wireframe
+
+When the wireframe needs changes (new elements, cleanup, style updates):
+
+```
+1. Agent reads .excalidraw JSON
+2. Agent modifies elements array:
+   - Add: data.elements.push(newElement)
+   - Remove: data.elements = data.elements.filter(e => !removeIds.has(e.id))
+   - Update: element.strokeColor = '#ffffff'
+3. Agent writes file back
+4. User closes and reopens tab in VS Code (extension caches in memory)
+5. User reviews, adjusts, exports new PNG
+```
+
+### Workflow C: Spec ↔ Wireframe Sync
+
+When wireframe and spec need to stay aligned:
+
+```
+Wireframe changed → Update spec:
+1. Agent reads wireframe, catalogs all text elements and groups
+2. Agent compares against spec sections
+3. Agent updates spec: layout diagram, object specs, Object ID table
+
+Spec changed → Update wireframe:
+1. Agent reads spec for new/changed objects
+2. Agent adds/modifies wireframe elements
+3. User adjusts layout visually
+```
+
+### Workflow D: Annotation and Cleanup
+
+For development annotations that should be removed before export:
+
+```
+Adding annotations:
+- Red (#e03131) + fontFamily 3 = component ID labels: [object-id]
+- Brown (#846358) + fontFamily 3 = section numbers: ①②③
+- Green (#2f9e44) + fontFamily 3 = change notes
+- Place outside page boundaries (x < 100 or x >= 1560)
+- Leave groupIds empty (not part of any section)
+
+Removing annotations (before export):
+- Filter by strokeColor: #e03131, #846358, #2f9e44
+- Filter by fontFamily: 3 (monospace = annotation font)
+- Filter by position: outside page bounds
+- Filter by empty groupIds
+```
+
+---
+
+## Spec Page Integration
+
+### Header Format
+
+Every spec page that has a wireframe should use this header structure:
+
+```markdown
+### page-name
+
+**Previous Step:** ...
+**Next Step:** → ...
+
+![Page Wireframe](Sketches/page-wireframe.png)
+
+[page-wireframe.excalidraw](Sketches/page-wireframe.excalidraw) (open in VS Code with Excalidraw extension)
+
+**Previous Step:** ...
+**Next Step:** → ...
+
+---
+```
+
+**Key rules:**
+- Navigation appears **above and below** the wireframe (user shouldn't have to scroll back up)
+- PNG image renders inline on GitHub
+- Excalidraw link opens in VS Code for editing
+
+### Layout Structure Diagram
+
+The spec should include an ASCII layout diagram that matches the wireframe:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ [SHARED] Site Header                                             │
+├──────────────────────────────────────────────────────────────────┤
+│ [PAGE] Hero Section                                              │
+│ Status badge, H1, subtitle, CTA buttons                         │
+├──────────────────────────────────────────────────────────────────┤
+│ [PAGE] Content Section                                           │
+├──────────────────────────────────────────────────────────────────┤
+│ [SHARED] Footer                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## WDS Best Practices
+
+### DO
+
+**1. Use GroupIds Consistently**
+- Every element belongs to a group matching its spec section
+- Shared components: `"header"`, `"service-menu"`, `"footer"`
+- Page sections: `"hero"`, `"about"`, `"trust-card-0"`, `"season-2"`
+
+**2. Use Descriptive Element IDs**
+- `"hero_badge_bg"`, `"lang_pill_bg"`, `"hitta_btn_bg"`
+- Or sequential: `"elem_1"`, `"elem_2"` for initial scaffolding
+
+**3. Keep Wireframe Content Accurate**
+- Text in wireframe should match spec content (at least Swedish version)
+- Layout proportions should roughly match intended design
+- Use placeholder patterns (X-cross lines) for image areas
+
+**4. Export PNG After Each Major Change**
+- PNG is what renders on GitHub
+- Excalidraw extension has built-in export
+- Keep PNG and .excalidraw in sync
+
+**5. Version Control Both Files**
+- Commit `.excalidraw` (editable source) and `.png` (rendered image)
+- JSON diffs show exactly what changed
+
+### DON'T
+
+**1. Don't Leave Annotations in Exports**
+- Always clean up red/brown/green annotations before PNG export
+- Agent can batch-remove with a filter script
+
+**2. Don't Over-Detail Wireframes**
+- Wireframes show layout and content hierarchy, not pixel-perfect design
+- The hand-drawn style is a feature — it communicates "this is iterative"
+- Save visual polish for Figma or production code
+
+**3. Don't Edit While Agent Is Writing**
+- VS Code extension caches in memory
+- If agent modifies file on disk, close and reopen the tab
+- Avoid simultaneous edits
+
+**4. Don't Add Annotations to Exported Images**
+- Annotations are for the editable .excalidraw file only
+- PNG should show only what the end user sees
+
+---
+
+## Caveats and Limitations
+
+### VS Code Extension Caching
+
+The Excalidraw VS Code extension caches file content in memory. When the agent modifies the `.excalidraw` file on disk via scripts, the editor tab does **not** auto-reload. The user must **close and reopen** the tab to see changes.
+
+**Always warn the user about this after programmatic modifications.**
+
+### No MCP Server
+
+Unlike Figma, Excalidraw has no MCP server for live bidirectional sync. The agent reads and writes the JSON file directly. This is actually simpler — no server setup, no API keys, no network dependency.
+
+### Desktop Canvas Size
+
+Wireframes use a 1440px desktop canvas width convention:
+- Page content area: x=100 to x=1540
+- Annotations: x < 100 (left margin) or x >= 1560 (right margin)
+
+### Export Quality
+
+PNG export from the VS Code extension is adequate for documentation. For higher quality, open the file at excalidraw.com and export from there.
+
+---
+
+## When to Use
+
+### Use Excalidraw for:
+
+- **Phase 4 wireframing** — Layout structure, content hierarchy, component placement
+- **Spec ↔ wireframe sync** — Agent keeps both artifacts aligned
+- **Iterative design** — User adjusts layout, agent updates spec
+- **Documentation** — PNG renders on GitHub, Excalidraw source stays editable
+- **Early mockups** — Quick visual representation of page structure
+
+### Don't use for:
+
+- **Pixel-perfect design** — Use Figma for production-ready visuals
+- **Image asset creation** — Use NanoBanana for hero photos, card images
+- **Interactive prototypes** — Use HTML/Astro prototypes for interactivity
+- **Design system documentation** — Use Figma or code-based design tokens
+
+---
+
+## Resources
+
+- Website: <https://excalidraw.com>
+- VS Code Extension: [Excalidraw Editor](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor)
+- File Format: <https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/json.ts>
+
+---
+
+[← Back to Tools](wds-tools-guide.md)

package/docs/tools/wds-tools-guide.md

@@ -2,7 +2,7 @@
 
 **Purpose:** Recommended tools for WDS workflows with setup instructions and best practices.
 
-**Last Updated:** January 8, 2026
+**Last Updated:** February 25, 2026
 
 ---
 
@@ -30,6 +30,11 @@ WDS works best with a curated set of tools that support the concept-first, itera
 
 ### Recommended Tools
 
+**[Excalidraw](excalidraw.md)**
+- Agent + human collaborative wireframing (JSON format)
+- Agent writes elements, user edits visually in VS Code
+- **Status:** Recommended for Phase 4 wireframing
+
 **[Figma MCP](figma-mcp.md)**
 - MCP server for automated Figma integration
 - Component-level injection and bidirectional sync
@@ -62,6 +67,7 @@ WDS works best with a curated set of tools that support the concept-first, itera
 |------|----------|-------------|-----------|--------|
 | **[Cursor/Windsurf](cursor-windsurf.md)** | IDE | Development, agent interaction | All | Required |
 | **[Git](git.md)** | Version Control | Track changes, collaborate | All | Required |
+| **[Excalidraw](excalidraw.md)** | Wireframing | Agent+human wireframes, JSON format | 4 | Recommended |
 | **[Figma](figma.md)** | Design | Visual refinement, design system | 4-5 | Optional |
 | **[Figma MCP](figma-mcp.md)** | Integration | Automated Figma ↔ WDS sync | 4-5 | Recommended |
 | **[html.to.design](html-to-design.md)** | Conversion | HTML → Figma (fallback) | 4-5 | Optional |
@@ -81,18 +87,20 @@ WDS works best with a curated set of tools that support the concept-first, itera
 
 1. Install [Cursor or Windsurf IDE](cursor-windsurf.md)
 2. Install [Git](git.md)
-3. Create [Figma](figma.md) account
-4. Install and configure [Figma MCP](figma-mcp.md) server
-5. Set up Figma API access token
+3. Install [Excalidraw](excalidraw.md) VS Code extension (wireframing)
+4. Create [Figma](figma.md) account
+5. Install and configure [Figma MCP](figma-mcp.md) server
+6. Set up Figma API access token
 
 ### Full Setup (All Features)
 
 1. Install [Cursor or Windsurf IDE](cursor-windsurf.md)
 2. Install [Git](git.md)
-3. Create [Figma](figma.md) account
-4. Install and configure [Figma MCP](figma-mcp.md) server
-5. Set up Figma API access token
-6. Explore [NanoBanana](nanobanana.md) for asset creation
+3. Install [Excalidraw](excalidraw.md) VS Code extension (wireframing)
+4. Create [Figma](figma.md) account
+5. Install and configure [Figma MCP](figma-mcp.md) server
+6. Set up Figma API access token
+7. Explore [NanoBanana](nanobanana.md) for asset creation
 
 ### Optional Tools
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "whiteport-design-studio",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Whiteport Design Studio - Strategic design methodology for AI-powered workflows",
   "keywords": [
     "design",
@@ -32,7 +32,7 @@
     "src/module.yaml",
     "src/module-help.csv",
     "docs/getting-started/",
-    "docs/learn-wds/",
+    "docs/learn/",
     "docs/method/",
     "docs/models/",
     "docs/tools/"

package/src/agents/freya-ux.agent.yaml

@@ -21,11 +21,12 @@ agent:
     communication_style: |
       Creative collaborator who brings strategic depth. Asks "WHY?" before "WHAT?" — connecting
       design choices to business goals and user psychology. Explores one challenge deeply rather
-      than skimming many. Suggests workshops when strategic thinking is needed.
+      than skimming many. Keeps responses focused and actionable — leads with decisions, follows
+      with rationale. Suggests workshops when strategic thinking is needed.
     principles: |
       - Domain: Phases 4 (UX Design), 6 (Asset Generation), 7 (Design System - optional). Hand over other domains to specialist agents.
       - Replaces BMM Sally (UX Designer) when WDS is installed.
-      - Load strategic context BEFORE designing — always connect to VTC/Trigger Map.
+      - Load strategic context BEFORE designing — always connect to Trigger Map.
       - Specifications must be logical and complete — if you can't explain it, it's not ready.
       - Prototypes validate before production — show, don't tell.
       - Design systems grow organically from actual usage, not upfront planning.
@@ -35,30 +36,30 @@ agent:
       - HELP: Reading the actual template into context before writing. Discussing decisions with the user. Delivering artifacts that the next phase can consume without auditing. The user's time goes to decisions, not corrections.
 
   menu:
+    - trigger: SC or fuzzy match on scenarios
+      exec: "{project-root}/_bmad/wds/workflows/3-scenarios/workflow.md"
+      description: "[SC] Scenarios — Outline user flows and journeys"
+
     - trigger: UX or fuzzy match on ux-design
       exec: "{project-root}/_bmad/wds/workflows/4-ux-design/workflow.md"
-      description: "[UX] UX Design: Create specifications and scenarios (Phase 4)"
+      description: "[UX] UX Design — Create pages and storyboards"
 
-    - trigger: AD or fuzzy match on agentic-development
-      exec: "{project-root}/_bmad/wds/workflows/_agent-dialogs/workflow.md"
-      description: "[AD] Agentic Development: Build features iteratively with agent dialogs"
+    - trigger: SP or fuzzy match on specifications
+      exec: "{project-root}/_bmad/wds/workflows/4-ux-design/workflow.md"
+      description: "[SP] Specifications — Write content, interaction and functionality specs"
 
     - trigger: SA or fuzzy match on audit-spec
       exec: "{project-root}/_bmad/wds/workflows/4-ux-design/data/specification-audit-workflow.md"
-      description: "[SA] Spec Audit: Audit page or scenario specifications for completeness and quality"
+      description: "[SA] Audit — Check spec completeness and quality"
 
-    - trigger: VD or fuzzy match on visual-design
+    - trigger: GA or fuzzy match on generate-assets
       exec: "{project-root}/_bmad/wds/workflows/6-asset-generation/workflow.md"
-      description: "[VD] Visual Design: Asset generation including Stitch AI and Figma integration (Phase 6)"
+      description: "[GA] Generate Assets — Nano Banana, Stitch and other services"
 
     - trigger: DS or fuzzy match on design-system
       workflow: "{project-root}/_bmad/wds/workflows/7-design-system/workflow.md"
-      description: "[DS] Design System: Build component library with design tokens (Phase 7 - optional)"
-
-    - trigger: ST or fuzzy match on testing
-      exec: "{project-root}/_bmad/wds/workflows/5-agentic-development/workflow-acceptance-testing.md"
-      description: "[ST] Acceptance Testing: Validate implementation matches design (Phase 5)"
+      description: "[DS] Design System — Build component library with design tokens"
 
     - trigger: DD or fuzzy match on design-delivery
       exec: "{project-root}/_bmad/wds/workflows/4-ux-design/workflow-handover.md"
-      description: "[DD] Design Handover: Package complete flows for development handoff (Phase 4)"
+      description: "[DD] Design Delivery — Package flows for development handoff"

package/src/agents/saga-analyst.agent.yaml

@@ -33,6 +33,17 @@ agent:
       - HARM: Producing output that looks complete but doesn't follow the template. The user must then correct what should have been right — wasting time, money, and trust. Plausible-looking wrong output is worse than no output. Custom formats break the pipeline for every phase downstream.
       - HELP: Reading the actual template into context before writing. Discussing decisions with the user. Delivering artifacts that the next phase can consume without auditing. The user's time goes to decisions, not corrections.
 
+  prompts:
+    - id: activation
+      content: |
+        Hi {user_name}, I'm Saga, your strategic analyst! 👋
+
+        I'll help you create a Product Brief and Trigger Map for {project_name}.
+
+        Check {starting_point} from config:
+        - If "pitch": Say "Before we dive into formal documentation, let's talk about your idea! Tell me in your own words — **what's the big idea? What problem are you solving and for whom?**" Then have a free-flowing discovery conversation to understand vision, audience, and goals before transitioning to the Product Brief workflow.
+        - If "brief": Say "Let's start with the Product Brief. Tell me in your own words: **What are you building?**" Then proceed directly with the [PB] Product Brief workflow.
+
   menu:
     - trigger: AS or fuzzy match on alignment-signoff
       exec: "{project-root}/_bmad/wds/workflows/0-alignment-signoff/workflow.md"

package/src/data/agent-guides/freya/agentic-development.md

@@ -1,14 +1,16 @@
 # Freya's Agentic Development Guide
 
-**When to load:** When implementing features, building prototypes, or fixing bugs through structured agent dialogs
+**When to load:** When implementing features, building prototypes, or fixing bugs through structured development
+
+> **Note:** Agent dialogs have been replaced by the Design Log system. Use `_progress/00-design-log.md` for state tracking and `_progress/agent-experiences/` for session insights.
 
 ---
 
 ## Core Principle
 
-**Agentic Development uses structured dialogs to build incrementally with full traceability.**
+**Agentic Development builds incrementally with full traceability via the design log.**
 
-Agent Dialogs bridge the gap between specifications and working code. Each step is self-contained, allowing fresh context while maintaining continuity.
+The design log bridges the gap between specifications and working code. Each step is self-contained, allowing fresh context while maintaining continuity.
 
 ---
 
@@ -23,7 +25,7 @@ Agentic Development is a **workflow approach** that produces various outputs:
 | **Bug Fixes** | Structured debugging and fixing | Issue resolution |
 | **Design Exploration** | Exploring visual/UX directions | Creative iteration |
 
-**Key Insight:** By structuring work into documented dialog folders, we create:
+**Key Insight:** By structuring work with a design log and experience records, we create:
 - **Isolation** — Each step can run in a fresh context
 - **Traceability** — Clear record of what was planned and executed
 - **Replayability** — Instructions can be rerun if needed
@@ -33,14 +35,14 @@ Agentic Development is a **workflow approach** that produces various outputs:
 
 ## Agent Startup Protocol
 
-**When awakened, always check for pending dialogs:**
+**When awakened, always check the design log:**
 
 ```
-1. Check: {output_folder}/_progress/agent-dialogs/
-2. Find dialogs where:
-   - Status = "Not Started" or "In Progress"
-   - Agent matches the awakened agent
-3. Present pending dialogs to user
+1. Read: {output_folder}/_progress/00-design-log.md
+2. Check Current and Backlog sections for:
+   - Items in progress
+   - Items ready to start
+3. Present current state to user
 ```
 
 This ensures no captured work is forgotten.
@@ -49,14 +51,14 @@ This ensures no captured work is forgotten.
 
 ## The Bridge Role
 
-Agent Dialogs bridge **specifications** and **development**:
+The design log bridges **specifications** and **development**:
 
 ```
 ┌─────────────────────┐         ┌─────────────────────┐         ┌─────────────────────┐
-│   SPECIFICATION     │         │   AGENT DIALOG      │         │   DEVELOPMENT       │
+│   SPECIFICATION     │         │   DESIGN LOG        │         │   DEVELOPMENT       │
 │                     │         │                     │         │                     │
 │ • What to build     │────────▶│ • What's in scope   │────────▶│ • How to build      │
-│ • Object IDs        │         │ • Step breakdown    │         │ • Code files        │
+│ • Object IDs        │         │ • Current/Backlog   │         │ • Code files        │
 │ • Requirements      │         │ • Traceability      │         │ • Components        │
 │ • Translations      │         │ • Progress tracking │         │ • Tests             │
 └─────────────────────┘         └─────────────────────┘         └─────────────────────┘
@@ -64,20 +66,18 @@ Agent Dialogs bridge **specifications** and **development**:
       of Truth                         Layer
 ```
 
-**The specification is the single source of truth.** Dialogs do not duplicate spec content — they map implementation tasks to spec sections via Object IDs.
+**The specification is the single source of truth.** The design log does not duplicate spec content — it maps implementation tasks to spec sections via Object IDs.
 
 ---
 
-## Dialog Folder Structure
+## Progress Folder Structure
 
 ```
-{output_folder}/_progress/agent-dialogs/
-└── {DATE}-{agent}-{feature-name}/
-    ├── {DATE}-{agent}-{feature-name}-dialog.md    ← Main file
-    └── steps/
-        ├── 01-{step-name}.md                      ← Self-contained steps
-        ├── 02-{step-name}.md
-        └── ...
+{output_folder}/_progress/
+├── 00-design-log.md                               ← Main state tracking
+└── agent-experiences/
+    ├── {DATE}-{agent}-{feature-name}.md            ← Session insights
+    └── ...
 ```
 
 ---
@@ -198,10 +198,10 @@ For each Object ID:
 - **Object IDs are the contract** — Every implementation maps to an Object ID
 - **Spec changes update the spec** — Not the dialog or step files
 
-### Dialog Files
+### Design Log
 - **Be thorough in Setup Context** — Assume zero prior knowledge
 - **Include file paths** — Always use absolute or project-relative paths
-- **Track progress** — Update the Steps Overview table after each step
+- **Track progress** — Update the design log after each step
 
 ### Execution
 - **Read spec first** — Before implementing any Object ID
@@ -213,9 +213,8 @@ For each Object ID:
 
 ## Related Resources
 
-- **Agent Dialog Workflow:** `workflows/_agent-dialogs/workflow.md`
-- **Dialog Template:** `workflows/_agent-dialogs/templates/dialog.template.md`
-- **Step Template:** `workflows/_agent-dialogs/templates/step.template.md`
+- **Design Log:** `{output_folder}/_progress/00-design-log.md`
+- **Agent Experiences:** `{output_folder}/_progress/agent-experiences/`
 - **Phase 4 UX Design:** `workflows/4-ux-design/workflow.md`
 - **Inline Testing Guide:** `workflows/5-agentic-development/guides/INLINE-TESTING-GUIDE.md`