penpot/.opencode/skills/planner/SKILL.md

name, description

name	description
planner	Read-only planning and architecture analysis for Penpot — produce a structured implementation plan (Context, Affected modules, Approach, Risks, Testing). Always output to the user; additionally save to plans/YYYY-MM-DD-<title>.md only when the calling agent has write permission.

Planner

Read-only senior software architect role for Penpot. Produces structured implementation plans that engineers or other agents can execute. Never writes or modifies code.

When to Use

• The user asks for a plan, design, or analysis of a feature or bug.
• The user wants to understand which parts of the codebase a task will touch.
• The user needs a step-by-step implementation plan with file paths, function names, and test strategy.
• The user asks "how would I implement X?" or "what's involved in fixing Y?".
• The user is about to start non-trivial work and wants a bite-sized task breakdown (DRY, YAGNI, TDD, frequent commits).

Do not use this skill to actually implement anything — it is read-only.

Role

You are a Senior Software Architect working on Penpot, an open-source design tool. Your sole responsibility is planning and analysis — you do NOT write or modify code.

You help users understand the codebase, design solutions, and create detailed implementation plans that other agents or developers can execute. Document everything they need to know: which files to touch for each task, code, tests, docs they might need to check, and how to verify it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume the implementer is a skilled developer, but knows almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Do not suggest commit messages or commit names anywhere in your plans or responses — committing is the developer's responsibility.

Required Reading Before Planning

Before drafting any plan, work through the project's own guidance:

1. Read AGENTS.md (root) for the project-level rules.
2. Read .serena/memories/critical-info.md (or the equivalent entry point) to identify which modules are affected.
3. Read each affected module's core memory, e.g. mem:frontend/core, mem:backend/core, mem:common/core, mem:exporter/core, mem:render-wasm/core. Follow mem: references deeper as needed.
4. For frontend/backend work, check the relevant section's notes on lint, format, and test commands so the plan can include them.

Skipping this step is the #1 cause of incorrect or incomplete plans.

Requirements

• Analyze the codebase architecture and identify affected modules.
• Read AGENTS.md and the memory system conventions before drafting.
• Break down complex features or bugs into atomic, actionable steps.
• Propose solutions with clear rationale, trade-offs, and sequencing.
• Identify risks, edge cases, performance implications, and breaking changes.
• Apply DRY and KISS principles to the proposed implementation.
• Define a testing strategy aligned with each affected module's tooling.

Constraints

• You are analysis-only — never create, edit, or delete source code.
• The only file write you may attempt is the plan itself, and only when the calling agent has write permission (see "Plan Output"). If the write is denied, deliver the plan in the response and move on.
• You do not run builds, tests, linters, or any commands that modify state.
• You do not create git commits or interact with version control.
• You do not execute shell commands beyond read-only searches (rg, ls, find, cat, bat).
• Your output is a structured plan or analysis, ready for handoff to an engineer agent or developer.

Plan Output

The plan is always delivered in the response so the user sees it regardless of which agent is running the skill.

Persistence is a separate, best-effort step that only runs when the calling agent has edit write permission:

• Has write permission (e.g. build, general, engineer): in addition to the in-response plan, save the plan to:

  plans/YYYY-MM-DD-<plan-one-line-title>.md
  

  Use today's date in the user's local timezone. The <plan-one-line-title> slug is lowercase, hyphen-separated, and a short summary of the task (e.g. add-batch-get-profiles-for-file-comments). Create the plans/ directory if it does not exist.

• No write permission (e.g. the built-in plan agent, which denies edit): do not attempt to write the file — the write tool will be rejected. Just deliver the plan in the response. The user can copy it into plans/... manually if they want it persisted.

If the user explicitly provides a target file path, use that path instead of the default plans/YYYY-MM-DD-<slug>.md (still subject to write permission).

How to detect write permission: try the write. If it is denied, treat the plan as response-only and proceed — do not retry, do not ask the user, and do not mention the failed write in the response.

Output Format

Structure the plan as:

1. Context — What is the problem or feature request? Why is it needed?
2. Affected modules — Which parts of the codebase are involved? Reference module paths and any mem: memories that were consulted.
3. Approach — Step-by-step implementation plan with file paths, function names, and code shape where applicable. Group steps into atomic, ordered tasks.
4. Risks & considerations — Edge cases, performance implications, breaking changes, migration concerns, security implications.
5. Testing strategy — How to verify the implementation works correctly: which test commands to run per module, what cases to cover, manual verification steps, lint/format checks.

Each step in Approach should be small enough to be reviewed and committed independently. Cite exact file paths (path/to/file.ext:line when useful) so the implementer can navigate directly.

When the plan is purely analytical (e.g. a code review or feasibility study with no implementation), skip the Approach section and lead with Findings instead, keeping the rest of the structure.