claude-flow

claude-flow

Generate interactive multi-diagram feature briefs as self-contained HTML files, viewable in the browser. Each brief contains tabbed diagrams (architecture, logic flow, optional state) with expand/collapse nodes and Catppuccin Mocha theming.

Trigger phrases

• /claude-flow:claude-flow
• "generate a flow diagram for..."
• "show me the architecture of..."
• "visualize this feature"
• "create a feature brief for..."
• "diagram this"

Input modes

1. Feature description — user provides a plain-language description of what they want to diagram
2. Existing code — user points at files or a directory; read the relevant code to understand the architecture

Output

Writes to: ~/github/claude-notes/claude-tools/previews/{slug}-flow.html

{slug} is derived from the feature field: lowercased, non-alphanumeric chars replaced by hyphens, consecutive hyphens collapsed. Example: "User OAuth Login!" → user-oauth-login.

---

Step 1: Generate FeatureBrief JSON

Generate a FeatureBrief object conforming to this schema:

interface FeatureBrief {
  version: "1"
  feature: string           // short feature name, used for slug
  diagrams: DiagramView[]
}
interface DiagramView {
  type: "architecture" | "flow" | "state"
  title: string
  description?: string
  layout?: "TB" | "LR"     // default TB; use LR for architecture
  nodes: FlowNode[]
  edges: FlowEdge[]
}
interface FlowNode {
  id: string
  type: "feature" | "action" | "decision" | "state" | "external" | "user" | "component"
  label: string
  description?: string
  sublabel?: string          // file path or tech detail (monospace)
  status?: "planned" | "in-progress" | "done" | "blocked"
  collapsed?: boolean        // false = start expanded; omit or true = start collapsed
  children?: FlowNode[]      // child nodes shown on expand
}
interface FlowEdge {
  id: string
  source: string
  target: string
  label?: string
  type?: "default" | "conditional" | "async" | "error"
}

Generation rules

• Always generate at minimum: one architecture diagram and one flow diagram
• Use multiple tabs liberally — each tab is a DiagramView. For features with major subsystems (e.g. frontend + backend, auth + data layer), add one tab per subsystem showing its internal architecture. The first tab is always the high-level overview showing only module-to-module connections; subsequent tabs drill into each module.
• Include a state diagram tab only when the feature introduces meaningful new stateful behavior (new entity lifecycle, UI state machine, session/connection states)
• Architecture diagram: use layout: "LR" (left-to-right); shows components, services, external systems
• Flow diagram: use layout: "TB" (top-to-bottom, default); shows request/logic flow with decision branches
• State diagram: use layout: "LR"; shows states and transitions
• Each DiagramView must have 3–20 top-level nodes (nodes without parents, visible before expand)
• decision nodes must have exactly 2 outbound edges, each with type: "conditional" and a non-empty label
• All FlowEdge source and target IDs must reference valid node IDs within the same DiagramView
• children render as inline sub-cards inside the parent card — use them for implementation detail (file paths, tech notes, sub-steps). They are never edge endpoints; all FlowEdge source/target IDs must be top-level nodes only
• A node starts collapsed (showing a [+N] expand button) unless collapsed: false; sub-cards within children have their own local expand toggle
• Keep the overview tab's node count low (5–10) so the high-level picture is immediately readable. Put detail in subsystem tabs, not in nested children.
• Node type guide:
  • feature — the primary feature being built
  • action — a processing step, handler, or function
  • decision — a branch point (exactly 2 outbound edges)
  • state — a named state in a state machine
  • external — external system, third-party service, or outside boundary
  • user — a human actor
  • component — a reusable component, module, or infrastructure piece

---

Step 2: Check template exists

TEMPLATE="$(dirname "$0")/references/template.html"
if [ ! -f "$TEMPLATE" ]; then
  echo "ERROR: Template not found. Rebuild with: cd ~/github/claude-tools/claude-flow/app && bun run build:template"
  exit 1
fi

Step 3: Inject JSON and write output

Derive the output slug and path, then inject via Python:

FEATURE_JSON='<the generated FeatureBrief JSON>'
SLUG=$(echo "$FEATURE_JSON" | uv run python -c "
import sys, re, json
d = json.load(sys.stdin)
name = d['feature'].lower()
slug = re.sub(r'-+', '-', re.sub(r'[^a-z0-9]+', '-', name)).strip('-')
print(slug)
")

OUTDIR="$HOME/github/claude-notes/claude-tools/previews"
mkdir -p "$OUTDIR"
OUTFILE="$OUTDIR/${SLUG}-flow.html"

uv run python -c "
import sys, json
template = open('$TEMPLATE').read()
raw = sys.stdin.read()
escaped = raw.replace('</script>', r'<\/script>')
out = template.replace('__FLOW_DATA_JSON__', escaped)
open('$OUTFILE', 'w').write(out)
print(f'Written: $OUTFILE')
" <<< "$FEATURE_JSON"

Step 4: Open in browser

powershell.exe -c "Start-Process '$(wslpath -w "$OUTFILE")'"

---

Step 5: Report and feedback loop

After opening, report:

Opened: {feature name}
Diagrams: architecture ({N} nodes), flow ({N} nodes)[, state ({N} nodes)]
Output: ~/github/claude-notes/claude-tools/previews/{slug}-flow.html

Then use AskUserQuestion to ask:

• Question: "How does the diagram look? Request changes or approve to finish."
• Options:
  • "Looks good — done" → end the loop, report the final output path
  • "Make changes" → proceed to re-generate
  • Other (user types specific changes) → incorporate feedback and regenerate

If user approves: End the loop. Output final path.

If user requests changes:

1. Incorporate the feedback into the FeatureBrief JSON
2. Re-inject into template, overwrite the same $OUTFILE
3. Re-open in browser
4. Report updated diagram summary
5. Ask again

Loop continues until the user explicitly approves or abandons.