StackSketch

Overview

Create and edit StackSketch JSON diagrams that serve as a visual source of truth for full-stack web app planning, including navigation flows, state machines, infrastructure maps, and UI mockups.

When to Activate

• Use when the user asks for visual planning, flowcharts, UI mockups, architecture diagrams, or system design diagrams.
• Use when the user mentions StackSketch, JSON-based diagrams, or a Figma-like editor backed by versioned JSON files.
• Use when the work requires a visual feedback loop before implementation.

Complete Workflow

Phase 1: Discovery

Step 1: Print Intro Banner

╔═══════════════════════════════════════════════════════════════╗
║  📐 StackSketch - Visual Planning                              ║
╠═══════════════════════════════════════════════════════════════╣
║  Phase 1: Discovery (research + interview)                    ║
║  Phase 2: Creation (JSON diagrams)                            ║
║  Phase 3: Iteration (visual feedback loop)                    ║
╚═══════════════════════════════════════════════════════════════╝

Step 2: Validate Input

Confirm the user's request describes something to visualize. If unclear, ask for clarification.

Step 3: Research Decision

Use AskUserQuestion to offer research options:

Would you like me to research before creating your diagram?

1. Codebase exploration - Examine existing patterns, UI components, navigation, infrastructure
2. Web research - Look up UX patterns, architecture best practices, design systems
3. Both - Comprehensive research from code and web sources
4. Skip - Go directly to interview questions

Step 4: Execute Research (if selected)

• Codebase: Launch Explore subagent with targeted queries (see references/research-protocol.md)
• Web: Use WebSearch for relevant patterns and best practices
• Save findings to .stacksketch/stacksketch-research.md

Step 5: Interview

Use AskUserQuestion to clarify requirements (see references/interview-protocol.md):

• Flow diagrams: Entry points, outcomes, decision points, state persistence
• Infrastructure: Entry point, databases, external services, data flow patterns
• UI mockups: Platform/viewport, screen count, layout structure, key components

Save transcript to .stacksketch/stacksketch-interview.md

Step 6: Synthesize Requirements

Create .stacksketch/stacksketch-spec.md summarizing:

• Diagram type(s) needed
• Key elements and relationships
• Visual preferences
• Out of scope items

Phase 2: Creation

Step 7: Determine Diagram Types

Based on requirements, create one or more diagrams:

• Flow: Navigation, state machines, decision trees, logic branches
• Infrastructure: Frontend, backend, database, cache, queue, external services
• UI Mockups: Web app viewports with components (desktop, laptop, tablet, mobile-web)

Step 8: Create JSON Files

Author StackSketch JSON following references/schema.md:

• Store in .stacksketch/ directory
• Use descriptive kebab-case filenames: user-dashboard.json, checkout-flow.json
• Include diagram.type in every file

Step 9: Validate Output

Ensure JSON is valid and complete:

• All required fields present
• Node IDs are unique
• Edge references valid node IDs
• Positions don't overlap

Phase 3: Iteration (Visual Feedback Loop)

Step 10: Open Viewer

Open the diagram in the browser for visual review:

// Using Chrome DevTools MCP
mcp__chrome-devtools__new_page({
  url: `file://${process.cwd()}/skills/stack-sketch/viewer/index.html?file=.stacksketch/diagram-name.json`
})

// Or using Claude in Chrome
mcp__claude-in-chrome__navigate({
  url: `file://${process.cwd()}/skills/stack-sketch/viewer/index.html?file=.stacksketch/diagram-name.json`,
  tabId: currentTabId
})

Step 11: Take Screenshot

Capture the rendered diagram:

// Chrome DevTools
mcp__chrome-devtools__take_screenshot()

// Or Claude in Chrome
mcp__claude-in-chrome__computer({ action: 'screenshot', tabId: currentTabId })

Step 12: Show to User

Present the visual for user review. Ask:

• "Does this capture what you had in mind?"
• "Any elements missing or incorrectly positioned?"
• "Would you like any style changes?"

Step 13: Iterate

Based on feedback:

• Update JSON with minimal diffs (preserve stable IDs)
• Refresh viewer
• Take new screenshot
• Repeat until user is satisfied

Step 14: Finalize

Mark session complete:

• Update .stacksketch/PROGRESS.md with status
• Summarize created diagrams
• Offer to export or integrate into documentation

Session State Management

Track progress with files in .stacksketch/:

.stacksketch/
├── stacksketch-research.md      # Research findings (optional)
├── stacksketch-interview.md     # Q&A transcript
├── stacksketch-spec.md          # Synthesized requirements
├── {diagram-name}.json          # Generated diagrams
└── PROGRESS.md                  # Session tracking

Session Resumption

Diagram Types and Intent

• Flow: Navigation, state machines, decision trees, and logic branches
• Infrastructure: Frontend, backend, database, cache, queue, external services, and data flows
• UI Mockups: Web app viewports (desktop, laptop, tablet, mobile-web) with UI components

Authoring Rules

• Preserve stable id values for nodes, edges, and groups across iterations
• Use a grid (8 or 16) and avoid overlaps or edge crossings
• Prefer node.type for shape and node.kind for semantic role
• Keep label short; place long descriptions in data.notes
• Maintain one diagram per file, and avoid rewriting unrelated sections
• Use 2-space indentation and keep key ordering consistent

File Layout Defaults

• Store diagrams in .stacksketch/ unless the user requests a different location
• Use descriptive filenames: user-dashboard.json, checkout-flow.json, infra-map.json
• Include diagram.type in every file so the viewer can render correctly

Output Expectations

• Output valid JSON only when asked to generate or modify a diagram
• Do not output ASCII art
• When asked to describe a diagram, summarize key nodes/edges instead of pasting the full file

Logging Format

Log progress with timestamps:

[HH:MM] Phase 1: Discovery
[HH:MM] ├─ Research: codebase exploration complete
[HH:MM] ├─ Interview: 4 questions answered
[HH:MM] └─ Spec: requirements synthesized

[HH:MM] Phase 2: Creation
[HH:MM] ├─ Created: user-onboarding-flow.json (flow, 7 nodes, 6 edges)
[HH:MM] └─ Created: dashboard-mockup.json (ui, 12 components)

[HH:MM] Phase 3: Iteration
[HH:MM] ├─ Viewer opened, screenshot captured
[HH:MM] ├─ User feedback: adjust sidebar width
[HH:MM] └─ Updated: dashboard-mockup.json

References

• [Schema](./references/schema.md) - StackSketch JSON structure and field definitions
• [Examples](./references/examples.md) - Sample flow, infra, and UI mockup diagrams
• [Research Protocol](./references/research-protocol.md) - When and how to research before creating
• [Interview Protocol](./references/interview-protocol.md) - How to gather requirements through questions
• [Viewer](./viewer/index.html) - Self-contained diagram viewer (React-Flow based)