issue-212: Add the image-to-design workflow to skills/penpot/SKILL.md #245

Merged

david merged 3 commits from feature/issue-212/add-the-image-to-design-workflow-to-skills-penpot into main

2026-09-15 07:15:58 +00:00

david commented

2026-09-15 07:15:57 +00:00

Owner

212: Add the image-to-design workflow to skills/penpot/SKILL.md

Closes #212 — 212.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 7m 43s.

Review findings

I'll start by examining the relevant files and project configuration.Let me verify the findings against the extension source.All findings verified. Now let me apply the fixes.Now the CHANGELOG entry. Let me insert a bullet at the top of the ### Added section.Now let me validate the frontmatter and run the project test gate.All 8 findings addressed, tests match the pre-existing baseline (1 unrelated failure). Let me confirm the working-tree diff scope.# Review Findings — 212

Summary

Fixed all eight findings (4 Medium, 4 Low) as documentation-accuracy corrections against the extension source: the SVG self-critique step now detects rsvg-convert/resvg and states the renderer is optional in Prerequisites; the reference-layer section records that locking is a manual Penpot-UI step and that a staged raster must be dropped with penpot_discard; the colour-by-role section explains staged assets are invisible to name resolution until committed and names the real flip7-* assets; the loop, spacing and description clauses were corrected to match observable behaviour; and a CHANGELOG ### Added bullet was added. Changes touch skills/penpot/SKILL.md and CHANGELOG.md only. Gates: npm test → 823 tests, 821 pass / 1 fail / 1 skipped, the same pre-existing, unrelated local-install.test.mjs:1860 mongodb-manifest failure recorded in the review (no build/lint scripts exist). No regressions introduced.

Critical

High

Medium

skills/penpot/SKILL.md:195 — the self-critique step hard-codes rsvg-convert, but that binary is not on PATH in this environment (command -v rsvg-convert → not found; the only copies live inside flatpak runtime sandboxes), while resvg 0.47 (/usr/bin/resvg), inkscape and ImageMagick are. An agent following the skill verbatim gets "command not found" with no fallback, and Prerequisites (SKILL.md:29-33) lists only PENPOT_URL/PENPOT_TOKEN. Suggested fix: make the step conditional — e.g. "if rsvg-convert is installed (or use the equivalent resvg input.svg -o /tmp/preview.png)", and add a one-line note to Prerequisites that rsvg-convert/resvg is optional and only needed for this step.
skills/penpot/SKILL.md:180 — the reference-layer advice is not achievable with the extension's tools: no penpot_* tool exposes Penpot's lock/blocked field (no locked/blocked anywhere in extensions/penpot/src/shapes.ts or src/tools/image.ts — the only "lock" is the proportionLock aspect-ratio flag at src/tools/image.ts:219), and dropping the raster with penpot_add_image stages an add-obj that the next penpot_commit writes. So "lock it in Penpot" (a manual UI action the API cannot do) plus "keep it out of the committed screen" contradicts the only tool available for adding it. Suggested fix: state that locking is a manual Penpot-UI step (the extension cannot set it), and that if the raster is staged with penpot_add_image it must be dropped with penpot_discard before the final commit — or simply say the layer is not usable with the current tools.
skills/penpot/SKILL.md:151 — "stage a new colour with penpot_create_color and state the addition" does not work in the same pass: asset-name → id resolution reads the committed library from the live get-file body (extensions/penpot/src/libraryRefs.ts:52, fed by ensureChangesetFromFile in extensions/penpot/src/staging.ts:100-120), and staged add-color changes are never merged into that body, so a later fill: "new-colour" fails as an unknown name. Suggested fix: add "…and commit it (the changeset is not visible to name resolution) before referencing it by name; until then use the literal hex".

Low

