feat: Planner agent + Chat task creation — readiness checklist, workspace selector, TaskSpec

[Abernaughty]

Summary

Add a lightweight Planner agent and Chat-based task creation flow. The Chat UI collects structured fields conversationally, while the Planner validates completeness against a Task Readiness Checklist before releasing to the Architect.

Context

Per the Dashboard Workflow Roadmap, Section 2. This is the hybrid approach (Option C) finalized during the brainstorm session. The Planner acts as a gatekeeper — no task reaches the Architect until it meets minimum readiness requirements.

What Shipped (PR #117)

PR #117 delivered the workspace-aware task creation plumbing:

• Backend: POST /workspaces, DELETE /workspaces, POST /workspaces/verify-auth endpoints
• Backend: WorkspaceManager with allowed-directory registry, protected workspace PIN auth, persistence
• Backend: POST /tasks accepts workspace + pin fields, validates against allowed list
• Dashboard: WorkspaceSelector.svelte — dropdown of workspaces, PIN entry for protected workspaces
• Dashboard: workspacesStore — reactive workspace state, auto-selects default, PIN verification
• Dashboard: ChatView.svelte — workspace-aware task submission with PIN forwarding
• Dashboard: tasksStore.create() accepts workspace + options

What's Missing

Phase A — Workspace Selector UX (Small, dashboard-only)

The dropdown shows existing workspaces but has no way to add new ones from the UI.

• "Add directory" option at bottom of workspace dropdown (text input + confirm)
• Path validation feedback (exists / doesn't exist / already added)
• "Create new project" option (scaffolds empty dir + auto-adds to allowed list)
• GitHub repo picker (search + select from user repos) — deferred: needs GitHub MCP integration, can be Phase 3

Phase B — Planner Agent (Large, orchestrator + dashboard)

No Planner agent exists. Tasks currently go directly from Chat → POST /tasks → Architect with no validation or conversational refinement.

Backend (orchestrator):

• planner_node function — lightweight LLM call (no tools), validates TaskSpec against readiness checklist
• PLANNER_MODEL env var (default: gemini-2.0-flash-lite or similar lightweight model)
• Zero tool access enforced for Planner (no configurable tools passed)
• Task Readiness Checklist validation logic (Required / Recommended / Optional tiers)
• Auto-inference of languages/frameworks from workspace contents (orchestrator-level read-only inspection of package.json, pyproject.toml, etc. — not Planner tool call)
• TaskSpec schema (workspace, objective, languages, frameworks, output_type, acceptance_criteria, constraints, related_files)
• New API endpoint: POST /tasks/plan — starts a Planner conversation session
• New API endpoint: POST /tasks/plan/{session_id}/message — sends user message to Planner
• New API endpoint: POST /tasks/plan/{session_id}/submit — confirms and submits to Architect
• SSE events for Planner responses (planner_message event type)

Dashboard (ChatView):

• Conversational Planner flow: user types objective → Planner responds with missing checklist items → user provides info → Planner confirms
• Planner summary display: "Here's what I'll send to the Architect: [summary]. Ready to submit?"
• "Submit to Architect" confirmation button
• Minimal-input warning: "Task objective is minimal — success may be impacted. Submit anyway?"
• Chat messages from Planner rendered distinctly from system/orchestrator messages

Tests:

• Unit tests for Planner validation logic (checklist enforcement)
• Unit tests for TaskSpec construction from Planner conversation
• Unit tests for auto-inference (package.json → languages/frameworks)

Recommended Build Order

1. Phase A first — "Add directory" button is a quick win, no backend changes needed (POST /workspaces already exists). Unblocks testing with multiple workspaces.
2. Phase B backend — Planner node + TaskSpec + API endpoints. Can test via curl/API before dashboard work.
3. Phase B dashboard — ChatView conversational flow wired to Planner API.

Design

Task Readiness Checklist

Requirement	Priority	Notes
Workspace / directory	Required	Local path or GitHub repo + branch
Objective statement	Required	What the agents should accomplish
Target language(s)	Required	Can be auto-inferred from workspace
Framework(s)	Required	Can be auto-inferred from workspace
Expected output type	Recommended	Files, PR, command output, etc.
Acceptance criteria	Recommended	Warning if missing but does not block
Constraints	Optional	E.g., don't modify existing auth flow
Related files / context	Optional	E.g., see src/middleware/

TaskSpec Schema

class TaskSpec(TypedDict):
    workspace: str           # Path or repo URL
    objective: str           # What to accomplish
    languages: list[str]     # Auto-inferred or user-specified
    frameworks: list[str]    # Auto-inferred or user-specified
    output_type: str | None  # Files, PR, command output
    acceptance_criteria: list[str]
    constraints: list[str]
    related_files: list[str]

Plan-to-Act UX

1. User clicks "New Task" in Chat panel
2. Workspace selector appears — dropdown of approved directories + "Add new" + "Create new project"
3. User writes objective in chat area
4. Planner validates against checklist, prompts for missing info conversationally
5. Planner displays summary: "Here's what I'll send to the Architect: [summary]. Ready to submit?"
6. User confirms → "Submit to Architect" executes

Minimal-input path: Brief one-liner + submit → warning: "Task objective is minimal — success may be impacted. Submit anyway?"

Dependencies

• feat: Workspace security model — allowed directories, protected workspaces, PIN auth #105 (Workspace security model) ✅ Shipped in PR feat(#105): Workspace security model — allowed dirs, protected workspaces, PIN auth #115

Effort

Large (2-3 sessions) — Phase A is small (1 hour), Phase B is the bulk.

Source

Dashboard Workflow Roadmap, Section 2 — Task Creation via Chat