project-planning

name	project-planning
description	Create structured implementation plans with repository research, phased execution, risks, and verification. Use when work is unclear, risky, multi-file, or the user asks for a plan.

Project Planning

Use this skill when work is unclear, spans multiple files, carries hidden risk, or benefits from sequencing before implementation.

Workflow

1. Restate the goal in one sentence.
2. Search the codebase for existing patterns, related tests, and constraints.
3. Decide whether external context is needed. If the user enabled a relevant MCP, load the matching mcp-* skill. If crucial context is unavailable, state the gap and plan around explicit assumptions or ask a focused question.
4. Identify concrete files, dependencies, and likely order of operations.
5. Break the work into small phases that can be verified independently.
6. List risks, rollback considerations, assumptions, and unknowns.
7. Define exact verification commands based on the repository.
8. Always write durable plan artifacts inside the repository so later implementation can reload context without relying on chat history.

Planning Checklist

• Goal and acceptance criteria
• Existing patterns to follow
• Files likely to change
• Dependencies and sequencing
• Risks and rollback notes
• Verification commands

Phase Heuristics

• Put data shape, schema, or contract changes before consumers.
• Put shared types, helpers, or interfaces before dependent files.
• Prefer phases that can be reviewed and verified independently.
• Call out anything that should ship behind a flag or be rollout-safe.

Relevant MCP Skills

• mcp-context7 for official library and framework docs
• mcp-github for issues, PRs, CI, releases, and discussions
• mcp-figma for design-driven implementation planning
• mcp-sentry for production issue or release context
• mcp-playwright for browser-flow or UI verification planning
• mcp-open-bridge for architecture comparison, plan stress-testing, and second-pass reasoning

Required Plan Artifacts

Create a folder using this structure:

Before naming the folder, run date +%Y%m%d-%H%M%S or an equivalent command to get <YYYYMMDD-HHMMSS>. If a timestamp cannot be retrieved, use plan/<topic>/.

plan/
└── <topic>-<YYYYMMDD-HHMMSS>/
    ├── README.md
    ├── plan.md
    ├── research/
    │   ├── requirements.md
    │   ├── existing-code.md
    │   └── references.md
    └── phases/
        ├── phase-1-<name>.md
        ├── phase-2-<name>.md
        └── ...

Rules:

• plan.md is the single source of truth for implementation.
• README.md is the quick human summary.
• research/ captures inputs, existing patterns, and external references.
• phases/ contains execution-ready steps with verification.

Output

Return a concise plan summary with these sections and the saved artifact path; do not duplicate the full file contents in chat:

• Goal
• Acceptance criteria
• Existing patterns
• Files to change
• Phases
• Risks and unknowns
• Verification
• Recommended first implementation step

Read reference.md only when templates, estimation cues, or extra risk prompts would improve the plan.