skills/penpot/SKILL.md:111 — the loop "penpot_commit → look at the result → refine" implies visual feedback on the committed screen, but Penpot output cannot be rendered back (there is no frame/preview-to-PNG tool; penpot_export_library produces a .penpot ZIP, not an image, and penpot_get_file returns structure only). Suggested fix: reword to "penpot_commit → re-read with penpot_get_file and compare the committed structure against your description → refine", matching the clarification already at line 171.
skills/penpot/SKILL.md:158 — "express it with penpot_add_frame layout … rather than dumping absolute coordinates. Fall back to x/y only where no layout frame can express the intent" reads as if x/y can be omitted, but both are required arguments on penpot_add_frame (extensions/penpot/src/tools/frame.ts:113-114). Suggested fix: add "every frame still needs its own x/y for its position — the layout props govern the spacing inside it".
skills/penpot/SKILL.md:149 — the role list "(surface, primary, muted, accent, border)" reads like library asset names, but the committed library exports flip7-* names only (extensions/penpot/src/librarySpec.ts:242-259: flip7-surface, flip7-card, flip7-ink, flip7-gold, …). An agent may pass a literal role word and hit an unknown-name error. Suggested fix: say the role is a concept resolved to the library's assets, and name the real ones (e.g. "surface → flip7-surface, ink → flip7-ink").
skills/penpot/SKILL.md:3 — the rewritten description drops the previous read/inspect trigger ("checking what a file or library contains"), even though When to use still lists "Inspect a file or its linked libraries before composing" (line 24). This can stop the skill from triggering on "what's in this Penpot file?" requests. Suggested fix: re-add a clause such as "or inspecting a file's and its linked libraries' assets before composing".
CHANGELOG.md:9 — every penpot feature lands an ## [Unreleased] / ### Added bullet (issue #211 immediately above, #210, #209, #208 …), but this branch adds none for the image → design workflow. Suggested fix: add an ### Added bullet summarising the new image → design path and the rsvg-convert self-critique step (mirroring how the forgejo-plumber / victorialogs-debugging skill additions were logged at CHANGELOG.md:43-44).

Documentation

Updated files:

README.md

