openpencil-design-orchestrator

name

openpencil-design-orchestrator

description

Orchestrate Pencil/OpenPencil design work through MCP using a staged workflow: preflight, planning, skeleton, section content, refinement, and safe fallback. Use when working with Pencil/OpenPencil, .fig/.pen design files, MCP-based design editing, or when Claude Code, Codex, Cursor, or Windsurf needs reliable prompt patterns, client setup guidance, and risk controls for AI-assisted design changes.

OpenPencil Design Orchestrator

Use this skill to turn vague Pencil/OpenPencil requests into a controlled multi-step workflow. Default to MCP-first execution. Prefer small, verifiable edits over one-shot generation.

Quick Start

1. Run scripts/preflight-check.sh when the environment or MCP connectivity is unknown.
2. Read references/prompt-framework.md before drafting or executing prompts.
3. Read references/client-adapters.md when the user mentions Claude Code, Codex, Cursor, or Windsurf setup.
4. Read references/risk-matrix.md when debugging failures or choosing guardrails.
5. Read references/fallback-mode.md when MCP is unavailable or unstable.

Workflow

Step 1 - Preflight

• Confirm Pencil/OpenPencil is running if the workflow depends on desktop-hosted MCP.
• Confirm whether transport is stdio or HTTP.
• Confirm openpencil-mcp is installed when using MCP.
• Read the current file/page tree before proposing mutations.
• Refuse giant blind edits when the current structure is unknown.

Step 2 - Planning

• Translate the request into pages, sections, components, tokens, and execution order.
• Resolve ambiguity before editing.
• Ask for confirmation only when ambiguity materially changes layout or scope.
• Prefer explicit checkpoints over creative guessing.

Step 3 - Skeleton

• Create only structural scaffolding: pages, frames, sections, containers, autolayout, naming.
• Avoid visual polish and long-form copy generation in this phase.
• Keep hierarchy obvious and reusable.

Step 4 - Section Content

• Edit one section at a time.
• Re-read the relevant nodes before each mutation batch.
• Report what changed: nodes touched, nodes created, styles/tokens applied, unresolved conflicts.
• Stop when cross-section drift appears.

Step 5 - Refinement

• Refine spacing, alignment, typography consistency, color/token consistency, and emphasis hierarchy.
• Avoid restructuring information architecture unless the user explicitly requests it.
• Preserve the approved skeleton.

Step 6 - Save / Handoff

• Save only after confirming the changed scope.
• Summarize what changed and any remaining weak spots.
• Offer a next pass rather than silently widening the change scope.

Core Operating Rules

• Prefer MCP-first workflows; use file-level fallback only when MCP is unavailable or unsuitable.
• Prefer stdio for local interactive use and HTTP for controlled automation or remote workflows.
• Treat eval as high risk. Do not rely on it by default. When using HTTP mode, keep eval disabled unless the user explicitly accepts the risk.
• Prefer staged prompts over one-shot “design the whole app” prompts.
• Keep each mutation batch bounded to a page or section whenever possible.
• Re-read tree/node context before writing.
• Stop and report conflicts instead of improvising through them.

Reference Routing

• For prompt wording and reusable templates, read references/prompt-framework.md.
• For exact phase ordering and mutation discipline, read references/workflow-sequence.md.
• For agent/client-specific setup patterns, read references/client-adapters.md.
• For failure modes, mitigations, and known risks, read references/risk-matrix.md.
• For degraded-mode operation without MCP, read references/fallback-mode.md.

Scripts

• scripts/preflight-check.sh
  • Check whether openpencil-mcp exists.
  • Inspect common MCP config locations.
  • Print a short readiness report.
• scripts/scaffold-phase-prompt.py
  • Generate phase-specific prompt scaffolds for planning, skeleton, section, refine, and safety.

Task Fit Guidance

Use this skill for:

• Pencil/OpenPencil MCP orchestration
• staged design prompt generation
• design read/write workflows through coding agents
• design audits, diff reviews, export checks, and token/consistency analysis

Do not use this skill as the primary path for:

• unconstrained one-shot whole-product generation
• unreviewed destructive bulk edits
• security-insensitive automation that assumes unrestricted eval
• fake/live-edit claims when running in fallback-only mode

Output Expectations

When using this skill, structure the response around:

1. Current mode (MCP-first, HTTP automation, or fallback)
2. Current phase
3. Exact scope being changed
4. Risks / blockers
5. Next action

Keep outputs operational. Do not bury the active scope or failure condition inside long prose.