# AWP Delivery, Deployment, and Connection Planning Design **Date:** 2026-08-19 **Status:** Working product-design baseline; approved direction, not yet implementation-grade spec. **Purpose:** Define how AWP infers, presents, customizes, and enforces CI/CD/deployment choices for every Plan, and how external provider accounts/connections are represented without mixing credentials into project configuration. ## 1. Core position AWP owns software-delivery planning end to end. CI, release, deployment, rollback, promotion, provider/account selection, launch readiness and execution policy are planned product behavior, not implementation details discovered after coding finishes. Do not reduce "CD" to one selector. The effective delivery setup has independent dimensions: ```text QualityStrategy CIPlan ReleaseStrategy EnvironmentStrategy PromotionPolicy DeploymentStrategy DeploymentProvider Rollback / recovery policy Connection requirements and bindings ExecutionPolicy ``` The planner may summarize them together, but AWP stores them separately enough that changing one does not silently redefine the others. ## 2. Project defaults and per-Plan resolution Every Project has an inferred or user-approved `ProjectDeliveryProfile`. More broadly, Planning may maintain project-level expert defaults (`ProjectPlanningDefaults` working concept) for reusable technical choices. For an existing project, AWP infers current delivery behavior primarily from: ```text CI workflows and required checks release/versioning tooling deployment manifests/scripts hosting/provider configuration environments promotion/approval behavior rollback mechanics connected provider/resource metadata ``` For a new project, AWP infers a recommendation from product type, architecture, risk, user journeys, environment needs, target platform, quality requirements and accepted planning decisions. Every PlanRevision resolves an `EffectiveDeliveryPlan` from Project defaults plus explicit Plan overrides: ```text ProjectDeliveryProfile / ProjectPlanningDefaults | +-- inherited defaults | PlanRevision | +-- explicit overrides / discovered requirements v EffectiveDeliveryPlan ``` A Plan-specific exception never silently rewrites Project defaults. ## 3. Simple versus Expert participation Delivery planning is always performed. Participation mode changes whether technical delivery decisions become chat questions. ### Simple AWP resolves delegable expert choices from Project defaults, repository evidence and the least-complex industry-grounded recommendation that satisfies the Plan. The user sees the delivery plan build in structured UI, but is not asked: ```text Which CI do you want? Which runner model? Which deployment strategy? How many agent lanes? Which test pyramid? ``` merely because those decisions exist. Technical decisions are shown with source/confidence and remain editable. Escalate only when the consequence becomes user-owned or policy-required, for example: ```text production should deploy automatically vs require approval acceptable cloud spend/budget customer data residency commitment customer-facing downtime tolerance provider OAuth/account authorization irreversible migration/risk acceptance ``` Ask about that consequence rather than exposing unnecessary implementation jargon. ### Expert The same underlying delivery decisions become eligible for detailed recommendation/review in conversation. The user may accept, refute or customize CI, testing, release, deployment, execution and provider choices. Expert mode remains recommendation-first, not a blank infrastructure questionnaire. ## 4. Recommendation-first UX with compact density Do not ask a chain of separate technical questions. Use compact consequence-first rows: ```text Delivery & execution Quality CUJ-first + affected verification resolved CI GitHub Actions + ARC project default Delivery staging auto / production approval resolved Execution dependency-aware / 3 lanes inferred Connections 1 deferred attention ``` Only the current/reviewed row expands. An expanded row carries: ```text recommendation confidence basis material consequences what would change the recommendation alternatives when useful ``` ### Simple-mode behavior Rows resolve automatically as AWP learns enough. A compact update may say: ```text Technical plan updated Quality, CI and deployment defaults were resolved from this Project's defaults. No action required. [Review] ``` There is no repeated `Use recommended delivery setup` question in chat. ### Expert-mode behavior The integrated recommendation can be explicitly reviewed. `Use recommended setup` is the primary normal-path action and `Review or customize` opens only the relevant dimension. Rejecting one dimension does not reopen accepted ones. ## 5. Existing-project truth model Repository evidence is not automatically intended architecture. When they differ, distinguish: ```text Observed current state Documented intended state User-stated desired state AWP recommendation ``` Example: ```text Observed production deploys manually from a local script Documented intent move deployment to Cloudflare Workers Desired keep explicit production approval AWP recommendation preserve script temporarily behind DeploymentProvider, then migrate trusted deployment into AWP ``` Conflicts become visible Findings/Decisions instead of being collapsed into one inferred truth. ## 6. Open deployment requirements are planning state A sound recommendation can exist before external access is configured. ```text Deployment Cloudflare Workers Connection required Cloudflare account not connected Required by: Deployment preflight [ Connect Cloudflare ] Set up later ``` This is a `ConnectionRequirement`, not an ad-hoc warning. States include: ```text satisfied missing needs resource selection needs additional permission needs re-authentication blocked by policy intentionally deferred ``` Planning may continue until the declared lifecycle gate actually needs the connection. In Simple mode, do not interrupt early for connection setup merely because the future requirement is known. Surface it visibly and ask for user action at the appropriate gate unless the user chooses to connect now. ## 7. Connection and account model Keep provider adapter code, authenticated identity, project usage and secret material separate. ```text ProviderAdapter GitHub / Cloudflare / AWS / GitLab / etc. Connection user-owned authenticated provider identity reusable across Projects multiple Connections per provider allowed ProjectConnectionBinding Project-local authorization to use one Connection capability/role + provider resource scope ConnectionRequirement structured access requirement CredentialReference secret/token reference behind SecretStore ``` Never model a provider as one magic `githubToken` or `cloudflareToken`. ## 8. Capability and resource scoping A Project binding is narrower than the authenticated account. Examples: ```text GitHub capabilities: repository read, checks, PRs, releases, publication resources: installation/org/repository Cloudflare capabilities: Workers, Pages, DNS, R2, KV, D1, account read resources: account, zone, Worker/Pages project ``` Least privilege is default. Binding an account does not grant every provider capability to the Project. ## 9. Connection precedence and selection ```text User Connection registry | v ProjectConnectionBinding(s) | v Plan effective selection | v attempt-bound access grant ``` A Plan may select/narrow among Project-permitted bindings. It cannot silently attach an unrelated user-global Connection. Where several bindings satisfy one role, use explicit selection or a project `ConnectionSelectionPolicy`. ## 10. Connection lifecycle and health Connections are stateful: ```text connected needs-resource-selection needs-permission needs-reauth revoked degraded/error ``` AWP distinguishes credential/permission/resource failures from provider outages. Dependent Plans/Deployments retain their requirement and next action. Connection UX analytics should track: ```text flow started provider auth completed resource selected Project binding completed returned to PlanningSession interrupted decision resumed ``` OAuth completion without return-to-planning is not a successful user journey. ## 11. Secrets and delegation ```text Connection -> CredentialReference -> SecretStore ``` Raw provider secrets are never copied into Project/Plan/Task/Run/CIExecution/Deployment configuration. Agents and CI runners receive only attempt-bound minimum access. Reusable publication/production authority remains in trusted control-plane/provider execution paths. Prefer short-lived/delegated credentials where supported. ## 12. Delivery dimensions AWP must plan Conditional dimensions include: ```text CI provider and runner model verification/quality policy merge gate release cadence/versioning artifact identity and promotion registry/storage environments promotion policy production approval/autonomy provider/target selection deployment technique health/readiness checks rollback/recovery migrations/ordering secrets/config changes post-deploy verification incident/resolver behavior required external connections/resources ``` A static library with no deployment target should not receive a fake deployment interview. ## 13. Deployment strategy selection Recommend from platform/risk rather than generic maturity labels: ```text static site / edge function immutable build -> provider deployment -> health/CUJ check ordinary Kubernetes service rolling update baseline canary/blue-green only when justified stateful migration explicit ordering + compatibility window + rollback/forward-fix policy library/package publication + provenance is the delivery endpoint ``` Progressive delivery is not inherently more mature. ## 14. Continuous delivery versus continuous deployment ```text continuous delivery every qualifying change remains releasable/deployable; production may still require explicit approval continuous deployment qualifying changes automatically reach production after gates ``` The planner recommends the least operationally complex method that satisfies release risk and business needs. In Simple mode, the technical default may be delegated, but the owner-facing consequence of automatic production promotion versus explicit approval is surfaced when it is a business/policy choice. ## 15. Artifact promotion rule When built artifacts exist, default to promoting the **same immutable artifact identity** between environments instead of rebuilding different production binaries. Preserve: ```text source revision artifact digest/identity verification evidence configuration/environment differences promotion history actual deployed identity previous known-good identity ``` ## 16. Deployment readiness and preflight Before deployment-requiring launch activation, verify: ```text EffectiveDeliveryPlan resolved required Connections healthy required ProjectConnectionBindings/resources valid release/artifact path available CI/quality gates satisfied required environments exist configuration/secrets resolved migration prerequisites satisfied production approval/autonomy policy satisfied rollback/recovery path known where required ``` Missing setup becomes `Waiting / Needs attention` without erasing launch intent. Readiness copy must show both immediate permission and future obligation: ```text Ready for implementation You can continue now. Before production: connect Cloudflare production account approve production promotion policy ``` ## 17. Planner-led delivery conversation When Delivery becomes relevant, AWP does not wait for the user to remember it. Simple: ```text resolve delegable delivery choices -> update compact delivery rows -> surface user/business/policy consequences only when needed -> continue agenda ``` Expert: ```text present integrated recommendation -> accept -> or open one dimension for focused discussion -> recompute consequences -> continue automatically ``` Missing connection/resource can be connected inline or deferred to its gate. ## 18. First Expert Plan -> future Simple Plans A first substantial Expert Plan can establish reusable project delivery defaults. At completion AWP proposes default-eligible choices only: ```text quality/testing policy CI provider + runner model release/CD policy environment/promotion defaults deployment provider/strategy connection roles approval conventions execution policy defaults ``` The user explicitly chooses `Use as project defaults` or reviews the candidate set. Plan-specific values such as a one-off migration sequence or temporary concurrency exception are excluded. Later Simple Plans inherit these defaults and expose only technical deltas in the UI unless the user chooses to inspect them. ## 19. Planning workspace placement Stable skeleton: ```text DEFINE DESIGN SPECIFY DELIVER Technical delivery summary Quality CI Release/CD Deployment Connections Execution LAUNCH ``` In Simple mode the technical delivery summary is collapsed by default with status/counts. Blockers and required future user actions remain surfaced. ## 20. Specification follow-up ```text Q1 Exact ProjectDeliveryProfile / ProjectPlanningDefaults / EffectiveDeliveryPlan schemas. Q2 Generalizable-default eligibility vs Plan-specific overrides. Q3 Release/environment/deployment/promotion aggregate boundaries. Q4 ProviderAdapter capability discovery and normalized permission/resource model. Q5 OAuth/token lifecycle, re-authentication, audit and SecretStore contracts. Q6 ProjectConnectionBinding authorization and multi-user ownership. Q7 Plan-level selection without privilege broadening. Q8 Short-lived credential delegation into CI/deployment execution. Q9 Deployment health, rollback, migration and post-deploy verification contracts. Q10 Existing-project observed/documented/desired/recommended conflict model. Q11 Simple/Expert escalation rules for delivery decisions with business/policy consequences. ```