## 212: Add the image-to-design workflow to skills/penpot/SKILL.md Closes #212 — [212](https://git.excelera.net/david/pi-extensions-and-skills/issues/212). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 7m 43s. ## Review findings I'll start by examining the relevant files and project configuration.Let me verify the findings against the extension source.All findings verified. Now let me apply the fixes.Now the CHANGELOG entry. Let me insert a bullet at the top of the `### Added` section.Now let me validate the frontmatter and run the project test gate.All 8 findings addressed, tests match the pre-existing baseline (1 unrelated failure). Let me confirm the working-tree diff scope.# Review Findings — 212 ## Summary Fixed all eight findings (4 Medium, 4 Low) as documentation-accuracy corrections against the extension source: the SVG self-critique step now detects `rsvg-convert`/`resvg` and states the renderer is optional in *Prerequisites*; the reference-layer section records that locking is a manual Penpot-UI step and that a staged raster must be dropped with `penpot_discard`; the colour-by-role section explains staged assets are invisible to name resolution until committed and names the real `flip7-*` assets; the loop, spacing and description clauses were corrected to match observable behaviour; and a CHANGELOG `### Added` bullet was added. Changes touch `skills/penpot/SKILL.md` and `CHANGELOG.md` only. Gates: `npm test` → 823 tests, **821 pass / 1 fail / 1 skipped**, the same pre-existing, unrelated `local-install.test.mjs:1860` mongodb-manifest failure recorded in the review (no build/lint scripts exist). No regressions introduced. ## Critical ## High ## Medium - [x] `skills/penpot/SKILL.md:195` — the self-critique step hard-codes `rsvg-convert`, but that binary is **not on `PATH`** in this environment (`command -v rsvg-convert` → not found; the only copies live inside flatpak runtime sandboxes), while `resvg` 0.47 (`/usr/bin/resvg`), `inkscape` and ImageMagick are. An agent following the skill verbatim gets "command not found" with no fallback, and `Prerequisites` (SKILL.md:29-33) lists only `PENPOT_URL`/`PENPOT_TOKEN`. Suggested fix: make the step conditional — e.g. "if `rsvg-convert` is installed (or use the equivalent `resvg input.svg -o /tmp/preview.png`)", and add a one-line note to *Prerequisites* that `rsvg-convert`/`resvg` is optional and only needed for this step. - [x] `skills/penpot/SKILL.md:180` — the reference-layer advice is not achievable with the extension's tools: no `penpot_*` tool exposes Penpot's lock/`blocked` field (no `locked`/`blocked` anywhere in `extensions/penpot/src/shapes.ts` or `src/tools/image.ts` — the only "lock" is the `proportionLock` aspect-ratio flag at `src/tools/image.ts:219`), and dropping the raster with `penpot_add_image` stages an `add-obj` that the next `penpot_commit` writes. So "lock it in Penpot" (a manual UI action the API cannot do) plus "keep it out of the committed screen" contradicts the only tool available for adding it. Suggested fix: state that locking is a **manual Penpot-UI** step (the extension cannot set it), and that if the raster is staged with `penpot_add_image` it must be dropped with `penpot_discard` before the final commit — or simply say the layer is not usable with the current tools. - [x] `skills/penpot/SKILL.md:151` — "stage a new colour with `penpot_create_color` and state the addition" does not work in the same pass: asset-name → id resolution reads the **committed** library from the live `get-file` body (`extensions/penpot/src/libraryRefs.ts:52`, fed by `ensureChangesetFromFile` in `extensions/penpot/src/staging.ts:100-120`), and staged `add-color` changes are never merged into that body, so a later `fill: "new-colour"` fails as an unknown name. Suggested fix: add "…and commit it (the changeset is not visible to name resolution) before referencing it by name; until then use the literal hex". ## Low - [x] `skills/penpot/SKILL.md:111` — the loop "`penpot_commit` → look at the result → refine" implies visual feedback on the committed screen, but Penpot output cannot be rendered back (there is no frame/preview-to-PNG tool; `penpot_export_library` produces a `.penpot` ZIP, not an image, and `penpot_get_file` returns structure only). Suggested fix: reword to "`penpot_commit` → re-read with `penpot_get_file` and compare the committed structure against your description → refine", matching the clarification already at line 171. - [x] `skills/penpot/SKILL.md:158` — "express it with `penpot_add_frame` layout … rather than dumping absolute coordinates. Fall back to `x`/`y` only where no layout frame can express the intent" reads as if `x`/`y` can be omitted, but both are required arguments on `penpot_add_frame` (`extensions/penpot/src/tools/frame.ts:113-114`). Suggested fix: add "every frame still needs its own `x`/`y` for its position — the layout props govern the spacing *inside* it". - [x] `skills/penpot/SKILL.md:149` — the role list "(surface, primary, muted, accent, border)" reads like library asset names, but the committed library exports `flip7-*` names only (`extensions/penpot/src/librarySpec.ts:242-259`: `flip7-surface`, `flip7-card`, `flip7-ink`, `flip7-gold`, …). An agent may pass a literal role word and hit an unknown-name error. Suggested fix: say the role is a concept resolved to the library's assets, and name the real ones (e.g. "surface → `flip7-surface`, ink → `flip7-ink`"). - [x] `skills/penpot/SKILL.md:3` — the rewritten description drops the previous read/inspect trigger ("checking what a file or library contains"), even though *When to use* still lists "Inspect a file or its linked libraries before composing" (line 24). This can stop the skill from triggering on "what's in this Penpot file?" requests. Suggested fix: re-add a clause such as "or inspecting a file's and its linked libraries' assets before composing". - [x] `CHANGELOG.md:9` — every penpot feature lands an `## [Unreleased] / ### Added` bullet (issue #211 immediately above, #210, #209, #208 …), but this branch adds none for the image → design workflow. Suggested fix: add an `### Added` bullet summarising the new image → design path and the `rsvg-convert` self-critique step (mirroring how the `forgejo-plumber` / `victorialogs-debugging` skill additions were logged at `CHANGELOG.md:43-44`). ## Documentation Updated files: - README.md

david added 3 commits

2026-09-15 07:15:57 +00:00