A warm, editorial planning system that turns one goal into a realistic roadmap you can edit, re-review, and execute.

Quick Start · Architecture · API Surface · Service Guides

Live App: https://multi-agent-planner-liard.vercel.app

---

Why This Feels Different

Most planners stop at generation. Multi-Agent Planner stays useful during execution.

Stage	What You Get	Why It Matters
Plan	Multi-step roadmap from one goal	Fast first draft
Review	Dedicated reviewer pass	Better realism and sequencing
Edit	Manual task refinement	Human control where it counts
Operate	Standups, status flow, history	Day-to-day execution clarity

This documentation suite follows the language and visual direction in DESIGN.md.

Architecture

┌───────────────────────────────────────────────────────────────────────────────┐
│                           MULTI-AGENT PLANNER FLOW                           │
└───────────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────┐      POST /generate-plan       ┌──────────────────────────────┐
│ Frontend                     │ ──────────────────────────────> │ AI Service                   │
│ Next.js 16 + React 19        │      POST /re-review-plan      │ FastAPI                      │
│ http://localhost:3000        │ ──────────────────────────────> │ http://localhost:8000        │
│                              │      POST /daily-standup       │                              │
└───────────────┬──────────────┘ ──────────────────────────────> └──────────────┬──────────────┘
                                │                     reviewed plan + standup                   │
                                │ <───────────────────────────────────────────────────────────── │
                                │                                                               │ POST /api/plans
                                │                                                               │ PATCH /api/tasks/:id
                                ▼                                                               ▼
┌──────────────────────────────┐      read/write plans + tasks   ┌──────────────────────────────┐
│ Task API                     │ ───────────────────────────────> │ SQLite planner.db            │
│ Express + TypeScript         │ <─────────────────────────────── │ task-api/data/planner.db     │
│ http://localhost:4000        │           query results          │                              │
└──────────────────────────────┘                                  └──────────────────────────────┘

Stack Snapshot

Layer	Stack	Responsibility
Frontend	Next.js 16 + React 19	Goal capture, task editing, standup and history UI
AI Service	FastAPI + provider fallback chain	Planner/reviewer orchestration and normalization
Task API	Express + TypeScript + SQLite	Durable storage and task lifecycle updates

AI Model Strategy (Quality + Low Latency)

Both planner and reviewer calls use the same ordered fallback chain. The runtime starts on Groq first for strong latency, then fails over to OpenRouter models for resilience.

Order	Provider	Model
1	Groq	llama-3.3-70b-versatile
2	Groq	openai/gpt-oss-120b
3	Groq	qwen/qwen3-32b
4	Groq	llama-3.1-8b-instant
5	OpenRouter	openai/gpt-oss-120b:free
6	OpenRouter	meta-llama/llama-3.3-70b-instruct:free
7	OpenRouter	qwen/qwen3-next-80b-a3b-instruct:free
8	OpenRouter	google/gemma-4-31b-it:free
9	OpenRouter	openai/gpt-oss-20b:free

Why this works well:

• Lower median response times by prioritizing Groq models first.
• Better uptime via provider-level fallback across Groq and OpenRouter.
• Stable structured outputs because planner/reviewer responses are schema-validated before use.

Repository Map

multi-agent-planner/
├─ ai-service/      FastAPI planner/reviewer orchestration
├─ task-api/        Express + SQLite persistence API
├─ frontend/        Next.js planning studio UI
├─ DESIGN.md        Design language and writing direction
└─ README.md

Quick Start

Prerequisites

• Node.js 20+
• Python 3.10+
• npm 10+

1) Create local env files

Copy-Item ai-service/.env.example ai-service/.env
Copy-Item task-api/.env.example task-api/.env
Copy-Item frontend/.env.example frontend/.env.local

Add provider keys in ai-service/.env. Set the same shared value for TASK_API_INTERNAL_TOKEN in ai-service/.env and INTERNAL_API_TOKEN in task-api/.env.

2) Install dependencies

python -m venv ai-service/venv
ai-service/venv/Scripts/python.exe -m pip install -r ai-service/requirements.txt
npm install --prefix task-api
npm install --prefix frontend

3) Run all services (three terminals)

Terminal A:

npm run dev --prefix task-api

Terminal B:

cd ai-service
venv/Scripts/python.exe -m uvicorn main:app --reload --port 8000

Terminal C:

npm run dev --prefix frontend

Open http://localhost:3000.

One-command build validation checklist

npm run build --prefix task-api
npm run build --prefix frontend
python -m compileall ai-service

API Surface

Service	Endpoint	Purpose
AI Service	POST /generate-plan	Build and review the initial task roadmap
AI Service	POST /re-review-plan	Critique manually edited tasks
AI Service	POST /daily-standup	Summarize done, in-progress, and blocked work
AI Service	PATCH /update-task/:id	Securely proxy mutable task updates to Task API
Task API	POST /api/plans	Persist plan and task graph
Task API	GET /api/plans/:id	Fetch one plan with tasks
Task API	PATCH /api/tasks/:id	Update mutable task fields (internal caller)
Task API	DELETE /api/plans/:id	Delete one plan and related tasks

Service Guides

Service	Guide
AI Service	ai-service/README.md
Task API	task-api/README.md
Frontend	frontend/README.md

Troubleshooting

• If Python imports fail, run commands with ai-service/venv/Scripts/python.exe.
• If plan persistence falls back locally, verify Task API on http://localhost:4000.
• If the frontend appears stale, restart Next.js and hard refresh the browser.