# AWP Product UI and Information Architecture **Status:** Approved target-state baseline — Goals, dependency-aware Queues, Advisor/Search and full-target visual freeze integrated **Purpose:** Define one coherent work-focused shell across all increments. ## Target Navigation ```text AWP | +-- HOME | +-- Work | +-- Needs your attention | +-- WORK | +-- Projects | +-- Goals | +-- Plans | +-- Requests / Work Items | +-- Saved views | +-- EXECUTION | +-- Factory Runs | +-- Agents | +-- CI | +-- DELIVERY | +-- Reviews / Changes | +-- Releases | +-- Deployments | +-- OPERATIONS | +-- Queues | +-- Health | +-- Incidents | +-- Cluster | +-- SETTINGS +-- Accounts & Models +-- Advisors +-- Providers / Connections +-- Configuration +-- Security / Policy +-- Integrations / Communications +-- Audit ``` Search and Advisor are cross-cutting shell capabilities, not permanent left-nav groups: ```text Search / Commands Cmd/Ctrl+K + visible shell affordance Advisor Project -> Ask Project Manager; Home -> Ask AWP ``` `Queues` and `Health` are separate jobs. Queues owns dispatch ordering/readiness/dependency constraints; Health owns infrastructure/provider/system health. ## Full-Target Visual Freeze Increment activation controls functionality, not the first moment AWP decides where material capability belongs. Early high-fi designs use the complete target composition when future capability affects layout/hierarchy/mental model. Future controls are unmistakably `Planned I#` and inert until activation. ```text Search Planned I3 Ask Project Manager Planned I3 Decision Log Planned I3 CI control plane Planned I5 Release / Deployment Planned I6 Cluster management Planned I7 Incident product depth Planned I8 ``` Do not fill pages with fake empty dashboards; reserve only layout-relevant final positions. ## Project Context ```text Project Overview Vision Goals Plans / Planning Work / Tasks Queues / Graph Factory Runs / Agents Reviews / Changes CI Decisions / Approvals Releases / Deployments Incidents Settings ``` Project Overview is operational, with canonical scan order: ```text Current Goals Needs Your Attention Blockers Queue / Next to Factory Current Plans Current Factory Runs Recently Completed / Recent Progress ``` Vision and Settings are direct destinations but not dominant Overview content. ## Product Shell Desktop target: ```text ┌────────────────────────────────────────────────────────────────────────────┐ │ AWP [Project context] Search… ⌘K Attention User │ ├──────────────────────┬─────────────────────────────────────────────────────┤ │ HOME │ Breadcrumbs │ │ WORK │ Page title / state / one primary action │ │ EXECUTION │ │ │ DELIVERY │ Main work surface │ │ OPERATIONS │ │ │ SETTINGS │ [Advisor launcher] │ └──────────────────────┴─────────────────────────────────────────────────────┘ ``` Groups may collapse. Current group/page remains visible. Labels use user goals/product nouns rather than backend module names. ## Page / Primitive Relationship Every visible entity has stable clickable identity where a detail surface exists: ```text Project ProjectVision Goal Plan Task / Work Item FactoryRun AgentRun / Attempt ChangeSet Review CIExecution Decision Approval Release Deployment Incident Cluster / Machine AdvisorPersona / AdvisorThread ``` Plan and Task rows are primary navigation targets. Do not duplicate `Open Plan` / `Open Task` buttons in routine rows. ## Global Collections - Goals: active/future/completed Project outcomes; - Plans: all active/recent Plans and readiness/execution state; - Requests / Work Items: owner-facing Asked/In progress/Waiting/Done work; - Factory Runs: execution current/history; - Agents: current agents + provenance/analytics; - CI: current/history CI executions and health; - Reviews: review/change queues; - Releases / Deployments: delivery queues/history; - Queues: dependency-aware work ordering + Graph view; - Health: infrastructure/provider/system health; - Incidents: operational failures/resolution; - Settings collections. These are projections over canonical domain primitives, not duplicate stores. ## Queue / Graph Pattern Queues exposes two peer views over the same Work/dispatch truth: ```text Queue | Graph ``` Queue optimizes for ordering/dispatch/blocker explanation. Graph is a compound directed dependency graph: ```text Plan = group Task = node prerequisite -> dependent = directed edge ``` Cross-Plan edges remain visible. Filtering cannot make hidden prerequisites disappear semantically. Clicking a Plan/Task navigates directly to it. ## Global Search / Command Target Search uses visible shell affordance plus Cmd+K/Ctrl+K. `cmdk` is interaction substrate after compatibility verification; `@platform-modules/search` is reuse-first backend seam. Search finds/navigates exact objects; Advisor analyzes/recommends. ## Advisor ```text Planning one Plan creation/revision Project Manager Advisor one Project across Goals/Plans/lifecycle AWP Advisor all authorized Projects/resources Execution Agent chat one coding/review AgentRun/Attempt ``` Advisor surfaces show persona, scope and page context. Recommendations become explicit proposal/actions through canonical commands/policy; chat is not a mutation backdoor. ## Attention `Needs Your Attention` projects OwnerRequired Decisions, PolicyRequired Approval, blocked ConnectionRequirement, work waiting for user, and relevant Incident/security issues. Advisors may explain/prioritize Attention but never replace it. ## Canonical Interaction Patterns Operational surfaces answer: ```text LAST latest meaningful state-changing event CURRENT authoritative state + current owner NEXT expected transition/actor ATTENTION whether user action is required/available ``` Every waiting/blocked state exposes who/what/why/since/next/user action. Collections support Search | Filter | Sort | Group | Saved views, keyboard navigation and URL-restorable state. ## UI Principles - self-explanatory rather than narrating obvious UI; - one primary action per decision context; - progressive disclosure of technical detail; - immediate mutation feedback + duplicate-submit protection; - friction proportional to risk; - complete empty/loading/error/populated/stale states where material; - waiting/blocked/recovery are first-class; - WCAG 2.2 AA target; - no raw provider/event/Kubernetes JSON as primary UX; - no dependency meaning encoded by color alone; - planned future capability never masquerades as active; - generated image mockups are not visual authority; deterministic repo HTML/prototypes are preferred for implementation reference. ## Increment Realization | Increment | UI activation | |---|---| | I1 | shell + Project/Goals/Plan/Task/Queue minimum + Factory/Review/Merge + U1–U6 states. | | I2 | full Planning/onboarding/Goal management/connections. | | I3 | Decision/HITL + Project Manager + Search/Command palette. | | I4 | full Factory/Agent observability + AWP Advisor. | | I5 | CI control plane. | | I6 | Release/Deployment. | | I7 | Cluster management + deeper capacity/placement Queue context. | | I8 | Incident/Resolver. | | I9 | organization/tenant/reliability productization. | ## Related UI Specs ```text home-work-command-center project plan planning queues-and-dependency-graph advisory-chat search-command-palette factory-run agents agent review ci decision-log approval release-deployment cluster incident settings ``` ## Acceptance A user can navigate by goal across Work, Execution, Delivery and Operations; understand Goals/current/next/completed work; inspect dependency legality visually; find exact objects through Search; and add later functionality without rearranging approved page composition.