@diegopetrucci/pi-extensions 0.1.43 → 0.1.44

package/README.md

@@ -1,6 +1,6 @@
 # pi-extensions
 
-A collection of [pi](https://github.com/earendil-works/pi-mono) agent extensions I made.
+A collection of [pi](https://github.com/earendil-works/pi-mono) agent extensions and skills I made.
 
 - [`agent-workflow-audit`](./extensions/agent-workflow-audit): Adds `/agent-workflow-audit`, which runs an isolated repo workflow audit subagent and returns only the final distilled report to the main session.
 - [`annotate-git-diff`](./extensions/annotate-git-diff): Adds `/annotate-git-diff`, a native Glimpse UI for annotating git diffs and appending structured feedback prompts to the editor.
@@ -14,6 +14,7 @@ A collection of [pi](https://github.com/earendil-works/pi-mono) agent extensions
 - [`git-footer`](./extensions/git-footer): Standalone extension that adds TLH-style git dirty counts, ahead/behind, and optional PR number to pi's built-in footer status area.
 - [`gnosis`](./extensions/gnosis): Exposes the `gn` repo-local knowledge base CLI as an agent tool for searching and recording durable project decisions, constraints, and intent.
 - [`inline-bash`](./extensions/inline-bash): Expands `!{command}` snippets in user prompts by running them through bash before the prompt reaches the agent.
+- [`illustrations-to-explain-things`](./extensions/illustrations-to-explain-things): Adds a skill for generating clean, absurd Xiaohei-style article illustrations, shot lists, image edits, and visual metaphors.
 - [`librarian`](./extensions/librarian): Adds a GitHub research scout with a local repo checkout cache disabled by default under the OS user cache directory, toggleable with `/librarian-cache`, configurable subagent model/thinking defaults via `/librarian-config`, and cached repos expiring after 7 days of non-use.
 - [`minimal-footer`](./extensions/minimal-footer): Replaces pi's built-in footer with a minimal configurable two-line layout: branch/repo on the first line, context/model on the second, optional `DUMB ZONE`, plus OpenAI Codex 5-hour and 7-day usage when available.
 - [`notify`](./extensions/notify): Sends configurable terminal, desktop, bell, and sound notifications when pi finishes and is ready for input.

package/extensions/illustrations-to-explain-things/.pi-fleet-tested-version

@@ -0,0 +1 @@
+0.78.0

package/extensions/illustrations-to-explain-things/README.md

@@ -0,0 +1,52 @@
+# illustrations-to-explain-things
+
+A pi skill for generating clean, absurd Xiaohei-style article illustrations, shot lists, image edits, and visual metaphors.
+
+The skill helps the agent turn one key judgment, process, structure, state, or metaphor from source material into a sparse 16:9 hand-drawn explainer image with Xiaohei as the causal actor.
+
+## Use cases
+
+- Article and blog-post inline illustrations
+- Shot lists for longer essays or Notion pages
+- Visual metaphors for workflows, methods, structures, and states
+- Focused image-generation prompts with style and QA constraints
+
+## Install
+
+### Standalone npm package
+
+```bash
+pi install npm:@diegopetrucci/pi-illustrations-to-explain-things
+```
+
+### Collection package
+
+```bash
+pi install npm:@diegopetrucci/pi-extensions
+```
+
+### GitHub package
+
+```bash
+pi install git:github.com/diegopetrucci/pi-extensions
+```
+
+Then reload pi:
+
+```text
+/reload
+```
+
+## Usage
+
+Ask pi for article illustrations or use the skill command directly:
+
+```text
+/illustrations-to-explain-things propose a shot list for @article.md
+```
+
+```text
+Generate three Xiaohei-style illustrations for this workflow: ...
+```
+
+By default, response text, shot lists, and handwritten image labels are in English unless you explicitly ask for another language.

package/extensions/illustrations-to-explain-things/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@diegopetrucci/pi-illustrations-to-explain-things",
+  "version": "0.1.0",
+  "description": "A pi skill for generating clean, absurd Xiaohei-style article illustrations, shot lists, and visual metaphors.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "skill",
+    "illustration",
+    "image-generation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegopetrucci/pi-extensions.git",
+    "directory": "extensions/illustrations-to-explain-things"
+  },
+  "files": [
+    "skills",
+    "README.md",
+    ".pi-fleet-tested-version"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "skills": [
+      "skills"
+    ]
+  }
+}

package/extensions/illustrations-to-explain-things/skills/illustrations-to-explain-things/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: illustrations-to-explain-things
+description: Generate clean, absurd article illustrations in Ian's Xiaohei style. Use this skill when the user wants inline illustrations, shot lists, image edits, or visual metaphors for articles, blog posts, Notion pages, workflows, methods, structures, states, or key ideas. Default all response text and handwritten image labels to English unless the user explicitly requests another language.
+---
+
+# Illustrations to Explain Things
+
+## Core positioning
+
+Design and generate 16:9 landscape article illustrations. The goal is not commercial illustration, formal PPT infographics, or cute cartoon art. The goal is to turn one key judgment, process, structure, state, or metaphor from the source material into a clean, strange, memorable hand-drawn explainer image.
+
+The default recurring character is Xiaohei: a small solid-black figure with white dot eyes, tiny legs, and a blank serious expression, doing something absurd but functional. Xiaohei must perform the core action in the image rather than standing off to the side as decoration.
+
+## Default language policy
+
+- Default to **English** for response text, shot lists, and handwritten image labels.
+- Switch to another language only if the user explicitly asks for it.
+- If the user requests another language, keep that language consistent across both the written response and the image labels.
+
+## Read these references as needed
+
+Load only what is relevant to the current task instead of stuffing all references into context:
+
+- `references/style-dna.md`: style DNA, color rules, label rules, and anti-patterns.
+- `references/xiaohei-ip.md`: Xiaohei character design, personality, action library, and prohibitions.
+- `references/composition-patterns.md`: structure types, metaphor-invention method, and anti-copy rules.
+- `references/prompt-template.md`: single-image generation prompt template.
+- `references/qa-checklist.md`: post-generation review and iteration rules.
+- `assets/examples/`: low-frequency visual calibration only. Do not copy these example compositions, objects, or labels.
+
+## Workflow
+
+### 1. Digest the source material
+
+Read the article, link, Notion page, Markdown file, screenshot, or topic the user provided. Extract:
+
+- the core claim
+- the paragraphs that carry the cognitive turning points
+- the ideas that truly benefit from illustration
+- the parts that should stay as text and do not need images
+
+Do not distribute illustrations evenly. Prefer cognitive anchors such as core judgments, breakpoints, input/output loops, splits, before/after contrasts, one-input-many-outputs patterns, handoff paths, common traps, or role-state changes.
+
+### 2. Propose the illustration strategy first
+
+If the user asks how to illustrate the piece, think through it first and output a shot list. For each image, specify:
+
+- where it should appear
+- the theme
+- the core idea
+- the structure type
+- what Xiaohei is doing
+- suggested elements
+- suggested handwritten labels in English
+
+Default to 4-8 images. For very short pieces, 1-3 may be enough. Even for long pieces, avoid going past 9 unless the user clearly needs more.
+
+### 3. Generate single images
+
+If the user clearly asks you to generate, output, or make images, do not pause for confirmation. Use the built-in `image_gen` tool and generate each image separately. Do not combine multiple concepts into one image.
+
+Each image should express only one core structure. The prompt must include:
+
+- 16:9 landscape article illustration
+- pure white background
+- black hand-drawn line art
+- sparse red/orange/blue handwritten labels, in English by default
+- lots of whitespace
+- Xiaohei as the actor performing the core conceptual action
+- prohibitions against PPT slides, commercial illustration, childish/cute styling, dense architecture diagrams, and top-left type titles
+
+Do not copy older example compositions. Examples are only for line density, whitespace, restraint, and Xiaohei participation. Unless the user explicitly asks to imitate a specific example, invent a fresh metaphor for the current article.
+
+### 4. Review and iterate
+
+After generation, check the result against `references/qa-checklist.md`. If you see any of the following, regenerate or make a focused edit:
+
+- Xiaohei is decorative instead of causal
+- the canvas feels too full
+- the result looks like a flowchart or PPT slide
+- labels are too long or contain obvious errors
+- the image has a top-left title such as "Workflow" or "Common traps"
+- the style drifts into cute, childish, or stiff
+- the background is not clean white
+
+### 5. Save and deliver
+
+If the user is working inside a writable workspace, copy the final images to:
+
+```text
+assets/<article-slug>-illustrations/
+```
+
+Name them in order:
+
+```text
+01-topic-name.png
+02-topic-name.png
+```
+
+Keep original generated files rather than overwriting existing assets, unless the user explicitly asks to replace them.
+
+## Delivery style
+
+Keep planning outputs short and precise. After generating images, report:
+
+- how many images were generated
+- what each image is for
+- where the files were saved
+- which results are strongest and which are optional
+
+Do not spend paragraphs explaining the style theory. Let the images do the work.

package/extensions/illustrations-to-explain-things/skills/illustrations-to-explain-things/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Illustrations to Explain Things"
+  short_description: "Create clean, absurd article illustrations with Xiaohei. Default output language: English unless the user explicitly requests another language."
+  default_prompt: "Use $illustrations-to-explain-things to plan and generate article illustrations for this piece. Default all response text and handwritten image labels to English unless I explicitly request another language."
+policy:
+  allow_implicit_invocation: true

package/extensions/illustrations-to-explain-things/skills/illustrations-to-explain-things/references/composition-patterns.md

@@ -0,0 +1,91 @@
+# Composition Patterns and Originality Rules
+
+## Base structure types
+
+Pick one structure type per image. Do not mix too many.
+
+### Workflow
+
+Best for: input -> process -> output, content production, AI workflows, automation chains.
+
+Typical composition: input on the left, Xiaohei or a strange machine doing the work in the middle, output on the right, with orange arrows showing the main flow.
+
+### System slice
+
+Best for: information sources, filters, databases, renderers, or one local slice of an agent system.
+
+Typical composition: show only 3-5 core modules, and make Xiaohei participate in one key action.
+
+### Before / after
+
+Best for: chaos vs. order, manual vs. automated, scattered vs. consolidated, anxious vs. stable.
+
+Typical composition: messy left side, stable right side, orange arrow in the middle. The character can be more exaggerated here.
+
+### Role state
+
+Best for: user pain points, creator state, tool overload, information anxiety, stuck-to-moving transitions.
+
+Typical composition: 2-4 mini states, each with one short label.
+
+### Concept metaphor
+
+Best for: content factory, information warehouse, black-box thinking, workflow machine, auto-reporting.
+
+Typical composition: one large strange object or machine, a small amount of input, and one output. It should be memorable.
+
+### Method layers
+
+Best for: methodology frameworks, system layers, capability stacks, layered content systems.
+
+Typical composition: stacked boxes or levels, but not a formal pyramid. Xiaohei can be building, carrying, or fitting parts into place.
+
+### Route map
+
+Best for: idea-to-launch journeys, user paths, content handoff paths, learning routes.
+
+Typical composition: one curved route with a few nodes. Xiaohei can be pulling the line or walking the path.
+
+### Comic beats
+
+Best for: failure-to-success arcs, real process snapshots, commentary, before/after usage shifts.
+
+Typical composition: 2-4 mini scenes, with one action per panel.
+
+## How to invent a fresh metaphor
+
+Reinvent the metaphor from the current article every time. Do not reuse old image logic by default.
+
+### Three-step method
+
+1. Convert the abstract idea into a physical action: getting stuck, leaking, getting heavier, sorting, settling, fermenting, opening, folding, unpacking, looping back.
+2. Convert the system structure into a low-tech object: a broken machine, cardboard boxes, drawers, pipes, mail slots, a weird dial, a scale, a well, a ladder, a strange workstation.
+3. Make Xiaohei perform the action: not standing nearby, but wedged inside the machine, pulling the wrong wire, guarding a gate, carrying parts, patching a leak, weighing something, holding a ladder, recording a result, or feeding material into a strange device.
+
+### Object pool
+
+- cardboard box, drawer, old machine, funnel, scale, mailbox, door, well, ladder, pipe, cable knot, gate, turntable, black box, puncher, press, clothesline, strange workstation
+- choose only 1-2 at a time rather than piling them up
+
+### Xiaohei action pool
+
+- pull, carry, stuff, scoop, press, weigh, stitch, cut, twist, guard, push, catch, unpack, mark, recycle
+- the action should serve the core idea instead of being strange for its own sake
+
+## Anti-copy rules
+
+Do not automatically open or imitate `assets/examples/`. Those images are only for style calibration such as line density, whitespace, color restraint, and Xiaohei attitude.
+
+Unless the user explicitly says "copy this one," "recreate this composition," or "edit this example," do not directly reuse these old compositions:
+
+- a conveyor belt with two breakpoints
+- Xiaohei pulling a judgment lever inside a content machine
+- Xiaohei as a funnel sorting reach / trust / conversion
+- Xiaohei cutting up a source-material fish
+- Xiaohei pulling a handoff route
+- Xiaohei tugging three layers of information sources
+- three Xiaohei figures holding a megaphone, building a bridge, and opening a door
+- Xiaohei stamping a messaging toolbox
+- Xiaohei holding a warning sign over a trap path
+
+Even when the theme is similar, invent a new metaphor. For example, a handoff path does not have to be a route; it could be Xiaohei connecting the tail of a piece of content to a doorknob. One-input-many-outputs does not have to be a fish; it could be Xiaohei pressing one paper lump into several different shapes.

package/extensions/illustrations-to-explain-things/skills/illustrations-to-explain-things/references/prompt-template.md

@@ -0,0 +1,51 @@
+# Image Prompt Template
+
+Generate each image separately. Replace the placeholders with details from the current article. Do not combine multiple images into one.
+
+```text
+Generate one standalone 16:9 horizontal article illustration.
+
+Visual DNA:
+Pure white background. Minimal black hand-drawn line art. Slightly wobbly pen lines. Lots of empty white space. Sparse red/orange/blue handwritten labels in English by default; switch languages only if the user explicitly asks. Clean absurd product-sketch feeling. No gradients, no shadows, no paper texture, no complex background, no commercial vector style, no PPT infographic look, no cute mascot poster, no children's illustration, no realistic UI.
+
+Recurring IP character required:
+Xiaohei, a small solid-black absurd creature with white dot eyes, tiny thin legs, blank serious expression, and a slightly uneven hand-drawn body shape. Xiaohei must perform the core conceptual action, not decorate the scene. Make Xiaohei serious, deadpan, and slightly bizarre, not cute.
+
+Theme:
+{illustration theme}
+
+Structure type:
+{Workflow / System slice / Before-after / Role state / Concept metaphor / Method layers / Route map / Comic beats}
+
+Core idea:
+{the core idea this image must explain}
+
+Composition:
+{where Xiaohei is, what Xiaohei is doing, what the main object is, and how information or motion flows}
+
+Suggested elements:
+{element 1} / {element 2} / {element 3} / {element 4}
+
+Handwritten labels:
+{label 1} / {label 2} / {label 3} / {label 4} / {optional label 5}
+
+Color use:
+Black for the main line art and Xiaohei. Orange for the main flow, path, or arrows. Red only for key warnings, problems, or outcomes. Blue only for secondary notes, feedback, or system state.
+
+Constraints:
+One image explains only one core structure. Keep the main subject around 40%-60% of the canvas. Preserve at least 35% blank white space. Use at most 5-8 short handwritten labels. Do not write a title in the top-left corner. Do not write the structure type on the image. Do not make it a formal diagram, course slide, or dense explainer. Do not copy prior examples or known case compositions unless the user explicitly requests it; invent a fresh visual metaphor for this specific article. The result should be clear but not over-instructional, interesting but not childish, and strange but clean.
+```
+
+## Image editing prompts
+
+Remove a top-left title:
+
+```text
+Edit the provided image. Remove only the handwritten title "{text to remove}" and its underline from the top-left corner. Fill that area with the same clean white background, matching the surrounding blank paper. Preserve everything else exactly: characters, labels, paths, line style, composition, aspect ratio, and image quality. Do not add any new text or objects.
+```
+
+Make the image stranger while keeping the idea:
+
+```text
+Regenerate this illustration with the same core meaning and simple layout, but make Xiaohei more central to the conceptual action. Xiaohei should be doing the strange work that explains the idea, not standing beside the diagram. Keep it clean, sparse, hand-drawn, and not cute.
+```

package/extensions/illustrations-to-explain-things/skills/illustrations-to-explain-things/references/qa-checklist.md

@@ -0,0 +1,48 @@
+# QA Checklist
+
+## Must-pass checks
+
+- It is a 16:9 landscape image.
+- The background is clean white.
+- Xiaohei is present.
+- Xiaohei performs the core action instead of acting as decoration.
+- The composition is not a copy of an old example; it uses a new metaphor for the current article.
+- The image feels strange, inventive, and interesting.
+- The canvas stays clean and sparse, with the subject using no more than about 60% of the space.
+- One image explains only one core structure.
+- Handwritten labels are few, short, and legible.
+- Orange is used only for the main path or arrows.
+- Red is used only for key points, warnings, problems, or results.
+- Blue is used only for supporting notes, feedback, or system state.
+- Unless the user explicitly requested another language, the response text and handwritten image labels are in English.
+
+## Failure signals
+
+If any of these appear, regenerate or make a focused edit:
+
+- There is a top-left title such as "Common traps," "Workflow," "System architecture," or "Route map."
+- Xiaohei looks like a mascot, sticker, reaction image, or cute cartoon.
+- The image looks like a PPT slide, courseware page, or formal flowchart.
+- There are too many elements, arrows, or nodes.
+- The labels turn into sentence-length explanations.
+- The background contains paper texture, shadow, gradient, beige tint, or noise.
+- The result contains realistic UI or glossy tech interfaces.
+- Labels are unreadable or obviously incorrect.
+- The image is stiff and lacks an absurd metaphor.
+- The composition looks too similar to something in `assets/examples/`.
+
+## Iteration moves
+
+- Too ordinary: make Xiaohei the action engine and add one strange but believable metaphor.
+- Too complex: remove nodes and keep one action plus 3-5 short labels.
+- Too cute: emphasize deadpan, blank serious expression, not cute, not mascot.
+- Too PPT: remove titles, frames, tidy grids, and extra arrows; turn it back into a hand-drawn scene.
+- Too similar to an old case: keep the core idea and replace the main object plus Xiaohei's action.
+- Text errors: prefer a local edit first; if there are many errors, regenerate with fewer labels.
+- Wrong language: regenerate or edit so the default output is English unless the user asked for another language.
+
+## Delivery bar
+
+A high-quality image should make the reader think "that's a little weird" first, then understand the structure within one second.
+
+If it looks like a tutorial page instead of an absurd product sketch on white paper, it is not ready.

package/extensions/illustrations-to-explain-things/skills/illustrations-to-explain-things/references/style-dna.md

@@ -0,0 +1,49 @@
+# Style DNA
+
+## One-line summary
+
+Pure white, minimal, hand-drawn, whitespace-heavy, restrained, absurd, product-sketch-like, with handwritten labels and a structure that reads clearly without turning into a manual.
+
+It should feel like a quick explanatory sketch made on white paper by someone who has spent a long time working on AI, product, design, and developer tools.
+
+## Must-have traits
+
+- 16:9 landscape article illustration.
+- Pure white background: no beige, warm gray, paper texture, gradient, shadow, noise, or retro paper feel.
+- Mostly black hand-drawn line art: thin lines, slight wobble, not mechanical, not vector-clean, not heavy-outline.
+- Lots of whitespace: the subject should use about 40%-60% of the canvas, with at least 35% quiet blank space.
+- Sparse handwritten labels: ideally no more than 5-8, and keep them short.
+- English handwritten labels by default; switch only if the user explicitly requests another language.
+- One image should explain one core action, structure, state, or metaphor.
+- Let the structure read naturally without writing the structure-type name onto the image.
+
+## Color rules
+
+- Black: main line art, character, outlines, structure, primary text, main objects.
+- Red: priority notes, problems, emotional pressure points, key reminders, results.
+- Orange: main flow, path, arrows, automation direction, movement from A to B.
+- Blue: supporting notes, mental state, system state, second-layer explanation, AI/assistant/automation cues.
+
+Blue is optional. Keep the palette restrained: fewer color accents are better than more.
+
+## Absolutely avoid
+
+- commercial illustration
+- PPT infographics
+- formal flowcharts
+- course slides
+- cute mascot posters
+- children's illustration
+- complex architecture diagrams
+- polished flat illustration
+- glossy tech UI
+- real app screenshots
+- complex backgrounds, gradients, shadows, or textures
+- explaining every node in full detail
+- a top-left type label such as "Workflow," "System architecture," "Common traps," or "Route map"
+
+## Aesthetic direction
+
+Aim for strange, inventive, interesting, clean, and imaginative.
+
+Avoid cute, childish, overcomplicated, or rigid.

package/extensions/illustrations-to-explain-things/skills/illustrations-to-explain-things/references/xiaohei-ip.md

@@ -0,0 +1,53 @@
+# Xiaohei IP
+
+## Character definition
+
+Xiaohei is the recurring visual character in Ian's article-illustration style.
+
+Xiaohei should appear in most images by default. Xiaohei is not a mascot, sticker, or cute decoration. Xiaohei is an absurd worker who is seriously participating in how the system functions.
+
+## Shape
+
+- a small solid-black creature
+- white dot eyes
+- thin legs, sometimes thin arms
+- a body that can read as a capsule, bean, box, funnel, shadow, hole, or black internal block inside a machine
+- a slightly irregular outline with a hand-drawn feel
+- a blank, deadpan, calm, serious expression
+
+## Personality
+
+- serious, even when the task is absurd
+- like a low-key system operator
+- dryly funny, never trying to be cute
+- slightly clumsy, but not stupid
+- believable as if it really owns one small job inside a whiteboard sketch
+
+## Typical jobs
+
+Make Xiaohei carry the core action:
+
+- moving source material
+- pulling lines to gather information sources
+- getting stuck inside a breakpoint
+- operating a judgment lever inside a machine
+- becoming a sorting funnel
+- cutting up a source-material fish
+- stamping a handoff message
+- pulling a handoff path
+- holding a warning sign over a trap
+- reaching out from a hole but failing to catch the content
+- building, bridging, opening, sorting, logging, or carrying beside the main structure
+
+## Do not
+
+- draw Xiaohei as an overly cute mascot
+- turn Xiaohei into a children's-cartoon character
+- give Xiaohei elaborate clothes, meme expressions, or sparkling eyes
+- let Xiaohei stand in the corner and watch
+- let Xiaohei overpower the structural idea
+- make Xiaohei feel too commercial, too rounded, or too polished
+
+## Test for success
+
+If you can remove Xiaohei and the core metaphor still works exactly the same, Xiaohei is too decorative. Rewrite the prompt so Xiaohei becomes the action engine.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@diegopetrucci/pi-extensions",
-  "version": "0.1.43",
-  "description": "A collection of pi extensions for annotation UIs, context management, workflow audits, review-comment triage, notifications, brrr push alerts, safety guards, GitHub research, repo-local knowledge, todos, tool rendering, and model/provider helpers.",
+  "version": "0.1.44",
+  "description": "A collection of pi extensions and skills for annotation UIs, context management, workflow audits, review-comment triage, notifications, brrr push alerts, safety guards, GitHub research, repo-local knowledge, todos, tool rendering, model/provider helpers, and Xiaohei-style article illustrations.",
   "keywords": [
     "pi-package",
     "pi",
@@ -56,7 +56,10 @@
       "./extensions/todo/index.ts",
       "./extensions/triage-comments/index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/diegopetrucci/pi-extensions/main/assets/oracle-preview.svg"
+    "image": "https://raw.githubusercontent.com/diegopetrucci/pi-extensions/main/assets/oracle-preview.svg",
+    "skills": [
+      "./extensions/illustrations-to-explain-things/skills"
+    ]
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.78.0",