thierryc/glyphs3-to-glyphs4-skill

Migrate a Glyphs 3 plug-in to Glyphs 4

Create a reviewable migrated copy of a Python plug-in. Treat static migration as preparation for a manual launch test in Glyphs 4, not proof of runtime compatibility.

Guardrails

• Preserve the original plug-in or repository.
• Never migrate in place. Refuse an existing output path.
• Never install, execute, reload, restart Glyphs, or change a live Plugins folder unless the user separately requests it.
• Use the Glyphs MCP docs_search and docs_get tools as the primary development knowledge base. Tool namespaces vary by client; resolve them by their final tool names and descriptions.
• Fetch focused official guidance before changing GlyphsApp APIs, plug-in lifecycle methods, selectors, callbacks, bundle metadata, or shape handling.
• Do not call docs_enable_page_resources for normal work. Retrieve pages on demand.
• Prefer the current Glyphs4 branch of schriftgestalt/GlyphsSDK; do not assume a Glyphs 3 template or cached loader is current.
• Keep behavioral changes separate from mechanical migration changes.

Glyphs MCP knowledge-base workflow

Read references/glyphs-mcp-development-kb.md before reviewing API-specific findings.

1. Confirm that docs_search and docs_get are available from the Glyphs MCP server.
2. Establish a documentation baseline before editing:
   • Search plugins and fetch the official plug-in handbook result.
   • Search Info.plist and fetch the Python plug-in template overview and plist template.
   • Search the exact base class, such as GeneralPlugin, ReporterPlugin, FilterWithoutDialog, PalettePlugin, SelectTool, or FileFormatPlugin; fetch its guide, source template, and the relevant plug-in API section.
3. Search each unfamiliar class, property, callback, or selector separately. Prefer short exact symbols such as GSLayer, shapes, or addCallback.
4. Fetch results by the returned doc_id or path. If truncated is true, continue from nextOffset until the relevant section is complete.
5. Record each fetched page's title, docId, sourceKind, sourceUrl, and the migration decision it supports. Include this evidence in the handoff.
6. If the tools are unavailable, report that the Glyphs MCP documentation review is blocked. A static audit may continue, but do not present unverified API or lifecycle changes as migration-ready.

Workflow

1. Resolve the source plug-in or repository, the intended compatibility target (Glyphs 4 only or Glyphs 3 and 4), and a new output path.

2. Connect to the Glyphs MCP development knowledge base and fetch the baseline pages for the detected plug-in family.

3. Obtain or locate a current checkout of the official GlyphsSDK Glyphs4 branch.

4. Audit before copying:

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --sdk "/path/to/GlyphsSDK"
   

5. Read references/migration-review.md. For every API-specific finding, search the bundled Glyphs docs for that class, property, callback, selector, or plug-in type and fetch only the relevant pages.

6. Create the migrated copy and apply conservative framework-import fixes:

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --output "/path/to/new-glyphs4-copy" \
     --sdk "/path/to/GlyphsSDK" \
     --apply-safe-fixes
   

7. Use optional rewrites only after reviewing their impact:

   • Add --rewrite-wildcard-imports to replace simple from GlyphsApp import * statements using symbols found in the Glyphs 4 .pyi stub.
   • Add --replace-loader to copy the SDK template's Contents/MacOS/plugin into each bundle.
   • Add --align-glyphs4-plist to remove legacy update-feed keys absent from the current Glyphs 4 templates. Confirm the plug-in does not depend on its own update feed first.

8. Review the generated migration report and the complete source diff. Fix lifecycle, API, dependency, UI, or mixed-shape findings manually. Tie each API-specific change to a fetched KB page.

9. Validate every bundle:

   • Parse all Python files with the intended Glyphs Python version.
   • Run plutil -lint on every Contents/Info.plist.
   • Confirm NSPrincipalClass, PyMainFileNames, and the principal Python class agree.
   • Compare the bundle structure with the matching current Glyphs 4 SDK template.
   • Recompile .xib files when their interface changed.

10. Hand off a manual test plan. Test a disposable copy in Glyphs 4, exercise every menu entry and callback, inspect Macro Panel and Console output, and test undo, export, drawing, and dependency paths relevant to the plug-in.

Compatibility decision

• For Glyphs 4 only, allow APIs and Python syntax supported by the Glyphs 4 runtime after confirming them in the current stubs.
• For Glyphs 3 and 4, keep a shared code path when practical, gate true API differences with capability checks, and test both apps. Do not add Glyphs 4-only syntax merely for annotations.
• If the plug-in reconstructs layer.paths, layer.components, or layer.shapes, inspect whether it must preserve mixed shape order or newer shape kinds. Never infer that a paths-only rewrite is lossless.

Deliverables

Return the new copy, the migration report, the compatibility target, static validation results, and the remaining manual Glyphs 4 tests. Include a documentation evidence table with each page's title, Glyphs MCP docId, official sourceUrl, and the decision it supports. State clearly that no live installation or runtime test occurred unless it actually did.

Resources

• scripts/migrate_plugin.py: audit and non-destructive copy helper.
• references/migration-review.md: evidence-based review checklist and escalation points.
• references/glyphs-mcp-development-kb.md: exact MCP lookup, paging, evidence, and recovery protocol.
• .mcp.json: Claude Code plug-in connection to the local Glyphs MCP server.
• mcp.json: Cursor plug-in connection to the local Glyphs MCP server.
• .claude-plugin/plugin.json: Claude Code community/plugin metadata; load this folder with claude --plugin-dir.
• .cursor-plugin/plugin.json: Cursor plugin metadata that registers the root SKILL.md and mcp.json.
• agents/openai.yaml: Codex display metadata and Glyphs MCP dependency.