planning

1# AI Maestro Planning
2 
3Solve the execution problem -- staying focused during complex, multi-step tasks. Uses persistent markdown files to track goals, findings, and progress so you never lose context. Part of the [AI Maestro](https://github.com/23blocks-OS/ai-maestro) suite.
4 
5## When to Use
6 
7- Multi-step tasks (3+ steps)
8- Research projects
9- Building features requiring >5 tool calls
10- Any task where you might lose track of the goal
11 
12## The 3-File Pattern
13 
14Create in `docs_dev/` (or `$AIMAESTRO_PLANNING_DIR`):
15 
16| File | Purpose | Update When |
17|------|---------|-------------|
18| `task_plan.md` | Goals, phases, decisions, errors | After each phase |
19| `findings.md` | Research, discoveries, resources | During research |
20| `progress.md` | Session log, test results | Throughout session |
21 
22## Quick Start
23 
24```bash
25PLAN_DIR="${AIMAESTRO_PLANNING_DIR:-docs_dev}"
26mkdir -p "$PLAN_DIR"
27```
28 
29Then create `task_plan.md` with:
30```markdown
31# Task: [Goal]
32 
33## Phases
34- [ ] Phase 1: Research
35- [ ] Phase 2: Design
36- [ ] Phase 3: Implement
37- [ ] Phase 4: Test
38 
39## Decisions
40| Decision | Rationale | Date |
41|----------|-----------|------|
42 
43## Errors Encountered
44| Error | Attempt | Resolution |
45|-------|---------|------------|
46```
47 
48## The 6 Rules
49 
501. **Create plan first** -- Never start complex work without `task_plan.md`
512. **Read before decide** -- Re-read the plan before any major decision
523. **Update after act** -- Mark phases complete, log what changed
53…