Create Glyph
R pictogram glyphs → skill/agent/team icons in viz/. Pure-ggplot2 fn on 100x100 → neon glow → transparent WebP.
Use When
- New skill/agent/team needs icon
- Existing glyph needs replace/redesign
- Batch-create for new domain
- Prototype visual metaphors
In
- Required: Type —
skill, agent, team
- Required: Entity ID (
create-glyph, mystic, r-package-review) + domain (skills)
- Required: Visual concept
- Optional: Reference glyph (complexity calibration)
- Optional: Custom
--glow-sigma (def: 4)
Do
Step 1: Concept
- Read entity source:
- Skills:
skills/<id>/SKILL.md
- Agents:
agents/<id>.md
- Teams:
teams/<id>.md
- Metaphor type:
- Literal: flask→experiment, shield→security
- Abstract: arrows→merge, spirals→iterate
- Composite: 2-3 simple shapes (doc + pen)
- Complexity ref:
Complexity Tiers:
+----------+--------+-------------------------------------------+
| Tier | Layers | Examples |
+----------+--------+-------------------------------------------+
| Simple | 2 | glyph_flame, glyph_heartbeat |
| Moderate | 3-5 | glyph_document, glyph_experiment_flask |
| Complex | 6+ | glyph_ship_wheel, glyph_bridge_cpp |
+----------+--------+-------------------------------------------+
- Fn name:
glyph_<descriptive_name> (snake_case, unique)
Got: Mental sketch, 2-6 planned layers.
If err: Too abstract → concrete related. Check existing in same domain.
Step 2: Compose
Write R fn → ggplot2 layers.
Signature (immutable):
glyph_<name> <- function(cx, cy, s, col, bright) {
# cx, cy = center coordinates (50, 50 on 100x100 canvas)
# s = scale factor (1.0 = fill ~70% of canvas)
# col = domain color hex (e.g., "#ff88dd" for design)
# bright = brightened variant of col (auto-computed by renderer)
# Returns: list() of ggplot2 layers
}
Apply * s to ALL dims:
r <- 20 * s # radius
hw <- 15 * s # half-width
lw <- .lw(s) # line width (default base 2.5)
lw_thin <- .lw(s, 1.2) # thinner line width
Geometry primitives:
| Geometry |
Usage |
ggplot2::geom_polygon(data, .aes(x, y), ...) |
Filled shapes |
ggplot2::geom_path(data, .aes(x, y), ...) |
Open lines/curves |
ggplot2::geom_segment(data, .aes(x, xend, y, yend), ...) |
Segments, arrows |
ggplot2::geom_rect(data, .aes(xmin, xmax, ymin, ymax), ...) |
Rects |
ggforce::geom_circle(data, .aes(x0, y0, r), ...) |
Circles |
Color strategy:
Alpha Guide:
+----------------------+------------+--------------------------+
| Purpose | Alpha | Example |
+----------------------+------------+--------------------------+
| Large fill (body) | 0.08-0.15 | hex_with_alpha(col, 0.1) |
| Medium fill (accent) | 0.15-0.25 | hex_with_alpha(col, 0.2) |
| Small fill (detail) | 0.25-0.35 | hex_with_alpha(bright, 0.3) |
| Outline stroke | 1.0 | color = bright |
| Secondary stroke | 1.0 | color = col |
| No fill | --- | fill = NA |
+----------------------+------------+--------------------------+
Return flat list() → renderer wraps each w/ glow
Place fn in right primitives file:
- Skills: domain-grouped across 19 files:
primitives.R — bushcraft, compliance, containerization, data-serialization, defensive
primitives_2.R — devops, general, git, mcp-integration
primitives_3.R — mlops, observability, PM, r-packages, reporting, review, web-dev, esoteric, design
primitives_4.R through primitives_19.R for newer
- Agents:
viz/R/agent_primitives.R
- Teams:
viz/R/team_primitives.R
Got: Working R fn → list of 2-6 layers.
If err: ggforce::geom_circle err → install ggforce. Coords off → canvas 100x100, (0,0) bottom-left. Test:
source("viz/R/utils.R"); source("viz/R/primitives.R") # etc.
layers <- glyph_<name>(50, 50, 1.0, "#ff88dd", "#ffa8f0")
p <- ggplot2::ggplot() + ggplot2::coord_fixed(xlim=c(0,100), ylim=c(0,100)) +
ggplot2::theme_void()
for (l in layers) p <- p + l
print(p)
Step 3: Register
Map entity → glyph.
Skills:
- Open
viz/R/glyphs.R
- Find domain section comment (
# -- design (3))
- Alphabetical in domain block:
"skill-id" = "glyph_function_name",
- Update count comment if applicable
Agents:
- Open
viz/R/agent_glyphs.R
- Alphabetical in
AGENT_GLYPHS:"agent-id" = "glyph_function_name",
Teams:
Open viz/R/team_glyphs.R
Alphabetical in TEAM_GLYPHS:
"team-id" = "glyph_function_name",
Verify no dup ID
Got: *_GLYPHS list has new mapping.
If err: "No glyph mapped" → check ID exact match vs manifest + registry.
Step 4: Manifest
Register icon.
Skills: viz/data/icon-manifest.json
{
"skillId": "skill-id",
"domain": "domain-name",
"prompt": "<domain basePrompt>, <descriptors>, dark background, vector art",
"seed": <next_seed>,
"path": "public/icons/cyberpunk/<domain>/<skill-id>.webp",
"status": "pending"
}
Agents: viz/data/agent-icon-manifest.json
{
"agentId": "agent-id",
"prompt": "<agent-specific descriptors>, dark background, vector art",
"seed": <next_seed>,
"path": "public/icons/cyberpunk/agents/<agent-id>.webp",
"status": "pending"
}
Teams: viz/data/team-icon-manifest.json
{
"teamId": "team-id",
"prompt": "<team-specific descriptors>, dark background, vector art",
"seed": <next_seed>,
"path": "public/icons/cyberpunk/teams/<team-id>.webp",
"status": "pending"
}
Got: Valid JSON, entry among type siblings.
If err: Validate syntax. Common: trailing comma after last elem, missing quotes.
Step 5: Render
Run pipeline. Always build.sh → platform detect + R binary. See render-icon-pipeline.
# From project root — renders all palettes, standard + HD, skips existing icons
bash viz/build.sh --only <domain> --skip-existing # skills
bash viz/build.sh --type agent --only <id> --skip-existing # agents
bash viz/build.sh --type team --only <id> --skip-existing # teams
# Dry run first:
bash viz/build.sh --only <domain> --dry-run
build.sh = full pipeline (palette → data → manifest → render → terminal glyphs). Non-render steps +~10s but ensure current.
Out:
- Skills:
viz/public/icons/<palette>/<domain>/<skill-id>.webp
- Agents:
viz/public/icons/<palette>/agents/<agent-id>.webp
- Teams:
viz/public/icons/<palette>/teams/<team-id>.webp
Got: Log OK: <entity> (seed=XXXXX, XX.XKB), WebP exists.
If err:
"No glyph mapped" — Step 3 missing / typo
"Unknown domain" — Not in get_palette_colors() in palettes.R
- R pkg err —
install.packages(c("ggplot2", "ggforce", "ggfx", "ragg", "magick"))
- Crash → test fn interactive (Step 2 fallback)
Step 6: Verify
Check file + size:
ls -la viz/public/icons/cyberpunk/<type-path>/<entity-id>.webp
# Expected: 15-80 KB typical range
Open WebP → check:
- Shape clear @ 1024x1024
- Neon glow present, not overpowering
- BG transparent (no rect)
- No edge clip
Small sizes (~40-160px in graph):
- Shape recognizable
- Detail ≠ noise
- Glow doesn't overwhelm
Got: Clear pictogram + even glow + transparent BG.
If err:
- Glow strong → re-render
--glow-sigma 2
- Glow weak →
--glow-sigma 8
- Unreadable small → simplify (fewer layers, bolder strokes,
.lw(s, base) higher)
- Edge clip → reduce dims / shift center
Step 7: Iterate
Common adjustments:
- Bolder strokes:
.lw(s, base) → base = 3.0 / 3.5
- Visible fill: alpha 0.10 → 0.15-0.20
- Proportions: tweak
s multipliers (20 * s → 24 * s)
- Add/rm layers: 2-6 best
Re-render:
# Delete the existing icon first, then re-render
rm viz/public/icons/cyberpunk/<type-path>/<entity-id>.webp
# Use the appropriate build command from Step 5
When done → manifest status = "done" (auto on success)
Got: Icon passes Step 6.
If err: 3+ iter fail → try diff metaphor (→ Step 1).
Reference
Domain + Entity Palettes
All domain colors (skills) in viz/R/palettes.R (single truth). Agent/team colors same. Cyberpunk (hand-tuned neon) in get_cyberpunk_colors(). Viridis auto via viridisLite.
Lookup:
source("viz/R/palettes.R")
get_palette_colors("cyberpunk")$domains[["design"]] # skill domain
get_palette_colors("cyberpunk")$agents[["mystic"]] # agent
get_palette_colors("cyberpunk")$teams[["tending"]] # team
New domain → 3 places in palettes.R:
PALETTE_DOMAIN_ORDER (alphabetical)
get_cyberpunk_colors() domains list
- Run
bash viz/build.sh → regen palettes + data + manifests
Glyph Fn Catalog
Full catalog in primitives source:
- Skills:
viz/R/primitives.R → viz/R/primitives_19.R (domain-grouped)
- Agents:
viz/R/agent_primitives.R
- Teams:
viz/R/team_primitives.R
Helpers
| Fn |
Sig |
Purpose |
.lw(s, base) |
(scale, base=2.5) |
Scale-aware line width |
.aes(...) |
alias for ggplot2::aes |
Shorthand aes map |
hex_with_alpha(hex, alpha) |
(string, 0-1) |
Alpha on hex |
brighten_hex(hex, factor) |
(string, factor=1.3) |
Brighten |
dim_hex(hex, factor) |
(string, factor=0.4) |
Dim |
Check
Traps
- Forgot
* s: Hard-coded px breaks on scale. Multiply by s always.
- Canvas origin: (0,0) bottom-left. Higher
y = UP.
- Double glow: Renderer applies
ggfx::with_outer_glow(). Do NOT add in fn.
- Too many layers: Each gets glow wrap. >8 = slow + noisy.
- ID mismatch: Glyph map + manifest + registry must match exact.
- JSON trailing commas: Strict JSON. No trailing comma.
- Missing domain color: Not in
get_cyberpunk_colors() → render err. Add color first.
- Wrong primitives file: Skills →
primitives*.R, agents → agent_primitives.R, teams → team_primitives.R.
→
1---2name: create-glyph-103description: Create R-based pictogram glyphs for skill, agent, or team icons in the visualization layer. Covers concept sketching, ggplot2 layer composition using the primitives library, color strategy, registration in the appropriate glyph mapping file and manifest, rendering via the build pipeline, and visual verification of the neon-glow output. Use when a new entity has been added and needs a visual icon for the force-graph visualization, an existing glyph needs replacement, or when batch-creating glyphs for a new domain.4license: MIT5---67# Create Glyph89R pictogram glyphs → skill/agent/team icons in `viz/`. Pure-ggplot2 fn on 100x100 → neon glow → transparent WebP.1011## Use When1213- New skill/agent/team needs icon14- Existing glyph needs replace/redesign15- Batch-create for new domain16- Prototype visual metaphors1718## In1920- **Required**: Type — `skill`, `agent`, `team`21- **Required**: Entity ID (`create-glyph`, `mystic`, `r-package-review`) + domain (skills)22- **Required**: Visual concept23- **Optional**: Reference glyph (complexity calibration)24- **Optional**: Custom `--glow-sigma` (def: 4)2526## Do2728### Step 1: Concept29301. Read entity source:31 - Skills: `skills/<id>/SKILL.md`32 - Agents: `agents/<id>.md`33 - Teams: `teams/<id>.md`342. Metaphor type:35 - **Literal**: flask→experiment, shield→security36 - **Abstract**: arrows→merge, spirals→iterate37 - **Composite**: 2-3 simple shapes (doc + pen)383. Complexity ref:3940```text41Complexity Tiers:42+----------+--------+-------------------------------------------+43| Tier | Layers | Examples |44+----------+--------+-------------------------------------------+45| Simple | 2 | glyph_flame, glyph_heartbeat |46| Moderate | 3-5 | glyph_document, glyph_experiment_flask |47| Complex | 6+ | glyph_ship_wheel, glyph_bridge_cpp |48+----------+--------+-------------------------------------------+49```50514. Fn name: `glyph_<descriptive_name>` (snake_case, unique)5253**Got:** Mental sketch, 2-6 planned layers.5455**If err:** Too abstract → concrete related. Check existing in same domain.5657### Step 2: Compose5859Write R fn → ggplot2 layers.60611. Signature (immutable):62 ```r63 glyph_<name> <- function(cx, cy, s, col, bright) {64 # cx, cy = center coordinates (50, 50 on 100x100 canvas)65 # s = scale factor (1.0 = fill ~70% of canvas)66 # col = domain color hex (e.g., "#ff88dd" for design)67 # bright = brightened variant of col (auto-computed by renderer)68 # Returns: list() of ggplot2 layers69 }70 ```71722. Apply `* s` to ALL dims:73 ```r74 r <- 20 * s # radius75 hw <- 15 * s # half-width76 lw <- .lw(s) # line width (default base 2.5)77 lw_thin <- .lw(s, 1.2) # thinner line width78 ```79803. Geometry primitives:8182 | Geometry | Usage |83 |---|---|84 | `ggplot2::geom_polygon(data, .aes(x, y), ...)` | Filled shapes |85 | `ggplot2::geom_path(data, .aes(x, y), ...)` | Open lines/curves |86 | `ggplot2::geom_segment(data, .aes(x, xend, y, yend), ...)` | Segments, arrows |87 | `ggplot2::geom_rect(data, .aes(xmin, xmax, ymin, ymax), ...)` | Rects |88 | `ggforce::geom_circle(data, .aes(x0, y0, r), ...)` | Circles |89904. Color strategy:9192 ```text93 Alpha Guide:94 +----------------------+------------+--------------------------+95 | Purpose | Alpha | Example |96 +----------------------+------------+--------------------------+97 | Large fill (body) | 0.08-0.15 | hex_with_alpha(col, 0.1) |98 | Medium fill (accent) | 0.15-0.25 | hex_with_alpha(col, 0.2) |99 | Small fill (detail) | 0.25-0.35 | hex_with_alpha(bright, 0.3) |100 | Outline stroke | 1.0 | color = bright |101 | Secondary stroke | 1.0 | color = col |102 | No fill | --- | fill = NA |103 +----------------------+------------+--------------------------+104 ```1051065. Return flat `list()` → renderer wraps each w/ glow1071086. Place fn in right primitives file:109 - **Skills**: domain-grouped across 19 files:110 - `primitives.R` — bushcraft, compliance, containerization, data-serialization, defensive111 - `primitives_2.R` — devops, general, git, mcp-integration112 - `primitives_3.R` — mlops, observability, PM, r-packages, reporting, review, web-dev, esoteric, design113 - `primitives_4.R` through `primitives_19.R` for newer114 - **Agents**: `viz/R/agent_primitives.R`115 - **Teams**: `viz/R/team_primitives.R`116117**Got:** Working R fn → list of 2-6 layers.118119**If err:** `ggforce::geom_circle` err → install ggforce. Coords off → canvas 100x100, (0,0) bottom-left. Test:120```r121source("viz/R/utils.R"); source("viz/R/primitives.R") # etc.122layers <- glyph_<name>(50, 50, 1.0, "#ff88dd", "#ffa8f0")123p <- ggplot2::ggplot() + ggplot2::coord_fixed(xlim=c(0,100), ylim=c(0,100)) +124 ggplot2::theme_void()125for (l in layers) p <- p + l126print(p)127```128129### Step 3: Register130131Map entity → glyph.132133**Skills:**1341. Open `viz/R/glyphs.R`1352. Find domain section comment (`# -- design (3)`)1363. Alphabetical in domain block:137 ```r138 "skill-id" = "glyph_function_name",139 ```1404. Update count comment if applicable141142**Agents:**1431. Open `viz/R/agent_glyphs.R`1442. Alphabetical in `AGENT_GLYPHS`:145 ```r146 "agent-id" = "glyph_function_name",147 ```148149**Teams:**1501. Open `viz/R/team_glyphs.R`1512. Alphabetical in `TEAM_GLYPHS`:152 ```r153 "team-id" = "glyph_function_name",154 ```1551565. Verify no dup ID157158**Got:** `*_GLYPHS` list has new mapping.159160**If err:** "No glyph mapped" → check ID exact match vs manifest + registry.161162### Step 4: Manifest163164Register icon.165166**Skills:** `viz/data/icon-manifest.json`167```json168{169 "skillId": "skill-id",170 "domain": "domain-name",171 "prompt": "<domain basePrompt>, <descriptors>, dark background, vector art",172 "seed": <next_seed>,173 "path": "public/icons/cyberpunk/<domain>/<skill-id>.webp",174 "status": "pending"175}176```177178**Agents:** `viz/data/agent-icon-manifest.json`179```json180{181 "agentId": "agent-id",182 "prompt": "<agent-specific descriptors>, dark background, vector art",183 "seed": <next_seed>,184 "path": "public/icons/cyberpunk/agents/<agent-id>.webp",185 "status": "pending"186}187```188189**Teams:** `viz/data/team-icon-manifest.json`190```json191{192 "teamId": "team-id",193 "prompt": "<team-specific descriptors>, dark background, vector art",194 "seed": <next_seed>,195 "path": "public/icons/cyberpunk/teams/<team-id>.webp",196 "status": "pending"197}198```199200**Got:** Valid JSON, entry among type siblings.201202**If err:** Validate syntax. Common: trailing comma after last elem, missing quotes.203204### Step 5: Render205206Run pipeline. Always `build.sh` → platform detect + R binary. See [render-icon-pipeline](../render-icon-pipeline/SKILL.md).207208```bash209# From project root — renders all palettes, standard + HD, skips existing icons210bash viz/build.sh --only <domain> --skip-existing # skills211bash viz/build.sh --type agent --only <id> --skip-existing # agents212bash viz/build.sh --type team --only <id> --skip-existing # teams213214# Dry run first:215bash viz/build.sh --only <domain> --dry-run216```217218`build.sh` = full pipeline (palette → data → manifest → render → terminal glyphs). Non-render steps +~10s but ensure current.219220Out:221 - Skills: `viz/public/icons/<palette>/<domain>/<skill-id>.webp`222 - Agents: `viz/public/icons/<palette>/agents/<agent-id>.webp`223 - Teams: `viz/public/icons/<palette>/teams/<team-id>.webp`224225**Got:** Log `OK: <entity> (seed=XXXXX, XX.XKB)`, WebP exists.226227**If err:**228- `"No glyph mapped"` — Step 3 missing / typo229- `"Unknown domain"` — Not in `get_palette_colors()` in `palettes.R`230- R pkg err — `install.packages(c("ggplot2", "ggforce", "ggfx", "ragg", "magick"))`231- Crash → test fn interactive (Step 2 fallback)232233### Step 6: Verify2342351. Check file + size:236 ```bash237 ls -la viz/public/icons/cyberpunk/<type-path>/<entity-id>.webp238 # Expected: 15-80 KB typical range239 ```2402412. Open WebP → check:242 - Shape clear @ 1024x1024243 - Neon glow present, not overpowering244 - BG transparent (no rect)245 - No edge clip2462473. Small sizes (~40-160px in graph):248 - Shape recognizable249 - Detail ≠ noise250 - Glow doesn't overwhelm251252**Got:** Clear pictogram + even glow + transparent BG.253254**If err:**255- Glow strong → re-render `--glow-sigma 2`256- Glow weak → `--glow-sigma 8`257- Unreadable small → simplify (fewer layers, bolder strokes, `.lw(s, base)` higher)258- Edge clip → reduce dims / shift center259260### Step 7: Iterate2612621. Common adjustments:263 - **Bolder strokes**: `.lw(s, base)` → `base = 3.0` / `3.5`264 - **Visible fill**: alpha 0.10 → 0.15-0.20265 - **Proportions**: tweak `s` multipliers (`20 * s` → `24 * s`)266 - **Add/rm layers**: 2-6 best2672682. Re-render:269 ```bash270 # Delete the existing icon first, then re-render271 rm viz/public/icons/cyberpunk/<type-path>/<entity-id>.webp272 # Use the appropriate build command from Step 5273 ```2742753. When done → manifest status = `"done"` (auto on success)276277**Got:** Icon passes Step 6.278279**If err:** 3+ iter fail → try diff metaphor (→ Step 1).280281## Reference282283### Domain + Entity Palettes284285All domain colors (skills) in `viz/R/palettes.R` (single truth). Agent/team colors same. Cyberpunk (hand-tuned neon) in `get_cyberpunk_colors()`. Viridis auto via `viridisLite`.286287Lookup:288```r289source("viz/R/palettes.R")290get_palette_colors("cyberpunk")$domains[["design"]] # skill domain291get_palette_colors("cyberpunk")$agents[["mystic"]] # agent292get_palette_colors("cyberpunk")$teams[["tending"]] # team293```294295New domain → 3 places in `palettes.R`:2961. `PALETTE_DOMAIN_ORDER` (alphabetical)2972. `get_cyberpunk_colors()` domains list2983. Run `bash viz/build.sh` → regen palettes + data + manifests299300### Glyph Fn Catalog301302Full catalog in primitives source:303- **Skills**: `viz/R/primitives.R` → `viz/R/primitives_19.R` (domain-grouped)304- **Agents**: `viz/R/agent_primitives.R`305- **Teams**: `viz/R/team_primitives.R`306307### Helpers308309| Fn | Sig | Purpose |310|---|---|---|311| `.lw(s, base)` | `(scale, base=2.5)` | Scale-aware line width |312| `.aes(...)` | alias for `ggplot2::aes` | Shorthand aes map |313| `hex_with_alpha(hex, alpha)` | `(string, 0-1)` | Alpha on hex |314| `brighten_hex(hex, factor)` | `(string, factor=1.3)` | Brighten |315| `dim_hex(hex, factor)` | `(string, factor=0.4)` | Dim |316317## Check318319- [ ] Fn signature: `glyph_<name>(cx, cy, s, col, bright) -> list()`320- [ ] All dims `* s`321- [ ] Colors: `col` fills, `bright` outlines, `hex_with_alpha()` transparency322- [ ] Fn in correct primitives file323- [ ] Mapping in right `*_glyphs.R`324- [ ] Manifest entry + correct path + `"status": "pending"`325- [ ] Build runs no err (dry-run first)326- [ ] WebP at expected path327- [ ] Size 15-80 KB328- [ ] Reads clear 1024px + ~40px329- [ ] Transparent BG330- [ ] Status → `"done"` post-render331332## Traps333334- **Forgot `* s`**: Hard-coded px breaks on scale. Multiply by `s` always.335- **Canvas origin**: (0,0) bottom-left. Higher `y` = UP.336- **Double glow**: Renderer applies `ggfx::with_outer_glow()`. Do NOT add in fn.337- **Too many layers**: Each gets glow wrap. >8 = slow + noisy.338- **ID mismatch**: Glyph map + manifest + registry must match exact.339- **JSON trailing commas**: Strict JSON. No trailing comma.340- **Missing domain color**: Not in `get_cyberpunk_colors()` → render err. Add color first.341- **Wrong primitives file**: Skills → `primitives*.R`, agents → `agent_primitives.R`, teams → `team_primitives.R`.342343## →344345- [enhance-glyph](../enhance-glyph/SKILL.md) — improve quality / fix / add layers346- [audit-icon-pipeline](../audit-icon-pipeline/SKILL.md) — detect missing347- [render-icon-pipeline](../render-icon-pipeline/SKILL.md) — full pipeline E2E348- [ornament-style-mono](../ornament-style-mono/SKILL.md) — AI img gen alt349- [ornament-style-color](../ornament-style-color/SKILL.md) — color theory350- [create-skill](../create-skill/SKILL.md) — parent workflow triggering glyph