Detects .pen files and pencil-plan.md in .moai/design/, loads Pencil MCP, executes batch operations with layout verification, archives screenshots. Invoked from /moai design Phase B2.6 when preconditions are met.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview
name
moai-workflow-pencil-integration
description
Detects .pen files and pencil-plan.md in .moai/design/, loads Pencil MCP, executes batch operations with layout verification, archives screenshots. Invoked from /moai design Phase B2.6 when preconditions are met.
Pencil MCP integration skill for the /moai design Phase B2.6 workflow. Detects .pen files and pencil-plan.md, loads Pencil MCP tools via ToolSearch, parses DSL batch operations, executes them with layout verification, archives screenshots, and produces a run summary report.
This skill is invoked only when Phase B2.6 file/folder preconditions are satisfied. It is never invoked directly by the user.
Quick Reference
Entry Conditions (REQ-PENCIL-001)
Phase B2.6 checks these file/folder preconditions before invoking this skill:
.moai/design/pencil-plan.md exists.
At least one .pen file exists in .moai/design/ or project root.
If either condition fails, Phase B2.6 skips gracefully without error and proceeds to Phase B3 (REQ-PENCIL-002). This skill is not invoked in that case.
When both conditions are met, this skill is invoked and must complete (success or structured error) before Phase B3 begins (REQ-PENCIL-003).
ToolSearch with query "mcp__pencil" returns no matching tool schemas at runtime (REQ-PENCIL-013).
Return this code to the orchestrator. Phase B2.6 ends; orchestrator proceeds to Phase B3. Include Pencil MCP setup guidance: "Install and enable the Pencil MCP server. See Pencil MCP documentation for setup instructions."
PENCIL_CONNECTION_FAILED
mcp__pencil__get_editor_state returns a connection failure, or the open document name does not match the detected .pen file (REQ-PENCIL-006).
Return this code to the orchestrator. Phase B2.6 ends; orchestrator proceeds to Phase B3. Include user action guidance: "Restart Claude Desktop or open the correct .pen file in Pencil before retrying."
PENCIL_PLAN_SYNTAX_ERROR
pencil-plan.md contains tokens outside the DSL Grammar. Collect ALL errors before returning — do not halt on the first (REQ-PENCIL-016).
Return this code with a list of {line_number, offending_text} entries covering all discovered syntax errors. Halt execution. User must correct pencil-plan.md and re-run.
PENCIL_BATCH_FAILED
More from this repository
mcp__pencil__batch_design fails on the initial attempt AND the single retry (total 2 attempts) for a given batch (REQ-PENCIL-015).
Return this code with the failing batch index. Halt further batch execution. User must investigate Pencil state and re-run.
Implementation Guide
Step 1: ToolSearch Preloading (REQ-PENCIL-004)
Before issuing any mcp__pencil__* call, invoke ToolSearch:
ToolSearch(query="mcp__pencil")
If ToolSearch returns no matching tool schemas, return PENCIL_MCP_UNAVAILABLE immediately. Do not attempt any mcp__pencil__* calls.
If ToolSearch returns one or more matching schemas, proceed to Step 2.
Step 2: Editor State Verification (REQ-PENCIL-005)
Identify the .pen file detected by Phase B2.6 precondition check (the file found in .moai/design/ or project root).
Call mcp__pencil__get_editor_state and inspect the response:
If the response references the expected .pen file name: proceed to Step 3.
If the response indicates a connection failure or references a different document: return PENCIL_CONNECTION_FAILED with recovery guidance. Do not proceed.
parentId, nodeId are double-quoted string literals.
index is a non-negative integer.
{...props} is a JSON-serializable object literal per Pencil's batch_design schema.
Line comments (// ...) and block comments (/* ... */) are permitted and ignored.
Batch boundaries are delimited by ## Batch <N> Markdown headings (N is a positive integer starting from 1).
Each operation occupies exactly one line.
Any token that does not match I(...), M(...), R(...), a comment, or a batch heading is a syntax error.
Syntax error collection (REQ-PENCIL-016): Scan the entire file before returning. Collect every line containing an unrecognized token as {line_number, offending_text}. Do not halt on the first error. If any syntax errors are collected, return PENCIL_PLAN_SYNTAX_ERROR with the complete list.
Batch ordering (REQ-PENCIL-007): Extract batches in declaration order (Batch 1 through Batch N). Preserve this order in execution.
Step 4: Sub-batch Splitting (REQ-PENCIL-008)
For each parsed batch, if the number of operations exceeds 25:
Split into sub-batches of at most 25 operations each.
Preserve the original operation order across sub-batches.
Example: 30 operations → sub-batch A (ops 1-25) + sub-batch B (ops 26-30).
Sub-batches from the same batch are executed sequentially before moving to the next batch.
After all batches complete, list all files in .moai/design/screenshots/ matching the pattern frame-*-*.png.
Sort by filename (ISO8601 timestamp ensures chronological order). Keep the 5 most recent files. Delete any older files using the Write tool (overwrite with empty is insufficient; use Bash if needed to remove files).
Step 7: Summary Report (REQ-PENCIL-012)
Write a summary report to:
.moai/design/pencil-run-<ISO8601-timestamp>.md
The report must contain these sections:
# Pencil Run — <ISO8601-timestamp>## Applied Batches<listeachbatch:batchnumber, operationcount, sub-batchcountifsplit>## Screenshots Saved<listeachscreenshotpathsavedduringthisrun>## Warnings<listanynon-fatalwarningscollectedduringexecution, or "None">
Advanced Patterns
Partial pencil-plan.md Structures
If pencil-plan.md contains batch headings with no operations between them, treat the batch as empty and skip it (emit no batch_design call, no TaskUpdate for that batch). Do not treat an empty batch as a syntax error.
Connection Recovery
If get_editor_state indicates the Pencil app is not open (rather than a document mismatch), return PENCIL_CONNECTION_FAILED with specific guidance: "Open Pencil and load the .pen file before retrying."
Large pencil-plan.md Files
Files with many batches (> 10) will generate many TaskUpdate events. This is expected and intentional per REQ-PENCIL-014 — it allows users to monitor long-running Pencil sessions and prevents timeout confusion.
Works Well With
/moai design Phase B2.6: The only orchestrator that invokes this skill.
moai-workflow-design-context: Provides context about .moai/design/ contents before this skill runs (Phase B2.5).
moai-workflow-gan-loop: Receives Pencil wireframe artifacts for quality evaluation in Phase C.
REQ coverage: REQ-PENCIL-001 through REQ-PENCIL-016
SPEC: SPEC-DESIGN-PENCIL-001 v0.2.0
Version: 1.0.0
