JARVIS/docs/superpowers/specs/2026-03-25-schedule-planner-design.md

# Schedule Planner Agent Redesign

## Goal

Replace the current planner role with a schedule-focused planning system that analyzes conversation history, the task board, and forum signals to produce actionable scheduling recommendations for the user.

## Scope

This redesign covers both the main planner role and its subagents across backend orchestration, prompts, routing, scheduled execution, todo generation, frontend presentation, and related tests.

## User-Approved Direction

- Replace the current path-planning semantics with schedule-planning semantics.
- Redesign both the main planner role and its subagents.
- Inputs for planning:
  - conversation history
  - task board
  - forum information
- Output style:
  - conclusion first
  - executable schedule next
- Trigger modes:
  - when the user explicitly asks for scheduling advice
  - at a fixed daily time
- Daily scheduled analysis should write actionable suggestions into todo items.

## Architecture

### Main Role

The current `planner` role will be replaced at the system level by a new role id:

- `schedule_planner`

Its responsibility is no longer “find the shortest execution path for a goal.” Instead, it becomes the scheduling brain that:

1. understands current commitments and pressure signals
2. evaluates urgency, importance, dependency, and timing
3. recommends near-term scheduling actions
4. converts useful scheduled guidance into concrete todo items when triggered by the daily scheduler

### Subagents

The existing planner subagent structure will be redesigned into two schedule-specific subagents:

- `schedule_analysis`
  - analyzes conversation history, task board state, and forum signals
  - identifies priorities, pressure points, conflicts, dependencies, risks, and things that can be delayed

- `schedule_planning`
  - converts analysis into an execution-oriented schedule recommendation
  - outputs conclusion first, then a practical schedule proposal
  - when running from the daily scheduled workflow, produces todo-ready action items

### Trigger Paths

#### Interactive Trigger

When the user asks questions such as:

- what should I do today
- how should I arrange this week
- based on my recent work, what should I focus on next
- help me schedule upcoming work

The master agent should route to `schedule_planner`.

The expected response shape:

1. current conclusion
2. today / near-term schedule recommendation
3. next actions

#### Daily Scheduled Trigger

A daily scheduled job invokes the schedule planner flow automatically.

The daily run should:

1. collect relevant context from conversation history, tasks, and forum data
2. run `schedule_analysis`
3. run `schedule_planning`
4. convert only actionable, non-duplicate recommendations into todo items

The daily run should not dump raw analysis into todos. Only concise, action-worthy, user-meaningful recommendations become todos.

## Data Flow

### Inputs

The schedule planning system should read from three sources:

1. **Conversation history**
   - recent user intent
   - commitments implied in prior discussion
   - stated priorities, urgency, and unresolved threads

2. **Task board**
   - open items
   - current statuses
   - stalled work
   - high-priority or overdue work

3. **Forum information**
   - new items requiring attention
   - external pressure or discussion signals
   - updates that may change priority

### Internal Processing

The main flow should be:

- Master decides scheduling intent
- `schedule_planner` receives context
- `schedule_analysis` identifies priority structure
- `schedule_planning` produces human-usable output
- scheduled mode additionally writes selected suggestions into todos

### Outputs

#### Interactive Output

The default answer structure should be:

- conclusion first
- suggested schedule second
- next actions last

#### Scheduled Output

The scheduled run should create todo entries with:

- concise action phrasing
- enough context to be actionable
- source attribution where useful (conversation/task/forum)
- duplicate avoidance

## Migration Strategy

This redesign uses a two-phase migration to avoid breaking stored state and UI rendering.

### Phase 1: Compatibility Window

- accept legacy `planner` values from stored traces, mock payloads, and historical records
- normalize legacy `planner` to `schedule_planner` at read boundaries where practical
- accept legacy `planner_scope` and `planner_steps` as read-only legacy values and normalize them to `schedule_analysis` and `schedule_planning`
- write only the new ids going forward:
  - `schedule_planner`
  - `schedule_analysis`
  - `schedule_planning`

