# AWP VISION — Additive Extensions **Date:** 2026-08-20 **Status:** **CANONICAL ADDITIVE OWNER VISION** **Authority:** Read together with [`VISION.md`](VISION.md). This file preserves new owner intent without rewriting the original owner-worded Vision document. ## Why this is separate `VISION.md` intentionally preserves the owner's original wording and recovered Overdeck/AWP product intent. This extension records later owner requirements as equally binding Vision without silently editing that historical source. If this extension conflicts with an older mechanism in `VISION.md`, the newer explicit requirement here wins only for the stated feature; architectural implementation is still governed by accepted Decisions/specs. # Project/Product-Manager Advisory Agents AWP is not only an orchestration interface for developers. Its primary product UX increasingly targets a **project/product manager mental model**: understand product goals, project progress, risks, slow work, planning gaps, decisions and what should happen next. The owner must be able to **talk to the Project's Project Manager** from inside AWP. This is not the one-Plan Planning agent. It is project-level decision support across the Project's enduring Vision, all Plans, work, FactoryRuns, Agents, Decisions, CI, delivery, Incidents and relevant metrics. Example questions include: ```text What is the current progress in this project? Which tasks are taking too long? Why are they taking too long? What are the largest risks right now? How can we optimize our overall planning? Which Plans should be improved? What gaps exist across our Plans? Which project Decisions are likely stale? Are we spending effort on work that no longer supports the ProjectVision? What should I pay attention to next? ``` The Project Manager advisor must understand: ```text ProjectVision Project status / GOLIVE all current/historical Plans and Tasks FactoryRun / AgentRun / Attempt state Decision / Approval history Review / CI / Verification state Release / Deployment state when active Cluster / Incident state when relevant current page and selected primitive context current filters/time window when relevant ``` It must answer from canonical AWP state and attributable evidence, not from hidden chat memory. ## Context-aware floating UX On Project-scoped product pages, the Project Manager is accessible through a persistent floating chat launcher. The launcher opens a contextual conversation surface without forcing the user to leave the page being discussed. The assistant knows the current page context, such as: ```text Project: AWP Page: FactoryRun Selected FactoryRun: 5j13mlx Selected task: Task 11 Current time range/filter: 7d / waiting ``` This page context is visible to the user and removable/changeable. Page context never broadens authorization. # AWP System Advisor The owner must also be able to **talk to AWP itself**, across all Projects visible to that Principal. This advisor answers system/portfolio questions such as: ```text Which projects need my attention? Which projects are falling behind? Where are the largest delivery bottlenecks? Which projects have stale Plans or Decisions? Which projects are consuming the most agent/CI capacity? Where do we have recurring CI/deployment failures? What should I prioritize across the portfolio? Are there repeated planning gaps across Projects? How healthy is AWP itself? ``` The AWP Advisor is accessible prominently from the global Home/Overview experience. It is not limited to one Project. The same assistant shell may host both Project Manager and AWP Advisor, but scope must always be explicit. A Project-scoped advisor must never silently become system-wide because the user changed pages. # Storeable Agentic Personas / Advisors Project Manager and AWP Advisor are the first built-in **Advisor Personas**, not one-off hard-coded chat features. AWP must support persistent, versioned, configurable advisor definitions so future roles can be added without redesigning the system. Examples: ```text Project Manager AWP Advisor DBA CI Expert Release Expert Security Advisor Architecture Advisor ``` An Advisor Persona can define: ```text name / role / purpose scope class instructions / behavioral policy allowed tools/queries allowed actions model/account selection policy context requirements memory/thread policy capability/policy limits version / provenance ``` Built-in and user-created advisors share the same contract. Advisor Personas do not bypass AWP authority. A Project Manager/DBA/CI Expert may analyze, recommend and prepare proposals. Any canonical mutation—Decision, Plan revision, Task creation, policy/config change, merge, deployment, etc.—uses the same AWP command, capability, Decision/Approval and audit path as the rest of the product. ## Agent role distinction The older rule “agents only write/review/fix code” applies to ordinary **execution/coding AgentRuns**. AWP also has deliberately separate bounded agent roles: ```text Planner Agent builds/revises a Plan through Planning semantics Advisor Agent analyzes Project/system state and supports decisions Resolver Agent diagnoses/resolves bounded technical failures under ResolverPolicy Execution Agent writes/reviews/fixes code inside Factory execution ``` These roles cannot silently inherit each other's authority. # Advisor Knowledge / Memory Principle Project truth must not disappear into advisor memory. Durable facts belong in canonical primitives: ```text ProjectVision Decision Plan / PlanRevision ProjectPlanningDefaults Policy / Configuration Task / Work Evidence / Artifact Incident / ResolutionRecipe ``` Advisor threads can be persistent and searchable, but an important conclusion becomes durable project truth only when promoted through the relevant canonical primitive. Example: ```text Advisor: “Three Plans assume PostgreSQL 16, but Project settings now require 17.” User actions: [Open affected Plans] [Draft Decision] [Draft Plan corrections] ``` The advisor never silently edits those Plans because it noticed the inconsistency. # Advanced Search / Command Palette AWP requires fast global search and command access using **`cmdk`** (`dip/cmdk`) as the command-menu interaction substrate, subject to the normal reuse/compatibility gate. Primary keyboard access: ```text Cmd+K macOS Ctrl+K Linux / Windows ``` A visible Search/Command affordance remains in the shell so discoverability does not depend on knowing a shortcut. The command palette must search/navigate canonical AWP entities as they become active: ```text Projects ProjectVision versions Plans / PlanRevisions Tasks FactoryRuns AgentRuns / Attempts ChangeSets / Reviews Decisions / Approvals CIExecutions / evidence Artifacts / Releases / Deployments Machines / Workloads Incidents / Resolution attempts Connections / Settings destinations ``` It also exposes safe application commands/navigation such as: ```text Open Project Open Plan New Plan Open active FactoryRun Open Needs Your Attention Ask Project Manager Ask AWP Open Settings ``` Mutation commands remain policy/capability checked and use their canonical application command; the command palette is never an authorization bypass. ## Quick palette + deep search `Cmd/Ctrl+K` is optimized for quick find/navigate/act. Large or complex searches can continue to a dedicated URL-restorable Search result view with filters/pagination. The command palette and full Search page share one backend search/query contract. `cmdk` is a UI primitive, not the search database or authorization system. # UX Direction The advisor/search design follows the accepted UX principles: ```text progressive disclosure one primary action per decision context visible scope and page context clear distinction between recommendation and canonical Decision/action immediate async feedback complete Empty / Loading / Error / Populated / Stale states keyboard-first but discoverable without keyboard knowledge URL truth for deep search/filter state 44x44 minimum interactive targets where touch applies 2 AM scannability ``` The default UX should minimize competing global controls: ```text Project page floating Ask Project Manager launcher -> contextual right-side advisor drawer on desktop -> full-height mobile surface on small screens Home / global Overview prominent Ask AWP affordance -> same advisor shell, system scope explicit Advisor shell persona/scope header page-context chips conversation evidence/source links to canonical AWP primitives suggested follow-up actions saved thread/history access Cmd/Ctrl+K separate fast Search / Commands layer ``` Advisor chat and Search are related but must not collapse into one ambiguous input. Search retrieves/navigates exact product objects; Advisor conversation interprets and reasons over them. # Realization Timing These are fully designed target capabilities now but are **not part of the I1 U1–U6 first vertical slice**. Proposed realization: ```text I2 advisor/search context/query seams may exist as substrate where Planning needs them I3 AdvisorPersona + AdvisorThread first product realization Project Manager advisor Cmd/Ctrl+K global search/command palette Decision/Approval integration for advisor proposals I4 AWP system-wide Advisor across all accessible Projects richer operational/Factory/Agent analytics questions I5–I8 CI Expert / Release Expert / Cluster/Incident advisor capabilities can be added as configured personas over newly activated domains I9 organization/tenant persona sharing/governance and enterprise search scope if productized ``` Later evidence may move a specific realization boundary through an explicit Decision, but I1 must not absorb these features merely because they are specified. # Required UX Validation Before advisor high-fidelity is considered final, validate at minimum: ```text Can a project/product manager distinguish Project Manager scope from AWP-wide scope? Do users understand which page/context the advisor is using? Can they remove/change that context? Can they distinguish a recommendation from an actual Decision or mutation? Can they verify an answer by opening cited AWP primitives? Does the floating launcher remain discoverable without obscuring work? Can users resume a saved advisor thread and understand its current scope/freshness? ``` Before advanced Search high-fidelity is considered final, validate: ```text Can a user find a Project/Plan/Task/Agent quickly with Cmd/Ctrl+K? Can a non-shortcut user discover Search? Do users understand Search vs Ask Advisor? Can they recover from zero results? Can they narrow a large result set without losing query state? Do keyboard/focus/back/Escape interactions behave predictably? ``` Research findings follow the existing Findings -> Evidence -> Impact -> Recommendation -> Effort discipline.