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

code

╔═══════════════════════════════════════════════════════════════╗
║  📐 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:

code

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:

javascript

// 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:

javascript

// 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/:

code

.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

Files Found	Resume From
None	Step 2 (validate input)
stacksketch-research.md	Step 5 (interview)
+ stacksketch-interview.md	Step 7 (create diagrams)
+ *.json files	Step 10 (iteration)
+ PROGRESS.md with "complete"	Done

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:

code

[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 - StackSketch JSON structure and field definitions
•Examples - Sample flow, infra, and UI mockup diagrams
•Research Protocol - When and how to research before creating
•Interview Protocol - How to gather requirements through questions
•Viewer - Self-contained diagram viewer (React-Flow based)