diff --git a/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-tools-summary.md b/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-tools-summary.md index 2663115a7..a70888c1e 100644 --- a/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-tools-summary.md +++ b/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-tools-summary.md @@ -31,7 +31,7 @@ The HTML to Design workflow focuses on: ### Key Components Built #### 1. Dev Mode JavaScript Component -- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js` +- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/components/dev-mode.js` - **Purpose**: Interactive tool for extracting Object IDs from live prototypes - **Features**: - Toggle dev mode with button or Ctrl+E @@ -42,7 +42,7 @@ The HTML to Design workflow focuses on: - Form field protection (Shift disabled when typing) #### 2. Work File Template -- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml` +- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/work-file-template.yaml` - **Purpose**: Complete planning document for section-by-section implementation - **Structure**: - Metadata and device compatibility diff --git a/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-work-summary.md b/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-work-summary.md index d63d4a142..93b98feca 100644 --- a/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-work-summary.md +++ b/docs/examples/wds-v6-conversion/F-Agent-Dialogs/html-to-design-work-summary.md @@ -13,7 +13,7 @@ This document summarizes the work done on the HTML to Design side of the WDS v6 - ESLint rule compliance (`unicorn/prefer-module`, `no-unused-vars`, etc.) ### 2. Dev Mode JavaScript Component -- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js` +- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/components/dev-mode.js` - **Purpose**: Developer/feedback mode for copying Object IDs in prototypes - **Features Implemented**: - Toggle dev mode with button or Ctrl+E @@ -24,7 +24,7 @@ This document summarizes the work done on the HTML to Design side of the WDS v6 - Form field protection (Shift disabled when typing) ### 3. Work File Template -- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml` +- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/work-file-template.yaml` - **Purpose**: Complete planning document for section-by-section implementation - **Structure**: - Metadata and device compatibility diff --git a/docs/getting-started/MANUAL-INIT-GUIDE.md b/docs/getting-started/MANUAL-INIT-GUIDE.md index 638da2a98..672eac52d 100644 --- a/docs/getting-started/MANUAL-INIT-GUIDE.md +++ b/docs/getting-started/MANUAL-INIT-GUIDE.md @@ -118,9 +118,9 @@ Choose a workflow to start: ``` *Define your product vision and goals* -### 🎨 **Interactive Prototypes** +### 🎨 **Agentic Development** ``` -@wds/workflows/interactive-prototypes +@wds/workflows/agentic-development ``` *Build clickable prototypes for testing* @@ -158,7 +158,7 @@ Choose a workflow to start: |----------|---------|-----------| | **Trigger Map** | User pain points | `@wds/workflows/trigger-map` | | **Product Brief** | Product vision | `@wds/workflows/product-brief` | -| **Prototypes** | Interactive demos | `@wds/workflows/interactive-prototypes` | +| **Prototypes** | Interactive demos | `@wds/workflows/agentic-development` | | **Scenario Init** | User journeys | `@wds/workflows/scenario-init` | --- diff --git a/docs/models/gtd-getting-things-done.md b/docs/models/gtd-getting-things-done.md new file mode 100644 index 000000000..502976e2d --- /dev/null +++ b/docs/models/gtd-getting-things-done.md @@ -0,0 +1,193 @@ +# Getting Things Done (GTD) + +**By:** David Allen (2001) +**Source:** "Getting Things Done: The Art of Stress-Free Productivity" + +--- + +## Core Concept + +GTD is a personal productivity methodology that helps manage commitments, information, and action. The core insight: your mind is for having ideas, not holding them. Capture everything externally, then organize and act systematically. + +--- + +## The Five Steps + +### 1. Capture +Collect everything that has your attention into a trusted system. Don't rely on memory. + +### 2. Clarify +Process what you've captured: +- Is it actionable? +- What's the next action? +- What's the desired outcome? + +### 3. Organize +Put things where they belong: +- Next Actions (by context) +- Projects (multi-step outcomes) +- Waiting For (delegated) +- Someday/Maybe (future ideas) +- Reference (information) + +### 4. Reflect +Review your system regularly: +- Daily: Check calendar, review next actions +- Weekly: Full review of all lists, projects, commitments + +### 5. Engage +Do the work with confidence, knowing your system has captured everything. + +--- + +## The 2-Minute Rule + +**If an action takes less than 2 minutes, do it immediately.** + +This is one of GTD's most powerful and widely-adopted principles: + +- The overhead of tracking a 2-minute task exceeds doing it +- Immediate completion clears mental clutter +- Builds momentum through quick wins +- Prevents small tasks from accumulating + +### In Practice + +| Situation | Action | +|-----------|--------| +| Quick email reply | Send now | +| Simple file rename | Do now | +| Brief clarification | Ask now | +| Small fix | Fix now | + +### The Threshold + +2 minutes is a guideline, not a strict rule. The principle is: + +> **Planning overhead should not exceed task complexity.** + +If documenting, categorizing, and scheduling a task takes longer than doing it β€” just do it. + +--- + +## Applied in WDS Agentic Development + +### Task Complexity Assessment + +Before adding something to the plan, ask: + +| Question | If Yes β†’ | +|----------|----------| +| Can I fix this in < 2 minutes? | Do it now, log as sub-step | +| Does it need context I don't have? | Add to plan | +| Does it affect architecture? | Add to plan | +| Is it outside current scope? | Level 4 change request | + +### Bug Fixes vs. Features + +**Bugs (2-minute candidates):** +- Missing condition check +- Wrong variable name +- Off-by-one error +- Missing translation + +**Features (need planning):** +- New component +- New state handling +- Architectural changes +- Multi-file refactors + +### Sub-Step Pattern + +When a 2-minute fix arises during planned work: + +1. **Do** the fix immediately +2. **Log** it as a sub-step (e.g., 20a-1) +3. **Continue** with the main task + +This maintains traceability without planning overhead. + +--- + +## Why This Matters for AI Collaboration + +Agentic development involves constant micro-decisions: +- Should I plan this? +- Should I do this now? +- Should I defer this? + +The 2-minute rule provides a clear heuristic: + +``` +IF task_complexity < 2_minutes: + execute_immediately() + log_as_substep() +ELSE: + add_to_plan() +``` + +This prevents: +- Analysis paralysis on trivial tasks +- Planning overhead exceeding task value +- Context switching from minor interruptions +- Accumulated technical debt from deferred tiny fixes + +--- + +## Related Concepts + +### Inbox Zero +Process everything to zero β€” don't leave items in limbo. + +### Next Actions +Define the very next physical action for every project. + +### Waiting For +Track delegated items so nothing falls through cracks. + +### Weekly Review +Regular system maintenance keeps it trustworthy. + +--- + +## Source Materials + +### Book +- **"Getting Things Done: The Art of Stress-Free Productivity"** by David Allen (2001, revised 2015) + +### Website +- [GettingThingsDone.com](https://gettingthingsdone.com) + +### Key Articles +- "The 2-Minute Rule" β€” David Allen +- "GTD in 15 minutes" β€” Various summaries online + +--- + +## WDS Integration Points + +| WDS Context | GTD Application | +|-------------|-----------------| +| **Agentic Development** | 2-minute rule for bug fixes, sub-step logging | +| **Agent Dialogs** | Capture system for ideas (dialog files) | +| **Change Requests** | Someday/Maybe list for outside-scope items | +| **Progress Logs** | Review and reflect on completed work | +| **Session Start Protocol** | Weekly review concept (check reality vs. plan) | + +--- + +## Quick Reference + +### The 2-Minute Rule +> If it takes less than 2 minutes, do it now. + +### The Core Principle +> Planning overhead should not exceed task complexity. + +### Applied to Development +> Quick fixes β†’ Do and log as sub-step +> Complex changes β†’ Add to plan first + +--- + +*Getting Things Done - Stress-free productivity through systematic capture and action.* diff --git a/docs/models/models-guide.md b/docs/models/models-guide.md index c7f925620..f316d5290 100644 --- a/docs/models/models-guide.md +++ b/docs/models/models-guide.md @@ -93,7 +93,7 @@ Used in Trigger Mapping Workshop 1 to transform vision (visionary statements) in ### [Kathy Sierra Badass Users](./kathy-sierra-badass-users.md) -**By:** Kathy Sierra (2000s-2015) +**By:** Kathy Sierra (2000s-2015) **Core Idea:** Don't make a better product. Make users better at what they want to do. Focus on user capability. **Applied in WDS:** @@ -106,6 +106,21 @@ Used in Trigger Mapping Workshop 1 to transform vision (visionary statements) in --- +### [Getting Things Done (GTD)](./gtd-getting-things-done.md) + +**By:** David Allen (2001) +**Core Idea:** Your mind is for having ideas, not holding them. Capture everything, then process and act systematically. + +**Applied in WDS:** +- **2-Minute Rule:** If it takes < 2 minutes, do it now (don't plan trivial tasks) +- Agent Dialogs as capture system (externalize all ideas) +- Change Requests as "Someday/Maybe" list +- Session Start Protocol as weekly review concept + +**When to Use:** Deciding whether to plan or act, managing task complexity, avoiding planning overhead + +--- + ## Models vs. Methods ### Models (This Folder) @@ -227,6 +242,7 @@ These models represent decades of insight from brilliant thinkers who've shaped - **Mijo Balic & Ingrid Domingues** - Connecting goals to user behavior - **Gojko Adzic** - Making strategic planning accessible - **Simon Sinek** - Teaching us to start with WHY +- **David Allen** - Systematic productivity and the 2-minute rule - **George T. Doran** - Creating measurable, achievable objectives - **Cathy Moore** - Focusing on action over information - **Kathy Sierra** - Championing user capability diff --git a/src/agents/freya-ux.agent.yaml b/src/agents/freya-ux.agent.yaml index 6b12fb79f..9bda0f438 100644 --- a/src/agents/freya-ux.agent.yaml +++ b/src/agents/freya-ux.agent.yaml @@ -59,9 +59,10 @@ agent: **Micro-Guides (load when needed):** - Strategic Design β†’ data/agent-guides/freya/strategic-design.md (before designing, VTC/Trigger Map connection) - Specification Quality β†’ data/agent-guides/freya/specification-quality.md (creating specs, logical explanations) - - Interactive Prototyping β†’ data/agent-guides/freya/interactive-prototyping.md (HTML prototypes, validation) + - Agentic Development β†’ data/agent-guides/freya/agentic-development.md (agent dialogs, prototype implementation, iterative building) - Content Creation β†’ data/agent-guides/freya/content-creation.md (strategic content, 6-model framework) - Design System β†’ data/agent-guides/freya/design-system.md (Phase 5, organic growth, Figma integration) + - Stitch Generation β†’ workflows/4-ux-design/stitch-generation/workflow.md (AI-assisted UI generation with Google Stitch) **Collaboration:** - My domain: Phases 4 (UX Design), 5 (Design System - optional), 7 (Testing) @@ -74,6 +75,7 @@ agent: - Prototypes validate before production (micro-guide: interactive-prototyping.md) - Content is strategic, not decorative (micro-guide: content-creation.md) - Design systems grow organically (micro-guide: design-system.md if Phase 5) + - AI-assisted design via Google Stitch when spec + sketch ready (workflow: stitch-generation) - Visual refinement via Figma when design system incomplete (automated MCP integration) **Project Tracking:** @@ -88,12 +90,20 @@ agent: - trigger: ux-design exec: "{project-root}/{bmad_folder}/wds/workflows/4-ux-design/workflow.md" - description: Create interactive prototypes and scenarios (Phase 4) + description: Create specifications and scenarios (Phase 4) + + - trigger: agentic-development + exec: "{project-root}/{bmad_folder}/wds/workflows/9-agent-dialogs/workflow.md" + description: Build features iteratively with agent dialogs (prototypes, implementations, bug fixes) - trigger: audit-spec exec: "{project-root}/{bmad_folder}/wds/workflows/4-ux-design/specification-audit-workflow.md" description: "[AS] Audit page or scenario specifications for completeness and quality" + - trigger: stitch-generation + exec: "{project-root}/{bmad_folder}/wds/workflows/4-ux-design/stitch-generation/workflow.md" + description: Generate UI designs with Google Stitch AI from specifications and sketches + - trigger: design-system exec: "{project-root}/{bmad_folder}/wds/workflows/5-design-system/workflow.md" description: Build component library with design tokens (Phase 5 - optional) diff --git a/src/data/agent-guides/freya/agentic-development.md b/src/data/agent-guides/freya/agentic-development.md new file mode 100644 index 000000000..be6ce15c4 --- /dev/null +++ b/src/data/agent-guides/freya/agentic-development.md @@ -0,0 +1,200 @@ +# Freya's Agentic Development Guide + +**When to load:** When implementing features, building prototypes, or fixing bugs through structured agent dialogs + +--- + +## Core Principle + +**Agentic Development uses structured dialogs to build incrementally with full traceability.** + +Agent Dialogs bridge the gap between specifications and working code. Each step is self-contained, allowing fresh context while maintaining continuity. + +--- + +## What is Agentic Development? + +Agentic Development is a **workflow approach** that produces various outputs: + +| Output Type | Description | When to Use | +|-------------|-------------|-------------| +| **Interactive Prototypes** | HTML prototypes that let users FEEL the design | Validating UX before production | +| **Prototype Implementation** | Building features from specifications | Feature development | +| **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: +- **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 +- **Handoff** β€” Different agents or humans can continue the work + +--- + +## Agent Startup Protocol + +**When awakened, always check for pending dialogs:** + +``` +1. Check: docs/F-Agent-Dialogs/ +2. Find dialogs where: + - Status = "Not Started" or "In Progress" + - Agent matches the awakened agent +3. Present pending dialogs to user +``` + +This ensures no captured work is forgotten. + +--- + +## The Bridge Role + +Agent Dialogs bridge **specifications** and **development**: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SPECIFICATION β”‚ β”‚ AGENT DIALOG β”‚ β”‚ DEVELOPMENT β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β€’ What to build │────────▢│ β€’ What's in scope │────────▢│ β€’ How to build β”‚ +β”‚ β€’ Object IDs β”‚ β”‚ β€’ Step breakdown β”‚ β”‚ β€’ Code files β”‚ +β”‚ β€’ Requirements β”‚ β”‚ β€’ Traceability β”‚ β”‚ β€’ Components β”‚ +β”‚ β€’ Translations β”‚ β”‚ β€’ Progress tracking β”‚ β”‚ β€’ Tests β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + Single Source Navigation Implementation + 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. + +--- + +## Dialog Folder Structure + +``` +docs/F-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 + └── ... +``` + +--- + +## Feedback Protocol + +During implementation, classify and handle feedback naturally: + +| Type | What It Is | When to Address | +|------|------------|-----------------| +| **Bug/Issue** | Something broken or not working as expected | Now β€” iterate until fixed | +| **Quick Adjustment** | Small tweak to current work | Now β€” implement immediately | +| **Addition** | New requirement that fits current scope | Later step β€” add to plan | +| **Change Request** | Outside current dialog scope | Future session β€” document in Change Requests | + +**Response Pattern:** +1. **Classify** β€” Note what kind of feedback this is +2. **Timing** β€” State when it should be addressed +3. **Confirm** β€” For additions and change requests, confirm before proceeding +4. **Execute** β€” Implement or document as appropriate + +--- + +## Interactive Prototypes (Output Type) + +Interactive Prototypes are **one output** of Agentic Development. + +### Why HTML Prototypes? + +**Static Specs Can't Show:** +- How it FEELS to interact +- Where users get confused +- What's missing in the flow +- If the pacing feels right + +**HTML Prototypes Reveal:** +- Interaction feels natural or awkward +- Information appears when needed +- Flow has logical gaps +- Users understand next steps + +### Fidelity Levels + +| Level | Focus | Use When | +|-------|-------|----------| +| **Wireframe** | Information architecture | Testing flow logic only | +| **Interactive** | User experience | Validating UX (standard) | +| **Design System** | Component-based | Phase 5 enabled | + +### Prototype vs Production + +**Prototypes ARE:** +- Thinking tools +- Communication tools +- Validation tools +- Specification supplements + +**Prototypes are NOT:** +- Production code +- Pixel-perfect mockups +- Final design + +--- + +## Prototype Implementation (Output Type) + +Building features from specifications through structured dialog steps. + +### Step File Structure + +Each step links to specifications (doesn't duplicate): + +```markdown +## Object ID Implementation Map + +| Object ID | Spec Section | Lines | +|-----------|--------------|-------| +| `booking-detail-header` | Drawer Header | L149-L158 | +| `booking-detail-close` | Close Button | L159-L168 | +``` + +### Implementation Checklist Pattern + +For each Object ID: +1. **Read** β€” Load the spec section +2. **Implement** β€” Build to match spec +3. **Verify** β€” Confirm Object ID present and behavior correct + +--- + +## Best Practices + +### Single Source of Truth +- **Never duplicate spec content** β€” Link to spec sections with line numbers +- **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 +- **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 + +### Execution +- **Read spec first** β€” Before implementing any Object ID +- **Fresh context is fine** β€” Steps are designed to work in isolation +- **Update as you go** β€” Don't wait to update progress +- **Capture discoveries** β€” Note spec changes or issues found + +--- + +## Related Resources + +- **Agent Dialog Workflow:** `workflows/9-agent-dialogs/workflow.md` +- **Dialog Template:** `workflows/9-agent-dialogs/templates/dialog.template.md` +- **Step Template:** `workflows/9-agent-dialogs/templates/step.template.md` +- **Phase 4 UX Design:** `workflows/4-ux-design/workflow.md` + +--- + +*Build incrementally. Document thoroughly. Let users FEEL the design before committing to production.* diff --git a/src/data/agent-guides/freya/interactive-prototyping.md b/src/data/agent-guides/freya/interactive-prototyping.md deleted file mode 100644 index 8848fd7e8..000000000 --- a/src/data/agent-guides/freya/interactive-prototyping.md +++ /dev/null @@ -1,259 +0,0 @@ -# Freya's Interactive Prototyping Guide - -**When to load:** When creating HTML prototypes or interactive mockups - ---- - -## Core Principle - -**HTML prototypes are THINKING TOOLS, not final products.** - -Prototypes let users FEEL the design before we commit to production code. They reveal gaps in logic that static specs might miss. - ---- - -## Why HTML Prototypes? - -### Static Specs Can't Show -- ❌ How it FEELS to interact -- ❌ Where users get confused -- ❌ What's missing in the flow -- ❌ If the pacing feels right -- ❌ Whether copy actually works - -### HTML Prototypes Reveal -- βœ… Interaction feels natural or awkward -- βœ… Information appears when needed -- βœ… Flow has logical gaps -- βœ… Users understand next steps -- βœ… Content triggers emotions - ---- - -## Prototypes as Validation - -**Think of prototypes as:** -- **Thinking tools** - Help us understand what we're building -- **Communication tools** - Show stakeholders/users the vision -- **Validation tools** - Catch problems before coding -- **Specification supplements** - Demonstrate what words can't - -**NOT:** -- ❌ Production code (that's Phase 4 β†’ BMM handoff) -- ❌ Pixel-perfect mockups (that's Figma's job) -- ❌ Final design (they're meant to evolve) - ---- - -## When to Create Prototypes - -### Always Create For -- Complex interactions (multi-step forms, wizards) -- Novel UI patterns (users haven't seen before) -- Critical flows (signup, purchase, onboarding) -- Content-heavy pages (validate information hierarchy) - -### Optional For -- Simple pages (standard layouts) -- Repetitive patterns (once validated, reuse) -- Admin interfaces (if similar to known patterns) - -**When in doubt β†’ Prototype.** 30 minutes of HTML saves hours of rework. - ---- - -## Prototype Fidelity Levels - -### 1. Wireframe Prototype (Fastest) -- Basic HTML structure -- Placeholder content -- No styling (browser defaults) -- Focus: Information architecture - -**Use when:** Testing flow logic only - ---- - -### 2. Interactive Prototype (Standard) -- Structured HTML -- Actual content (multi-language) -- Basic CSS (layout, spacing, typography) -- Interactive elements (buttons, forms, navigation) - -**Use when:** Validating user experience - ---- - -### 3. Design System Prototype (If Enabled) -- Component-based HTML -- Design System classes -- Design tokens (colors, spacing) -- Real interactions - -**Use when:** Phase 5 (Design System) is enabled - ---- - -## Using Design System Components - -### If Design System Enabled (Phase 5) - -**Check first:** -1. Does this component exist in the Design System? -2. If yes β†’ Use it -3. If similar β†’ Assess opportunity/risk of creating variant -4. If no β†’ Mark for future extraction - -**In prototype:** -```html - - - - - -
- ... -
-``` - ---- - -### If Design System Disabled - -**Use page-specific classes:** -```html - - -``` - -**Developers know:** No design system = implement as-is, no abstraction needed. - ---- - -## What to Include in Prototypes - -### Must Have -- βœ… All sections in correct order -- βœ… Actual content (headlines, copy, CTAs) -- βœ… Multi-language versions (separate HTML files or language toggle) -- βœ… Interactive elements (buttons, forms, links) -- βœ… Key states (default, hover, active, disabled) - -### Optional -- Form validation (unless testing UX) -- Backend integration (never) -- Pixel-perfect design (Figma's job) -- Production-quality code (it's a prototype!) - ---- - -## Prototype Validation Process - -### 1. Internal Check -- Click through the flow yourself -- Does it feel natural? -- Any confusing moments? -- Missing information? -- Logical gaps? - -### 2. Stakeholder Review -- Show prototype in conversation -- Watch where they pause or ask questions -- Note confusion points -- Validate assumptions - -### 3. User Testing (Optional) -- If critical flow, test with 3-5 users -- Watch, don't explain -- Note where they struggle -- Identify patterns - -### 4. Iterate -- Fix gaps revealed by validation -- Update specification accordingly -- Re-prototype if major changes - ---- - -## Prototype β†’ Specification Flow - -**Prototypes inform specs, not replace them:** - -1. **Create prototype** - Think through interaction -2. **Validate prototype** - Catch issues early -3. **Update specification** - Document what works -4. **Generate final spec** - With prototype insights - -**Result:** Specification is battle-tested before development. - ---- - -## Common Prototype Mistakes - -### ❌ Over-Engineering -"Let me make this perfect production code..." -- **Why bad:** Wastes time, misses the point -- **Instead:** Quick and dirty is fine - it's a prototype - -### ❌ Under-Engineering -"Just some divs with text..." -- **Why bad:** Can't validate actual experience -- **Instead:** Make it interactive enough to feel real - -### ❌ Skipping Validation -"I know this works, no need to test..." -- **Why bad:** Your assumptions might be wrong -- **Instead:** Always validate with at least one other person - -### ❌ Treating as Final -"This prototype IS the spec..." -- **Why bad:** Missing critical specification details -- **Instead:** Prototype β†’ insights β†’ specification - ---- - -## Technical Notes - -### File Structure -``` -docs/C-Scenarios/[scenario-name]/prototypes/ -β”œβ”€β”€ landing-page-en.html -β”œβ”€β”€ landing-page-se.html -β”œβ”€β”€ signup-flow-en.html -└── styles.css (shared) -``` - -### Basic Template -```html - - - - - - [Page Name] - Prototype - - - - - - - - -``` - ---- - -## Related Resources - -- **Phase 4 Workflow:** `../../workflows/4-ux-design/` -- **Design System:** `../../workflows/5-design-system/` -- **Page Specification Template:** `../../workflows/4-ux-design/templates/page-specification.template.md` - ---- - -*Show, don't tell. Let users FEEL the design before we build it.* - diff --git a/src/workflows/00-system/FILE-NAMING-CONVENTIONS.md b/src/workflows/00-system/FILE-NAMING-CONVENTIONS.md index 0e4b1326f..8695af6fa 100644 --- a/src/workflows/00-system/FILE-NAMING-CONVENTIONS.md +++ b/src/workflows/00-system/FILE-NAMING-CONVENTIONS.md @@ -28,7 +28,7 @@ ## βœ… DO Use Specific Names ### Always Create: -- βœ… `INTERACTIVE-PROTOTYPES-GUIDE.md` (specific topic) +- βœ… `AGENTIC-DEVELOPMENT-GUIDE.md` (specific topic) - βœ… `FREYA-WORKFLOW-INSTRUCTIONS.md` (specific agent + purpose) - βœ… `PROTOTYPE-ROADMAP.md` (specific purpose) - βœ… `PROJECT-ANALYSIS-ROUTER.md` (specific function) @@ -43,7 +43,7 @@ ### Pattern 1: [TOPIC]-GUIDE.md **When**: Overview/introduction to a topic **Examples**: -- `INTERACTIVE-PROTOTYPES-GUIDE.md` +- `AGENTIC-DEVELOPMENT-GUIDE.md` - `DESIGN-SYSTEM-GUIDE.md` - `TESTING-GUIDE.md` @@ -199,7 +199,7 @@ project-analysis/ - `-ROADMAP.md` - Status/plan tracking **Examples**: -- `INTERACTIVE-PROTOTYPES-GUIDE.md` +- `AGENTIC-DEVELOPMENT-GUIDE.md` - `FREYA-WORKFLOW-INSTRUCTIONS.md` - `page-template.html` - `PROTOTYPE-ANALYSIS.md` @@ -228,7 +228,7 @@ project-analysis/ | ❌ Generic | βœ… Specific | |-----------|------------| -| `README.md` | `INTERACTIVE-PROTOTYPES-GUIDE.md` | +| `README.md` | `AGENTIC-DEVELOPMENT-GUIDE.md` | | `INSTRUCTIONS.md` | `FREYA-WORKFLOW-INSTRUCTIONS.md` | | `GUIDE.md` | `DESIGN-SYSTEM-GUIDE.md` | | `template.yaml` | `work-file-template.yaml` | diff --git a/src/workflows/00-system/INSTRUCTION-FILE-GUIDELINES.md b/src/workflows/00-system/INSTRUCTION-FILE-GUIDELINES.md index a4a27aef7..81ca2a909 100644 --- a/src/workflows/00-system/INSTRUCTION-FILE-GUIDELINES.md +++ b/src/workflows/00-system/INSTRUCTION-FILE-GUIDELINES.md @@ -141,8 +141,8 @@ topic/ **Example**: ``` -interactive-prototypes/ -β”œβ”€β”€ INTERACTIVE-PROTOTYPES-GUIDE.md (complete system overview) +agentic-development/ +β”œβ”€β”€ AGENTIC-DEVELOPMENT-GUIDE.md (complete system overview) β”œβ”€β”€ CREATION-GUIDE.md (detailed technical reference) └── PROTOTYPE-ANALYSIS.md (case study) ``` diff --git a/src/workflows/4-ux-design/interactive-prototypes/guides/INTERACTIVE-PROTOTYPES-GUIDE.md b/src/workflows/4-ux-design/agentic-development/guides/AGENTIC-DEVELOPMENT-GUIDE.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/guides/INTERACTIVE-PROTOTYPES-GUIDE.md rename to src/workflows/4-ux-design/agentic-development/guides/AGENTIC-DEVELOPMENT-GUIDE.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/guides/CREATION-GUIDE.md b/src/workflows/4-ux-design/agentic-development/guides/CREATION-GUIDE.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/guides/CREATION-GUIDE.md rename to src/workflows/4-ux-design/agentic-development/guides/CREATION-GUIDE.md diff --git a/src/workflows/4-ux-design/agentic-development/guides/FILE-INDEX.md b/src/workflows/4-ux-design/agentic-development/guides/FILE-INDEX.md new file mode 100644 index 000000000..d58885939 --- /dev/null +++ b/src/workflows/4-ux-design/agentic-development/guides/FILE-INDEX.md @@ -0,0 +1,212 @@ +# Agentic Development - File Index + +**Location**: `src/workflows/4-ux-design/agentic-development/` + +--- + +## πŸ“ Complete File Structure + +``` +agentic-development/ +β”‚ +β”œβ”€β”€ AGENTIC-DEVELOPMENT-GUIDE.md ← START HERE (overview & quick reference) +β”œβ”€β”€ workflow.md ← Workflow overview with phase links +β”œβ”€β”€ PROTOTYPE-INITIATION-DIALOG.md ← Conversation scripts for initiation +β”œβ”€β”€ CREATION-GUIDE.md ← Original detailed guide (reference) +β”œβ”€β”€ PROTOTYPE-ANALYSIS.md ← Dog Week analysis (examples) +β”‚ +β”œβ”€β”€ steps-c/ ← Micro-step workflow files +β”‚ β”œβ”€β”€ 1-prototype-setup.md ← Phase 1: Environment setup +β”‚ β”œβ”€β”€ 2-scenario-analysis.md ← Phase 2: Analyze spec & create views +β”‚ β”œβ”€β”€ 3-logical-view-breakdown.md ← Phase 3: Break view into sections +β”‚ β”œβ”€β”€ 4a-announce-and-gather.md ← Phase 4a: Announce section +β”‚ β”œβ”€β”€ 4b-create-story-file.md ← Phase 4b: Create story file +β”‚ β”œβ”€β”€ 4c-implement-section.md ← Phase 4c: Implement code +β”‚ β”œβ”€β”€ 4d-present-for-testing.md ← Phase 4d: Present for testing +β”‚ β”œβ”€β”€ 4e-handle-issue.md ← Phase 4e: Fix issues (loop) +β”‚ β”œβ”€β”€ 4f-handle-improvement.md ← Phase 4f: Handle improvements (loop) +β”‚ β”œβ”€β”€ 4g-section-approved.md ← Phase 4g: Section approved +β”‚ └── 5-finalization.md ← Phase 5: Integration test & approval +β”‚ +β”œβ”€β”€ templates/ +β”‚ β”œβ”€β”€ work-file-template.yaml ← Planning document template +β”‚ β”œβ”€β”€ story-file-template.md ← Section implementation template +β”‚ β”œβ”€β”€ page-template.html ← Complete HTML page template +β”‚ β”œβ”€β”€ PROTOTYPE-ROADMAP-template.md ← Scenario roadmap template +β”‚ β”œβ”€β”€ demo-data-template.json ← Demo data structure template +β”‚ └── components/ +β”‚ β”œβ”€β”€ dev-mode.html ← Dev mode toggle button +β”‚ β”œβ”€β”€ dev-mode.js ← Dev mode logic (Shift+Click to copy IDs) +β”‚ β”œβ”€β”€ dev-mode.css ← Dev mode styles +β”‚ └── DEV-MODE-GUIDE.md ← Dev mode usage guide +β”‚ +└── examples/ + └── (Dog Week prototypes as reference) +``` + +--- + +## πŸ“š What Each File Does + +### Core Documentation + +#### `AGENTIC-DEVELOPMENT-GUIDE.md` +**Purpose**: Complete system overview +**For**: All agents (Freya, Saga, Idunn) +**Contains**: +- System overview +- Folder structure +- Complete workflow summary +- Key principles +- Quick reference +- Success metrics + +**Read this**: To understand the complete system + +--- + +#### `workflow.md` +**Purpose**: Workflow overview with phase navigation +**For**: Freya (primary), other agents (reference) +**Contains**: +- Overview of all phases +- Clear links to step files +- When to use each phase +- What each phase creates + +**Read this**: To understand the workflow structure + +--- + +### Step Files + +#### `steps-c/1-prototype-setup.md` +**Purpose**: Environment setup instructions +**Contains**: Device compatibility, design fidelity, languages, demo data creation +**Next**: Phase 2 + +--- + +#### `steps-c/2-scenario-analysis.md` +**Purpose**: Scenario analysis and view identification +**Contains**: Spec analysis, logical view mapping +**Next**: Phase 3 + +--- + +#### `steps-c/3-logical-view-breakdown.md` +**Purpose**: Break view into implementable sections +**Contains**: Section breakdown, work file creation +**Next**: Phase 4 + +--- + +#### `steps-c/4a-4g-*.md` (Phase 4 Loop) +**Purpose**: Section-by-section implementation +**Contains**: Announce, create story, implement, test, handle feedback, approve +**Flow**: 4a β†’ 4b β†’ 4c β†’ 4d β†’ [4e/4f loop] β†’ 4g β†’ [next section] + +--- + +#### `steps-c/5-finalization.md` +**Purpose**: Integration test and completion +**Contains**: Final test, quality checklist, next steps +**Next**: New page (Phase 3) or new scenario (Phase 1) + +--- + +### Templates + +#### `templates/work-file-template.yaml` +**Purpose**: Planning document +**When to use**: Start of EVERY implementation +**Created**: Once per page at beginning +**Contains**: +- Metadata (page info, device compatibility) +- Design tokens (Tailwind config) +- Page requirements (from spec) +- Demo data needs +- Object ID map +- Section breakdown (4-8 sections) +- Testing checklist + +**Use this**: To create work file (plan BEFORE coding) + +--- + +#### `templates/story-file-template.md` +**Purpose**: Section implementation guide +**When to use**: Just-in-time (right before implementing each section) +**Created**: Once per section (4-8 per page) +**Contains**: +- Section goal +- What to build (HTML/JS) +- Tailwind classes to use +- Dependencies +- Acceptance criteria +- Test instructions +- Common issues + +**Use this**: To create story file before each section + +--- + +#### `templates/page-template.html` +**Purpose**: Complete HTML page structure +**When to use**: Creating new HTML page +**Created**: Once per page (at start of Section 1) +**Contains**: +- Complete HTML structure +- Tailwind CDN setup +- Tailwind config inline +- Component examples +- Shared script includes + +**Use this**: As starting point for new page HTML + +--- + +## 🎯 Which File When? + +### Starting New Scenario +1. Read: `workflow.md` (understand phases) +2. Follow: `steps-c/1-prototype-setup.md` (setup) +3. Use: `PROTOTYPE-ROADMAP-template.md` β†’ Create roadmap +4. Use: `demo-data-template.json` β†’ Create demo data + +### Starting New Page +1. Follow: `steps-c/2-scenario-analysis.md` (analyze) +2. Follow: `steps-c/3-logical-view-breakdown.md` (break down) +3. Use: `work-file-template.yaml` β†’ Create work file +4. Get approval + +### Implementing Each Section +1. Follow: `steps-c/4a-4g-*.md` (loop) +2. Use: `story-file-template.md` β†’ Create story file (just-in-time) +3. Implement in HTML (incrementally) +4. Test +5. Get approval +6. Repeat for next section + +### Finishing Page +1. Follow: `steps-c/5-finalization.md` (integration test) +2. Get final approval +3. Choose: New page, new scenario, or done + +--- + +## πŸ“ Template Usage Summary + +| Template | When Created | How Many | Purpose | +|----------|--------------|----------|---------| +| work-file | Start of page | 1 per page | Complete plan | +| story-file | Before each section | 4-8 per page | Section implementation | +| page | Start of Section 1 | 1 per page | HTML structure | +| roadmap | Start of scenario | 1 per scenario | Scenario overview | +| demo-data | Setup scenario | 1 per scenario | Auto-loading data | + +--- + +**All templates and micro-step instructions are ready!** + +Next step: Activate Freya and follow `workflow.md` β†’ `steps-c/1-prototype-setup.md` diff --git a/src/workflows/4-ux-design/interactive-prototypes/guides/PROTOTYPE-ANALYSIS.md b/src/workflows/4-ux-design/agentic-development/guides/PROTOTYPE-ANALYSIS.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/guides/PROTOTYPE-ANALYSIS.md rename to src/workflows/4-ux-design/agentic-development/guides/PROTOTYPE-ANALYSIS.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/guides/PROTOTYPE-INITIATION-DIALOG.md b/src/workflows/4-ux-design/agentic-development/guides/PROTOTYPE-INITIATION-DIALOG.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/guides/PROTOTYPE-INITIATION-DIALOG.md rename to src/workflows/4-ux-design/agentic-development/guides/PROTOTYPE-INITIATION-DIALOG.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/1-prototype-setup.md b/src/workflows/4-ux-design/agentic-development/steps-c/1-prototype-setup.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/1-prototype-setup.md rename to src/workflows/4-ux-design/agentic-development/steps-c/1-prototype-setup.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/2-scenario-analysis.md b/src/workflows/4-ux-design/agentic-development/steps-c/2-scenario-analysis.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/2-scenario-analysis.md rename to src/workflows/4-ux-design/agentic-development/steps-c/2-scenario-analysis.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/3-logical-view-breakdown.md b/src/workflows/4-ux-design/agentic-development/steps-c/3-logical-view-breakdown.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/3-logical-view-breakdown.md rename to src/workflows/4-ux-design/agentic-development/steps-c/3-logical-view-breakdown.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/4a-announce-and-gather.md b/src/workflows/4-ux-design/agentic-development/steps-c/4a-announce-and-gather.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/4a-announce-and-gather.md rename to src/workflows/4-ux-design/agentic-development/steps-c/4a-announce-and-gather.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/4b-create-story-file.md b/src/workflows/4-ux-design/agentic-development/steps-c/4b-create-story-file.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/4b-create-story-file.md rename to src/workflows/4-ux-design/agentic-development/steps-c/4b-create-story-file.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/4c-implement-section.md b/src/workflows/4-ux-design/agentic-development/steps-c/4c-implement-section.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/4c-implement-section.md rename to src/workflows/4-ux-design/agentic-development/steps-c/4c-implement-section.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/4d-present-for-testing.md b/src/workflows/4-ux-design/agentic-development/steps-c/4d-present-for-testing.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/4d-present-for-testing.md rename to src/workflows/4-ux-design/agentic-development/steps-c/4d-present-for-testing.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/4e-handle-issue.md b/src/workflows/4-ux-design/agentic-development/steps-c/4e-handle-issue.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/4e-handle-issue.md rename to src/workflows/4-ux-design/agentic-development/steps-c/4e-handle-issue.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/4f-handle-improvement.md b/src/workflows/4-ux-design/agentic-development/steps-c/4f-handle-improvement.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/4f-handle-improvement.md rename to src/workflows/4-ux-design/agentic-development/steps-c/4f-handle-improvement.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/4g-section-approved.md b/src/workflows/4-ux-design/agentic-development/steps-c/4g-section-approved.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/4g-section-approved.md rename to src/workflows/4-ux-design/agentic-development/steps-c/4g-section-approved.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/steps-c/5-finalization.md b/src/workflows/4-ux-design/agentic-development/steps-c/5-finalization.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/steps-c/5-finalization.md rename to src/workflows/4-ux-design/agentic-development/steps-c/5-finalization.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/PROTOTYPE-ROADMAP-template.md b/src/workflows/4-ux-design/agentic-development/templates/PROTOTYPE-ROADMAP-template.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/PROTOTYPE-ROADMAP-template.md rename to src/workflows/4-ux-design/agentic-development/templates/PROTOTYPE-ROADMAP-template.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/components/DEV-MODE-GUIDE.md b/src/workflows/4-ux-design/agentic-development/templates/components/DEV-MODE-GUIDE.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/components/DEV-MODE-GUIDE.md rename to src/workflows/4-ux-design/agentic-development/templates/components/DEV-MODE-GUIDE.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.css b/src/workflows/4-ux-design/agentic-development/templates/components/dev-mode.css similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.css rename to src/workflows/4-ux-design/agentic-development/templates/components/dev-mode.css diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.html b/src/workflows/4-ux-design/agentic-development/templates/components/dev-mode.html similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.html rename to src/workflows/4-ux-design/agentic-development/templates/components/dev-mode.html diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js b/src/workflows/4-ux-design/agentic-development/templates/components/dev-mode.js similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js rename to src/workflows/4-ux-design/agentic-development/templates/components/dev-mode.js diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/demo-data-template.json b/src/workflows/4-ux-design/agentic-development/templates/demo-data-template.json similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/demo-data-template.json rename to src/workflows/4-ux-design/agentic-development/templates/demo-data-template.json diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/page-template.html b/src/workflows/4-ux-design/agentic-development/templates/page-template.html similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/page-template.html rename to src/workflows/4-ux-design/agentic-development/templates/page-template.html diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/story-file-template.md b/src/workflows/4-ux-design/agentic-development/templates/story-file-template.md similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/story-file-template.md rename to src/workflows/4-ux-design/agentic-development/templates/story-file-template.md diff --git a/src/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml b/src/workflows/4-ux-design/agentic-development/templates/work-file-template.yaml similarity index 100% rename from src/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml rename to src/workflows/4-ux-design/agentic-development/templates/work-file-template.yaml diff --git a/src/workflows/4-ux-design/interactive-prototypes/validation-report-interactive-prototypes.md b/src/workflows/4-ux-design/agentic-development/validation-report-agentic-development.md similarity index 94% rename from src/workflows/4-ux-design/interactive-prototypes/validation-report-interactive-prototypes.md rename to src/workflows/4-ux-design/agentic-development/validation-report-agentic-development.md index cd54201d8..1a490fb35 100644 --- a/src/workflows/4-ux-design/interactive-prototypes/validation-report-interactive-prototypes.md +++ b/src/workflows/4-ux-design/agentic-development/validation-report-agentic-development.md @@ -1,7 +1,7 @@ --- validationDate: 2026-01-22 -workflowName: interactive-prototypes -workflowPath: c:\dev\WDS\bmad-method-wds-expansion\src\workflows\4-ux-design\interactive-prototypes +workflowName: agentic-development +workflowPath: c:\dev\WDS\bmad-method-wds-expansion\src\workflows\4-ux-design\agentic-development validationStatus: COMPLETE overallStatus: PASS - FIXED criticalIssues: 2 @@ -10,7 +10,7 @@ warnings: 1 warningsFixed: 1 --- -# Validation Report: Interactive Prototypes +# Validation Report: Agentic Development **Validation Started:** 2026-01-22 **Validator:** Wendy - BMAD Workflow Validation System @@ -30,7 +30,7 @@ warningsFixed: 1 ### Current Structure ``` -interactive-prototypes/ +agentic-development/ β”œβ”€β”€ phases/ ← ❌ Should be steps-c/ β”‚ β”œβ”€β”€ 1-prototype-setup.md (95 lines) βœ… β”‚ β”œβ”€β”€ 2-scenario-analysis.md (174 lines) βœ… @@ -46,7 +46,7 @@ interactive-prototypes/ β”œβ”€β”€ templates/ (template files) βœ… β”œβ”€β”€ CREATION-GUIDE.md (1,148 lines) β”œβ”€β”€ FILE-INDEX.md (365 lines) -β”œβ”€β”€ INTERACTIVE-PROTOTYPES-GUIDE.md (380 lines) +β”œβ”€β”€ AGENTIC-DEVELOPMENT-GUIDE.md (380 lines) β”œβ”€β”€ PROTOTYPE-ANALYSIS.md (832 lines) β”œβ”€β”€ PROTOTYPE-INITIATION-DIALOG.md (409 lines) └── PROTOTYPE-WORKFLOW.md (137 lines) ← ❌ Should be workflow.md @@ -87,7 +87,7 @@ interactive-prototypes/ **Current:** Guide files in root folder - CREATION-GUIDE.md -- INTERACTIVE-PROTOTYPES-GUIDE.md +- AGENTIC-DEVELOPMENT-GUIDE.md - PROTOTYPE-ANALYSIS.md - PROTOTYPE-INITIATION-DIALOG.md - FILE-INDEX.md @@ -147,7 +147,7 @@ interactive-prototypes/ **Action:** Move guide files to `guides/` subfolder **Files to move:** - CREATION-GUIDE.md -- INTERACTIVE-PROTOTYPES-GUIDE.md +- AGENTIC-DEVELOPMENT-GUIDE.md - PROTOTYPE-ANALYSIS.md - PROTOTYPE-INITIATION-DIALOG.md - FILE-INDEX.md @@ -207,7 +207,7 @@ This is a **well-designed workflow** with **structural compliance issues**. The 3. βœ… **Organized guides into guides/ subfolder** - Moved 5 guide files: - CREATION-GUIDE.md - - INTERACTIVE-PROTOTYPES-GUIDE.md + - AGENTIC-DEVELOPMENT-GUIDE.md - PROTOTYPE-ANALYSIS.md - PROTOTYPE-INITIATION-DIALOG.md - FILE-INDEX.md @@ -219,7 +219,7 @@ This is a **well-designed workflow** with **structural compliance issues**. The ### New Structure: ``` -interactive-prototypes/ +agentic-development/ β”œβ”€β”€ workflow.md (entry point) βœ… β”œβ”€β”€ steps-c/ (BMAD v6 compliant) βœ… β”‚ β”œβ”€β”€ 1-prototype-setup.md @@ -236,7 +236,7 @@ interactive-prototypes/ β”œβ”€β”€ guides/ (organized documentation) βœ… β”‚ β”œβ”€β”€ CREATION-GUIDE.md β”‚ β”œβ”€β”€ FILE-INDEX.md -β”‚ β”œβ”€β”€ INTERACTIVE-PROTOTYPES-GUIDE.md +β”‚ β”œβ”€β”€ AGENTIC-DEVELOPMENT-GUIDE.md β”‚ β”œβ”€β”€ PROTOTYPE-ANALYSIS.md β”‚ └── PROTOTYPE-INITIATION-DIALOG.md └── templates/ (existing templates) βœ… diff --git a/src/workflows/4-ux-design/agentic-development/workflow.md b/src/workflows/4-ux-design/agentic-development/workflow.md new file mode 100644 index 000000000..f6f8f958e --- /dev/null +++ b/src/workflows/4-ux-design/agentic-development/workflow.md @@ -0,0 +1,631 @@ +--- +name: Agentic Development +description: AI-assisted development for non-technical designers using Agent Dialogs and structured collaboration +web_bundle: true +--- + +# Agentic Development Workflow + +**Goal:** Enable non-technical designers to build production-ready code through structured AI collaboration + +**Your Role:** Implementation partner guiding step-by-step development with clear feedback protocols and approval gates + +--- + +## OVERVIEW + +Agentic Development is about **how** you work with AI β€” not **what** you build. + +Use this workflow to build a prototype, extend a production app, create a new feature, or anything else. The AI handles implementation while you focus on what to build and how it should behave. + +This workflow enables: +- βœ… Direct implementation from specifications +- βœ… Step-by-step development with approval gates +- βœ… Clear feedback protocol with timing guidance +- βœ… Agent Dialog structure for context and handoff +- βœ… Dynamic planning that adapts as we learn + +**Note:** We use "scenario step" instead of "page" - a step can be a full page, modal, overlay, state change, or any UI change requiring a new sketch. + +--- + +## WHEN TO USE + +Use this workflow when: +- βœ… Page specifications are complete and approved +- βœ… Ready to build working implementations +- βœ… Working with AI to develop production-ready code +- βœ… Want iterative development with approval gates +- βœ… Need structured collaboration with clear feedback handling + +Skip this workflow when: +- ❌ Specifications not complete yet +- ❌ Still in sketching or wireframe phase +- ❌ Simple one-file changes that don't need documentation +- ❌ Pure exploration where the path is unclear + +--- + +## USER FEEDBACK PROTOCOL + +During development, the designer provides feedback. **CRITICAL: Never implement feedback without first classifying it and stating when it should be addressed.** + +### Feedback Types + +| Type | What It Is | When to Address | +|------|------------|-----------------| +| **Bug/Issue** | Something broken, error, not working | Now β€” fix immediately, iterate until resolved | +| **Quick Adjustment** | Small tweak, change X to Y | Now β€” implement immediately | +| **Addition** | New requirement that fits current dialog | Later step β€” add to plan | +| **Change Request** | Outside current dialog scope | Future session β€” document in Change Requests | + +### The 2-Minute Rule (GTD) + +**If a fix takes less than 2 minutes, do it immediately.** + +From David Allen's "Getting Things Done": planning overhead should not exceed task complexity. See [GTD Model](../../../docs/models/gtd-getting-things-done.md). + +| Situation | Action | +|-----------|--------| +| Missing condition check | Fix now, log as sub-step | +| Wrong variable name | Fix now, log as sub-step | +| Needs new component | Add to plan | +| Architectural change | Add to plan | + +**Pattern:** Do the fix β†’ Log as sub-step (e.g., 20a-1) β†’ Continue main task + +### Response Flow + +**When user reports something:** + +1. **CLASSIFY** β€” What type of feedback is this? +2. **TIMING** β€” When should it be addressed? +3. **DOCUMENT** β€” For bugs, add to plan BEFORE fixing +4. **CONFIRM** β€” For additions and change requests, confirm before proceeding +5. **EXECUTE** β€” Implement or document as appropriate + +### Bug/Issue (Document First, Then Fix) + +**User says:** "This is broken" / "Error occurred" / "Not working" + +**Agent response:** +``` +This is a bug β€” [brief description of issue]. +Let's call it 10A and let me add it to the plan, then fix it. +``` + +**Required sequence:** +1. **Identify** β€” Understand and describe the bug clearly +2. **Document** β€” Add to dialog plan as sub-step (e.g., 21a, 21b) +3. **Execute** β€” Fix and iterate until resolved +4. **Log** β€” Record resolution in progress log + +**If user reports multiple issues at once:** +1. Identify and list each issue separately +2. Add ALL to the plan first +3. Then work through them one by one + +**Why document first:** Bugs discovered during implementation are valuable context. Recording them ensures traceability, prevents forgotten fixes, and creates a clear record for handoff. + +**Example:** +``` +User: "The drawer appears behind the overlay and the reassign doesn't work" + +Agent: "I see two issues: + 1. Drawer z-index (appears behind overlay) + 2. Reassign not working + + Let me add both to the plan as 21a and 21b, then fix them." +``` + +### Quick Adjustment (Fix Now) + +**User says:** "Change X to Y" / "Make this button go here" / "Use different color" + +**Agent response:** +``` +Quick adjustment β€” I'll implement this now. +``` + +Then implement the change. + +### Addition (Add to Plan) + +**User says:** "We should also add X" / "Don't forget to handle Y" + +**Agent response:** +``` +This is an addition that fits the current dialog. +I'll add it to Step {N} for later. Confirm? +``` + +Then add to the appropriate step or To Do section in the dialog file. + +### Change Request (Document for Later) + +**User says:** "The profile button should go to /family" / "We need a settings page" + +**Agent response:** +``` +This is outside the current dialog scope. +It doesn't block {feature name}. + +I'll add it to Change Requests for a future session. Confirm? +``` + +**WAIT for user confirmation.** + +If user confirms β†’ Add to Change Requests section +If user says "do it now" β†’ Treat as quick adjustment and implement + +### Anti-Pattern: What NOT to Do + +**NEVER do this:** + +User: "The profile button should go to /family" +Agent: *immediately edits the file* + +**ALWAYS do this:** + +User: "The profile button should go to /family" +Agent: "This is outside current scope. I'll add it to Change Requests. Confirm?" +User: "Yes" or "No, do it now" +*then acts accordingly* + +### Why This Matters + +From experience, skipping the classify-and-timing step leads to: +- Agent implementing things the user didn't want +- User frustration from lack of visibility +- Lost context when user wanted to discuss first +- Scope creep pulling focus from current implementation + +The extra seconds to classify and confirm build trust and ensure alignment. + +--- + +## SESSION START PROTOCOL + +When starting or resuming a session, **always follow this sequence before implementing anything:** + +### 1. Read the Dialog Document + +``` +Agent: "Let me read the dialog document to understand where we are." +``` + +Read the dialog file completely to understand: +- What steps are done +- What steps remain +- Any blockers or change requests +- Current context and decisions + +### 2. Verify Plan Against Reality + +**The plan may be outdated.** Check if: +- Steps marked "To Do" have actually been implemented +- Steps marked "Done" are truly complete +- The numbering is sequential and accurate + +``` +Agent: "I see steps 11-18 in To Do, but let me check the code..." +Agent: "These are already implemented. Let me update the plan." +``` + +If the plan is outdated β†’ Update it before proceeding. + +### 3. Present Current Status + +Summarize for the designer: +- What's done (with step numbers) +- What's remaining (with step numbers) +- Any change requests pending + +``` +Agent: "Here's where we are: + Done: Steps 9b, 10, 11-19 + To Do: Steps 20, 21 + Ready to continue?" +``` + +### 4. Before Implementing a Step + +**Always check the specification/sketches first:** + +``` +Agent: "Before implementing step 20, let me check the sketches..." +Agent: "I see this requires a nested drawer pattern, not inline buttons. + Should I break this into sub-steps?" +``` + +This prevents building the wrong thing and wasting effort. + +### Why This Matters + +Sessions can be interrupted. Context can be lost. The dialog document survives β€” but only if it's kept accurate. This protocol ensures: +- No duplicate work (re-implementing what exists) +- No missed work (skipping what's actually needed) +- Correct understanding of requirements before implementation + +--- + +## EXECUTION PRINCIPLES + +### Document Before Acting + +**Every decision, action, and problem must be documented in the dialog file BEFORE acting on it.** + +This ensures: +- Full traceability of what was decided and why +- Clean handoff if context is lost or session changes +- The dialog document is always the source of truth for progress + +### Sketch Fidelity + +**Implement code as close to the provided sketches as possible.** + +Sketches are intentional design decisions, not loose suggestions. Text sizes, proportions, spacing, and layout choices are made for a reason: + +| Element | Approach | +|---------|----------| +| **Text sizes** | Match relative sizes in sketch (headings vs body vs labels) | +| **Proportions** | Preserve ratios between elements | +| **Spacing** | Maintain visual rhythm and whitespace | +| **Layout** | Follow the arrangement precisely | +| **Component style** | Match the visual pattern (pills, cards, buttons) | + +**When in doubt:** +1. Ask the designer for clarification +2. Reference the sketch directly in your question +3. Don't assume "close enough" is acceptable + +**If constraints make exact matching impossible** (e.g., responsive behavior, platform limitations), document the deviation and explain why. + +### Sub-Steps During Execution + +While working on a step, you may discover additional tasks needed. Add these as sub-steps: + +```markdown +| # | Section | Status | Notes | +|---|---------|--------|-------| +| 14 | Book It Button | βœ… | Complete | +| 14a | Fix button alignment | βœ… | Added during 14 | +| 14b | Add loading state | βœ… | Added during 14 | +| 15 | Cancel Button | πŸ”„ | In progress | +``` + +Sub-steps use letter suffixes (14a, 14b) to maintain the parent step's position. + +### Dynamic Planning After Step Completion + +**After completing each step, review and adjust the plan:** + +1. **Review remaining steps** β€” Are they still accurate? +2. **Shuffle if needed** β€” Reorder based on what we learned +3. **Add new steps** β€” If implementation revealed new requirements +4. **Remove steps** β€” If no longer needed +5. **Update the dialog file** β€” Document the changes + +**Numbering Rules:** +- **Completed steps:** Fixed numbering (never renumber) +- **Future steps:** Dynamic numbering (can change) + +Example: +```markdown +### Done +| 9b | Carousel Refactor | βœ… | ← Fixed, never changes +| 10 | Deep Linking | βœ… | ← Fixed + +### To Do +| 11 | Wire up handlers | πŸ”² | ← Can be renumbered +| 12 | Add poop toggle | πŸ”² | ← Can be removed or moved +| 13 | NEW: Error states | πŸ”² | ← Can be inserted +``` + +### Handoff Always References Dialog + +**Any handoff β€” to a new session, new agent, or human β€” MUST reference the dialog document.** + +The dialog document is the single source of truth for: +- What has been done +- What decisions were made +- What remains to be done +- Any issues or blockers + +Never hand off by describing the task verbally. Always point to the dialog. + +### Plan-then-Execute Pattern + +**Separate planning from execution into distinct sessions.** + +Context windows are finite. Long sessions accumulate noise and risk context loss mid-implementation. The solution: end planning sessions deliberately, start execution sessions fresh. + +**Planning Session:** +1. Explore the codebase and requirements +2. Discuss approach with the designer +3. Write the plan to the dialog file +4. End with a clear handoff: *"The plan is documented. Hasta la vista!"* + +**Execution Session:** +1. Start fresh (new conversation) +2. Read the product brief for overall context +3. Read the page specification for requirements +4. Read the dialog document to understand the plan and progress +5. Execute the steps one by one + +**Why This Works:** +- Fresh context window for execution = maximum working memory +- Dialog document carries all decisions and context forward +- No risk of context loss mid-implementation +- Each session has a clear, focused purpose + +**When to Split:** +- After complex exploration or analysis +- When the plan is complete and approved +- When current session is getting long +- Before starting a major implementation phase + +**The Dialog is the Bridge:** +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” Dialog β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PLANNING SESSION │─────File────▢│ EXECUTION SESSION β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β€’ Explore codebase β”‚ β”‚ β€’ Fresh context β”‚ +β”‚ β€’ Discuss approach β”‚ β”‚ β€’ Read brief + spec β”‚ +β”‚ β€’ Write plan β”‚ β”‚ β€’ Read dialog β”‚ +β”‚ β€’ "Hasta la vista!" β”‚ β”‚ β€’ Execute steps β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## WORKFLOW ARCHITECTURE + +This uses **multi-phase architecture** with iterative loops: + +### Phase Structure + +**Sequential Phases (1-3, 5):** Setup β†’ Analysis β†’ Selection β†’ Finalization + +**Iterative Phase (4):** Section implementation loop with 7 micro-tasks + +### Critical Rules + +- 🎯 **ALWAYS** complete Phase 1 setup before starting +- πŸ“Š **ALWAYS** analyze scenario before selecting views +- πŸ” **ALWAYS** use section-by-section approach (Phase 4 loop) +- βœ… **ALWAYS** get approval before moving to next section +- πŸ“ **ALWAYS** create story files just-in-time (not upfront) + +--- + +## THE 5 PHASES + +### Phase 1: Prototype Setup +**When:** Starting new scenario prototype (one-time per scenario) + +**What:** Set up prototype environment and folder structure + +**Creates:** +- Prototype folder with complete structure +- Demo data files +- Roadmap document +- All working folders (work/, stories/, shared/, components/, etc.) + +**Go to:** [steps-c/1-prototype-setup.md](steps-c/1-prototype-setup.md) + +--- + +### Phase 2: Scenario Analysis +**When:** Setup complete, ready to start building (one-time per scenario) + +**What:** Analyze all scenario steps and identify logical views + +**Creates:** +- Logical View Map (maps steps to views) +- View identification and relationships + +**Go to:** [steps-c/2-scenario-analysis.md](steps-c/2-scenario-analysis.md) + +--- + +### Phase 3: Logical View Selection & Breakdown +**When:** User selects which logical view to build (per view) + +**What:** Identify all objects and break view into sections + +**Creates:** +- Work file with section breakdown +- Implementation sequence + +**Go to:** [steps-c/3-logical-view-breakdown.md](steps-c/3-logical-view-breakdown.md) + +--- + +### Phase 4: Section Story & Implementation Loop +**When:** Ready to build sections (iterative per section) + +**What:** For each section - prepare, create story, implement, test, handle feedback, approve + +**The 7 Micro-Tasks:** + +1. **[4a: Announce & Gather](steps-c/4a-announce-and-gather.md)** + - Announce section and gather requirements + +2. **[4b: Create Story File](steps-c/4b-create-story-file.md)** + - Create focused story file for this section + +3. **[4c: Implement Section](steps-c/4c-implement-section.md)** + - Implement code following story + +4. **[4d: Present for Testing](steps-c/4d-present-for-testing.md)** + - Present to user with test instructions + +5. **[4e: Handle Issue](steps-c/4e-handle-issue.md)** + - Fix issues if user reports problems (loop back to 4d) + +6. **[4f: Handle Improvement](steps-c/4f-handle-improvement.md)** + - Implement improvements if user suggests (loop back to 4d) + +7. **[4g: Section Approved](steps-c/4g-section-approved.md)** + - Finalize approval and move to next section (back to 4a) + +**Flow:** 4a β†’ 4b β†’ 4c β†’ 4d β†’ [4e or 4f if needed, loops to 4d] β†’ 4g β†’ [back to 4a for next section] + +**Creates (per section):** +- Story file (just-in-time) +- Incremental updates to view HTML +- Learnings captured + +**Key:** One clear task per file β†’ No confusion β†’ Linear execution β†’ Better results! + +--- + +### Phase 5: Finalization +**When:** All sections complete for a logical view (end of view) + +**What:** Integration test all states and final approval + +**Result:** Production-ready logical view handling all its states + +**Go to:** [steps-c/5-finalization.md](steps-c/5-finalization.md) + +--- + +## INITIALIZATION + +### Guide References + +**Process Guides:** +- [AGENTIC-DEVELOPMENT-GUIDE.md](guides/AGENTIC-DEVELOPMENT-GUIDE.md) - Overview and methodology +- [CREATION-GUIDE.md](guides/CREATION-GUIDE.md) - Technical implementation details +- [PROTOTYPE-INITIATION-DIALOG.md](guides/PROTOTYPE-INITIATION-DIALOG.md) - Conversation scripts +- [PROTOTYPE-ANALYSIS.md](guides/PROTOTYPE-ANALYSIS.md) - Quality standards +- [FILE-INDEX.md](guides/FILE-INDEX.md) - Complete file reference + +**Templates:** +- templates/work-file-template.yaml +- templates/story-file-template.md +- templates/page-template.html +- templates/components/dev-mode.* + +### First Step Execution + +Load, read and execute `steps-c/1-prototype-setup.md` to begin workflow. + +--- + +## OUTPUT + +**Per Scenario:** +``` +[Scenario-Number]-[Scenario-Name]-Prototype/ +β”œβ”€β”€ [View].html files (in root, one per logical view) +β”œβ”€β”€ shared/ (ONE COPY of shared code) +β”œβ”€β”€ components/ (ONE COPY of reusable components) +β”œβ”€β”€ pages/ (page-specific scripts if complex) +β”œβ”€β”€ data/ (demo data JSON files) +β”œβ”€β”€ stories/ (section development files - created just-in-time) +β”œβ”€β”€ work/ (planning files) +└── PROTOTYPE-ROADMAP.md +``` + +**Result:** Self-contained, production-ready interactive prototypes with: +- Clean HTML using Tailwind CSS +- Vanilla JavaScript components +- Demo data auto-loading +- All states implemented and tested + +--- + +## PROTOTYPE FOLDER STRUCTURE + +``` +[Scenario-Number]-[Scenario-Name]-Prototype/ +β”œβ”€β”€ [Page].html files ← Logical view HTML files (root) +β”œβ”€β”€ shared/ ← ONE COPY of shared code +β”œβ”€β”€ components/ ← ONE COPY of reusable components +β”œβ”€β”€ pages/ ← Page-specific scripts (if complex) +β”œβ”€β”€ data/ ← Demo data JSON files +β”œβ”€β”€ stories/ ← Section development files (JIT) +β”œβ”€β”€ work/ ← Planning files +β”‚ β”œβ”€β”€ Logical-View-Map.md ← Maps steps to views +β”‚ └── [View]-Work.yaml ← Section breakdowns per view +└── PROTOTYPE-ROADMAP.md ← Overall roadmap +``` + +--- + +## ITERATIVE WORKFLOW + +**Phase 1-2:** One-time setup and analysis per scenario + +**Phase 3:** Repeat for each logical view in scenario + +**Phase 4:** Repeat for each section in current view +- Inner loop: Repeat 4d-4e-4f until approved + +**Phase 5:** Repeat for each logical view (finalization) + +**Pattern:** +``` +Setup β†’ Analysis β†’ [View Selection β†’ [Section Loop*] β†’ Finalization]* +``` + +--- + +## EXAMPLES + +**Typical Scenarios:** + +1. **E-commerce Checkout:** 5 views (cart, shipping, payment, review, confirmation) +2. **SaaS Onboarding:** 4 views (signup, profile, preferences, dashboard) +3. **Booking System:** 6 views (search, select, details, confirm, payment, confirmation) + +Each view breaks into 3-8 sections depending on complexity. + +--- + +## QUALITY PRINCIPLES + +**Section-by-Section Approval:** Never implement entire view at once - break into sections with approval gates + +**Just-In-Time Stories:** Create story files only when needed (4b), not upfront + +**Incremental Implementation:** Each section builds on previous approved sections + +**Demo Data:** Use realistic demo data for testing and validation + +**Self-Contained:** Each prototype folder is complete and portable + +--- + +## TROUBLESHOOTING + +**Issue:** User feedback requires rework +**Solution:** Use Phase 4e (issues) or 4f (improvements) to handle, then loop back to 4d + +**Issue:** Section too complex +**Solution:** Break down further in Phase 3 before starting Phase 4 + +**Issue:** Logical view unclear +**Solution:** Revisit Phase 2 analysis to refine view mapping + +--- + +## NOTES + +This workflow enables **non-technical designers to build with AI** β€” whether that's: +- A quick prototype for user testing +- New features in an existing production app +- A complete application from scratch + +The methodology stays the same: +- Step-by-step with approval gates +- Clear feedback protocol ensures alignment +- Agent Dialogs provide structure and traceability +- AI handles implementation, designer focuses on what and how + +--- + +_Agentic Development - AI-assisted development for non-technical designers_ diff --git a/src/workflows/4-ux-design/interactive-prototypes/guides/FILE-INDEX.md b/src/workflows/4-ux-design/interactive-prototypes/guides/FILE-INDEX.md deleted file mode 100644 index 1f796b810..000000000 --- a/src/workflows/4-ux-design/interactive-prototypes/guides/FILE-INDEX.md +++ /dev/null @@ -1,365 +0,0 @@ -# Interactive Prototypes - File Index - -**Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/` - ---- - -## πŸ“ Complete File Structure - -``` -interactive-prototypes/ -β”‚ -β”œβ”€β”€ INTERACTIVE-PROTOTYPES-GUIDE.md ← START HERE (overview & quick reference) -β”œβ”€β”€ PROTOTYPE-WORKFLOW.md ← Workflow overview with phase links -β”œβ”€β”€ PROTOTYPE-INITIATION-DIALOG.md ← Conversation scripts for initiation -β”œβ”€β”€ CREATION-GUIDE.md ← Original detailed guide (reference) -β”œβ”€β”€ PROTOTYPE-ANALYSIS.md ← Dog Week analysis (examples) -β”‚ -β”œβ”€β”€ phases/ ← Micro-step workflow files -β”‚ β”œβ”€β”€ 1-prototype-setup.md ← Phase 1: Prototype environment setup -β”‚ β”œβ”€β”€ 2-per-page-planning.md ← Phase 2: Analyze spec & create work file -β”‚ β”œβ”€β”€ 3-section-implementation.md ← Phase 3: Build section-by-section -β”‚ └── 4-finalization.md ← Phase 4: Integration test & approval -β”‚ -β”œβ”€β”€ templates/ -β”‚ β”œβ”€β”€ work-file-template.yaml ← Planning document template -β”‚ β”œβ”€β”€ story-file-template.md ← Section implementation template -β”‚ β”œβ”€β”€ page-template.html ← Complete HTML page template -β”‚ β”œβ”€β”€ PROTOTYPE-ROADMAP-template.md ← Scenario roadmap template -β”‚ β”œβ”€β”€ demo-data-template.json ← Demo data structure template -β”‚ └── components/ -β”‚ β”œβ”€β”€ dev-mode.html ← Dev mode toggle button -β”‚ β”œβ”€β”€ dev-mode.js ← Dev mode logic (Shift+Click to copy IDs) -β”‚ β”œβ”€β”€ dev-mode.css ← Dev mode styles -β”‚ └── DEV-MODE-GUIDE.md ← Dev mode usage guide -β”‚ -└── examples/ - └── (Dog Week prototypes as reference) -``` - ---- - -## πŸ“š What Each File Does - -### Core Documentation - -#### `INTERACTIVE-PROTOTYPES-GUIDE.md` -**Purpose**: Complete system overview -**For**: All agents (Freya, Saga, Idunn) -**Contains**: -- System overview -- Folder structure -- Complete workflow summary -- Key principles -- Quick reference -- Success metrics - -**Read this**: To understand the complete system - ---- - -#### `PROTOTYPE-WORKFLOW.md` -**Purpose**: Workflow overview with phase navigation -**For**: Freya (primary), other agents (reference) -**Contains**: -- Overview of all 4 phases -- Clear links to phase-specific files -- When to use each phase -- What each phase creates - -**Read this**: To understand the workflow structure - ---- - -#### `phases/1-prototype-setup.md` -**Purpose**: Prototype environment setup instructions -**Contains**: Device compatibility, design fidelity, languages, demo data creation -**Next**: Phase 2 - ---- - -#### `phases/2-per-page-planning.md` -**Purpose**: Page analysis and work file creation -**Contains**: Spec analysis, section breakdown, work file creation -**Next**: Phase 3 - ---- - -#### `phases/3-section-implementation.md` -**Purpose**: Section-by-section building -**Contains**: Story creation, implementation, testing, approval loop -**Next**: Phase 4 or repeat for next section - ---- - -#### `phases/4-finalization.md` -**Purpose**: Integration test and completion -**Contains**: Final test, quality checklist, next steps -**Next**: New page (Phase 2) or new scenario (Phase 1) - ---- - -#### `PROTOTYPE-INITIATION-DIALOG.md` -**Purpose**: Conversation scripts for initiation -**For**: Freya (exact scripts to follow) -**Contains**: -- Scenario initiation questions -- Per-page section breakdown prompts -- Example complete exchange - -**Read this**: For exact conversation patterns - ---- - -#### `CREATION-GUIDE.md` -**Purpose**: Original detailed guide -**For**: Deep dives, specific techniques -**Contains**: -- Detailed file structure explanations -- Step-by-step creation process -- Component patterns -- Testing strategies -- Common patterns library - -**Read this**: For detailed technical reference - ---- - -#### `PROTOTYPE-ANALYSIS.md` -**Purpose**: Dog Week case study -**For**: Learning from examples -**Contains**: -- Analysis of Dog Week prototypes -- What works well -- Patterns to follow -- Lessons learned -- Quality metrics - -**Read this**: To see real-world examples - ---- - -### Templates - -#### `templates/work-file-template.yaml` -**Purpose**: Planning document -**When to use**: Start of EVERY prototype -**Created**: Once per page at beginning -**Contains**: -- Metadata (page info, device compatibility) -- Design tokens (Tailwind config) -- Page requirements (from spec) -- Demo data needs -- Object ID map -- Section breakdown (4-8 sections) -- Testing checklist - -**Use this**: To create work file (plan BEFORE coding) - ---- - -#### `templates/story-file-template.md` -**Purpose**: Section implementation guide -**When to use**: Just-in-time (right before implementing each section) -**Created**: Once per section (4-8 per page) -**Contains**: -- Section goal -- What to build (HTML/JS) -- Tailwind classes to use -- Dependencies -- Acceptance criteria -- Test instructions -- Common issues - -**Use this**: To create story file before each section - ---- - -#### `templates/page-template.html` -**Purpose**: Complete HTML page structure -**When to use**: Creating new HTML page -**Created**: Once per page (at start of Section 1) -**Contains**: -- Complete HTML structure -- Tailwind CDN setup -- Tailwind config inline -- Header example -- Form examples (input, textarea, split button) -- Submit button with loading state -- Toast notification -- Error banner -- Modal example (commented) -- Shared script includes -- Inline JavaScript template - -**Use this**: As starting point for new page HTML - ---- - -#### `templates/PROTOTYPE-ROADMAP-template.md` -**Purpose**: Scenario overview document -**When to use**: Start of scenario development -**Created**: Once per scenario -**Contains**: -- Scenario overview -- Device compatibility details -- Folder structure explanation -- Shared resources documentation -- Component documentation -- Prototype status table -- Testing requirements -- Troubleshooting guide - -**Use this**: To create roadmap for scenario - ---- - -#### `templates/demo-data-template.json` -**Purpose**: Demo data structure -**When to use**: Setting up scenario demo data -**Created**: Once per scenario (modify as needed) -**Contains**: -- User object -- Family object -- Members array -- Dogs array (or other entities) -- All fields with examples - -**Use this**: To create demo-data.json file - ---- - -## 🎯 Which File When? - -### Starting New Scenario -1. Read: `PROTOTYPE-WORKFLOW.md` (understand phases) -2. Follow: `phases/1-prototype-setup.md` (setup) -3. Use: `PROTOTYPE-ROADMAP-template.md` β†’ Create roadmap -4. Use: `demo-data-template.json` β†’ Create demo data - -### Starting New Page -1. Follow: `phases/2-per-page-planning.md` (analyze) -2. Use: `work-file-template.yaml` β†’ Create work file -3. Get approval -4. Follow: `phases/3-section-implementation.md` - -### Implementing Each Section -1. Follow: `phases/3-section-implementation.md` (loop) -2. Use: `story-file-template.md` β†’ Create story file (just-in-time) -3. Implement in HTML (incrementally) -4. Test -5. Get approval -6. Repeat for next section - -### Finishing Page -1. Follow: `phases/4-finalization.md` (integration test) -2. Get final approval -3. Choose: New page, new scenario, or done - -### Need Help -1. Check: `PROTOTYPE-WORKFLOW.md` (phase overview) -2. Check: `phases/[N]-*.md` (specific phase) -3. Check: `CREATION-GUIDE.md` (detailed reference) -4. Check: `PROTOTYPE-ANALYSIS.md` (examples) - ---- - -## πŸ“Š File Relationships - -``` -PROTOTYPE-WORKFLOW.md (overview) - β”œβ”€ phases/1-prototype-setup.md - β”œβ”€ phases/2-per-page-planning.md - β”œβ”€ phases/3-section-implementation.md - └─ phases/4-finalization.md - -PROTOTYPE-INITIATION-DIALOG.md - └─ Referenced by: phases/1-prototype-setup.md (conversation scripts) - -work-file-template.yaml - └─ Used in: phases/2-per-page-planning.md - └─ Each section becomes: story-file-template.md (later) - -story-file-template.md - └─ Used in: phases/3-section-implementation.md (just-in-time) - └─ Guides: Implementation in HTML - -page-template.html - └─ Used in: phases/3-section-implementation.md (Section 1 only) - └─ Modified: Section by section - -PROTOTYPE-ROADMAP-template.md - └─ Used in: phases/1-scenario-init.md - └─ Updated: As prototypes complete -``` - ---- - -## πŸš€ Quick Start Paths - -### Path 1: I want to understand the system -1. `INTERACTIVE-PROTOTYPES-GUIDE.md` (overview) -2. `PROTOTYPE-WORKFLOW.md` (workflow phases) -3. `PROTOTYPE-ANALYSIS.md` (examples) - -### Path 2: I want to create my first prototype -1. `PROTOTYPE-WORKFLOW.md` (start here) -2. `phases/1-prototype-setup.md` (follow step-by-step) -3. `phases/2-per-page-planning.md` (next) -4. `phases/3-section-implementation.md` (build loop) -5. `phases/4-finalization.md` (finish) - -### Path 3: I need specific technical details -1. `CREATION-GUIDE.md` (detailed techniques) -2. `PROTOTYPE-ANALYSIS.md` (real examples) -3. `page-template.html` (code examples) - -### Path 4: I'm stuck on something -1. `phases/[current-phase].md` (specific phase help) -2. `CREATION-GUIDE.md` β†’ Common Pitfalls section -3. `templates/components/DEV-MODE-GUIDE.md` (if dev mode issue) - ---- - -## πŸ“ Template Usage Summary - -| Template | When Created | How Many | Purpose | -|----------|--------------|----------|---------| -| work-file | Start of page | 1 per page | Complete plan | -| story-file | Before each section | 4-8 per page | Section implementation | -| page | Start of Section 1 | 1 per page | HTML structure | -| roadmap | Start of scenario | 1 per scenario | Scenario overview | -| demo-data | Setup scenario | 1 per scenario | Auto-loading data | - ---- - -## βœ… Checklist: Do I Have Everything? - -**For Freya to create prototypes**: -- [x] `INTERACTIVE-PROTOTYPES-GUIDE.md` (overview) -- [x] `PROTOTYPE-WORKFLOW.md` (workflow overview) -- [x] `phases/1-prototype-setup.md` (Phase 1) -- [x] `phases/2-per-page-planning.md` (Phase 2) -- [x] `phases/3-section-implementation.md` (Phase 3) -- [x] `phases/4-finalization.md` (Phase 4) -- [x] `PROTOTYPE-INITIATION-DIALOG.md` (conversation scripts) -- [x] `work-file-template.yaml` -- [x] `story-file-template.md` -- [x] `page-template.html` -- [x] `PROTOTYPE-ROADMAP-template.md` -- [x] `demo-data-template.json` -- [x] `templates/components/dev-mode.*` (dev mode feature) - -**For learning**: -- [x] `CREATION-GUIDE.md` (detailed) -- [x] `PROTOTYPE-ANALYSIS.md` (examples) - -**For reference**: -- [x] Dog Week examples (real prototypes) - ---- - -**All templates and micro-step instructions are ready!** πŸŽ‰ - -Next step: Activate Freya and follow `PROTOTYPE-WORKFLOW.md` β†’ `phases/1-prototype-setup.md` - diff --git a/src/workflows/4-ux-design/interactive-prototypes/workflow.md b/src/workflows/4-ux-design/interactive-prototypes/workflow.md deleted file mode 100644 index 89fdaed4c..000000000 --- a/src/workflows/4-ux-design/interactive-prototypes/workflow.md +++ /dev/null @@ -1,290 +0,0 @@ ---- -name: Interactive Prototypes -description: Create production-ready interactive prototypes using phased section-by-section implementation -web_bundle: true ---- - -# Interactive Prototypes Workflow - -**Goal:** Build self-contained, production-ready interactive prototypes from UX specifications - -**Your Role:** Implementation facilitator guiding section-by-section prototype development with approval gates - ---- - -## OVERVIEW - -This workflow creates interactive prototypes using: -- βœ… Tailwind CSS (no separate CSS files) -- βœ… Vanilla JavaScript (components in shared folders) -- βœ… Section-by-section implementation (approval gates) -- βœ… Just-in-time story files (created as needed) -- βœ… Demo data auto-loading - -**Note:** We use "scenario step" instead of "page" - a step can be a full page, modal, overlay, state change, or any UI change requiring a new sketch. - ---- - -## WHEN TO USE - -Use this workflow when: -- βœ… Page specifications are complete and approved -- βœ… Ready to build working interactive prototypes -- βœ… Need production-ready HTML/CSS/JS implementations -- βœ… Want iterative development with approval gates - -Skip this workflow when: -- ❌ Specifications not complete yet -- ❌ Still in sketching or wireframe phase -- ❌ Using different prototyping tools (Figma, Adobe XD) -- ❌ Building final production code (this is prototype stage) - ---- - -## WORKFLOW ARCHITECTURE - -This uses **multi-phase architecture** with iterative loops: - -### Phase Structure - -**Sequential Phases (1-3, 5):** Setup β†’ Analysis β†’ Selection β†’ Finalization - -**Iterative Phase (4):** Section implementation loop with 7 micro-tasks - -### Critical Rules - -- 🎯 **ALWAYS** complete Phase 1 setup before starting -- πŸ“Š **ALWAYS** analyze scenario before selecting views -- πŸ” **ALWAYS** use section-by-section approach (Phase 4 loop) -- βœ… **ALWAYS** get approval before moving to next section -- πŸ“ **ALWAYS** create story files just-in-time (not upfront) - ---- - -## THE 5 PHASES - -### Phase 1: Prototype Setup -**When:** Starting new scenario prototype (one-time per scenario) - -**What:** Set up prototype environment and folder structure - -**Creates:** -- Prototype folder with complete structure -- Demo data files -- Roadmap document -- All working folders (work/, stories/, shared/, components/, etc.) - -**Go to:** [steps-c/1-prototype-setup.md](steps-c/1-prototype-setup.md) - ---- - -### Phase 2: Scenario Analysis -**When:** Setup complete, ready to start building (one-time per scenario) - -**What:** Analyze all scenario steps and identify logical views - -**Creates:** -- Logical View Map (maps steps to views) -- View identification and relationships - -**Go to:** [steps-c/2-scenario-analysis.md](steps-c/2-scenario-analysis.md) - ---- - -### Phase 3: Logical View Selection & Breakdown -**When:** User selects which logical view to build (per view) - -**What:** Identify all objects and break view into sections - -**Creates:** -- Work file with section breakdown -- Implementation sequence - -**Go to:** [steps-c/3-logical-view-breakdown.md](steps-c/3-logical-view-breakdown.md) - ---- - -### Phase 4: Section Story & Implementation Loop -**When:** Ready to build sections (iterative per section) - -**What:** For each section - prepare, create story, implement, test, handle feedback, approve - -**The 7 Micro-Tasks:** - -1. **[4a: Announce & Gather](steps-c/4a-announce-and-gather.md)** - - Announce section and gather requirements - -2. **[4b: Create Story File](steps-c/4b-create-story-file.md)** - - Create focused story file for this section - -3. **[4c: Implement Section](steps-c/4c-implement-section.md)** - - Implement code following story - -4. **[4d: Present for Testing](steps-c/4d-present-for-testing.md)** - - Present to user with test instructions - -5. **[4e: Handle Issue](steps-c/4e-handle-issue.md)** - - Fix issues if user reports problems (loop back to 4d) - -6. **[4f: Handle Improvement](steps-c/4f-handle-improvement.md)** - - Implement improvements if user suggests (loop back to 4d) - -7. **[4g: Section Approved](steps-c/4g-section-approved.md)** - - Finalize approval and move to next section (back to 4a) - -**Flow:** 4a β†’ 4b β†’ 4c β†’ 4d β†’ [4e or 4f if needed, loops to 4d] β†’ 4g β†’ [back to 4a for next section] - -**Creates (per section):** -- Story file (just-in-time) -- Incremental updates to view HTML -- Learnings captured - -**Key:** One clear task per file β†’ No confusion β†’ Linear execution β†’ Better results! - ---- - -### Phase 5: Finalization -**When:** All sections complete for a logical view (end of view) - -**What:** Integration test all states and final approval - -**Result:** Production-ready logical view handling all its states - -**Go to:** [steps-c/5-finalization.md](steps-c/5-finalization.md) - ---- - -## INITIALIZATION - -### Guide References - -**Process Guides:** -- [INTERACTIVE-PROTOTYPES-GUIDE.md](guides/INTERACTIVE-PROTOTYPES-GUIDE.md) - Overview and methodology -- [CREATION-GUIDE.md](guides/CREATION-GUIDE.md) - Technical implementation details -- [PROTOTYPE-INITIATION-DIALOG.md](guides/PROTOTYPE-INITIATION-DIALOG.md) - Conversation scripts -- [PROTOTYPE-ANALYSIS.md](guides/PROTOTYPE-ANALYSIS.md) - Quality standards -- [FILE-INDEX.md](guides/FILE-INDEX.md) - Complete file reference - -**Templates:** -- templates/work-file-template.yaml -- templates/story-file-template.md -- templates/page-template.html -- templates/components/dev-mode.* - -### First Step Execution - -Load, read and execute `steps-c/1-prototype-setup.md` to begin workflow. - ---- - -## OUTPUT - -**Per Scenario:** -``` -[Scenario-Number]-[Scenario-Name]-Prototype/ -β”œβ”€β”€ [View].html files (in root, one per logical view) -β”œβ”€β”€ shared/ (ONE COPY of shared code) -β”œβ”€β”€ components/ (ONE COPY of reusable components) -β”œβ”€β”€ pages/ (page-specific scripts if complex) -β”œβ”€β”€ data/ (demo data JSON files) -β”œβ”€β”€ stories/ (section development files - created just-in-time) -β”œβ”€β”€ work/ (planning files) -└── PROTOTYPE-ROADMAP.md -``` - -**Result:** Self-contained, production-ready interactive prototypes with: -- Clean HTML using Tailwind CSS -- Vanilla JavaScript components -- Demo data auto-loading -- All states implemented and tested - ---- - -## PROTOTYPE FOLDER STRUCTURE - -``` -[Scenario-Number]-[Scenario-Name]-Prototype/ -β”œβ”€β”€ [Page].html files ← Logical view HTML files (root) -β”œβ”€β”€ shared/ ← ONE COPY of shared code -β”œβ”€β”€ components/ ← ONE COPY of reusable components -β”œβ”€β”€ pages/ ← Page-specific scripts (if complex) -β”œβ”€β”€ data/ ← Demo data JSON files -β”œβ”€β”€ stories/ ← Section development files (JIT) -β”œβ”€β”€ work/ ← Planning files -β”‚ β”œβ”€β”€ Logical-View-Map.md ← Maps steps to views -β”‚ └── [View]-Work.yaml ← Section breakdowns per view -└── PROTOTYPE-ROADMAP.md ← Overall roadmap -``` - ---- - -## ITERATIVE WORKFLOW - -**Phase 1-2:** One-time setup and analysis per scenario - -**Phase 3:** Repeat for each logical view in scenario - -**Phase 4:** Repeat for each section in current view -- Inner loop: Repeat 4d-4e-4f until approved - -**Phase 5:** Repeat for each logical view (finalization) - -**Pattern:** -``` -Setup β†’ Analysis β†’ [View Selection β†’ [Section Loop*] β†’ Finalization]* -``` - ---- - -## EXAMPLES - -**Typical Scenarios:** - -1. **E-commerce Checkout:** 5 views (cart, shipping, payment, review, confirmation) -2. **SaaS Onboarding:** 4 views (signup, profile, preferences, dashboard) -3. **Booking System:** 6 views (search, select, details, confirm, payment, confirmation) - -Each view breaks into 3-8 sections depending on complexity. - ---- - -## QUALITY PRINCIPLES - -**Section-by-Section Approval:** Never implement entire view at once - break into sections with approval gates - -**Just-In-Time Stories:** Create story files only when needed (4b), not upfront - -**Incremental Implementation:** Each section builds on previous approved sections - -**Demo Data:** Use realistic demo data for testing and validation - -**Self-Contained:** Each prototype folder is complete and portable - ---- - -## TROUBLESHOOTING - -**Issue:** User feedback requires rework -**Solution:** Use Phase 4e (issues) or 4f (improvements) to handle, then loop back to 4d - -**Issue:** Section too complex -**Solution:** Break down further in Phase 3 before starting Phase 4 - -**Issue:** Logical view unclear -**Solution:** Revisit Phase 2 analysis to refine view mapping - ---- - -## NOTES - -This workflow creates **prototypes**, not final production code. The code is production-ready quality but intended for: -- Stakeholder demos -- User testing -- Design validation -- Developer handoff reference - -Final production code will be built in development phase using proper frameworks and architecture. - ---- - -_Interactive Prototypes - Section-by-section implementation with approval gates_ diff --git a/src/workflows/4-ux-design/page-specification-quality/quality-guide.md b/src/workflows/4-ux-design/page-specification-quality/quality-guide.md index 648c2f670..a6ffdbd89 100644 --- a/src/workflows/4-ux-design/page-specification-quality/quality-guide.md +++ b/src/workflows/4-ux-design/page-specification-quality/quality-guide.md @@ -572,7 +572,7 @@ This quality workflow integrates with: - [Sketch Analysis](../substeps/4b-sketch-analysis.md) - Identifies page elements **After:** -- [Interactive Prototypes](../interactive-prototypes/) - Builds HTML demos from specs +- [Agentic Development](../agentic-development/) - Builds HTML demos from specs - [Design Deliveries](../../../6-design-deliveries/) - Packages specs for handoff - [PRD Generation](../../../3-prd-platform/) - Creates developer stories from specs diff --git a/src/workflows/4-ux-design/stitch-generation/stitch-prompt.template.md b/src/workflows/4-ux-design/stitch-generation/stitch-prompt.template.md new file mode 100644 index 000000000..bf7baebc6 --- /dev/null +++ b/src/workflows/4-ux-design/stitch-generation/stitch-prompt.template.md @@ -0,0 +1,174 @@ +# Stitch Prompt Template + +Use this template to prepare an effective Stitch prompt from a WDS specification. + +--- + +## How to Use + +1. **Copy this template** into your Stitch dialog +2. **Fill in each section** using your spec and design system +3. **Remove Object IDs, translations, technical details** - Stitch doesn't need them +4. **Keep one language only** - typically the primary language (English or Swedish) +5. **Paste the filled template** as your Stitch prompt + +--- + +## Template Structure + +``` +=== PROJECT CONTEXT === + +App: {App name} - {One-line description} +Target: {Target audience} +Brand feel: {2-3 adjectives describing the feel} +Market: {Market focus if relevant} + +=== DESIGN SYSTEM === + +Colors: +- Background: {color name} ({hex}) +- Primary/CTA: {color name} ({hex}) +- Text: {color name} ({hex}) +- Secondary text: {color name} ({hex}) +- Success: {hex} +- Error: {hex} + +Typography: +- Font: {font family} +- Headlines: {weight}, {characteristics} +- Body: {weight}, {size} + +Component styles: +- Buttons: {style description - rounded, gradient, shadow, etc.} +- Inputs: {style description - border, focus state, etc.} +- Cards: {style description if relevant} + +=== SCREEN DETAILS === + +Screen: {Screen name} +Purpose: {What this screen does, one sentence} +User context: {Where user is coming from, what they need} + +Layout structure: +1. {Section 1}: {elements} +2. {Section 2}: {elements} +3. {Section 3}: {elements} + +Key elements: +- {Element 1}: "{Actual content/text}" +- {Element 2}: "{Actual content/text}" +- {Element 3}: "{Actual content/text}" + +Key interactions: +- Primary action: {what happens} +- Secondary action: {what happens} + +=== CURRENT STATE NOTES === + +{Note any elements currently using default/unstyled components} +- {Component}: Currently ShadCN default, should match brand style +- {Component}: Uses custom gradient button + +=== GENERATION INSTRUCTIONS === + +Generate this screen matching: +- Visual style of the attached reference image +- Layout structure of the attached sketch +- All content and elements listed above + +Viewport: {Mobile 390px / Desktop 1440px} +``` + +--- + +## Example: Dog Week Sign-In + +``` +=== PROJECT CONTEXT === + +App: Dog Week - Family dog walk coordination app +Target: Swedish families (all ages from teens to grandparents) +Brand feel: Warm, friendly, trustworthy +Market: Sweden + +=== DESIGN SYSTEM === + +Colors: +- Background: Cream (#FEF3CF), gradient to #FFFBED +- Primary/CTA: Orange (#FD6408), gradient #FD8002 to #FF2714 +- Text: Brown (#2F1A0C) +- Secondary text: Gray (#686868) +- Success: Green (#28C54A) +- Error: Red (#DB0000) + +Typography: +- Font: Inter +- Headlines: Bold/Extra Bold, tight letter spacing +- Body: Regular weight, 16px base + +Component styles: +- Buttons: Rounded (8px), orange gradient for primary, subtle shadow +- Inputs: Light background, rounded corners, brown text +- Cards: Cream background, subtle shadow + +=== SCREEN DETAILS === + +Screen: Sign In +Purpose: Authenticate users with email magic link or Google SSO +User context: Coming from Start Page, ready to access the app + +Layout structure: +1. Header: Logo (left), Back button (right) +2. Main form: Email input, magic link button, divider, Google SSO +3. Trust section: Privacy and security messages +4. Help links: Support links at bottom + +Key elements: +- Email input label: "Email address" +- Email placeholder: "your@email.com" +- Helper text: "We'll send you a magic link to sign in" +- Primary button: "Send magic link" +- Divider text: "Or sign in with" +- Google button: "Continue with Google" +- Trust message 1: "Your information is secure and private" +- Trust message 2: "We'll never spam you or share your details" +- Trust message 3: "Safe for all family members to use" + +Key interactions: +- Primary: Enter email β†’ Send magic link β†’ Check email +- Secondary: Click Google β†’ OAuth flow β†’ Signed in + +=== CURRENT STATE NOTES === + +- Input fields: Currently ShadCN default styling, should use cream background +- Google button: Should match brand's rounded style with Google colors +- Trust icons: Need checkmark or shield icons in success green + +=== GENERATION INSTRUCTIONS === + +Generate this sign-in screen matching: +- Visual style of the attached Start Page screenshot (warm, cream, orange CTAs) +- Layout structure of the attached sketch +- All content and elements listed above + +Viewport: Mobile 390px +``` + +--- + +## Checklist Before Pasting to Stitch + +- [ ] Project context filled (app name, target, brand feel) +- [ ] Design system colors accurate (from Color-Palette.md) +- [ ] Typography correct (from Typography-System.md) +- [ ] Component styles described (buttons, inputs) +- [ ] Screen content in ONE language only (no translations) +- [ ] No Object IDs included +- [ ] No technical implementation details +- [ ] Current state notes added (what's ShadCN default) +- [ ] Viewport specified + +--- + +_Stitch Prompt Template β€” Freya WDS Designer_ diff --git a/src/workflows/4-ux-design/stitch-generation/workflow.md b/src/workflows/4-ux-design/stitch-generation/workflow.md new file mode 100644 index 000000000..496ec0bba --- /dev/null +++ b/src/workflows/4-ux-design/stitch-generation/workflow.md @@ -0,0 +1,288 @@ +--- +name: Stitch UI Generation +description: AI-assisted UI design using Google Stitch from specifications and sketches +web_bundle: true +--- + +# Stitch UI Generation + +**Goal:** Generate production-quality UI designs using Google Stitch AI + +**Your Role:** Guide the user through preparing inputs and creating a Stitch generation dialog + +--- + +## OVERVIEW + +Google Stitch is an AI-powered UI design tool that transforms text prompts, sketches, and reference images into responsive interfaces. + +**Input Formula:** +``` +Visual Reference + Sketch + Specification = Stitch Generation +``` + +**Output:** UI designs exportable to Figma or HTML/CSS + +--- + +## WHEN TO USE STITCH + +**Use Stitch when:** +- βœ… New page with detailed specification ready +- βœ… Have a visual reference (existing design or screenshot) +- βœ… Have a sketch showing layout structure +- βœ… Want rapid visual design iteration +- βœ… Need production-quality mockups quickly + +**Skip Stitch when:** +- ❌ Building design system components (use tokens instead) +- ❌ Minor updates to existing designs (edit directly) +- ❌ No specification exists yet (write spec first) +- ❌ Complex multi-screen flows (do 2-3 screens at a time) + +--- + +## BEFORE STARTING + +### Prerequisites + +1. **Specification exists** for the screen(s) to generate +2. **Visual reference available:** + - Screenshot of existing implemented page, OR + - Approved design that establishes visual language +3. **Sketch available** showing layout structure + +### Decision: What Visual Reference? + +| Situation | Reference Choice | +|-----------|------------------| +| Code exists and looks correct | Screenshot of running code | +| Starting fresh, no code | Original sketch or moodboard | +| Code exists but needs redesign | Original sketch | +| Want style from one page, layout from sketch | Both (upload 2 images) | + +--- + +## WORKFLOW + +### Step 1: Create Dialog + +Create a Stitch generation dialog in the project's Agent Dialogs folder. + +**Template:** Use `9-agent-dialogs/templates/dialog-types/stitch-generation.template.md` + +**Location:** `docs/F-Agent-Dialogs/{YYYY-MM-DD}-freya-stitch-{feature}/` + +**Dialog captures:** +- Which screens to generate +- What visual reference to use +- Pre-crafted prompts +- Generation results and decisions + +--- + +### Step 2: Answer Pre-Generation Questions + +For each potential screen, decide: + +**Question 1: Generate in Stitch?** + +| Screen | Has Code? | Has Sketch? | Generate? | Why | +|--------|-----------|-------------|-----------|-----| +| {screen} | βœ…/❌ | βœ…/❌ | βœ…/❌ | {reason} | + +**Question 2: What reference?** + +| Screen | Reference | Source | +|--------|-----------|--------| +| {screen} | Code screenshot / Sketch | {path or action} | + +--- + +### Step 3: Gather Inputs + +For each screen to generate: + +| Input | Action | +|-------|--------| +| **Visual Reference** | Take screenshot OR locate existing design | +| **Sketch** | Locate in spec's `Sketches/` folder | +| **Prompt** | Prepare using template (see Step 3a) | + +--- + +### Step 3a: Prepare the Prompt + +**DO NOT paste raw specifications into Stitch.** They contain: +- Object IDs (not useful for design generation) +- Multiple translations (confusing) +- Technical implementation details + +**Instead, use the prompt template:** [stitch-prompt.template.md](stitch-prompt.template.md) + +The prompt should include: + +| Section | Source | +|---------|--------| +| **Project Context** | Design System overview, Product Brief | +| **Design System** | Color-Palette.md, Typography-System.md | +| **Component Styles** | Button/Input specs from Design System | +| **Screen Content** | Specification (ONE language, no Object IDs) | +| **Current State Notes** | What's ShadCN default vs custom | + +**Important notes:** +- Use actual hex colors from your design system +- Describe component styles (rounded buttons, gradients, etc.) +- Include only ONE language (primary language) +- Note what's currently using default styling that needs brand styling + +--- + +### Step 4: Generate in Stitch + +1. Go to [stitch.withgoogle.com](https://stitch.withgoogle.com) +2. Upload **visual reference** image +3. Upload **sketch** image (if different from reference) +4. Paste **specification** as prompt +5. Add instruction: *"Generate this screen matching the visual style of the reference and layout of the sketch."* +6. Generate 2-3 variants +7. Select best result + +**Settings:** +- Standard Mode: Quick iteration +- Pro Mode: Higher fidelity (uses more quota) +- Viewport: Mobile 390px or Desktop 1440px + +--- + +### Step 5: Review Against Spec + +| Check | Pass? | +|-------|-------| +| Content/copy matches spec | βœ…/❌ | +| Layout follows sketch | βœ…/❌ | +| Visual style matches reference | βœ…/❌ | +| All key elements present | βœ…/❌ | + +**If issues:** Re-prompt with specific corrections or edit in Stitch. + +--- + +### Step 6: Export & Store + +| Format | When | Destination | +|--------|------|-------------| +| **Figma** | Team collaboration, design system work | Figma project | +| **HTML/CSS** | Code reference, rapid prototypes | `{spec-folder}/Visual-Design/` | +| **Screenshot** | Documentation | `{spec-folder}/Visual-Design/` | + +**Naming:** `{screen-name}-stitch-v{#}.{ext}` + +--- + +### Step 7: Update Specification + +Add to the specification file: + +```markdown +## Visual Design + +**Stitch Generated:** [sign-in-stitch-v1.png](Visual-Design/sign-in-stitch-v1.png) +``` + +--- + +## STITCH CAPABILITIES & LIMITS + +### What Stitch Does Well +- Single screen generation from prompts +- Style matching from reference images +- Responsive layouts (mobile/desktop) +- Clean HTML/CSS export +- Figma-compatible output + +### Current Limitations +- Best with 2-3 screens at a time +- Layouts can be generic (need refinement) +- Doesn't capture deep UX nuance +- No built-in design system awareness +- Free tier: 350 standard + 200 pro screens/month + +--- + +## PROMPT TIPS + +### Effective Prompts Include + +1. **App type:** "Mobile sign-in screen for..." +2. **Context:** "...a Swedish family dog walk coordination app" +3. **Visual direction:** "Match the attached reference..." +4. **Key elements:** List all major UI elements +5. **Content:** Include actual copy/text +6. **Mood:** "Friendly, trustworthy, family-oriented" + +### Example Prompt Structure + +``` +[App type] [screen name] for [product description]. + +Visual style: Match the attached reference exactly. + +Screen layout: +- [Section 1]: [elements and content] +- [Section 2]: [elements and content] +- [Section 3]: [elements and content] + +Key interactions: [primary action], [secondary action] + +Mood: [brand tone and feel] +Viewport: [Mobile 390px / Desktop 1440px] +``` + +--- + +## INTEGRATION WITH WDS + +### Workflow Position + +``` +Specification β†’ Stitch Generation β†’ Visual Design β†’ Implementation + ↓ ↓ ↓ ↓ + Content AI-Assisted Approved Code + & Structure Design Mockups Build +``` + +### Related Workflows + +- **Before Stitch:** Page Specification workflow (create the spec first) +- **After Stitch:** Prototype Implementation dialog (build from the design) +- **Alternative:** Design Exploration dialog (if exploring multiple directions) + +--- + +## QUICK START + +**Fastest path:** + +1. User: "I want to generate a UI design for [screen name]" +2. Freya: Creates Stitch dialog from template +3. Freya: Asks pre-generation questions (which screens, what reference) +4. User: Provides answers, takes screenshot if needed +5. User: Goes to Stitch, uploads inputs, pastes spec +6. User: Generates, reviews, exports +7. Freya: Updates dialog with results, links in spec + +--- + +## SUPPORT + +**Google Stitch:** +- [stitch.withgoogle.com](https://stitch.withgoogle.com) +- [Google Developers Blog - Introducing Stitch](https://developers.googleblog.com/stitch-a-new-way-to-design-uis/) + +**WDS Templates:** +- Dialog template: `9-agent-dialogs/templates/dialog-types/stitch-generation.template.md` + +--- + +_Stitch UI Generation Workflow β€” Freya WDS Designer β€” Phase 4 UX Design_ diff --git a/src/workflows/5-design-system/figma-integration/reference/tools-reference.md b/src/workflows/5-design-system/figma-integration/reference/tools-reference.md index 235041247..87a13376a 100644 --- a/src/workflows/5-design-system/figma-integration/reference/tools-reference.md +++ b/src/workflows/5-design-system/figma-integration/reference/tools-reference.md @@ -434,7 +434,7 @@ Area tags have limitations: **Purpose:** Interactive tool for extracting Object IDs and area coordinates from prototypes -**Location:** `workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js` +**Location:** `workflows/4-ux-design/agentic-development/templates/components/dev-mode.js` ### Features @@ -656,9 +656,9 @@ Area tags have limitations: - W3C Spec: **WDS Documentation:** -- Prototype Workflow: `workflows/4-ux-design/interactive-prototypes/` +- Prototype Workflow: `workflows/4-ux-design/agentic-development/` - Figma Integration: `workflows/5-design-system/figma-integration/` -- Dev Mode: `workflows/4-ux-design/interactive-prototypes/templates/components/` +- Dev Mode: `workflows/4-ux-design/agentic-development/templates/components/` --- diff --git a/src/workflows/9-agent-dialogs/steps/step-01-initialize-dialog.md b/src/workflows/9-agent-dialogs/steps/step-01-initialize-dialog.md index 6d86c51e3..2dd68034d 100644 --- a/src/workflows/9-agent-dialogs/steps/step-01-initialize-dialog.md +++ b/src/workflows/9-agent-dialogs/steps/step-01-initialize-dialog.md @@ -2,7 +2,58 @@ ## CONTEXT -This is the first step of the Agent Dialog Workflow. We create the folder structure and main dialog file. +This is the first step of the Agent Dialog Workflow. Before creating a new dialog, we first check for any existing pending dialogs. + +--- + +## CHECK FOR EXISTING DIALOGS + +⚠️ **IMPORTANT: Always check for pending dialogs before creating a new one.** + + +**Scan for existing dialogs:** + +1. Check if `docs/F-Agent-Dialogs/` exists +2. If it exists, scan all subdirectories for dialog files (*-dialog.md) +3. Read the Meta section of each dialog file +4. Identify dialogs where: + - Status = "Not Started" OR "In Progress" + - Agent matches the current agent (if known) + + + +**If pending dialogs found:** + +Present them to the user: + +``` +πŸ“‹ **Found {N} pending dialog(s):** + +| # | Date | Agent | Feature | Status | +|---|------|-------|---------|--------| +| 1 | {date} | {agent} | {feature} | {status} | + +**Options:** +[A] Continue existing dialog #{N} +[B] Create a new dialog (existing ones remain pending) + +Choice: +``` + +If user chooses an existing dialog: +- Load that dialog file +- Check the Steps Overview table for next incomplete step +- Continue from there + +If user chooses to create new: +- Continue to SELECT DIALOG TYPE below + + + +**If no pending dialogs found OR docs/F-Agent-Dialogs/ doesn't exist:** + +Continue to SELECT DIALOG TYPE below. + --- @@ -70,12 +121,18 @@ Agent: **Create dialog folder:** -Path: `docs/F-Agent-Dialogs/{date}-{feature_slug}/` +Path: `docs/F-Agent-Dialogs/{date}-{agent_slug}-{feature_slug}/` Where: - `{date}` = Today's date in YYYY-MM-DD format +- `{agent_slug}` = Agent name, lowercase (e.g., "freya", "saga", "dev") - `{feature_slug}` = Feature name, lowercase, hyphenated +**Examples:** +- `2026-01-23-freya-booking-details-overlay/` +- `2026-01-23-saga-course-workflow-integration/` +- `2026-01-23-dev-calendar-scroll-fix/` + **Create subfolders:** - `steps/` β€” For step instruction files @@ -87,9 +144,9 @@ Where: **Create main dialog file:** -File: `docs/F-Agent-Dialogs/{date}-{feature_slug}/{date}-{feature_slug}-dialog.md` +File: `docs/F-Agent-Dialogs/{date}-{agent_slug}-{feature_slug}/{date}-{agent_slug}-{feature_slug}-dialog.md` -**Use template from:** `templates/dialog.template.md` +**Use template from:** Selected dialog type template (see SELECT DIALOG TYPE step above) **Fill in:** - Date: Today's date @@ -158,8 +215,8 @@ Patterns: βœ… **Dialog initialized!** **Created:** -- Folder: `docs/F-Agent-Dialogs/{date}-{feature_slug}/` -- Dialog file: `{date}-{feature_slug}-dialog.md` +- Folder: `docs/F-Agent-Dialogs/{date}-{agent_slug}-{feature_slug}/` +- Dialog file: `{date}-{agent_slug}-{feature_slug}-dialog.md` - Steps folder: `steps/` **Next:** Proceed to Step 2 to analyze scope and create step breakdown. diff --git a/src/workflows/9-agent-dialogs/steps/step-04-execute-steps.md b/src/workflows/9-agent-dialogs/steps/step-04-execute-steps.md index f6e24c4ca..4792a6937 100644 --- a/src/workflows/9-agent-dialogs/steps/step-04-execute-steps.md +++ b/src/workflows/9-agent-dialogs/steps/step-04-execute-steps.md @@ -4,6 +4,8 @@ Step files are created. Now we execute each step, either in this dialog or in fresh agent dialogs. +**Note:** For implementation-specific execution details (feedback protocol, dynamic planning), see the **Agentic Development Workflow** in `workflows/4-ux-design/agentic-development/workflow.md`. + --- ## EXECUTION MODES @@ -34,9 +36,11 @@ Mode: 1. **Read the step file** completely -2. **Execute the implementation** following the instructions -3. **Verify against acceptance criteria** -4. **Test using the test instructions** +2. **Document any decisions or issues** in the dialog before implementing +3. **Execute the implementation** following the instructions +4. **Add sub-steps** if needed for things discovered during implementation +5. **Verify against acceptance criteria** +6. **Test using the test instructions** ### Step Completion Checklist @@ -73,7 +77,10 @@ Mode: Choice: - Load and execute next step file + + 1. Review and update remaining steps in dialog file + 2. Load and execute next step file + @@ -81,6 +88,7 @@ Choice: Update dialog file: - Status: "In Progress" - Progress Log: Note where we stopped + - Ensure all decisions documented Output: "Progress saved. The dialog is ready to resume." @@ -90,6 +98,20 @@ Choice: ## MODE B: FRESH DIALOG INSTRUCTIONS +### Handoff Always References Dialog + + +**Any handoff β€” to a new session, new agent, or human β€” MUST reference the dialog document.** + +The dialog document is the single source of truth for: +- What has been done +- What decisions were made +- What remains to be done +- Any issues or blockers + +Never hand off by describing the task verbally. Always point to the dialog. + + ### For Each Step @@ -98,20 +120,24 @@ Choice: ``` ## Execute Step {N}: {Step Name} -### Context -This is part of the {feature-name} implementation. -Dialog: docs/F-Agent-Dialogs/{date}-{feature-name}/ +### Dialog Document (READ FIRST) +`docs/F-Agent-Dialogs/{date}-{feature-name}/{date}-{feature-name}-dialog.md` + +Read the dialog file first to understand: +- Overall context and scope +- What steps are complete +- Current status and any blockers + +### Step File +`docs/F-Agent-Dialogs/{date}-{feature-name}/steps/{N}-{step-name}.md` ### Instructions -1. Read the step file: `steps/{N}-{step-name}.md` -2. Execute the implementation -3. Verify against acceptance criteria -4. When complete, update the dialog file: - - Change step status to βœ… - - Add entry to Progress Log - -### Step File Location -`docs/F-Agent-Dialogs/{date}-{feature-name}/steps/{N}-{step-name}.md` +1. Read the dialog file completely +2. Read the step file +3. Execute the implementation +4. Document decisions in the dialog BEFORE implementing +5. Verify against acceptance criteria +6. Update dialog file: step status β†’ βœ…, add Progress Log entry ``` @@ -197,7 +223,7 @@ Add to Progress Log: - πŸŽ‰ **All steps complete!** + **All steps complete!** Proceed to Step 5 to finalize the dialog. diff --git a/src/workflows/9-agent-dialogs/templates/dialog-types/INDEX.md b/src/workflows/9-agent-dialogs/templates/dialog-types/INDEX.md index 298e3fda0..98430b7c8 100644 --- a/src/workflows/9-agent-dialogs/templates/dialog-types/INDEX.md +++ b/src/workflows/9-agent-dialogs/templates/dialog-types/INDEX.md @@ -4,11 +4,24 @@ Choose the template that matches your work type. --- +## Naming Convention + +``` +docs/F-Agent-Dialogs/ +└── {YYYY-MM-DD}-{agent}-{feature-name}/ + └── {YYYY-MM-DD}-{agent}-{feature-name}-dialog.md +``` + +**Example:** `2026-01-23-freya-booking-details-overlay-dialog.md` + +--- + ## Available Types | Type | Icon | Template | Use When | |------|------|----------|----------| | **Prototype Implementation** | πŸ”§ | [prototype-implementation.template.md](prototype-implementation.template.md) | Building UI from specifications | +| **Stitch UI Generation** | πŸͺ‘ | [stitch-generation.template.md](stitch-generation.template.md) | AI-assisted UI design with Google Stitch | | **Bug Fix** | πŸ› | [bug-fix.template.md](bug-fix.template.md) | Fixing issues and defects | | **Design Exploration** | 🎨 | [design-exploration.template.md](design-exploration.template.md) | Exploring visual/UX directions | | **Capture** | πŸ’Ύ | [../dialog-capture.template.md](../dialog-capture.template.md) | Saving ideas for later | @@ -32,6 +45,25 @@ Choose the template that matches your work type. --- +### πŸͺ‘ Stitch UI Generation + +**Best for:** +- Generating UI designs from specifications using Google Stitch AI +- Rapid visual design iteration +- Creating production-quality screens from sketches + +**Key sections:** +- Input formula: Visual Reference + Sketch + Specification +- Screen-by-screen generation tracking +- Export and integration workflow + +**Input Formula:** +``` +Visual Reference + Sketch + Specification (as prompt) = Stitch Generation +``` + +--- + ### πŸ› Bug Fix **Best for:** @@ -92,7 +124,9 @@ Choose the template that matches your work type. ``` Start here: β”‚ - β”œβ”€β”€ Building from spec? β†’ πŸ”§ Prototype Implementation + β”œβ”€β”€ Building code from spec? β†’ πŸ”§ Prototype Implementation + β”‚ + β”œβ”€β”€ Generating UI designs with AI? β†’ πŸͺ‘ Stitch UI Generation β”‚ β”œβ”€β”€ Fixing something broken? β†’ πŸ› Bug Fix β”‚ diff --git a/src/workflows/9-agent-dialogs/templates/dialog-types/prototype-implementation.template.md b/src/workflows/9-agent-dialogs/templates/dialog-types/prototype-implementation.template.md index 593f3e59e..f5d34c4f6 100644 --- a/src/workflows/9-agent-dialogs/templates/dialog-types/prototype-implementation.template.md +++ b/src/workflows/9-agent-dialogs/templates/dialog-types/prototype-implementation.template.md @@ -1,4 +1,14 @@ -# {DATE} {Feature Name} β€” Prototype Implementation +# {YYYY-MM-DD} {Feature Name} β€” Prototype Implementation + + ## Meta @@ -6,7 +16,7 @@ |-------|-------| | **Date** | {YYYY-MM-DD} | | **Type** | πŸ”§ Prototype Implementation | -| **Agent** | Freya (UX Designer) | +| **Agent** | {Agent name} ({Role}) | | **Feature** | {Feature name} | | **Specification** | [{Spec name}]({path-to-spec}) | | **Target** | {Where to implement: app path or prototype folder} | @@ -126,24 +136,99 @@ Each section is implemented and approved before moving to the next: ### Approval Criteria -- [ ] Matches specification visually -- [ ] All Object IDs present +- [ ] **Matches sketches precisely** β€” Text sizes, proportions, spacing, layout +- [ ] All Object IDs present as `data-object-id` attributes - [ ] Translations work (SE/EN toggle) - [ ] Accessibility requirements met - [ ] No TypeScript errors +> **Sketch Fidelity:** Sketches are intentional design decisions. Text sizes, proportions, and spacing are chosen deliberately. Implement as close to the sketch as possible. If constraints prevent exact matching, document the deviation. + +--- + +## Feedback Protocol + +How designer feedback is handled during implementation: + +| Type | What It Is | When to Address | Documentation | +|------|------------|-----------------|---------------| +| **Bug/Issue** | Something broken or not working | Now β€” iterate until fixed | Part of current step | +| **Quick Adjustment** | Small tweak to current work | Now β€” implement immediately | Note in progress log | +| **Addition** | New requirement in scope | Later step β€” add to plan | Note in step file | +| **Change Request** | Outside current scope | Future session β€” document | Add to Change Requests | + +### The 2-Minute Rule (GTD) + +**If a fix takes less than 2 minutes, do it immediately.** + +Planning overhead should not exceed task complexity. See [GTD Model](../../../../docs/models/gtd-getting-things-done.md). + +**Pattern:** Do the fix β†’ Log as sub-step (e.g., 20a-1) β†’ Continue main task + +### Agent Response Pattern + +**When user reports something:** +1. **CLASSIFY** β€” What type of feedback is this? +2. **TIMING** β€” When should it be addressed? +3. **CONFIRM** β€” For additions and change requests, confirm before proceeding +4. **EXECUTE** β€” Implement or document as appropriate + +### Change Request Flow + +``` +Designer: "The profile button should go to /family" +Agent: "This is outside the current dialog scope. + It doesn't block {current feature}. + I'll add it to Change Requests for a future session. Confirm?" +Designer: "Yes" β†’ Agent adds to Change Requests + OR "Do it now" β†’ Agent treats as quick adjustment, implements +``` + +--- + +## Change Requests + +Structural changes identified during implementation. Assessed for timing. + +| # | Request | Raised | Assessment | Timing | Status | +|---|---------|--------|------------|--------|--------| +| _None yet_ | | | | | | + + + --- ## Steps Overview -| # | Section | Status | Approved | -|---|---------|--------|----------| -| 1 | [{Section name}](steps/01-{section}.md) | πŸ”² | πŸ”² | -| 2 | [{Section name}](steps/02-{section}.md) | πŸ”² | πŸ”² | -| 3 | [{Section name}](steps/03-{section}.md) | πŸ”² | πŸ”² | +### Done + +| # | Section | Notes | +|---|---------|-------| +| _None yet_ | | | + +### In Progress + +| # | Section | Status | Description | +|---|---------|--------|-------------| +| 1 | [{Section name}](steps/01-{section}.md) | πŸ”„ | {Brief description} | +| 1a | β€” {Sub-task} | πŸ”„ | {Sub-step added during execution} | + +### To Do + +| # | Section | Description | +|---|---------|-------------| +| 2 | [{Section name}](steps/02-{section}.md) | {Brief description} | +| 3 | [{Section name}](steps/03-{section}.md) | {Brief description} | **Status:** πŸ”² Not Started | πŸ”„ In Progress | βœ… Complete | ⏸️ Blocked -**Approved:** πŸ”² Pending | βœ… Approved | πŸ” Needs Changes + +**Sub-Step Numbering:** +- Main steps: `1`, `2`, `3`... +- Sub-steps during execution: `1a`, `1b`... +- Bug fixes (2-min rule): `1a-1`, `1a-2`... --- diff --git a/src/workflows/9-agent-dialogs/templates/dialog-types/stitch-generation.template.md b/src/workflows/9-agent-dialogs/templates/dialog-types/stitch-generation.template.md new file mode 100644 index 000000000..a8ec603fa --- /dev/null +++ b/src/workflows/9-agent-dialogs/templates/dialog-types/stitch-generation.template.md @@ -0,0 +1,311 @@ +# {YYYY-MM-DD} {Feature Name} β€” Stitch UI Generation + + + +## Meta + +| Field | Value | +|-------|-------| +| **Date** | {YYYY-MM-DD} | +| **Type** | πŸͺ‘ Stitch UI Generation | +| **Agent** | Freya (WDS Designer) | +| **Feature** | {Feature/flow name} | +| **Specifications** | [{Spec 1}]({path}), [{Spec 2}]({path}) | +| **Design Reference** | [{Reference design}]({path}) β€” visual style source | +| **Status** | Not Started | + +--- + +## Purpose + +Generate production-quality UI designs for {feature name} using Google Stitch AI, based on existing specifications and sketches. + +--- + +## About This Dialog + +This dialog guides the **AI-assisted UI generation workflow** using Google Stitch. + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ INPUTS β”‚ β”‚ STITCH PROCESS β”‚ β”‚ OUTPUTS β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β€’ Specifications │────────▢│ β€’ Prompt crafting │────────▢│ β€’ UI designs β”‚ +β”‚ β€’ Sketches β”‚ β”‚ β€’ Generation β”‚ β”‚ β€’ Figma exports β”‚ +β”‚ β€’ Reference designs β”‚ β”‚ β€’ Iteration β”‚ β”‚ β€’ HTML/CSS code β”‚ +β”‚ β€’ Strategic context β”‚ β”‚ β€’ Refinement β”‚ β”‚ β€’ Design decisions β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + Source Materials AI Generation Project Assets +``` + +**Specifications remain the single source of truth.** Stitch generates visual interpretations that must align with spec requirements. + +--- + +## When to Use Stitch + +| Scenario | Use Stitch? | Why | +|----------|-------------|-----| +| New page with detailed spec | βœ… Yes | Accelerates visual design from requirements | +| Exploring visual directions | βœ… Yes | Quick iteration on look & feel | +| Complex multi-state UI | ⚠️ Partially | Generate base, refine states manually | +| Design system components | ❌ No | Build from tokens, not generated | +| Minor spec updates | ❌ No | Edit existing designs directly | + +--- + +## Stitch Capabilities & Limits + +### What Stitch Does Well +- Single screen generation from prompts +- Style matching from reference images +- Responsive layouts (mobile/desktop) +- Clean HTML/CSS export +- Figma-compatible output + +### Current Limitations +- Best with 2-3 screens at a time +- Layouts can be generic (need refinement) +- Doesn't capture deep UX nuance +- No built-in design system awareness +- Requires iteration for production quality + +--- + +## Setup Context + +### Project Context + +- **Project:** {Project name} +- **Brand:** {Brand characteristics β€” tone, colors, typography} +- **Tech Stack:** {e.g., React, Next.js, Tailwind CSS} +- **Design System:** [{Design System}]({path}) + +### Strategic Context + +| Document | Path | Key Elements | +|----------|------|--------------| +| VTC/Trigger Map | [{path}]({path}) | {Key triggers for this feature} | +| User Personas | [{path}]({path}) | {Target personas} | +| Product Brief | [{path}]({path}) | {Relevant product goals} | + +### Reference Materials + +| Type | File | Purpose | +|------|------|---------| +| **Style Reference** | [{design}]({path}) | Visual language source for Stitch | +| **Sketch** | [{sketch}]({path}) | Layout and structure guide | +| **Specification** | [{spec}]({path}) | Requirements and content | + +--- + +## Pre-Generation Questions + +Before generating, decide for each screen: + +### Question 1: Which screens need Stitch generation? + +| Screen | Has Code? | Has Sketch? | Generate in Stitch? | Why | +|--------|-----------|-------------|---------------------|-----| +| {Screen 1} | βœ…/❌ | βœ…/❌ | βœ…/❌ | {reason} | +| {Screen 2} | βœ…/❌ | βœ…/❌ | βœ…/❌ | {reason} | + +### Question 2: What visual reference for each screen? + +| Option | When to Use | +|--------|-------------| +| **Screenshot of existing code** | Code exists and represents the correct visual direction | +| **Original sketch** | Starting fresh, or code doesn't match desired direction | +| **Both** | Use code as style reference + sketch for layout guidance | + +| Screen | Reference Choice | Source | +|--------|------------------|--------| +| {Screen 1} | Code screenshot / Sketch / Both | {path or "take screenshot"} | +| {Screen 2} | Code screenshot / Sketch / Both | {path or "take screenshot"} | + +--- + +## Screens to Generate + +| # | Screen | Specification | Visual Reference | Layout Guide | Priority | Status | +|---|--------|---------------|------------------|--------------|----------|--------| +| 1 | {Screen name} | [{spec}]({path}) | {screenshot/sketch} | {sketch if different} | High | πŸ”² | +| 2 | {Screen name} | [{spec}]({path}) | {screenshot/sketch} | {sketch if different} | High | πŸ”² | + +**Status:** πŸ”² Not Started | πŸ”„ In Progress | βœ… Generated | πŸ” Needs Refinement | βœ…βœ… Approved + +--- + +## Stitch Input Formula + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ VISUAL REFERENCEβ”‚ + β”‚ SKETCH β”‚ + β”‚ SPECIFICATION β”‚ = Stitch Generation +β”‚ (style source) β”‚ β”‚ (layout/structure)β”‚ β”‚ (paste as prompt)β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**That's it.** Upload the reference + sketch images, paste the spec as prompt text. + +--- + +## Stitch Workflow Steps + +### Step 1: Gather Inputs + +| Input | Source | Format | +|-------|--------|--------| +| **Visual Reference** | Screenshot of existing design (e.g., start page) | Image (PNG/JPG) | +| **Sketch** | Wireframe sketch from spec folder | Image (PNG/JPG) | +| **Specification** | Full spec markdown or key sections | Text (paste into prompt) | + +**Checklist:** +- [ ] Visual reference captured (shows brand style) +- [ ] Sketch image ready +- [ ] Spec content copied (full doc or key sections) + +--- + +### Step 2: Generate in Stitch + +1. Go to [stitch.withgoogle.com](https://stitch.withgoogle.com) +2. Upload **visual reference** image +3. Upload **sketch** image +4. Paste **specification** as prompt text (or key sections) +5. Add brief instruction: *"Generate this screen matching the visual style of the reference and layout of the sketch."* +6. Generate 2-3 variants +7. Select best result + +**Settings:** +- Mode: Standard (fast) or Pro (higher fidelity) +- Viewport: {Mobile 390px | Desktop 1440px} + +**Results:** +| Screen | Variants | Selected | Notes | +|--------|----------|----------|-------| +| {name} | {#} | v{#} | {observations} | + +--- + +### Step 3: Review Against Spec + +Quick check - does the output match spec requirements? + +| Check | βœ…/❌ | Fix Needed | +|-------|-------|------------| +| Content/copy matches spec | | | +| Layout follows sketch | | | +| Visual style matches reference | | | +| All key elements present | | | + +**If refinement needed:** Re-prompt with specific corrections or edit in Stitch. + +--- + +### Step 4: Export & Store + +| Format | Destination | +|--------|-------------| +| **Figma** | Copy to Figma for team/design system work | +| **HTML/CSS** | `{spec-folder}/Visual-Design/` | +| **Screenshot** | `{spec-folder}/Visual-Design/` | + +**Naming:** `{screen-name}-stitch-v{#}.{ext}` + +--- + +### Step 5: Link in Spec + +Add reference to the specification file: + +```markdown +## Visual Design + +**Stitch Generated:** [{screen-name}-stitch-v1.png](Visual-Design/{screen-name}-stitch-v1.png) +``` + +--- + +## Prompts + +Store each screen's prompt in a separate file in the dialog folder. + +**Naming:** Match the scenario numbering: `{scenario#}-{screen-name}-stitch-prompt.md` + +| # | Screen | Prompt File | Status | +|---|--------|-------------|--------| +| 1 | {Screen 1} | [{scenario#}-{screen-name}-stitch-prompt.md]({scenario#}-{screen-name}-stitch-prompt.md) | πŸ”² | +| 2 | {Screen 2} | [{scenario#}-{screen-name}-stitch-prompt.md]({scenario#}-{screen-name}-stitch-prompt.md) | πŸ”² | + +**Examples:** `1.2-sign-in-stitch-prompt.md`, `1.3-profile-setup-stitch-prompt.md` + +Use the [stitch-prompt.template.md](../../stitch-generation/stitch-prompt.template.md) to create each prompt file. + +--- + +## Outputs Log + +| Screen | Version | Format | Path | Approved? | +|--------|---------|--------|------|-----------| +| {name} | v1 | Figma | {link} | πŸ”² | +| {name} | v2 | HTML | {path} | βœ… | + +--- + +## Design Decisions + +| Decision | Context | Rationale | +|----------|---------|-----------| +| {what was decided} | {why it came up} | {reasoning} | + +--- + +## Spec Deviations + +Issues where Stitch output differs from specification: + +| Screen | Spec Requirement | Stitch Output | Resolution | +|--------|------------------|---------------|------------| +| {screen} | {requirement} | {what Stitch did} | {how resolved} | + +--- + +## Progress Log + +### {YYYY-MM-DD} + +- Created dialog for {feature} +- Identified {#} screens to generate +- Prepared reference materials + + + +--- + +## Learnings + + + +| What Worked | Why | Reuse For | +|-------------|-----|-----------| +| {technique} | {reason} | {future use} | + +--- + +_Stitch UI Generation Dialog β€” Freya WDS Designer β€” WDS Agent Dialog Workflow_ diff --git a/src/workflows/9-agent-dialogs/templates/dialog.template.md b/src/workflows/9-agent-dialogs/templates/dialog.template.md index 250eb9809..14861bc1d 100644 --- a/src/workflows/9-agent-dialogs/templates/dialog.template.md +++ b/src/workflows/9-agent-dialogs/templates/dialog.template.md @@ -104,6 +104,33 @@ This dialog **bridges the gap** between the page specification and the developme --- +## Implementation Workflow + +### Step-by-Step Process + +1. **Build step** β€” Implement the code +2. **Test step** β€” Verify against spec +3. **User approval** β€” Confirm it's correct +4. **CW status check** β€” Verify context window has room for next step +5. **Next step** β€” Move forward + +### Context Window (CW) Status Check + +At the end of each completed step, perform a CW status check to ensure the AI session can handle the next step without losing important context. + +| Check | Action | +|-------|--------| +| **Session length** | If conversation is very long, consider starting fresh for next step | +| **Context clarity** | Can the agent still reference earlier decisions accurately? | +| **Handoff summary** | If starting new session, document: completed steps, key decisions, current file states | + +**Recommendation thresholds:** +- **Continue** β€” Session is manageable, context is clear +- **Consider fresh start** β€” Session is long but context is still intact +- **Fresh start recommended** β€” Context overflow risk, or major architectural shift in next step + +--- + ## Steps Overview | # | Step | Status | Notes | diff --git a/src/workflows/9-agent-dialogs/templates/step.template.md b/src/workflows/9-agent-dialogs/templates/step.template.md index c7214280f..77b8e3b17 100644 --- a/src/workflows/9-agent-dialogs/templates/step.template.md +++ b/src/workflows/9-agent-dialogs/templates/step.template.md @@ -94,4 +94,25 @@ For each Object ID: --- +## CW Status Check + +At step completion, assess context window status: + +| Indicator | Status | +|-----------|--------| +| Session length | {Short / Medium / Long} | +| Context clarity | {Clear / Degraded} | +| Recommendation | {Continue / Consider fresh start / Fresh start recommended} | + +**If starting fresh session for next step, include handoff summary:** + +``` +Completed: Step {#} - {Step Name} +Key decisions: {list any important decisions made} +File states: {list modified files and their current state} +Next: Step {#+1} - {Next Step Name} +``` + +--- + _Step {#} of {total} β€” {Feature Name} Implementation_ diff --git a/src/workflows/9-agent-dialogs/workflow.md b/src/workflows/9-agent-dialogs/workflow.md index 4d68bdda7..23e62354c 100644 --- a/src/workflows/9-agent-dialogs/workflow.md +++ b/src/workflows/9-agent-dialogs/workflow.md @@ -388,12 +388,14 @@ To begin, load and execute [steps/step-01-initialize-dialog.md](steps/step-01-in Agent Dialogs can be created from: -- **Interactive Prototypes Workflow** β€” Each section becomes a step - **UX Design Workflow** β€” Specification implementation becomes a dialog - **Design System Workflow** β€” Component creation becomes a dialog +- **Testing Workflow** β€” Validation tasks become a dialog The Agent Dialog structure provides a consistent way to document and execute implementation work from any source. +**Note:** This workflow IS the Agentic Development approach. Interactive Prototypes, Prototype Implementation, Bug Fixes, and Design Exploration are all output types of this workflow. + --- _Agent Dialog Workflow β€” Structured, reproducible implementation with isolated context_ diff --git a/src/workflows/VALIDATION-SUMMARY-REPORT.md b/src/workflows/VALIDATION-SUMMARY-REPORT.md index acba6f630..ea99c5aa9 100644 --- a/src/workflows/VALIDATION-SUMMARY-REPORT.md +++ b/src/workflows/VALIDATION-SUMMARY-REPORT.md @@ -141,8 +141,8 @@ warningsFixed: 6 --- -### 10. interactive-prototypes ⚠️ EMPTY/INCOMPLETE -**Location:** `4-ux-design/interactive-prototypes` +### 10. agentic-development ⚠️ EMPTY/INCOMPLETE +**Location:** `4-ux-design/agentic-development` **Structure:** Directory exists but appears empty or undeveloped **Issue:** No files found **Recommendation:** Remove or develop workflow @@ -269,7 +269,7 @@ Individual validation reports created: ### Immediate Actions Required 1. **Create workflow.md files** for remaining workflows with step structures -2. **Investigate empty workflows** (interactive-prototypes, modular-architecture, object-types) - remove or develop +2. **Investigate empty workflows** (agentic-development, modular-architecture, object-types) - remove or develop 3. **Clarify guide vs workflow** distinction for excalidraw-integration and scenario-init 4. **Complete vtc-workshop** workflow.md creation