@haposoft/cafekit 0.13.3 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/README.md +1 -2
  2. package/bin/lib/i18n.js +2 -2
  3. package/bin/lib/manifest.js +15 -0
  4. package/bin/lib/opencode-install.js +0 -14
  5. package/bin/phases/claude-runtime.js +4 -1
  6. package/bin/phases/claude-settings.js +38 -7
  7. package/package.json +1 -1
  8. package/src/claude/agents/ui-ux-designer.md +4 -4
  9. package/src/claude/hooks/__tests__/privacy-block.test.js +79 -0
  10. package/src/claude/hooks/__tests__/session-writeenv.test.js +68 -0
  11. package/src/claude/hooks/__tests__/spec-gate.test.js +270 -0
  12. package/src/claude/hooks/privacy-block.cjs +22 -2
  13. package/src/claude/hooks/session.cjs +5 -1
  14. package/src/claude/hooks/spec-gate.cjs +173 -0
  15. package/src/claude/hooks/spec-state.cjs +10 -17
  16. package/src/claude/hooks/task-scaffold-guard.cjs +4 -2
  17. package/src/claude/migration-manifest.json +5 -4
  18. package/src/claude/rules/skill-domain-routing.md +2 -3
  19. package/src/claude/rules/skill-workflow-routing.md +2 -3
  20. package/src/claude/rules/state-sync.md +4 -0
  21. package/src/claude/runtime.json +4 -0
  22. package/src/claude/scripts/validate-docs.cjs +4 -7
  23. package/src/claude/scripts/validate-spec-output.cjs +29 -9
  24. package/src/claude/settings/settings.json +4 -0
  25. package/src/claude/skills/ai-multimodal/.env.example +11 -13
  26. package/src/claude/skills/ai-multimodal/SKILL.md +1 -1
  27. package/src/claude/skills/ai-multimodal/references/audio-processing.md +25 -27
  28. package/src/claude/skills/ai-multimodal/references/video-analysis.md +23 -27
  29. package/src/claude/skills/ai-multimodal/references/vision-understanding.md +26 -26
  30. package/src/claude/skills/ai-multimodal/scripts/check_setup.py +1 -1
  31. package/src/claude/skills/ai-multimodal/scripts/gemini_batch_process.py +7 -9
  32. package/src/claude/skills/brainstorm/SKILL.md +1 -2
  33. package/src/claude/skills/docx/SKILL.md +1 -1
  34. package/src/claude/skills/frontend-design/SKILL.md +1 -1
  35. package/src/claude/skills/frontend-design/references/ai-multimodal-overview.md +4 -4
  36. package/src/claude/skills/frontend-design/references/analysis-techniques.md +3 -3
  37. package/src/claude/skills/frontend-design/references/asset-generation.md +2 -2
  38. package/src/claude/skills/frontend-design/references/design-extraction-overview.md +4 -4
  39. package/src/claude/skills/frontend-design/references/extraction-best-practices.md +3 -3
  40. package/src/claude/skills/frontend-design/references/technical-accessibility.md +1 -1
  41. package/src/claude/skills/frontend-design/references/technical-optimization.md +1 -1
  42. package/src/claude/skills/frontend-design/references/technical-overview.md +2 -2
  43. package/src/claude/skills/frontend-design/references/technical-workflows.md +6 -6
  44. package/src/claude/skills/frontend-design/references/visual-analysis-overview.md +3 -3
  45. package/src/claude/skills/inspect/SKILL.md +3 -3
  46. package/src/claude/skills/inspect/references/external-gemini-inspection.md +9 -9
  47. package/src/claude/skills/pdf/SKILL.md +1 -1
  48. package/src/claude/skills/pptx/SKILL.md +1 -1
  49. package/src/claude/skills/specs/SKILL.md +1 -1
  50. package/src/claude/skills/xlsx/SKILL.md +1 -1
  51. package/src/opencode/AGENTS.md +1 -2
  52. package/src/opencode/plugins/session.ts +2 -2
  53. package/src/opencode/plugins/spec-state.ts +244 -0
  54. package/src/opencode/plugins/task-scaffold-guard.ts +161 -0
  55. package/src/claude/scripts/browser-tool.cjs +0 -138
  56. package/src/claude/skills/generate-graph/LICENSE +0 -21
  57. package/src/claude/skills/generate-graph/README.md +0 -523
  58. package/src/claude/skills/generate-graph/SKILL.md +0 -429
  59. package/src/claude/skills/generate-graph/agentloop-core.svg +0 -101
  60. package/src/claude/skills/generate-graph/agents/openai.yaml +0 -4
  61. package/src/claude/skills/generate-graph/assets/samples/sample-style1-flat.png +0 -0
  62. package/src/claude/skills/generate-graph/assets/samples/sample-style2-dark.png +0 -0
  63. package/src/claude/skills/generate-graph/assets/samples/sample-style3-blueprint.png +0 -0
  64. package/src/claude/skills/generate-graph/assets/samples/sample-style4-notion.png +0 -0
  65. package/src/claude/skills/generate-graph/assets/samples/sample-style5-glass.png +0 -0
  66. package/src/claude/skills/generate-graph/assets/samples/sample-style6-claude.png +0 -0
  67. package/src/claude/skills/generate-graph/assets/samples/sample-style7-openai.png +0 -0
  68. package/src/claude/skills/generate-graph/fixtures/agent-memory-types-style4.json +0 -181
  69. package/src/claude/skills/generate-graph/fixtures/api-flow-style7.json +0 -40
  70. package/src/claude/skills/generate-graph/fixtures/mem0-style1.json +0 -297
  71. package/src/claude/skills/generate-graph/fixtures/microservices-style3.json +0 -64
  72. package/src/claude/skills/generate-graph/fixtures/multi-agent-style5.json +0 -45
  73. package/src/claude/skills/generate-graph/fixtures/system-architecture-style6.json +0 -48
  74. package/src/claude/skills/generate-graph/fixtures/tool-call-style2.json +0 -182
  75. package/src/claude/skills/generate-graph/package.json +0 -42
  76. package/src/claude/skills/generate-graph/references/icons.md +0 -281
  77. package/src/claude/skills/generate-graph/references/style-1-flat-icon.md +0 -108
  78. package/src/claude/skills/generate-graph/references/style-2-dark-terminal.md +0 -107
  79. package/src/claude/skills/generate-graph/references/style-3-blueprint.md +0 -113
  80. package/src/claude/skills/generate-graph/references/style-4-notion-clean.md +0 -94
  81. package/src/claude/skills/generate-graph/references/style-5-glassmorphism.md +0 -125
  82. package/src/claude/skills/generate-graph/references/style-6-claude-official.md +0 -209
  83. package/src/claude/skills/generate-graph/references/style-7-openai.md +0 -215
  84. package/src/claude/skills/generate-graph/references/style-diagram-matrix.md +0 -135
  85. package/src/claude/skills/generate-graph/references/svg-layout-best-practices.md +0 -100
  86. package/src/claude/skills/generate-graph/scripts/generate-diagram.sh +0 -157
  87. package/src/claude/skills/generate-graph/scripts/generate-from-template.py +0 -1556
  88. package/src/claude/skills/generate-graph/scripts/test-all-styles.sh +0 -135
  89. package/src/claude/skills/generate-graph/scripts/validate-svg.sh +0 -292
  90. package/src/claude/skills/generate-graph/templates/agent-architecture.svg +0 -28
  91. package/src/claude/skills/generate-graph/templates/architecture.svg +0 -23
  92. package/src/claude/skills/generate-graph/templates/comparison-matrix.svg +0 -14
  93. package/src/claude/skills/generate-graph/templates/data-flow.svg +0 -28
  94. package/src/claude/skills/generate-graph/templates/er-diagram.svg +0 -21
  95. package/src/claude/skills/generate-graph/templates/flowchart.svg +0 -21
  96. package/src/claude/skills/generate-graph/templates/sequence.svg +0 -20
  97. package/src/claude/skills/generate-graph/templates/state-machine.svg +0 -20
  98. package/src/claude/skills/generate-graph/templates/timeline.svg +0 -19
  99. package/src/claude/skills/generate-graph/templates/use-case.svg +0 -21
  100. package/src/claude/skills/impact-analysis/SKILL.md +0 -276
  101. package/src/claude/skills/impact-analysis/references/change-detection.md +0 -270
  102. package/src/claude/skills/impact-analysis/references/dependency-scouting.md +0 -338
  103. package/src/claude/skills/impact-analysis/references/edge-case-identification.md +0 -439
  104. package/src/claude/skills/impact-analysis/references/industry-techniques.md +0 -695
  105. package/src/claude/skills/impact-analysis/references/practical-techniques-guide.md +0 -753
  106. package/src/claude/skills/impact-analysis/references/project-detection.md +0 -704
  107. package/src/claude/skills/impact-analysis/references/react-native-customization.md +0 -508
  108. package/src/claude/skills/impact-analysis/references/report-template.md +0 -604
  109. package/src/claude/skills/impact-analysis/references/test-scenario-generation.md +0 -459
  110. package/src/claude/skills/impact-analysis/scripts/README.md +0 -476
  111. package/src/claude/skills/impact-analysis/scripts/ast-analyze.js +0 -403
  112. package/src/claude/skills/impact-analysis/scripts/calculate-risk.js +0 -475
  113. package/src/claude/skills/impact-analysis/scripts/find-dependencies.sh +0 -202
  114. package/src/claude/skills/impact-analysis/scripts/run-analysis.sh +0 -312