### Phase 2: Legacy Removal

After the migration is complete and all active UI payloads, mock data, and tests are updated:

- remove legacy id acceptance from orchestration and frontend display logic
- remove legacy mock fixtures
- keep migration code out of prompts and core scheduling behavior

### Migration Scope

The migration must cover:

- backend enums and routing
- frontend agent ids and telemetry labels
- stored trace rendering paths
- mock data used by agent dashboards and chat orchestration views
- tests that still refer to `planner`, `planner_scope`, or `planner_steps`

## Input Contracts

The schedule planning system reads from three sources with explicit limits.

### Conversation History Contract

- use recent conversation history from the current user context
- default retrieval window: last 7 days of relevant conversation turns, capped at the latest 50 turns
- prefer turns that include commitments, priorities, deadlines, blockers, or future-oriented intent
- if conversation history is unavailable, continue with degraded confidence

### Task Board Contract

- include open, in-progress, blocked, overdue, and high-priority tasks
- exclude completed and archived items by default
- include enough task metadata to reason about urgency and dependency:
  - title
  - status
  - priority
  - due date if present
  - last updated time if present
- if task data is unavailable, continue with degraded confidence

### Forum Information Contract

- include recent forum items that may affect user priorities
- default retrieval window: last 7 days of relevant forum signals
- forum signals may include:
  - new posts requiring attention
  - replies or escalations
  - updates that change urgency or expected follow-up
- if forum data is unavailable, continue with degraded confidence

## Output Contracts

### `schedule_analysis` Output Schema

The analysis stage should produce a structured summary with these fields:

- `top_priorities`: list of current highest-priority focus areas
- `risks`: list of risk or pressure signals
- `conflicts`: list of timing or dependency conflicts
- `deferrable_items`: list of lower-priority items that can be delayed
- `evidence`: source references grouped by `conversation`, `task_board`, or `forum`
- `confidence`: one of `high`, `medium`, `low`

### `schedule_planning` Output Schema

The planning stage should produce a structured recommendation with these fields:

- `conclusion`: short decision-oriented summary
- `today_plan`: list of suggested actions for the current day or immediate next window
- `near_term_plan`: list of actions for the next few days or current week
- `next_actions`: short ordered action list
- `todo_candidates`: only present in scheduled mode; candidate todo items derived from the recommendation
- `confidence`: one of `high`, `medium`, `low`

### `todo_candidates` Schema

Each `todo_candidate` must use this structure:

- `title`: required short action text
- `description`: required short rationale grounded in source context
- `sources`: required list of provenance objects
- `priority`: optional normalized priority such as `high`, `medium`, `low`
- `target_window`: optional string such as `today` or `this_week`

Each provenance object in `sources` must contain:

- `type`: one of `conversation`, `task_board`, `forum`
- `id`: source object id when available, otherwise a stable synthetic reference
- `label`: short human-readable source label

### Evidence Structure

Each item in `schedule_analysis.evidence` must contain:

- `type`: one of `conversation`, `task_board`, `forum`
- `id`: source object id when available, otherwise a stable synthetic reference
- `label`: short human-readable identifier
- `reason`: brief explanation of why the signal matters to scheduling

### Interactive Response Contract

The user-facing answer should always follow this shape:

1. conclusion
2. suggested schedule
3. next actions

If confidence is low, the response must say that explicitly and avoid overconfident scheduling language.

## Daily Scheduler Contract

The daily scheduled trigger must follow explicit execution semantics.

### Execution Model

- run once per user per local date
- default execution time: 07:00 in the user's configured timezone
- if the user has no configured timezone, skip the run and log the skip reason
- do not automatically backfill missed runs
- enforce idempotency by `(user_id, local_date, job_type)` so the same daily analysis is not executed more than once successfully

### Scheduled Mode Behavior

A successful scheduled run should:

1. gather available context from the three input sources
2. execute `schedule_analysis`
3. execute `schedule_planning`
4. create todo items from selected `todo_candidates`
5. store run telemetry and outcome metadata

