planning · diff
v1.0.0 to v1.1.0
22 added, 277 removed. Audit A to A.
---
name: planning
description: Creates and manages persistent markdown planning files (task_plan.md, findings.md, progress.md) for complex task execution. Use when starting multi-step tasks, research projects, or any task requiring >5 tool calls. Solves the EXECUTION problem - staying focused during long-running tasks.
allowed-tools: Read Write Edit Bash Glob Grep
compatibility: Requires Bash shell access for file operations
user-invocable: true
metadata:
author: 23blocks
- version: 1.0.0
- ---
-
- # AI Maestro Planning Skill
-
- ## The Problem This Solves: EXECUTION
-
- This skill solves the **execution problem** - losing focus during complex tasks:
-
- | Problem | Symptom | This Skill Fixes It |
- |---------|---------|---------------------|
- | Goal drift | Forgot original objective after 50 tool calls | Re-read plan before decisions |
- | Lost progress | Can't remember what phase I'm in | Phase tracking in task_plan.md |
- | Repeated errors | Make same mistake twice | Error log prevents repetition |
- | Session loss | Can't resume after /clear | Planning files persist on disk |
-
- **Note:** This is different from the Memory skill (which solves recall of past conversations). Planning solves staying focused NOW.
-
- ---
-
- ## Core Principle
-
- ```
- Context Window = RAM (volatile, limited, fast)
- Filesystem = Disk (persistent, unlimited, explicit read required)
-
- Anything important gets written to disk.
- ```
-
- ---
-
- ## Output Directory
-
- Planning output files (`task_plan.md`, `findings.md`, `progress.md`) should be written to:
-
- 1. The directory specified by the `AIMAESTRO_PLANNING_DIR` environment variable (if set)
- 2. Otherwise, `docs_dev/` in the current project root
- 3. Create the directory if it does not exist
-
- Do NOT write planning files to the project root — use `docs_dev/` to avoid cluttering the project.
-
+ version: 1.1.0
---
- ## The 3-File Pattern
-
- Create these files in `docs_dev/` (not the project root or the skill directory):
+ # Planning Files
- | File | Purpose | Update When |
- |------|---------|-------------|
- | `task_plan.md` | Goals, phases, decisions, errors | After each phase |
- | `findings.md` | Research, discoveries, resources | During research |
- | `progress.md` | Session log, test results | Throughout session |
+ The context window is lost on `/clear`, compaction or a new session; files on disk are not. For a long task, keep the goal, what you have learned and where you are in three files, so you (or the next session) can pick up from them. This is about the current task; the memory-search skill covers what happened in earlier sessions.
- ---
+ Your in-session todo list is still the right place for step-by-step tracking. The files hold what must survive the session.
- ## Quick Start
+ ## Where the files go
- Before any complex task (3+ steps):
+ `$AIMAESTRO_PLANNING_DIR` if set, otherwise `docs_dev/` in the project root (keeps the root clean). Start from the templates next to this file:
```bash
- # 1. Determine output directory
PLAN_DIR="${AIMAESTRO_PLANNING_DIR:-docs_dev}"
mkdir -p "$PLAN_DIR"
-
- # 2. Create planning files from templates
- cat ~/.claude/skills/planning/templates/task_plan.md > "$PLAN_DIR/task_plan.md"
- cat ~/.claude/skills/planning/templates/findings.md > "$PLAN_DIR/findings.md"
- cat ~/.claude/skills/planning/templates/progress.md > "$PLAN_DIR/progress.md"
-
- # 3. Edit task_plan.md with your specific goal and phases
- ```
-
- Then follow the rules below.
-
- ---
-
- ## The 6 Rules
-
- ### Rule 1: Create Plan First
-
- **NEVER start a complex task without creating task_plan.md.**
-
- Before writing any code or making any changes:
- 1. Create task_plan.md with clear goal
- 2. Break work into phases
- 3. List key questions to answer
-
- ### Rule 2: Read Before Decide
-
- Before any major decision, re-read the plan:
-
- ```bash
- cat "${AIMAESTRO_PLANNING_DIR:-docs_dev}/task_plan.md" | head -50
- ```
-
- This refreshes your goals in the context window, preventing drift.
-
- ### Rule 3: Update After Act
-
- After completing any phase:
- - Mark phase as `[x]` complete
- - Update status section
- - Log any errors encountered
- - Note files created/modified
-
- ### Rule 4: The 2-Action Rule
-
- After every 2 search/view/browse operations, **immediately** save key findings to findings.md.
-
- Visual content (screenshots, PDFs, browser results) doesn't persist in context. Write it down NOW.
-
- ### Rule 5: Log ALL Errors
-
- Every error goes in task_plan.md:
-
- ```markdown
- ## Errors Encountered
- | Error | Attempt | Resolution |
- |-------|---------|------------|
- | FileNotFoundError | 1 | Created missing config |
- | API timeout | 2 | Added retry with backoff |
- ```
-
- This prevents repeating the same mistakes.
-
- ### Rule 6: Never Repeat Failures
-
- ```
- if action_failed:
- next_action != same_action
- ```
-
- After a failure, CHANGE your approach. Don't retry the exact same thing.
-
- ---
-
- ## The 3-Strike Protocol
-
- **Attempt 1: Diagnose & Fix**
- - Read error carefully
- - Identify root cause
- - Apply targeted fix
-
- **Attempt 2: Alternative Approach**
- - Same error? Try different method
- - Consider different tools/libraries
- - NEVER repeat exact failing action
-
- **Attempt 3: Broader Rethink**
- - Question assumptions
- - Search for similar issues
- - Update task plan with learnings
-
- **After 3 Failures: Escalate**
- - Explain all approaches tried
- - Share specific error messages
- - Ask user for guidance
-
- ---
-
- ## When to Read vs Write
-
- | Situation | Action | Why |
- |-----------|--------|-----|
- | Just wrote a file | DON'T read | Content is in context |
- | Viewed image/PDF | Write findings NOW | Visual content doesn't persist |
- | Browser returned data | Write to findings.md | Screenshots don't persist |
- | Starting new phase | Read task_plan.md | Re-orient from plan |
- | Error occurred | Read relevant file | Need current state |
- | Resuming after gap | Read ALL planning files | Recover context |
-
- ---
-
- ## The 5-Question Reboot
-
- Lost? Answer these questions:
-
- | Question | Find Answer In |
- |----------|----------------|
- | Where am I? | Current phase in task_plan.md |
- | Where am I going? | Remaining phases in task_plan.md |
- | What's the goal? | Goal section in task_plan.md |
- | What have I learned? | findings.md |
- | What have I done? | progress.md |
-
- ---
-
- ## When to Use This Skill
-
- **USE for:**
- - Multi-step tasks (3+ steps)
- - Research projects
- - Building features
- - Tasks requiring >5 tool calls
- - Anything needing organization
-
- **SKIP for:**
- - Simple questions
- - Single-file edits
- - Quick lookups
- - Trivial changes
-
- ---
-
- ## Anti-Patterns
-
- | DON'T | DO Instead |
- |-------|------------|
- | Use TodoWrite for complex tasks | Create task_plan.md file |
- | State goals once and forget | Re-read plan before decisions |
- | Hide errors and retry | Document errors in plan |
- | Stuff everything in context | Store large content in files |
- | Start executing immediately | Create plan FIRST |
- | Repeat failed actions | Track attempts, change approach |
-
- ---
-
- ## Integration with Memory Skill
-
- Planning and Memory solve **different problems**:
-
- | Skill | Problem | Timescale |
- |-------|---------|-----------|
- | **Memory** | "What did we discuss last week?" | Days/weeks/months |
- | **Planning** | "What am I supposed to do next?" | Minutes/hours |
-
- Use BOTH for complex work:
- 1. **Memory** - Search for past decisions and context
- 2. **Planning** - Stay focused during execution
-
- ---
-
- ## Templates
-
- Templates are in `~/.claude/skills/planning/templates/`:
-
- - `task_plan.md` - Phase and progress tracking
- - `findings.md` - Research and discoveries
- - `progress.md` - Session logging
-
- **Note:** The template path depends on how the skill was installed:
- - **User scope** (global): `~/.claude/skills/planning/templates/`
- - **Project scope** (local): `<project>/.claude/skills/planning/templates/`
-
- Copy to `docs_dev/` and customize.
-
- ---
-
- ## Example Workflow
-
+ cp "${CLAUDE_SKILL_DIR}"/templates/{task_plan,findings,progress}.md "$PLAN_DIR"/
```
- User: "Build a new authentication system"
- 1. CREATE PLAN
- - Copy templates to docs_dev/
- - Define goal: "Implement JWT authentication"
- - Break into phases: Research, Design, Implement, Test, Document
-
- 2. EXECUTE PHASE 1 (Research)
- - Search memory: memory-search.sh "authentication"
- - Search docs: docs-search.sh "auth patterns"
- - Write findings to findings.md
- - Mark Phase 1 complete in task_plan.md
-
- 3. EXECUTE PHASE 2 (Design)
- - READ task_plan.md (refresh goals)
- - READ findings.md (recall research)
- - Design approach, document decisions
- - Mark Phase 2 complete
-
- 4. CONTINUE...
- - Always read plan before major decisions
- - Always update after completing phases
- - Always log errors
- ```
+ `${CLAUDE_SKILL_DIR}` is this skill's folder. If your agent does not expand it, the templates are in `templates/` beside this SKILL.md. If the files already exist, you are resuming: read them instead of overwriting.
- ---
+ | File | Holds | Update |
+ |------|-------|--------|
+ | `task_plan.md` | Goal, phases with checkboxes, decisions and why, errors and how they were resolved | When a phase completes or a decision is made |
+ | `findings.md` | What you learned: requirements, research, code facts, sources | When you learn something you would need after losing context |
+ | `progress.md` | Session log: actions, files changed, test results | At phase boundaries and before stopping |
- ## Troubleshooting
+ Cut the template sections the task does not need, and replace the generic phases with the task's real ones.
- **Templates not found:**
- ```bash
- ls ~/.claude/skills/planning/templates/
- ```
+ ## Using them
- If missing, reinstall the skill or copy from AI Maestro repo.
+ - **Starting a phase or resuming after a gap:** read `task_plan.md` (and the other two when resuming). This puts the goal back in context.
+ - **After viewing images, PDFs or browser pages:** write the relevant facts into `findings.md`; that content is the first to be lost when context is compacted.
+ - **When an attempt fails:** add it to the errors table with what you tried, so a later session does not repeat it. After three different failed approaches, stop and ask the user, listing what you tried.
+ - **Before stopping:** update `progress.md` and the phase checkboxes so the next session starts from the right place.
- **Forgot the goal:**
- ```bash
- cat "${AIMAESTRO_PLANNING_DIR:-docs_dev}/task_plan.md" | head -20
- ```
+ A quick way to see where things stand:
- **Lost track of progress:**
```bash
- grep -E "^\s*-\s*\[" "${AIMAESTRO_PLANNING_DIR:-docs_dev}/task_plan.md"
+ grep -nE '^\s*-\s*\[' "${AIMAESTRO_PLANNING_DIR:-docs_dev}/task_plan.md"
```
- Shows all checkboxes and their status.
+ Skip this skill for questions, quick lookups and single-file edits.