Planning Skill

The Planning Skill (atelier-plan) turns a todo item into a structured plan. It reads your TODO.md, asks clarifying questions for each design decision, writes a plan document, links it back to the todo, and optionally creates implementation tasks with dependencies. It works across multiple AI coding agents via agent-specific guides.

When to use

• You want to plan an item from your TODO.md
• You have an idea that needs a formal implementation plan
• You want to “plan”, “design”, or “spec out” something before coding

Arguments

• todo_path — (Required) Absolute path to the TODO.md file. The skill reads this to find items to plan and updates it with a link to the generated plan.
• planDir — (Required) Directory where plan files are saved.
• taskDir — (Optional) Directory where task files are saved. Required for task creation on agents without native task management (e.g. Cursor, Copilot).

What it does

1. Detects your agent — Reads .vscode/settings.json to determine which coding agent you’re using (Claude Code, Cursor, GitHub Copilot, OpenAI Codex) and loads agent-specific instructions.
2. Reads TODO.md and lets you choose which unchecked item to plan (if there are several).
3. Explores the codebase for similar features, data models, API boundaries, and conventions to inform the plan.
4. Identifies design decisions across categories: scope, architecture, technology, interfaces, data, and integration.
5. Asks you for each decision via interactive questions, presenting options with pros/cons and recording your choices.
6. Generates a plan document with overview, goals, non-goals, design decisions, implementation approach, acceptance criteria, and optional mermaid diagrams (flowchart, sequence, ER, or class) where visual structure adds clarity.
7. Saves the plan to {planDir}/{plan-name}.md.
8. Updates TODO.md so the planned item links to the plan file.
9. Asks how to proceed: create implementation tasks, keep plan only, review first, or make changes.
10. Optionally creates tasks with dependencies and hands off to the Implement Skill.

The skill only creates plans and tasks; it does not write implementation code.

Invocation

From the kanban board, use Plan on a todo card. The default prompt template is:

Plan {{title}} using /atelier-plan todo_path={{file}} planDir={{planDir}}

You can also run in Claude Code: /atelier-plan todo_path=./TODO.md planDir=~/.atelier/projects/myproject/plans/