If one or more sources are missing, continue when there is still enough evidence to produce a useful recommendation and mark confidence as reduced.

Signal evaluation rules:

- a **strong source** is a source with enough current evidence to support prioritization on its own, such as multiple open high-priority tasks or a recent forum escalation
- a **meaningful signal** is a discrete scheduling-relevant item extracted from any source, such as an overdue task, a stated commitment in conversation history, or a forum escalation
- the planner may still run with one strong source
- scheduled mode may create todos only when at least two meaningful signals exist across all inputs

If fewer than two meaningful signals are available across all sources, the scheduler should not create todos and should log a low-context outcome.

Delayed execution rule:

- if the 07:00 run is delayed by temporary outage or worker unavailability, the system may still execute one delayed run later on the same user-local date
- if the entire local date passes without a successful run, do not backfill on the next day

## Todo Creation Rules

Todo creation is the main scheduled side effect and must be tightly constrained.

### Creation Rules

- create at most 3 todo items per daily run
- only create todos for actions that are concrete, near-term, and user-actionable
- do not create todos for vague advice, reflections, or duplicated reminders
- store source provenance when available:
  - `conversation`
  - `task_board`
  - `forum`

### Duplicate Detection

A candidate todo is considered a duplicate if there is already an open todo that matches all of the following:

- same normalized action text
- same source category or same source object when available
- created within the last 7 days

Normalization rules for action text:

- trim surrounding whitespace
- collapse repeated internal whitespace to a single space
- lowercase Latin characters
- remove trailing full stop / period punctuation only

Source comparison rules:

- if a provenance object includes a stable source `id`, compare by `(type, id)`
- if no stable source id exists, compare by `(type, normalized label)`
- if multiple sources support one recommendation, compare against the highest-priority provenance in this order: `task_board`, `forum`, `conversation`

When a duplicate is detected:

- do not create a new todo
- record the skip reason in scheduler telemetry

### Todo Fields

Scheduled-created todos should include at minimum these persisted fields:

- `title`: required
- `description`: required
- `source_type`: required primary provenance type
- `source_id`: optional stable source id
- `source_label`: required fallback human-readable provenance label
- `created_by`: required and set to `schedule_planner`
- `created_at`: required timestamp
- `priority`: optional normalized priority
- `target_window`: optional normalized scheduling window

## Routing Boundaries

The system must distinguish scheduling from adjacent planning behaviors.

### Route to `schedule_planner` when the user asks for:

- today or this week planning
- what to focus on next
- priority ordering across ongoing work
- time-aware sequencing of current commitments

### Do not route to `schedule_planner` when the user asks for:

- deep implementation planning for a feature
- code execution or task fulfillment
- research-only retrieval
- pure analysis without scheduling intent

In ambiguous cases such as "what should I do next?", prefer `schedule_planner` when the available context includes multiple active tasks, recent commitments, or forum pressure signals.

## Backend Changes

### Role and Graph Layer

Update the orchestration layer so the planner role is redefined as `schedule_planner` rather than `planner`.

Files likely involved:

- `backend/app/agents/state.py`
- `backend/app/agents/graph.py`
- `backend/app/agents/prompts.py`
- `backend/app/routers/agent.py`
- `backend/app/services/agent_service.py`

Required changes:

- rename role ids where appropriate
- update graph node registration
- update master routing rules
- replace planner subagent mappings
- update telemetry and sub-commander trace labels

### Prompt Layer

Replace the current planner prompt family with schedule-specific instructions.

Needed prompt families:

- `SCHEDULE_PLANNER_SYSTEM_PROMPT`
- `SCHEDULE_ANALYSIS_PROMPT`
- `SCHEDULE_PLANNING_PROMPT`

Prompt requirements:

- reason over conversation history, tasks, and forum state
- prioritize urgency, importance, and dependency
- avoid abstract productivity advice
- produce concrete, immediate scheduling output
- in scheduled mode, generate todo-worthy suggestions only

### Scheduled Execution Layer

