# Advisory Agent Architecture **Status:** Approved target-state baseline **First product realization:** I3 Project Manager advisor; I4 AWP-wide advisor **Vision:** `../../VISION-EXTENSIONS-2026-08-20.md` ## Target State AWP supports persistent contextual **advisory agents** for project/product management and later expert roles without conflating them with Planning, resolver or coding AgentRuns. ```text UI AdvisorShell / API / CLI / MCP ↓ AdvisorSession application service ↓ AdvisorPersona + AdvisorThread + AdvisorContextEnvelope ↓ AWP query/application command layer ↓ Project / Vision / Plans / Work / Runs / Decisions / CI / Delivery / Cluster / Incidents ↓ model/provider adapter through Account/Model/Provider seams ``` Advisors reason over canonical AWP state; they do not become a parallel project database. ## Role Taxonomy ```text Planner Agent builds/revises Plan through Planning authority Advisor Agent analyzes Project/system state and supports decisions Resolver Agent diagnoses/resolves bounded technical failures under ResolverPolicy Execution Agent writes/reviews/fixes code in Factory execution ``` Role boundaries are policy/capability boundaries, not prompt wording. A persona cannot gain another role's authority by asking for it in natural language. ## Advisor Scope Minimum scope classes: ```text ProjectScoped SystemScoped ``` `ProjectScoped` queries exactly one Project plus related primitives visible to the Principal. `SystemScoped` can query all Projects/resources the Principal is authorized to see. Changing scope is explicit and audited when consequential. Route/page context never broadens scope. ## Advisor Context Envelope Each turn resolves a deterministic context envelope conceptually like: ```text AdvisorContextEnvelope { principalId personaId / personaVersion scopeType projectId? route primitiveRefs[] selectedViewState? filters? timeRange? explicitAttachments[] observedAt } ``` Page/view context is an orientation hint. Every referenced primitive is re-authorized through the canonical query/application layer. Do not serialize raw credentials, secret values or unredacted sensitive provider payload into advisor context. ## Query-first Management Answers Material factual answers about current project/system state query canonical read models at turn time or expose freshness when using a cached projection. Examples: ```text project progress -> ProjectVision + GOLIVE + Plans + Work + current delivery state slow tasks -> Task durations/waits + dependencies + Factory/Agent/Review/CI state planning gaps -> Vision + Plans + Decisions + Findings/Risks/Deferrals + evidence portfolio priorities -> authorized cross-Project projections + attention + health/capacity ``` Telemetry can support duration/capacity/trend analysis but never overrides lifecycle state. ## Recommendation / Action Boundary Advisor text is recommendation/evidence, not a hidden mutation. An advisor may expose action proposals such as: ```text Open affected Plans Draft Decision Open Planning Draft Plan correction Create investigation Task Open CI/Review/Incident ``` If selected, the action invokes an existing AWP application command with the current Principal, exact target revision, PolicyEvaluation, idempotency and audit. There is no advisor-only write path. ## Persona / Model Routing `AdvisorPersona` references model/account selection policy using the existing Account/Model/Provider domain. Persona configuration never stores raw provider tokens. A turn records enough provenance to explain which persona version/model/account/provider produced it where policy permits. Provider/model fallback produces a new model invocation/turn provenance rather than silently rewriting historical attribution. ## Persistent Thread / Memory Boundary Advisor threads are persistent UX state and evidence, not canonical project truth. Allowed durable advisor state: ```text thread metadata messages/turns context snapshots source/evidence references model/persona provenance proposal links explicit user thread titles/pins ``` Canonical durable project facts remain ProjectVision, Decision, PlanRevision, ProjectPlanningDefaults, Policy/Configuration, Task, Incident/ResolutionRecipe and other defining primitives. If a conclusion matters outside the thread, promote it through the appropriate canonical command. ## Compaction / Summaries Long threads may create derived summaries for model context/performance. Invariants: - raw retained turns remain authoritative conversation history under retention policy; - summary is marked derived with source-turn range/version; - summary never substitutes for current AWP queries; - stale source primitives are re-read/revalidated before consequential recommendation/action. ## Security / Privacy - Principal authorization applies to every source query and proposed command; - `SystemScoped` does not imply administrator visibility; - Project context cannot access another Project unless the Principal/scope permits; - snippets/logs/diffs follow existing classification/redaction policy; - custom persona instructions cannot broaden capability or data scope; - advisor tools are allowlisted by capability, not arbitrary shell access; - external model/provider data handling follows Connection/provider policy; - advisor history retention/export/delete follows configured policy. ## Control Surface Integration Advisor interaction uses the same application layer from Web/API/CLI/MCP. Possible shared commands/queries include: ```text ListAdvisorPersonas GetAdvisorPersona Create/UpdateAdvisorPersona ListAdvisorThreads CreateAdvisorThread SendAdvisorTurn GetAdvisorTurnSources ProposeAdvisorAction ExecuteAcceptedAdvisorAction ArchiveAdvisorThread ``` Naming is illustrative; implementation contract is finalized in typed schemas without creating a separate web-only lifecycle. ## Observability / Audit Record material advisor operations: ```text persona/version thread/turn identity scope source primitive references model/account/provider provenance where allowed latency/failure class accepted proposal -> canonical command linkage policy/authorization denial ``` Do not log secret prompt payload blindly. Observability respects classification/redaction. ## Failure / Recovery Model/provider failure leaves thread durable with retry/switch-provider action according to policy. Source-query partial failure produces explicit partial/stale response state rather than fabricated completeness. Browser refresh/navigation preserves thread and current draft where appropriate. Sending a turn is idempotent against duplicate submit. ## Invariants From Day 1 - advisor scope is explicit; - context is not authorization; - advisor has no secret/private mutation path; - management facts are traceable to AWP sources/freshness; - canonical project truth does not live only in chat memory; - persona/model provenance is versioned; - changing persona instructions cannot rewrite historical turn attribution; - Planner/Advisor/Resolver/Execution agent authority remains distinct. ## Reuse / Provider Boundary Before custom generic conversation/model/history mechanics: ```text Platform AI/provider helpers existing AWP/Platform realtime/chat primitives Astryx AI chat behavior approved provider/account routing seam ``` are inspected/reused where fitting. No external generic “agent framework” becomes AWP domain authority merely because it provides chat/tool loops. ## Increment Realization | Increment | Advisory architecture | |---|---| | I1 | not active; no advisor product behavior. | | I2 | query/context seams may be reused by Planning; no generic advisor surface required. | | I3 | `AdvisorPersona`, `AdvisorThread`, ProjectScoped Project Manager, proposal -> Decision/Approval integration. | | I4 | SystemScoped AWP Advisor + richer Factory/Agent analytics context. | | I5–I8 | expert personas consume activated CI/Delivery/Cluster/Incident domains. | | I9 | organization/tenant persona sharing, retention/governance where productized. | ## Current Implementation State Target specification only. ## Deferred Realization Autonomous background advisory monitoring, organization-shared persona marketplaces and external customer support assistants are not required for first advisor realization. ## Temporary Dogfood Behavior No temporary hidden chat-memory implementation is allowed. When advisors activate, use final `AdvisorPersona`/`AdvisorThread` identities even if the first persona set is only Project Manager. ## Decisions / ADRs Advisor agents are a separate bounded role in the control plane. A future decision to permit autonomous advisor-triggered mutations must still preserve canonical command/policy/Approval authority and cannot be implemented as direct tool side effects.