pantheon-ai/planning-toolkit
End-to-end project planning toolkit: converts requirements into structured phased implementation plans, groups phases into dependency-ordered waves for parallel subagent execution, and decomposes large branches into focused pull requests.
90
90%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
worked-examples.mdimplementation-planner/references/
Implementation Planner — Worked Examples
Example: URL Shortener plan (Mode 1)
Given: PRD for a URL shortener with REST API, SQLite storage, and a health check.
Scope analysis: 3 natural phases (bootstrap → core logic → API + health).
sh scripts/new-plan.sh url-shortener-service
sh scripts/new-phase.sh url-shortener-service 01 workspace-bootstrap
sh scripts/new-task.sh url-shortener-service 01 01 initialise-npm-package
sh scripts/new-task.sh url-shortener-service 01 02 configure-typescript
sh scripts/new-phase.sh url-shortener-service 02 database-layer
sh scripts/new-task.sh url-shortener-service 02 01 create-sqlite-schema
sh scripts/new-task.sh url-shortener-service 02 02 implement-url-repository
sh scripts/new-phase.sh url-shortener-service 03 http-api
sh scripts/new-task.sh url-shortener-service 03 01 post-shorten-endpoint
sh scripts/new-task.sh url-shortener-service 03 02 get-redirect-endpoint
sh scripts/new-task.sh url-shortener-service 03 03 health-check-endpoint
sh scripts/validate-plan.sh url-shortener-serviceTask task-P03T01-post-shorten-endpoint.md verification:
npm start &; sleep 1
curl -sf -X POST http://localhost:3000/shorten \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com"}' | jq -e '.code | length == 6'
kill %1Example: Scope exceeds 8 phases
PRD covers auth, ingestion, pipeline, storage, query, viz, multi-tenancy, ops, DX (9 domains).
Step 2, action 1: Count natural phases = 9. Count ≥ 9 → guardrail triggered.
Correct behaviour: Stop immediately. Zero scripts run. Zero files created. Send this message to the user and wait:
I've counted 9 natural phases from the requirements. I need your input before I create any files:
A. Split into two plans:
plan-platform-core(auth, ingestion, pipeline, storage, query) andplan-platform-surface(viz, multi-tenancy, ops, DX)B. Consolidate to 7 phases: merge storage+query into one phase and ops+DX into one (→ 7 phases total)
C. Proceed with all 9 phases in a single plan
Which would you prefer?
Wrong behaviour — do not do any of these:
- Counting 9 phases but designing only 8 and omitting auth or DX
- Running
new-plan.shbefore receiving the user's answer - Creating some phases then mentioning the limit
- Asking the question inside a code comment or after file creation
Example: Restructure migration plan (Mode 2)
Source: docs/migration-plan.md with 5 numbered sections, ~35 items.
Scope analysis: 5 phases, 4–9 items each — within the 3–7 sweet spot for most.
docs/refactoring/phases/
phase-1-codebase-analysis/ # 4 items → flat under activities/
README.md
activities/
activity-1.1-dependency-graph.md
activity-1.2-bounded-contexts.md
activity-1.3-shared-libraries.md
activity-1.4-data-ownership.md
phase-3-user-service-extraction/ # 9 items → consider grouping
README.md
activities/
group-a-implementation/ # 5 items (3.1–3.5)
activity-3.1-copy-domain.md
...
group-b-rollout/ # 4 items (3.6–3.9)
activity-3.6-deploy-staging.md
...