# Planning Workspace UI **Status:** Approved target-state behavior **Activation:** I2 **High-fi:** mandatory before I2 implementation. ## Page Job Keep the full planning process legible during a long multi-session agent-led conversation: ```text LEFT What did I ask for / what has been planned? CENTER What are we doing now? RIGHT Why / impact / evidence / what comes next? ``` The user should never need to ask “what remains?” when structured state already knows. ## Desktop Three-Area Workspace ```text ┌──────────────────────────────────────────────────────────────────────────────┐ │ Project / Plan Mode: Simple [Change] Saved Readiness │ ├──────────────────────┬───────────────────────────────────┬───────────────────┤ │ PLAN INDEX │ CURRENT │ CONTEXT │ │ │ │ │ │ DEFINE │ Current owner question / │ Recommendation │ │ ✓ Intent │ recommendation / artifact │ confidence/basis │ │ ● Pricing │ │ consequences │ │ │ [primary action] │ affected items │ │ DESIGN │ alternatives/customize/evidence │ │ │ ✓ Experience │ │ Agenda │ │ ▸ Technical 7 │ Planner response / conversation │ Now / Next / Later│ │ │ composer │ │ │ SPECIFY │ │ │ │ DELIVER │ │ │ │ LAUNCH │ │ │ └──────────────────────┴───────────────────────────────────┴───────────────────┘ ``` ## Plan Index Primary planning navigation; stable landmarks: ```text DEFINE DESIGN SPECIFY DELIVER LAUNCH ``` Dynamic children come from PlanningWorkflow. Progressive disclosure: - current group expanded; - next unresolved group partially visible; - completed groups collapsed to summary; - blockers/deferred items always surfaced even when parent collapsed; - technical delegated decisions summarized by count/change/attention; - search/filter for large Plans; - clicking restores active item in URL/session. ### Simple Technical Visibility Technical work builds visibly without becoming chat interrogation: ```text DESIGN ▸ Technical design 7 decisions · 1 changed Architecture modular monolith project default Data PostgreSQL inferred · high Security project policy inherited DELIVER ▸ Quality / CI / CD 9 decisions · project defaults ! Connection required before production ``` Expansion shows recommendation/basis/confidence/impact and `Change` action. ## Current Center One active planning item at a time: owner question, recommendation/comparison, artifact review, connection requirement or readiness/launch review. Exactly one primary action when an action is required. Recommendation comparison uses 2–4 credible options and consequence-based differences. `Accept recommendation` is primary when evidence supports one. Secondary `Review/customize` or focused rejection does not reopen unrelated decisions. Composer remains available but does not force the user to drive the agenda. ## Context Rail Follows active item rather than duplicating navigation. Shows: ```text current decision/position why / evidence / confidence material consequences what would change recommendation affected artifacts/work risk/question authority/provenance Now / Next / Later ``` User can Pin context. Collections/search expose all Decisions/Risks/Evidence/Artifacts/Open Questions. On narrow screens Context is a drawer. ## Simple Mode Conversation focuses on OwnerRequired/PolicyRequired items: product direction, scope, taste/UX, pricing/business/customer policy, budget/risk/commitments and required consent. DelegableExpert technical decisions appear in Plan Index/context and can be changed by choice. Low-confidence consequential technical decisions surface as attention/recommendation. Ask business consequence rather than technical implementation when possible. ## Expert Mode Technical recommendation becomes a normal center item: architecture, security, libraries, Quality/CI/CD, deployment, execution, integrations. User can accept/refute/customize section by section. Same full Plan state and defaults. ## Planning Profile Auto-applied inferred profile appears unobtrusively with `Change`. Changing profile previews Added / Removed / Kept requirements; accepted Decisions/artifacts never silently disappear. ## Readiness Use explicit state, never fake percentage: ```text Ready for specification You can continue now. Before production you still need: Cloud provider connection Production approval policy ``` `Ready with deferred gaps` always states future consequences/gates. ## Delivery Recommendation Compact layered rows, current section expanded: ```text Quality CUJ-first affected verification accepted CI GitHub Actions + ARC accepted Delivery staging auto / prod approval review Execution dependency-aware / 3 lanes inferred Connections 1 deferred attention ``` Simple mode does not ask acceptance for every technical row; Expert can review deeply. ## Connection Interruption Connection card preserves exact Planning context through auth/resource selection and returns automatically to the interrupted item. `Set up later` shows blocking gate/consequence. ## Ready to Launch Concise PlanRevision decision brief: outcome, scope/non-goals, delivery/execution, connections/approvals, gaps/risks and preflight. ```text [Start now] [Schedule] [Park] then one Confirm ``` Start revalidates preflight. Schedule captures local date/time/timezone and is cancellable/reschedulable. Park is intentional ready state. Material change creates new PlanRevision. ## States - Empty: project has no active Plan; one New Plan CTA. - Loading: restore shell/index and active item skeleton. - Error: preserve durable state and explain which source/action failed. - Populated: normal workspace. - Stale: repository/connection/evidence changed; mark affected items and re-evaluate. - Disconnected: local draft stays safe; authoritative mutations show pending/retry state. ## Responsive Wide: all three areas. Medium: Plan Index + Current; Context drawer. Small: Current dominant; Plan Index and Context drawers, breadcrumbs/header compressed but always accessible. Do not stack all three into endless vertical page. ## Accessibility / Focus Landmarks and drawer focus management; keyboard navigation of Plan Index; live regions for saved/mutation state without noisy announcements; comparison tables semantic; focus returns to triggering item after modal/auth/drawer action. ## URL Truth Route identifies Project, Plan/PlanRevision and active planning item; drill-down/pinned context where practical. Browser back/refresh restores state, never loses accepted planning. ## Increment Realization Full workspace activates I2; I3 deepens Decision/Approval collections; I5/I6 technical delivery rows become operational links; future sections fit same Plan Index landmarks. ## High-Fidelity Required Set Before I2 implementation at minimum: ```text P1 Simple owner decision P2 Simple technical plan expanded P3 Expert recommendation/comparison P4 Existing-project truth conflict P5 Connection required + return P6 Deferred gap/readiness P7 Ready-to-launch P8 Medium responsive P9 Small responsive P10 representative Empty/Loading/Error/Stale ``` ## Target State Planning is a durable, agent-led workspace that converts intent/evidence into structured PlanRevision, Decisions, artifacts, delivery configuration and launch state. Conversation is an interaction surface; canonical Planning state is never trapped in chat history. ## Primary Users / Jobs - project owner/product engineer: express intent, business/user constraints and OwnerRequired choices without becoming the agenda manager; - technical lead/expert: inspect, challenge and customize delegated technical recommendations; - returning user: resume a multi-session Plan and immediately understand what was decided, what is active and what remains. ## Entry / Exit Points Entry: Project onboarding, Project/Plan `Resume Planning`, New Plan, Decision/Connection deep link, browser-restored PlanningSession. Exit: Plan page, Connection flow with durable return target, Decision/artifact detail, or explicit Start/Schedule/Park handoff to execution state. ## User Journeys ### J1 — New Plan, planner-led ```text New Plan -> intent captured -> PlanningProfile inferred visibly -> planner advances DEFINE/DESIGN/SPECIFY/DELIVER -> only consequential OwnerRequired questions interrupt -> delegated recommendations remain inspectable/changeable -> readiness becomes explicit -> launch brief -> Start / Schedule / Park + Confirm ``` ### J2 — Challenge a recommendation without losing progress ```text active recommendation -> inspect confidence/basis/consequence -> Review/customize or reject -> compare 2–4 credible alternatives -> accept replacement Decision -> affected artifacts/recommendations re-evaluate -> planner resumes next highest-value unresolved item ``` ### J3 — Defer a real requirement safely ```text missing requirement/connection -> show why + blockingAt + consequence -> Set up later -> persist DecisionDeferral owner/revisit trigger -> continue current gate if allowed -> deferred item remains visible -> resurfaces before declared blocking gate ``` ### J4 — External connection interruption and exact return ```text ConnectionRequirement -> start auth/resource binding -> preserve PlanningSession + active item + draft -> external redirect/auth -> verify identity/resource/capabilities -> return to exact item -> re-evaluate decision/readiness -> planner continues automatically ``` ### J5 — Resume after interruption ```text reopen Plan hours/days later -> Plan Index restores current/completed/deferred/blockers -> Current restores active planning item -> Context shows why/impact/Now-Next-Later -> no need to ask “what remains?” ``` ## Data / Source of Truth Canonical data comes from PlanningSession/PlanningWorkflow, Plan/PlanRevision, Decision/DecisionDeferral, Research/Evidence/Artifact, ProjectPlanningDefaults, EffectiveDeliveryPlan, ConnectionRequirement/Binding and Policy/Approval state. Repository/provider inspection is attributable evidence, not desired-state truth. Model conversation text is not authoritative without structured persistence. ## Actions / Authorization OwnerRequired choices require owner authority. DelegableExpert decisions may be accepted by the planner according to participation/autonomy policy but remain visible/changeable. PolicyRequired protected actions require Approval. No Simple/Expert mode can bypass authority classes or capability ceilings. ## Async / Duplicate-Mutation Safety Draft text autosaves with visible state. Accepted Decisions/PlanRevision mutations use revision/idempotency protection. External auth has a durable return target. Start/Schedule/Park requires one explicit confirmation and protected preflight revalidation; duplicate confirmation cannot start multiple runs. High-risk launch action is never queued offline. ## Invariants From Day 1 - planner leads when structured state knows the next agenda item; - Plan Index, Current and Context answer asked/now/next without chat archaeology; - accepted decisions/artifacts never silently disappear on profile/mode change; - low-confidence consequential inference cannot masquerade as settled truth; - blockers/deferred items remain visible despite progressive disclosure; - conversation and structured state cannot diverge silently; - launch never starts without explicit Start/Schedule/Park selection and confirmation. ## Current Implementation State Target specification only. Planning implementation begins at I2 after its dedicated high-fi/usability gate. ## Deferred Realization I3 deepens generic Decision/Approval collections; I5/I6 turn planned CI/delivery rows into operational links. Research/validation behavior is conditional on PlanningProfile/risk rather than a mandatory extra stage for every Plan. ## Temporary Dogfood Behavior No throwaway I1 planner model should be introduced. I1 may create a narrow Plan/Task through final Plan identities while the rich Planning workspace remains inactive until I2. ## Related Contracts / Decisions - [`../domains/planning.md`](../domains/planning.md) - [`../workflows/interactive-planning.md`](../workflows/interactive-planning.md) - [`../workflows/connection-onboarding.md`](../workflows/connection-onboarding.md) - [`../domains/approvals-decisions.md`](../domains/approvals-decisions.md) - [`../domains/integrations-connections.md`](../domains/integrations-connections.md) - [`plan.md`](plan.md), [`decision-log.md`](decision-log.md), [`approval.md`](approval.md) - accepted Planning UX/leadership/research decisions under `../../plans/` constrain this page. ## Visual Mockup Authority No high-fidelity Planning frame is approved yet. Low-fi/ASCII Planning diagrams are behavioral references only. The P1–P10 high-fi set plus lean usability validation must be reconciled with this contract before Planning UI implementation. ## Acceptance User can always locate current question, inspect AWP technical choices without being forced to decide them, challenge any material decision, understand readiness/deferred consequences and resume after interruption.