Planning setup

Planning Setup

I scaffold persistent planning files for complex work:

• Three planning files (task_plan.md, findings.md, progress.md)
• A planning rules document the project can reference
• A snippet for the repo's agent instructions file or files

This skill is written to stay portable across Codex, Claude Code, and OpenCode. Prefer capability-based behavior over product-specific commands or file names.

When To Use This

• Use this skill when the work needs durable context across restarts, handoffs, or long multi-step implementation.
• For short single-session tasks, prefer the agent's built-in planner or task list if one exists.
• If the repo already has planning files, update them instead of creating duplicates.

Setup Intake

Ask at most four questions, using structured choice prompts when the client supports them. If it does not, ask concise inline questions using the options below.

1. Project name and goal: Free text plus one sentence describing the outcome.
2. Phase strategy:
   • Suggest phases from the goal (Recommended): Fastest start, good when the user has not preplanned.
   • User provides phases: Best when the workflow is already known.
   • Hybrid: Agent drafts phases, user edits.
3. Placement:
   • planning/ (Recommended): Keeps the root clean and is easy to discover. Use docs/planning/ when project docs already live under docs/, or the project root for small repos.
   • Instruction file target: Update both AGENTS.md and CLAUDE.md if both exist; update the one shared instructions file if only one exists; create a new AGENTS.md when none exists.
4. Constraints: Free text for non-negotiables, deadlines, tooling, or approval limits.

Apply these defaults without asking, and report them in the final summary:

• Key questions: Draft 3-5 from the goal; the user can edit them in task_plan.md.
• Task tracking: Planning files plus built-in task tracking when available; planning files only when the client has no task tracker.
• Rules placement: planning-rules.md inside the planning directory. Use an existing client-specific rules directory only if the repo already has one.

If the user does not care about a question either, choose the recommended option and state the assumption. If both AGENTS.md and CLAUDE.md already exist, update both unless the user asks for one canonical file only.

What Gets Created

Planning Files (Customized from Templates)

task_plan.md - Phase tracking, decisions, errors

• Goal and current phase
• Phase checklist with status
• Key questions to answer
• Decisions made table
• Errors encountered table

findings.md - Research discoveries, evidence behind decisions

• Requirements section
• Research findings
• Research conclusions table (decisions themselves live in task_plan.md)
• Issues encountered
• Visual/browser findings (with 2-Action Rule reminder; adapt or remove for non-UI work)

progress.md - Session log, test results

• Session-by-session log format
• Test results table
• 5-Question Reboot Check

Agent Instruction Update

Create or append a planning methodology section from templates/agent-instructions-additions.md:

• High-level overview
• When to use planning-with-files
• References to the planning files and rules document
• Apply the same section to every selected instruction file so guidance stays in sync

Planning Rules

Create a reusable rules document from templates/planning-rules.md:

• Create plan first - For complex tasks requiring >5 tool calls
• 2-Action Rule - Save findings after any expensive context-gathering (browsing, web search, long document reads, exploratory code reading)
• Read before decide - Refresh goals before major decisions
• Log all errors - Track and mutate approach

Workflow

After gathering answers or applying defaults:

1. Create the planning directory if needed
2. Generate customized task_plan.md with your goal, phases, and questions
3. Generate findings.md with initial structure
4. Generate progress.md with session log template
5. Generate planning-rules.md in the chosen location
6. Adapt every generated file to the project before finishing:
   • Remove or rename template sections that do not fit the work. A backend migration does not need "Visual/Browser Findings"; a UI project might not need a test-results table yet.
   • Frame the 2-Action Rule around the context-gathering this project will actually do (browsing, web search, long document reads, exploratory code reading) instead of leaving browser-specific wording.
   • Tailor tables, checklists, and placeholder text to the domain. Generic boilerplate signals to future sessions that the file is ignorable.
   • This is Principle 6 ("don't get few-shotted") applied at setup time: the templates are starting points, not fixed output.
7. Update the chosen instruction file or files with the planning methodology snippet
8. Summarize what was created, where it lives, which instruction files were updated, and which defaults were assumed

Integration With Built-In Task Tracking

Planning-with-files can work alongside any built-in task tracker:

• task_plan.md tracks project phases (high-level)
• The task tracker handles individual action items within each phase

This hybrid approach gives you:

• Big-picture phase tracking in files
• Detailed task management in the client, when available
• Full context preserved across sessions

After Setup

Once setup is complete, see references/usage-guide.md for:

• Daily workflow
• When to update each file
• The 5-Question Reboot Test
• Working with the 4 core rules

For the principles behind this system, see references/manus-principles.md.

Templates

All templates are linked directly from this file and customized during setup:

• templates/task_plan.md
• templates/findings.md
• templates/progress.md
• templates/agent-instructions-additions.md
• templates/planning-rules.md