Add or update the daily scheduled workflow so it can call the schedule planner flow automatically.

Likely touchpoints:

- scheduler service
- existing daily planning jobs
- todo creation services

Required behavior:

- fixed daily execution time
- fetch relevant context
- call schedule planner pipeline
- write selected recommendations into todos
- skip duplicate todo creation

## Frontend Changes

Frontend needs to reflect the new role system consistently.

Files likely involved:

- `frontend/src/data/agents.ts`
- `frontend/src/pages/agents/index.vue`
- `frontend/src/components/chat/OrchestrationPanel.vue`
- `frontend/src/pages/chat/composables/useChatView.ts`
- related frontend tests

Required updates:

- replace planner display labels with schedule planner labels
- rename planner subagents to schedule analysis / schedule planning
- update orchestration telemetry labels
- update example mock state and tests
- use these exact frontend ids:
  - `schedule_planner`
  - `schedule_analysis`
  - `schedule_planning`
- use these exact default Chinese labels:
  - `日程规划师`
  - `日程分析员`
  - `日程编排员`
- update active route visualization and commander skill labels to the new ids

## Naming

### Main Agent

- old: `planner`
- new: `schedule_planner`
- display role: `日程规划师`

### Subagents

- old: `planner_scope`
- new: `schedule_analysis`
- display role: `日程分析员`

- old: `planner_steps`
- new: `schedule_planning`
- display role: `日程编排员`

## Constraints

- do not keep dual role names for long-term compatibility unless a specific dependency forces it
- do not create todos for every suggestion
- do not turn the planner into a generic life coach
- keep scheduling grounded in current project signals
- preserve the existing agent architecture where possible, while fully changing planner semantics

## Observability

The redesign must emit enough telemetry to debug routing and scheduled execution.

Required telemetry fields:

- selected main route
- selected subagent
- available input sources
- missing input sources
- run mode: `interactive` or `scheduled`
- confidence level
- todos created count
- todos skipped as duplicates count
- scheduler run success / skipped / failed

## Acceptance Criteria

### Backend Acceptance Criteria

- a scheduling-intent user query routes to `schedule_planner`
- `schedule_analysis` and `schedule_planning` are both reachable through the orchestration layer
- legacy planner ids are normalized during the compatibility window
- daily scheduled runs do not execute more than once per user per local date
- low-context daily runs do not create todos
- duplicate todo candidates are skipped instead of recreated

### Frontend Acceptance Criteria

- the agents page displays `日程规划师` instead of the previous planner label
- the planner subagent chips display `日程分析员` and `日程编排员`
- orchestration mock data and route highlights use the new ids
- tests no longer depend on `planner_scope` or `planner_steps` after migration is complete

### Failure and Fallback Criteria

- if forum data is missing, the planner still runs with degraded confidence
- if task board data is missing, the planner still runs with degraded confidence when other strong context exists
- if fewer than two meaningful signals are available, scheduled mode creates no todos
- if the user has no timezone configured, the daily scheduled run is skipped and logged

## Testing Strategy

### Backend

Add or update tests for:

- master routing to `schedule_planner`
- schedule subagent selection behavior
- prompt invariants for schedule-focused output
- scheduled daily run creates todos from actionable suggestions
- duplicate todo protection

### Frontend

Add or update tests for:

- renamed main role and subagent labels
- orchestration panel route display
- active subagent telemetry
- mock agent graph data using `schedule_planner`, `schedule_analysis`, and `schedule_planning`

## Risks

1. **Broad rename surface**
   - `planner` is referenced across backend and frontend, so a full rename must be systematic

2. **Scheduled todo spam**
   - daily runs may create low-value or duplicate todos unless filtered carefully

3. **Prompt drift**
   - if prompts stay too abstract, the new agent will sound renamed but not actually scheduling-oriented

## Recommendation

Implement this as a real role-system redesign, not as a display-only rename. The role id, subagent ids, prompt family, routing logic, and frontend telemetry should all align on the new scheduling semantics so the system remains internally coherent.