ascii-diagram
Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 931
- Forks
- 84
01 前言 Front Matter
- name
- ascii-diagram
- license
- MIT
- description
- Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.
- auto-trigger
- false
- user-invocable
- true
- trigger_keywords
- [ "ascii diagram", "ascii art", "box diagram", "architecture diagram", "flow diagram", "sequence diagram", "draw a diagram", "text diagram" ]
02 资源文件 2
- 参考文档__benchmarks__/no-citadel-scripts.md974 B
- 参考文档__benchmarks__/simple-pipeline.md890 B
03 SKILL.md 正文
/ascii-diagram — Perfectly Aligned ASCII Diagrams
Orientation
Use when:
- The user wants any kind of text/ASCII diagram: architecture, flow, sequence, box-and-arrow, tree, table, org chart, network topology
- A diagram needs to be embedded in markdown, code comments, or plain text
- Visual alignment matters
Do NOT use when:
- The user wants an image (suggest Mermaid, PlantUML, or an image tool instead)
- The diagram is trivial (a single box or a one-line arrow)
What this skill needs:
- A description of what to diagram
- Optional: preferred style (single-line
+--+, double-line╔══╗, rounded╭──╮, heavy┏━━┓) - Optional: target width constraint
Protocol
Step 1: PLAN THE LAYOUT
Before writing ANY characters, plan the diagram structurally:
- Identify elements: List every box/node and its label text
- Identify connections: List every arrow/line between elements, with optional labels
- Choose layout direction: left-to-right, top-to-bottom, or mixed
- Calculate dimensions:
- Each box width = max label line length + 4 (2 padding + 2 border)
- Each box height = label line count + 2 (top + bottom border)
- Gutters between boxes: minimum 3 characters for arrows (
→) - For vertical arrows: minimum 1 row gap
Write this plan out explicitly before proceeding. Example:
Elements:
A: "Client" → width=10, height=3
B: "Server" → width=10, height=3
C: "Database" → width=12, height=3
Layout: left-to-right
Connections: A→B (HTTP), B→C (SQL)
Total width: 10 + 6 + 10 + 6 + 12 = 44
Step 2: BUILD ON A CHARACTER GRID
Use this JavaScript approach mentally (or actually execute it via Bash if the diagram is complex):
// For complex diagrams, RUN this — don't try to hand-align
class Grid {
constructor(w, h) {
this.w = w; this.h = h;
this.cells = Array.from({length: h}, () => Array(w).fill(' '));
}
put(x, y, char) {
if (x >= 0 && x < this.w && y >= 0 && y < this.h) this.cells[y][x] = char;
}
text(x, y, str) {
for (let i = 0; i < str.length; i++) this.put(x + i, y, str[i]);
}
box(x, y, w, h, label) {
// Top border
this.put(x, y, '+');
for (let i = 1; i < w-1; i++) this.put(x+i, y, '-');
this.put(x+w-1, y, '+');
// Bottom border
this.put(x, y+h-1, '+');
for (let i = 1; i < w-1; i++) this.put(x+i, y+h-1, '-');
this.put(x+w-1, y+h-1, '+');
// Sides
for (let j = 1; j < h-1; j++) {
this.put(x, y+j, '|');
this.put(x+w-1, y+j, '|');
}
// Label (centered)
const lines = label.split('\n');
const startY = y + Math.floor((h - lines.length) / 2);
for (let li = 0; li < lines.length; li++) {
const line = lines[li];
const startX = x + Math.floor((w - line.length) / 2);
this.text(startX, startY + li, line);
}
}
hArrow(x1, x2, y, label) {
// Horizontal arrow from x1 to x2 at row y
const dir = x2 > x1 ? 1 : -1;
for (let x = x1; x !== x2; x += dir) this.put(x, y, '-');
this.put(x2, y, dir > 0 ? '>' : '<');
if (label) {
const lx = Math.min(x1, x2) + Math.floor((Math.abs(x2-x1) - label.length) / 2);
this.text(lx, y - 1, label);
}
}
vArrow(x, y1, y2, label) {
// Vertical arrow from y1 to y2 at column x
const dir = y2 > y1 ? 1 : -1;
for (let y = y1; y !== y2; y += dir) this.put(x, y, '|');
this.put(x, y2, dir > 0 ? 'v' : '^');
if (label) this.text(x + 2, Math.min(y1, y2) + Math.floor(Math.abs(y2-y1) / 2), label);
}
render() {
return this.cells.map(row => row.join('').trimEnd()).join('\n');
}
}
For any diagram with 4+ boxes or crossing connections, ACTUALLY RUN the script via Bash using Node. Do not attempt to mentally compute grid coordinates for complex diagrams. This is the entire point of the skill — let code handle alignment.
Pre-built grid engine: .citadel/scripts/grid.cjs provides
Grid and autoLayout(). For auto-layout, pass a JSON spec:
node .citadel/scripts/grid.cjs '{"direction":"horizontal","boxes":[{"id":"a","label":"Input"},{"id":"b","label":"Output"}],"arrows":[{"from":"a","to":"b","label":"data"}]}'
For complex/nested diagrams, use the Grid class directly via require():
node -e "
const {Grid} = require('./.citadel/scripts/grid.cjs');
const g = new Grid(60, 10);
g.box(0, 0, 20, 5, 'Box A');
g.box(30, 0, 20, 5, 'Box B');
g.hArrow(20, 29, 2, 'flow');
console.log(g.render());
"
Verification: .citadel/scripts/verify.cjs checks alignment:
echo "<diagram>" | node .citadel/scripts/verify.cjs --stdin
Step 3: VERIFY ALIGNMENT
After generating the diagram, verify these properties:
- Box closure: Every
+corner has matching corners forming a rectangle - Consistent widths: All rows within a box have the same width
- Arrow continuity: Every arrow is an unbroken sequence of
-,|, or diagonal characters ending in>,<,v,^ - Label centering: Labels are centered within their boxes (±1 char)
- No trailing whitespace issues: Right edges of boxes in the same column align vertically
Verification method: Count characters. Pick any two | side borders that
should be in the same column — they MUST be at the same character offset from
the start of their respective lines.
If verification fails, fix by adjusting coordinates and re-rendering — do NOT try to patch individual characters.
Step 4: OUTPUT
Present the diagram in a fenced code block:
```
[diagram here]
```
If the diagram was generated by a script, also offer to save the generator script so the user can modify and re-run it.
Style Guide
Box styles (use single-line by default):
Single: +--------+ Double: ╔════════╗ Rounded: ╭────────╮
| Label | ║ Label ║ │ Label │
+--------+ ╚════════╝ ╰────────╯
Arrow styles:
Horizontal: -----> <-----> ──────>
Vertical: | | │
| | │
v v ▼
Labeled: HTTP
------->
Common patterns:
Pipeline (left-to-right):
+-------+ +-------+ +-------+
| Input |---->| Process|--->| Output|
+-------+ +-------+ +-------+
Layered (top-to-bottom):
+-------------------+
| Presentation |
+-------------------+
|
+-------------------+
| Business |
+-------------------+
|
+-------------------+
| Data |
+-------------------+
Nested (container with children):
+--[ Kubernetes cluster ]------------------+
| |
| +----------+ +----------+ +--------+ |
| | Service | | Service | |Registry| |
| +----------+ +----------+ +--------+ |
| |
+------------------------------------------+
Failure Modes & Recovery
| Symptom | Cause | Fix |
|---|---|---|
| Boxes misaligned vertically | Computed wrong Y offset | Recalculate from top, re-render full grid |
| Arrow doesn't reach target | Off-by-one in x/y range | Use box.x + box.w for right edge, not box.x + box.w - 1 |
| Label overflows box | Box width too small | Recalculate: width = max(label.length + 4, minWidth) |
| Pipes don't line up across rows | Mixed tabs/spaces or variable-width chars | Use ONLY spaces, ONLY ASCII (unless explicitly using Unicode box-drawing) |
Complexity Thresholds
- 1-3 boxes, linear flow: Render mentally, verify by counting
- 4-7 boxes, simple topology: Use the Grid class, run via Node
- 8+ boxes or crossing connections: Use the Grid class, AND generate a reusable script the user can tweak
- Sequence diagrams: Always use the Grid class — column alignment across many rows is error-prone
Anti-Patterns (NEVER do these)
- NEVER freehand complex diagrams — you WILL misalign them
- NEVER use tabs — only spaces for monospace alignment
- NEVER mix Unicode box-drawing with ASCII
+--+— pick one style - NEVER try to "fix" a misaligned diagram by editing individual lines — re-render from the grid
- NEVER assume your output is aligned — always verify by counting columns
Fringe Cases
.citadel/scripts/grid.cjsnot present: The harness hasn't been initialized in this project yet. Either run/do setupto initialize, or use the inline Grid class from Step 2 directly — it's embedded in this skill's protocol as a copy-paste template.- User asks for an image, not ASCII: Suggest Mermaid (for GitHub/GitLab rendering), PlantUML, or an image generation tool. Do not attempt to produce ASCII for an image request.
- Diagram has crossing arrows: ASCII doesn't handle crossings well. Either restructure the layout (change direction, use layered topology) or note the limitation and offer Mermaid instead.
- Unicode box-drawing renders incorrectly: The user's terminal or font may not support Unicode box-drawing characters. Fall back to single-line ASCII (
+--+style) and note the switch. - Diagram is trivial (1-2 nodes): Skip the full protocol. Render directly in a code block without running the grid engine.
- Very large diagram (20+ nodes): Warn the user that ASCII has width limits. Consider breaking into sub-diagrams or using a proper diagramming tool for publication.
Quality Gates
- Every diagram MUST pass the verification step (Step 3) — count characters to confirm alignment, or run
verify.cjs --stdin - No tabs — only spaces
- Box corners must form closed rectangles
- All arrows must be unbroken sequences ending in a head character
- Unicode and ASCII box-drawing styles must not be mixed in the same diagram
- For diagrams with 4+ boxes: the Grid class was used (not freehand)
Contextual Gates
Disclosure: "Generating ASCII diagram. Output to screen (or file if requested)." Reversibility: green — outputs ASCII diagram to screen or a new file; no existing files modified Trust gates:
- Any: full diagram generation, verification, and output.
Exit Protocol
Present the diagram in a fenced code block. If a script was used to generate it, offer to save it so the user can tweak and re-run. If verification found issues, fix them before presenting.
04 同仓库更多 Skills
workspace
Multi-repo campaign coordinator. Same lifecycle as fleet -- scope claims, discovery relay, wave-based execution -- but the unit of work is a repo, not a file. Coordinates campaigns across repositories with shared context.
wiki
Markdown-first knowledge base where the LLM acts as librarian. Ingests raw sources, compiles and interlinks topic files, self-maintains an index. No vector DB or embeddings required -- uses LLM-native navigation over structured markdown up to ~400K words.
watch
File sentinel that monitors the working directory for changes and marker comments, then auto-triggers appropriate skills. Poll-based via git diff against the last scan commit. Writes intake items for batch processing and routes marker actions through /do. Use for automatic reactions to file changes; do NOT use for one-off inspection or tasks needing human judgment per file.
verify
Self-test the Citadel hook pipeline from within a live session. Exercises real tool calls (Write, Edit, Bash, Read) and checks that hooks fired, telemetry accumulated, and no errors occurred. Reports HOOK HEALTH: PASS or HOOK HEALTH: FAIL with a per-hook breakdown.
unharness
Safely leave Citadel using the active adoption receipt. Produces a no-write, reviewable plan, preserves a portable archive, removes only exact owned material, and reports modified or externally registered surfaces as retained or unknown. Legacy installs must be imported before exact leave is claimed.
triage
GitHub issue and PR investigator. Pulls open issues/PRs, classifies them, searches the codebase for root cause or reviews contributed code, proposes fixes with file:line references, and optionally implements fixes. Use for investigating GitHub issues and reviewing PRs; do NOT use for general code review unrelated to GitHub issues.