@@ -1,429 +0,0 @@
1
- ---
2
- name: hapo:generate-graph
3
- description: >-
4
- user-invocable: true
5
- when_to_use: "Invoke to build a queryable graph or diagram from code or data."
6
- category: utilities
7
- keywords: [graph, visualization, diagram, analysis]
8
- metadata:
9
- author: haposoft
10
- version: "1.0.0"
11
- ---
12
- # Generate Graph
13
-
14
- Generate production-quality SVG technical diagrams exported as PNG via `rsvg-convert`.
15
-
16
- ## CafeKit Integration
17
-
18
- This skill is bundled with CafeKit and is expected to live under:
19
-
20
- ```bash
21
- .claude/skills/generate-graph
22
- ```
23
-
24
- Runtime prerequisites:
25
-
26
- ```bash
27
- python3
28
- rsvg-convert
29
- ```
30
-
31
- `rsvg-convert` is recommended for syntax validation and PNG export. If it is unavailable, you can still generate SVG output and skip PNG export.
32
-
33
- ## Helper Scripts (Recommended)
34
-
35
- Four helper scripts in `scripts/` directory provide stable SVG generation and validation:
36
-
37
- ### 1. `generate-diagram.sh` - Validate SVG + export PNG
38
- ```bash
39
- ./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg
40
- ```
41
- - Validates an existing SVG file
42
- - Exports PNG after validation
43
- - Example: `./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg`
44
-
45
- ### 2. `generate-from-template.py` - Create starter SVG from template
46
- ```bash
47
- python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}'
48
- ```
49
- - Loads a built-in SVG template
50
- - Renders nodes, arrows, and legend entries from JSON input
51
- - Escapes text content to keep output XML-valid
52
-
53
- ### 3. `validate-svg.sh` - Validate SVG syntax
54
- ```bash
55
- ./scripts/validate-svg.sh <svg-file>
56
- ```
57
- - Checks XML syntax
58
- - Verifies tag balance
59
- - Validates marker references
60
- - Checks attribute completeness
61
- - Validates path data
62
-
63
- ### 4. `test-all-styles.sh` - Batch test all styles
64
- ```bash
65
- ./scripts/test-all-styles.sh
66
- ```
67
- - Tests multiple diagram sizes
68
- - Validates all generated SVGs
69
- - Generates test report
70
-
71
- **When to use scripts:**
72
- - Use scripts when generating complex SVGs to avoid syntax errors
73
- - Scripts provide automatic validation and error reporting
74
- - Recommended for production diagrams
75
-
76
- **When to generate SVG directly:**
77
- - Simple diagrams with few elements
78
- - Quick prototypes
79
- - When you need full control over SVG structure
80
-
81
- ## Workflow (Always Follow This Order)
82
-
83
- 1. **Classify** the diagram type (see Diagram Types below)
84
- 2. **Extract structure** — identify layers, nodes, edges, flows, and semantic groups from user description
85
- 3. **Plan layout** — apply the layout rules for the diagram type
86
- 4. **Load style reference** — always load `references/style-1-flat-icon.md` unless user specifies another; load the matching `references/style-N.md` for exact color tokens and SVG patterns
87
- 5. **Map nodes to shapes** — use Shape Vocabulary below
88
- 6. **Check icon needs** — load `references/icons.md` for known products
89
- 7. **Write SVG** with adaptive strategy (see SVG Generation Strategy below)
90
- 8. **Validate**: Run `rsvg-convert file.svg -o /dev/null 2>&1` to check syntax
91
- 9. **Export PNG**: `rsvg-convert -w 1920 file.svg -o file.png`
92
- 10. **Report** the generated file paths
93
-
94
- ## Diagram Types & Layout Rules
95
-
96
- ### Architecture Diagram
97
- Nodes = services/components. Group into **horizontal layers** (top→bottom or left→right).
98
- - Typical layers: Client → Gateway/LB → Services → Data/Storage
99
- - Use `<rect>` dashed containers to group related services in the same layer
100
- - Arrow direction follows data/request flow
101
- - ViewBox: `0 0 960 600` standard, `0 0 960 800` for tall stacks
102
-
103
- ### Data Flow Diagram
104
- Emphasizes **what data moves where**. Focus on data transformation.
105
- - Label every arrow with the data type (e.g., "embeddings", "query", "context")
106
- - Use wider arrows (`stroke-width: 2.5`) for primary data paths
107
- - Dashed arrows for control/trigger flows
108
- - Color arrows by data category (not just Agent/RAG — use semantics)
109
-
110
- ### Flowchart / Process Flow
111
- Sequential decision/process steps.
112
- - Top-to-bottom preferred; left-to-right for wide flows
113
- - Diamond shapes for decisions, rounded rects for processes, parallelograms for I/O
114
- - Keep node labels short (≤3 words); put detail in sub-labels
115
- - Align nodes on a grid: x positions snap to 120px intervals, y to 80px
116
-
117
- ### Agent Architecture Diagram
118
- Shows how an AI agent reasons, uses tools, and manages memory.
119
- Key conceptual layers to always consider:
120
- - **Input layer**: User, query, trigger
121
- - **Agent core**: LLM, reasoning loop, planner
122
- - **Memory layer**: Short-term (context window), Long-term (vector/graph DB), Episodic
123
- - **Tool layer**: Tool calls, APIs, search, code execution
124
- - **Output layer**: Response, action, side-effects
125
- Use cyclic arrows (loop arcs) to show iterative reasoning. Separate memory types visually.
126
-
127
- ### Memory Architecture Diagram (Mem0, MemGPT-style)
128
- Specialized agent diagram focused on memory operations.
129
- - Show memory **write path** and **read path** separately (different arrow colors)
130
- - Memory tiers: Working Memory → Short-term → Long-term → External Store
131
- - Label memory operations: `store()`, `retrieve()`, `forget()`, `consolidate()`
132
- - Use stacked rects or layered cylinders for storage tiers
133
-
134
- ### Sequence Diagram
135
- Time-ordered message exchanges between participants.
136
- - Participants as vertical **lifelines** (top labels + vertical dashed lines)
137
- - Messages as horizontal arrows between lifelines, top-to-bottom time order
138
- - Activation boxes (thin filled rects on lifeline) show active processing
139
- - Group with `<rect>` loop/alt frames with label in top-left corner
140
- - ViewBox height = 80 + (num_messages × 50)
141
-
142
- ### Comparison / Feature Matrix
143
- Side-by-side comparison of approaches, systems, or components.
144
- - Column headers = systems, row headers = attributes
145
- - Row height: 40px; column width: min 120px; header row height: 50px
146
- - Checked cell: tinted background (e.g. `#dcfce7`) + `✓` checkmark; unsupported: `#f9fafb` fill
147
- - Alternating row fills (`#f9fafb` / `#ffffff`) for readability
148
- - Max readable columns: 5; beyond that, split into two diagrams
149
-
150
- ### Timeline / Gantt
151
- Horizontal time axis showing durations, phases, and milestones.
152
- - X-axis = time (weeks/months/quarters); Y-axis = items/tasks/phases
153
- - Bars: rounded rects, colored by category, labeled inside or beside
154
- - Milestone markers: diamond or filled circle at specific x position with label above
155
- - ViewBox: `0 0 960 400` typical; wider for many time periods: `0 0 1200 400`
156
-
157
- ### Mind Map / Concept Map
158
- Radial layout from central concept.
159
- - Central node at `cx=480, cy=280`
160
- - First-level branches: evenly distributed around center (360/N degrees)
161
- - Second-level branches: branch off first-level at 30-45° offset
162
- - Use curved `<path>` with cubic bezier for branches, not straight lines
163
-
164
- ### Class Diagram (UML)
165
- Static structure showing classes, attributes, methods, and relationships.
166
- - **Class box**: 3-compartment rect (name / attributes / methods), min width 160px
167
- - Top compartment: class name, bold, centered (abstract = *italic*)
168
- - Middle: attributes with visibility (`+` public, `-` private, `#` protected)
169
- - Bottom: method signatures, same visibility notation
170
- - **Relationships**:
171
- - Inheritance (extends): solid line + hollow triangle arrowhead, child → parent
172
- - Implementation (interface): dashed line + hollow triangle, class → interface
173
- - Association: solid line + open arrowhead, label with multiplicity (1, 0..*, 1..*)
174
- - Aggregation: solid line + hollow diamond on container side
175
- - Composition: solid line + filled diamond on container side
176
- - Dependency: dashed line + open arrowhead
177
- - **Interface**: `<<interface>>` stereotype above name, or circle/lollipop notation
178
- - **Enum**: compartment rect with `<<enumeration>>` stereotype, values in bottom
179
- - Layout: parent classes top, children below; interfaces to the left/right of implementors
180
- - ViewBox: `0 0 960 600` standard; `0 0 960 800` for deep hierarchies
181
-
182
- ### Use Case Diagram (UML)
183
- System functionality from user perspective.
184
- - **Actor**: stick figure (circle head + body line) placed outside system boundary
185
- - Label below figure, 13-14px
186
- - Primary actors on left, secondary/supporting on right
187
- - **Use case**: ellipse with label centered inside, min 140×60px
188
- - Keep names verb phrases: "Create Order", "Process Payment"
189
- - **System boundary**: large rect with dashed border + system name in top-left
190
- - **Relationships**:
191
- - Include: dashed arrow `<<include>>` from base to included use case
192
- - Extend: dashed arrow `<<extend>>` from extension to base use case
193
- - Generalization: solid line + hollow triangle (specialized → general)
194
- - Layout: system boundary centered, actors outside, use cases inside
195
- - ViewBox: `0 0 960 600` standard
196
-
197
- ### State Machine Diagram (UML)
198
- Lifecycle states and transitions of an entity.
199
- - **State**: rounded rect with state name, min 120×50px
200
- - Internal activities: small text `entry/ action`, `exit/ action`, `do/ activity`
201
- - **Initial state**: filled black circle (r=8), one outgoing arrow
202
- - **Final state**: filled circle (r=8) inside hollow circle (r=12)
203
- - **Choice**: small hollow diamond, guard labels on outgoing arrows `[condition]`
204
- - **Transition**: arrow with optional label `event [guard] / action`
205
- - Guard conditions in square brackets
206
- - Actions after `/`
207
- - **Composite/nested state**: larger rect containing sub-states, with name tab
208
- - **Fork/join**: thick horizontal or vertical black bar (synchronization)
209
- - Layout: initial state top-left, final state bottom-right, flow top-to-bottom
210
- - ViewBox: `0 0 960 600` standard
211
-
212
- ### ER Diagram (Entity-Relationship)
213
- Database schema and data relationships.
214
- - **Entity**: rect with entity name in header (bold), attributes below
215
- - Primary key attribute: underlined
216
- - Foreign key: italic or marked with (FK)
217
- - Min width: 160px; attribute font-size: 12px
218
- - **Relationship**: diamond shape on connecting line
219
- - Label inside diamond: "has", "belongs to", "enrolls in"
220
- - Cardinality labels near entity: `1`, `N`, `0..1`, `0..*`, `1..*`
221
- - **Weak entity**: double-bordered rect with double diamond relationship
222
- - **Associative entity**: diamond + rect hybrid (rect with diamond inside)
223
- - Line style: solid for identifying relationships, dashed for non-identifying
224
- - Layout: entities in 2-3 rows, relationships between related entities
225
- - ViewBox: `0 0 960 600` standard; wider `0 0 1200 600` for many entities
226
-
227
- ### Network Topology
228
- Physical or logical network infrastructure.
229
- - **Devices**: icon-like rects or rounded rects
230
- - Router: circle with cross arrows
231
- - Switch: rect with arrow grid
232
- - Server: stacked rect (rack icon)
233
- - Firewall: brick-pattern rect or shield shape
234
- - Load Balancer: horizontal split rect with arrows
235
- - Cloud: cloud path (overlapping arcs)
236
- - **Connections**: lines between device centers
237
- - Ethernet/wired: solid line, label bandwidth
238
- - Wireless: dashed line with WiFi symbol
239
- - VPN: dashed line with lock icon
240
- - **Subnets/Zones**: dashed rect containers with zone label (DMZ, Internal, External)
241
- - **Labels**: device hostname + IP below, 12-13px
242
- - Layout: tiered top-to-bottom (Internet → Edge → Core → Access → Endpoints)
243
- - ViewBox: `0 0 960 600` standard
244
-
245
- ## UML Coverage Map
246
-
247
- Full mapping of UML 14 diagram types to supported diagram types:
248
-
249
- | UML Diagram | Supported As | Notes |
250
- |-------------|-------------|-------|
251
- | Class | Class Diagram | Full UML notation |
252
- | Component | Architecture Diagram | Use colored fills per component type |
253
- | Deployment | Architecture Diagram | Add node/instance labels |
254
- | Package | Architecture Diagram | Use dashed grouping containers |
255
- | Composite Structure | Architecture Diagram | Nested rects within components |
256
- | Object | Class Diagram | Instance boxes with underlined name |
257
- | Use Case | Use Case Diagram | Full actor/ellipse/relationship |
258
- | Activity | Flowchart / Process Flow | Add fork/join bars |
259
- | State Machine | State Machine Diagram | Full UML notation |
260
- | Sequence | Sequence Diagram | Add alt/opt/loop frames |
261
- | Communication | — | Approximate with Sequence (swap axes) |
262
- | Timing | Timeline | Adapt time axis |
263
- | Interaction Overview | Flowchart | Combine activity + sequence fragments |
264
- | ER Diagram | ER Diagram | Chen/Crow's foot notation |
265
-
266
- ## Shape Vocabulary
267
-
268
- Map semantic concepts to consistent shapes across all diagram types:
269
-
270
- | Concept | Shape | Notes |
271
- |---------|-------|-------|
272
- | User / Human | Circle + body path | Stick figure or avatar |
273
- | LLM / Model | Rounded rect with brain/spark icon or gradient fill | Use accent color |
274
- | Agent / Orchestrator | Hexagon or rounded rect with double border | Signals "active controller" |
275
- | Memory (short-term) | Rounded rect, dashed border | Ephemeral = dashed |
276
- | Memory (long-term) | Cylinder (database shape) | Persistent = solid cylinder |
277
- | Vector Store | Cylinder with grid lines inside | Add 3 horizontal lines |
278
- | Graph DB | Circle cluster (3 overlapping circles) | |
279
- | Tool / Function | Gear-like rect or rect with wrench icon | |
280
- | API / Gateway | Hexagon (single border) | |
281
- | Queue / Stream | Horizontal tube (pipe shape) | |
282
- | File / Document | Folded-corner rect | |
283
- | Browser / UI | Rect with 3-dot titlebar | |
284
- | Decision | Diamond | Flowcharts only |
285
- | Process / Step | Rounded rect | Standard box |
286
- | External Service | Rect with cloud icon or dashed border | |
287
- | Data / Artifact | Parallelogram | I/O in flowcharts |
288
-
289
- ## Arrow Semantics
290
-
291
- Always assign arrow meaning, not just color:
292
-
293
- | Flow Type | Color | Stroke | Dash | Meaning |
294
- |-----------|-------|--------|------|---------|
295
- | Primary data flow | blue `#2563eb` | 2px solid | none | Main request/response path |
296
- | Control / trigger | orange `#ea580c` | 1.5px solid | none | One system triggering another |
297
- | Memory read | green `#059669` | 1.5px solid | none | Retrieval from store |
298
- | Memory write | green `#059669` | 1.5px | `5,3` | Write/store operation |
299
- | Async / event | gray `#6b7280` | 1.5px | `4,2` | Non-blocking, event-driven |
300
- | Embedding / transform | purple `#7c3aed` | 1px solid | none | Data transformation |
301
- | Feedback / loop | purple `#7c3aed` | 1.5px curved | none | Iterative reasoning loop |
302
-
303
- Always include a **legend** when 2+ arrow types are used.
304
-
305
- ## Layout Rules & Validation
306
-
307
- **Spacing**:
308
- - Same-layer nodes: 80px horizontal, 120px vertical between layers
309
- - Canvas margins: 40px minimum, 60px between node edges
310
- - Snap to 8px grid: horizontal 120px intervals, vertical 120px intervals
311
-
312
- **Arrow Labels** (CRITICAL):
313
- - MUST have background rect: `<rect fill="canvas_bg" opacity="0.95"/>` with 4px horizontal, 2px vertical padding
314
- - Place mid-arrow, ≤3 words, stagger by 15-20px when multiple arrows converge
315
- - Maintain 10px safety distance from nodes
316
-
317
- **Arrow Routing**:
318
- - Prefer orthogonal (L-shaped) paths to minimize crossings
319
- - Anchor arrows on component edges, not geometric centers
320
- - Route around dense node clusters, use different y-offsets for parallel arrows
321
- - Jump-over arcs (5px radius) for unavoidable crossings
322
-
323
- **Line Overlap Prevention** (CRITICAL - most common bug on Codex):
324
- When two arrows must cross each other, ALWAYS use jump-over arcs to prevent visual overlap:
325
- - Crossing horizontal arrows: add a small semicircle arc (radius 5px, stroke same color as arrow, fill none) that "jumps over" the other line
326
- - SVG pattern for jump-over: use a white/matching-background arc on the lower layer, then draw the upper arc on top
327
- - Multiple crossings: stagger arc radii (5px, 7px, 9px) so arcs don't overlap each other
328
- - Never let two arrows' straight-line segments cross without a jump-over arc
329
-
330
- **Validation Checklist** (run before finalizing):
331
- 1. **Arrow-Component Collision**: Arrows MUST NOT pass through component interiors (route around with orthogonal paths)
332
- 2. **Text Overflow**: All text MUST fit with 8px padding (estimate: `text.length × 7px ≤ shape_width - 16px`)
333
- 3. **Arrow-Text Alignment**: Arrow endpoints MUST connect to shape edges (not floating); all arrow labels MUST have background rects
334
- 4. **Container Discipline**: Prefer arrows entering and leaving section containers through open gaps between components, not through inner component bodies
335
-
336
- ## SVG Technical Rules
337
-
338
- - ViewBox: `0 0 960 600` default; `0 0 960 800` tall; `0 0 1200 600` wide
339
- - Fonts: embed via `<style>font-family: ...</style>` — no external `@import` (breaks rsvg-convert)
340
- - `<defs>`: arrow markers, gradients, filters, clip paths
341
- - Text: minimum 12px, prefer 13-14px labels, 11px sub-labels, 16-18px titles
342
- - All arrows: `<marker>` with `markerEnd`, sized `markerWidth="10" markerHeight="7"`
343
- - Drop shadows: `<feDropShadow>` in `<filter>`, apply sparingly (key nodes only)
344
- - Curved paths: use `M x1,y1 C cx1,cy1 cx2,cy2 x2,y2` cubic bezier for loops/feedback arrows
345
- - Clip content: use `<clipPath>` if text might overflow a node box
346
-
347
- ## SVG Generation & Error Prevention
348
-
349
- **MANDATORY: Python List Method** (ALWAYS use this):
350
- ```python
351
- python3 << 'EOF'
352
- lines = []
353
- lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')
354
- lines.append(' <defs>')
355
- # ... each line separately
356
- lines.append('</svg>')
357
-
358
- with open('/path/to/output.svg', 'w') as f:
359
- f.write('\n'.join(lines))
360
- print("SVG generated successfully")
361
- EOF
362
- ```
363
-
364
- **Why mandatory**: Prevents character truncation, typos, and syntax errors. Each line is independent and easy to verify.
365
-
366
- **Pre-Tool-Call Checklist** (CRITICAL - use EVERY time):
367
- 1. ✅ Can I write out the COMPLETE command/content right now?
368
- 2. ✅ Do I have ALL required parameters ready?
369
- 3. ✅ Have I checked for syntax errors in my prepared content?
370
-
371
- **If ANY answer is NO**: STOP. Do NOT call the tool. Prepare the content first.
372
-
373
- **Error Recovery Protocol**:
374
- - **First error**: Analyze root cause, apply targeted fix
375
- - **Second error**: Switch method entirely (Python list → chunked generation)
376
- - **Third error**: STOP and report to user - do NOT loop endlessly
377
- - **Never**: Retry the same failing command or call tools with empty parameters
378
-
379
- **Validation** (run after generation):
380
- ```bash
381
- rsvg-convert file.svg -o /tmp/test.png 2>&1 && echo "✓ Valid" && rm /tmp/test.png
382
- ```
383
-
384
- **If using `generate-from-template.py`**:
385
- - Prefer `source` / `target` node ids in arrow JSON so the generator can snap to node edges
386
- - Keep `x1,y1,x2,y2` as hints or fallback coordinates, not the main routing primitive
387
- - Let the generator choose orthogonal routes; avoid hardcoding center-to-center straight lines unless the path is guaranteed clear
388
-
389
- **Common Syntax Errors to Avoid**:
390
- - ❌ `yt-anchor` → ✅ `y="60" text-anchor="middle"`
391
- - ❌ `x="390` (missing y) → ✅ `x="390" y="250"`
392
- - ❌ `fill=#fff` → ✅ `fill="#ffffff"`
393
- - ❌ `marker-end=` → ✅ `marker-end="url(#arrow)"`
394
- - ❌ `L 29450` → ✅ `L 290,220`
395
- - ❌ Missing `</svg>` at end
396
-
397
- ## Output
398
-
399
- - **Default**: `./[derived-name].svg` and `./[derived-name].png` in current directory
400
- - **Custom**: user specifies path with `--output /path/` or `输出到 /path/`
401
- - **PNG export**: `rsvg-convert -w 1920 file.svg -o file.png` (1920px = 2x retina)
402
-
403
- ## Styles
404
-
405
- | # | Name | Background | Best For |
406
- |---|------|-----------|----------|
407
- | 1 | **Flat Icon** (default) | White | Blogs, docs, presentations |
408
- | 2 | **Dark Terminal** | `#0f0f1a` | GitHub, dev articles |
409
- | 3 | **Blueprint** | `#0a1628` | Architecture docs |
410
- | 4 | **Notion Clean** | White, minimal | Notionnce |
411
- | 5 | **Glassmorphism** | Dark gradient | Product sites, keynotes |
412
- | 6 | **Claude Official** | Warm cream `#f8f6f3` | Anthropic-style diagrams |
413
- | 7 | **OpenAI Official** | Pure white `#ffffff` | OpenAI-style diagrams |
414
-
415
- Load `references/style-N.md` for exact color tokens and SVG patterns.
416
-
417
- ## Style Selection
418
-
419
- **Default**: Style 1 (Flat Icon) for most diagrams. Load `references/style-diagram-matrix.md` for detailed style-to-diagram-type recommendations.
420
-
421
- These patterns appear frequently — internalize them:
422
-
423
- **RAG Pipeline**: Query → Embed → VectorSearch → Retrieve → Augment → LLM → Response
424
- **Agentic RAG**: adds Agent loop with Tool use between Query and LLM
425
- **Agentic Search**: Query → Planner → [Search Tool / Calculator / Code] → Synthesizer → Response
426
- **Mem0 / Memory Layer**: Input → Memory Manager → [Write: VectorDB + GraphDB] / [Read: Retrieve+Rank] → Context
427
- **Agent Memory Types**: Sensory (raw input) → Working (context window) → Episodic (past interactions) → Semantic (facts) → Procedural (skills)
428
- **Multi-Agent**: Orchestrator → [SubAgent A / SubAgent B / SubAgent C] → Aggregator → Output
429
- **Tool Call Flow**: LLM → Tool Selector → Tool Execution → Result Parser → LLM (loop)
@@ -1,101 +0,0 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">
2
- <defs>
3
- <marker id="arrowBlue" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
4
- <polygon points="0 0, 10 3.5, 0 7" fill="#2563eb"/>
5
- </marker>
6
- <marker id="arrowPurple" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
7
- <polygon points="0 0, 10 3.5, 0 7" fill="#7c3aed"/>
8
- </marker>
9
- <marker id="arrowGreen" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
10
- <polygon points="0 0, 10 3.5, 0 7" fill="#059669"/>
11
- </marker>
12
- <marker id="arrowOrange" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
13
- <polygon points="0 0, 10 3.5, 0 7" fill="#ea580c"/>
14
- </marker>
15
- </defs>
16
- <style>
17
- text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
18
- .title { font-size: 24px; font-weight: 700; fill: #1e293b; }
19
- .node-label { font-size: 16px; font-weight: 600; fill: #1e293b; }
20
- .sub-label { font-size: 13px; font-weight: 400; fill: #64748b; }
21
- .arrow-label { font-size: 12px; font-weight: 400; fill: #475569; }
22
- </style>
23
- <rect width="960" height="700" fill="#ffffff"/>
24
- <text x="480" y="50" text-anchor="middle" class="title">AgentLoop Core Architecture</text>
25
-
26
- <!-- Input Layer -->
27
- <circle cx="480" cy="120" r="35" fill="#dbeafe" stroke="#2563eb" stroke-width="2.5"/>
28
- <text x="480" y="118" text-anchor="middle" class="node-label">User</text>
29
- <text x="480" y="135" text-anchor="middle" class="sub-label">Input</text>
30
-
31
- <!-- Agent Core -->
32
- <rect x="360" y="200" width="240" height="100" rx="12" fill="#f3e8ff" stroke="#7c3aed" stroke-width="3"/>
33
- <text x="480" y="235" text-anchor="middle" class="node-label">Agent Loop</text>
34
- <text x="480" y="255" text-anchor="middle" class="sub-label">Reasoning Engine</text>
35
- <text x="480" y="275" text-anchor="middle" class="sub-label">Plan → Act → Observe</text>
36
-
37
- <!-- Memory Layer -->
38
- <rect x="100" y="220" width="180" height="60" rx="8" fill="#dcfce7" stroke="#059669" stroke-width="2.5" stroke-dasharray="5,3"/>
39
- <text x="190" y="245" text-anchor="middle" class="node-label">Short-term</text>
40
- <text x="190" y="265" text-anchor="middle" class="sub-label">Context Window</text>
41
-
42
- <ellipse cx="190" cy="400" rx="80" ry="50" fill="#dcfce7" stroke="#059669" stroke-width="2.5"/>
43
- <text x="190" y="395" text-anchor="middle" class="node-label">Long-term</text>
44
- <text x="190" y="415" text-anchor="middle" class="sub-label">Vector Store</text>
45
-
46
- <!-- Tool Layer -->
47
- <rect x="680" y="220" width="160" height="60" rx="8" fill="#fed7aa" stroke="#ea580c" stroke-width="2.5"/>
48
- <text x="760" y="245" text-anchor="middle" class="node-label">Tools</text>
49
- <text x="760" y="265" text-anchor="middle" class="sub-label">Functions</text>
50
-
51
- <!-- Output Layer -->
52
- <rect x="390" y="500" width="180" height="70" rx="8" fill="#dbeafe" stroke="#2563eb" stroke-width="2.5"/>
53
- <text x="480" y="525" text-anchor="middle" class="node-label">Response</text>
54
- <text x="480" y="545" text-anchor="middle" class="sub-label">Action / Output</text>
55
-
56
- <!-- Arrows -->
57
- <line x1="480" y1="155" x2="480" y2="200" stroke="#2563eb" stroke-width="2" marker-end="url(#arrowBlue)"/>
58
- <rect x="455" y="168" width="50" height="18" fill="#ffffff" opacity="0.95"/>
59
- <text x="480" y="180" text-anchor="middle" class="arrow-label">query</text>
60
-
61
- <path d="M 360,250 L 280,250" stroke="#059669" stroke-width="2" marker-end="url(#arrowGreen)"/>
62
- <rect x="295" y="237" width="50" height="18" fill="#ffffff" opacity="0.95"/>
63
- <text x="320" y="249" text-anchor="middle" class="arrow-label">read</text>
64
-
65
- <path d="M 280,250 L 360,250" stroke="#059669" stroke-width="2" stroke-dasharray="5,3" marker-end="url(#arrowGreen)"/>
66
- <rect x="297" y="257" width="50" height="18" fill="#ffffff" opacity="0.95"/>
67
- <text x="320" y="269" text-anchor="middle" class="arrow-label">write</text>
68
-
69
- <path d="M 600,250 L 680,250" stroke="#ea580c" stroke-width="2" marker-end="url(#arrowOrange)"/>
70
- <rect x="615" y="237" width="50" height="18" fill="#ffffff" opacity="0.95"/>
71
- <text x="640" y="249" text-anchor="middle" class="arrow-label">call</text>
72
-
73
- <path d="M 680,250 L 600,250" stroke="#ea580c" stroke-width="2" marker-end="url(#arrowOrange)"/>
74
- <rect x="615" y="257" width="55" height="18" fill="#ffffff" opacity="0.95"/>
75
- <text x="642" y="269" text-anchor="middle" class="arrow-label">result</text>
76
-
77
- <line x1="480" y1="300" x2="480" y2="500" stroke="#2563eb" stroke-width="2" marker-end="url(#arrowBlue)"/>
78
- <rect x="445" y="390" width="70" height="18" fill="#ffffff" opacity="0.95"/>
79
- <text x="480" y="402" text-anchor="middle" class="arrow-label">generate</text>
80
-
81
- <path d="M 240,380 Q 240,320 360,280" stroke="#059669" stroke-width="1.5" marker-end="url(#arrowGreen)"/>
82
- <rect x="265" y="317" width="60" height="18" fill="#ffffff" opacity="0.95"/>
83
- <text x="295" y="329" text-anchor="middle" class="arrow-label">retrieve</text>
84
-
85
- <path d="M 420,300 Q 420,450 390,520" stroke="#7c3aed" stroke-width="2" marker-end="url(#arrowPurple)"/>
86
- <rect x="365" y="400" width="60" height="18" fill="#ffffff" opacity="0.95"/>
87
- <text x="395" y="412" text-anchor="middle" class="arrow-label">feedback</text>
88
-
89
- <!-- Legend -->
90
- <line x1="750" y1="90" x2="780" y2="90" stroke="#2563eb" stroke-width="2" marker-end="url(#arrowBlue)"/>
91
- <text x="790" y="95" class="arrow-label">Data Flow</text>
92
-
93
- <line x1="750" y1="115" x2="780" y2="115" stroke="#059669" stroke-width="2" marker-end="url(#arrowGreen)"/>
94
- <text x="790" y="120" class="arrow-label">Memory</text>
95
-
96
- <line x1="750" y1="140" x2="780" y2="140" stroke="#ea580c" stroke-width="2" marker-end="url(#arrowOrange)"/>
97
- <text x="790" y="145" class="arrow-label">Tool Call</text>
98
-
99
- <line x1="750" y1="165" x2="780" y2="165" stroke="#7c3aed" stroke-width="2" marker-end="url(#arrowPurple)"/>
100
- <text x="790" y="170" class="arrow-label">Feedback Loop</text>
101
- </svg>
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: "Fireworks Tech Graph"
3
- short_description: "Generate polished SVG and PNG technical diagrams"
4
- default_prompt: "Turn the user's system or workflow description into a polished SVG diagram and export a PNG."