# AWP — Planning & Architecture Review **Status:** Planning baseline for future specification work **Purpose:** Convert the AWP vision into an implementation-oriented architecture and planning review that can be used to create authoritative specifications. **Source:** Derived from the AWP vision document supplied by the project owner. Recommendations introduced by this review are explicitly marked as **Review recommendation** rather than silently treated as original requirements. --- ## 1. Executive Summary AWP should be designed as an **Agentic Software Delivery Control Plane**: a product that owns the desired software-development lifecycle while delegating specialized execution mechanics to replaceable adapters and proven external systems. The core architectural rule should be: > **AWP owns intent, policy, state, relationships, authorization, and lifecycle. Adapters own execution mechanics.** This is the most important distinction between AWP and Overdeck. Overdeck evolved organically from a collection of workstation tools and accumulated architectural inconsistency, weak containment, missing observability, configuration drift, and unclear ownership of the software-delivery lifecycle. AWP should not repeat that history by rebuilding the same functionality behind a cleaner UI. It should begin with a strict domain model, durable state, typed configuration, policy-controlled authority, observable execution, and explicit provider boundaries. The recommended architecture is a **modular monolith for the AWP control plane**, integrated with external systems through adapters. The runtime topology is fixed from day 1 as a **stateless edge/gateway plane -> authoritative AWP control plane -> K3s execution plane**. The gateway and control plane are separate deployable targets even when initially co-located, so a future edge/serverless move does not require extracting public transport concerns from the stateful product core. See `AWP-DEPLOYMENT-TOPOLOGY.md`. The control plane itself should remain one coherent deployable product until real scale or isolation requirements justify splitting domain modules into separate services. The current vision is directionally strong, but the implementation sequence needs two major corrections: 1. **Execution containment must exist from the first usable increment.** K3s cannot be postponed until late in the roadmap if the intent is to eliminate agent execution on the workstation. 2. **Durable observability must exist from the first usable increment.** The polished observability UI may come later, but the event/state model cannot be retrofitted after the factory already exists. The recommended first vertical slice is therefore: ```text Project ↓ Plan ↓ Task ↓ Factory Run ↓ Agent Run in isolated K3s workload ↓ ChangeSet ↓ Review ↓ Merge ``` with durable events, persisted ownership, account/model selection, and enough UI to understand what is happening. --- # 2. Product Definition ## 2.1 Canonical classification AWP should be described primarily as: > **Agentic Software Delivery Control Plane** A secondary description may be: > **A software-development lifecycle operating system for autonomous and supervised agents.** AWP is not primarily: - an AI coding agent; - an agent orchestrator; - a project tracker; - a CI server; - a Kubernetes management product; - a deployment controller; - a Git wrapper. Those are capabilities underneath the product. The distinguishing responsibility of AWP is that it owns the complete desired lifecycle: ```text Project → Planning → Work Management → Factory Execution → Review → CI → Merge → Release → Deployment → Resolution ``` Specialized systems may execute parts of this lifecycle, but AWP remains the authoritative control plane. --- ## 2.2 Product boundary with Overdeck AWP is not a rewrite of Overdeck. Overdeck remains the personal workstation/toolkit environment containing things that are intentionally outside the AWP product boundary, including at least: - Botmaster CLI; - systray tooling; - workstation-specific personal automation; - other personal utilities that do not belong in a general software-delivery platform. AWP should preserve reusable modules, scripts, capabilities, and operational knowledge from Overdeck where they fit the new architecture, but it should not preserve accidental architecture merely because existing code depends on it. The migration principle should be: > **Preserve proven capability; discard accidental coupling.** --- # 3. Problems AWP Exists to Solve The vision identifies four root failures in Overdeck: 1. UI quality and consistency degraded continuously. 2. Observability was insufficient. 3. The factory was not autonomous. 4. Workstation security and containment were unacceptable. A fifth architectural problem underlies all four: 5. Overdeck had no coherent architecture or source-of-truth specification from the beginning. AWP should treat these as architectural constraints, not merely historical context. --- # 4. Non-Negotiable Product Requirements The following should be treated as product-level invariants. ## 4.1 Full lifecycle ownership AWP owns the lifecycle from initial project planning through merged and deployed software. Agents should not be responsible for lifecycle mechanics. Agent responsibilities are limited to: - writing code; - reviewing code; - fixing code; - producing structured decisions only where explicitly delegated by policy. AWP owns: - project state; - planning state; - task state; - work allocation; - workspace creation; - factory orchestration; - CI progression; - merge progression; - release progression; - deployment progression; - cleanup; - retry/resolution policy; - human-in-the-loop decisions; - durable observability. --- ## 4.2 Containment by default Agents must not run directly on the user's workstation as the normal execution model. The standard execution environment should be isolated workloads on K3s. Containment is not an optional later hardening phase. It is part of the initial execution contract. At minimum, every agent workload should have explicit: - identity; - resource limits; - filesystem/workspace scope; - network policy; - credentials/capabilities; - timeout; - lifecycle ownership; - cancellation path; - observability. --- ## 4.3 Full configurability Configuration must be visible and understandable from the web UI at all applicable scopes: ```text System ↓ Project ↓ Plan ↓ Task ↓ Run ``` The user must be able to see: - configured value; - effective value; - where the value came from; - whether it is inherited; - whether it can be overridden; - why a value is read-only; - the schema and valid options. Configuration must not exist only as hidden JSON known to engineers. --- ## 4.4 Full observability AWP must answer, at any point: - What is happening? - Why is it happening? - Which project/plan/task caused it? - Which factory run owns it? - Which agent is acting? - Where is it running? - What model/account is being used? - What changed? - What failed? - What is waiting? - Why is it waiting? - What happens next? - Does the user need to act? Raw JSON must never be the primary product UX for normal operational understanding. --- ## 4.5 Configurable autonomy AWP must be capable of fully autonomous operation but must not mandate autonomy. Human-in-the-loop behavior must be configurable by policy. Examples include decisions involving: - architecture; - implementation deviations; - test modifications; - security findings; - merges; - staging; - production; - custom project events; - arbitrary content conditions. The system must eventually support rules as arbitrary as requiring human involvement when a defined textual or behavioral condition occurs. --- ## 4.6 Proven infrastructure first AWP should avoid rebuilding commodity infrastructure. Before implementing a subsystem, the project should explicitly evaluate whether a permissively licensed external system can provide the execution mechanics behind an AWP adapter. The vision already identifies candidate roles for: - Fabro — factory workflow execution; - ARC — **day-one** Kubernetes-hosted GitHub Actions runner lifecycle/scaling; - K3s — workload execution substrate; - Subrouter — model/account routing; - existing Overdeck deployment recovery scripts — deterministic operational resolvers. **Review recommendation:** Flux should be evaluated for Kubernetes GitOps/CD reconciliation rather than implementing AWP's own Kubernetes reconciler. The exact provider choice for each capability should be finalized in dedicated integration specifications. --- # 5. Architectural Verdict ## 5.1 Recommended architecture: modular monolith The AWP control plane should begin as a modular monolith. This is appropriate because: - the domains are strongly related; - lifecycle operations require transactional coordination; - premature distributed boundaries would multiply operational complexity; - external providers already make the overall system distributed; - AWP needs strong internal invariants more than independently scalable services; - modular boundaries can later become process boundaries if required. Do not begin with independent services for Projects, Planning, Factory, Accounts, Cluster, CI, and CD. Instead, define strict internal modules with narrow interfaces. Suggested top-level structure: ```text awp/ ├── identity ├── projects ├── planning ├── work ├── factory ├── agents ├── vcs ├── ci ├── releases ├── cd ├── deployments ├── environments ├── cluster ├── accounts ├── models ├── policies ├── configuration ├── incidents ├── artifacts ├── observability ├── audit └── adapters ``` This is a conceptual module map, not yet a filesystem mandate. --- ## 5.2 Control plane versus execution plane AWP should maintain a strict distinction between control-plane state and execution-plane mechanics. ```text AWP ┌──────────────────┐ │ CONTROL PLANE │ │ │ │ Projects │ │ Plans │ │ Work │ │ Policies │ │ Factory Runs │ │ CI/CD │ │ Configuration │ │ Audit/Events │ └────────┬─────────┘ │ adapters ┌─────────────────┼─────────────────┐ │ │ │ ▼ ▼ ▼ Factory Git/VCS Accounts provider provider provider │ │ │ └──────────┬──────┴──────────┬──────┘ ▼ ▼ K3s CI/CD execution plane providers ``` AWP should be authoritative for lifecycle meaning. External systems should be authoritative only for the mechanics they perform. --- # 6. Primitive Model The vision uses the principle "Everything is a primitive." This is useful but must be constrained to prevent every setting or operation from becoming an artificial domain object. ## 6.1 Primitive qualification rule A concept should normally become a first-class primitive when it has meaningful independent: - identity; - state; - lifecycle; - relationships; - policy; - configuration; - events. A primitive is not simply "anything that appears in the product." --- ## 6.2 Recommended canonical primitives ### Product and planning - Project - Repository - Plan - WorkItem - Wave - Phase - Task ### Execution - Workflow - FactoryRun - Agent - AgentRun - Workspace - Attempt ### AI/provider - Provider - Model - Account - AccountSelectionPolicy ### Source and change - ChangeSet - Commit - Review - Merge ### CI - ChangeClassification - Capability - Check - CIInvariant - CIExecutionPlan - CIResult ### Delivery - Artifact - Release - Environment - Deployment ### Infrastructure - Cluster - Machine - MachineCapability - Workload - PlacementDecision ### Governance - Policy - Approval - Decision - Principal - Role - Permission - CredentialReference ### Operations - Incident - Resolver - ResolutionAttempt ### Communication - CommunicationEndpoint - Notification --- ## 6.3 Concepts that should not automatically become primitives Examples: - retry count; - timeout; - branch prefix; - SSH port; - temperature; - UI page size. These are usually configuration values or telemetry. Operations such as: - merge; - deploy; - approve; - clone; - retry; are usually commands/events applied to primitives rather than independent primitives themselves. --- # 7. Canonical Relationship Model A core relationship graph should exist before feature implementation. Recommended baseline: ```text Project ├── Repository* ├── Plan* │ ├── WorkItem* │ │ ├── Wave / Phase / Task hierarchy │ │ └── FactoryRun* │ │ ├── AgentRun* │ │ │ ├── Workspace │ │ │ ├── Tool activity │ │ │ └── ChangeSet* │ │ └── Result │ ├── CIExecution* │ ├── Release* │ └── Deployment* ├── Environment* ├── Policy* └── Configuration* ``` The exact hierarchy should not assume that every FactoryRun maps one-to-one to one Task. --- # 8. Factory Run Scope The vision explicitly questions whether a factory runs on a task, phase, or wave. The architecture should support all of them. Recommended model: ```text FactoryRun scope: type: task | phase | wave | plan | adhoc id: ``` Examples: ```text Plan └── Wave 3 └── FactoryRun FR-42 ├── Task 11 │ └── AgentRun AR-87 ├── Task 12 │ └── AgentRun AR-88 └── Task 13 ├── AgentRun AR-89 └── AgentRun AR-90 ``` or: ```text Task 11 └── FactoryRun FR-43 ├── implementation ├── review └── correction ``` Factory execution should therefore be scoped, not hard-coded around one work-management level. --- # 9. Workspace Abstraction The vision says AWP should own Git worktrees. The user requirement is correct, but the architectural primitive should be **Workspace**, not **Worktree**. AWP should expose a deep interface such as: ```text Workspace.create(repository, revision, isolationPolicy) Workspace.status(id) Workspace.collectChanges(id) Workspace.destroy(id) ``` A provider may implement that through: - Git worktrees; - ephemeral clones; - persistent volumes; - remote development environments; - future sandbox providers. This avoids coupling the product model to one Git implementation detail. --- # 10. Durable Execution Ownership A control plane cannot safely orchestrate autonomous work without persisted ownership. Every asynchronous execution should support: - lease owner; - heartbeat; - attempt number; - timeout; - retry policy; - cancellation; - recovery; - idempotency key; - terminal state; - failure reason. Recommended principle: > **Use at-least-once execution with idempotent operations and a single persisted lease owner rather than assuming exactly-once execution.** This applies to: - task dispatch; - factory runs; - agent runs; - merge actions; - CI plan execution; - deployment; - resolver runs; - machine enrollment steps. This should be specified before factory concurrency is implemented. --- # 11. Event and Audit Architecture Observability must be built from durable structured state, not scraped from logs later. ## 11.1 Business events Important lifecycle changes should produce structured events. Examples: ```text ProjectCreated PlanApproved TaskReady TaskAssigned FactoryRunCreated FactoryRunStarted FactoryStageEntered FactoryRunCompleted FactoryRunFailed AgentRunStarted AgentHeartbeat AgentToolExecuted AgentChangeProduced AgentRunCompleted ReviewRequested ReviewPassed ReviewFailed HumanApprovalRequested HumanApprovalGranted HumanApprovalRejected CIPlanned CICheckStarted CICheckPassed CICheckFailed MergeRequested MergeCompleted MergeFailed ReleaseCreated DeploymentStarted DeploymentHealthy DeploymentFailed RollbackStarted RollbackCompleted IncidentOpened ResolverStarted ResolverSucceeded ResolverFailed ``` --- ## 11.2 Event requirements Each durable lifecycle event should normally include: - event ID; - event type; - occurred-at timestamp; - actor/principal; - project; - related primitive IDs; - correlation/run ID; - causation ID; - attempt; - structured payload; - schema version. Events must make it possible to reconstruct why state changed. --- ## 11.3 Telemetry is separate Metrics, logs, and distributed traces remain important, but they are not the same thing as AWP business events. The architecture should distinguish: ```text Business state/events = durable lifecycle truth Operational telemetry = runtime diagnosis and performance data ``` An external telemetry stack may handle transport/storage for normal metrics, logs, and traces without becoming the source of truth for plan/task/deployment state. --- # 12. Artifact and Provenance Model AWP should model the identity of what was produced. The platform should eventually be able to answer: ```text This Deployment came from this Release containing this Artifact built from this Commit/ChangeSet produced by this FactoryRun for this Task belonging to this Plan belonging to this Project ``` Recommended primitives include: - ChangeSet; - Commit; - Build; - Artifact; - TestResult; - ReviewResult; - Release; - Deployment. This is essential for rollback, audit, reproducibility, and trustworthy automation. --- # 13. Identity, Authorization, and Capability Model Security cannot rely on "the AWP process has credentials." ## 13.1 Principals Recommended principals: ```text Principal ├── Human ├── Agent └── System ``` Every meaningful action should be attributable to a principal. --- ## 13.2 Authority must be scoped The fact that AWP can perform an action does not mean an agent can perform it. Example: ```text AWP controller: may merge Coding agent: may modify workspace may run approved tools may request merge may NOT merge ``` This is a critical control-plane boundary. --- ## 13.3 Narrowing-only capability inheritance **Review recommendation:** security/capability policies should inherit downward and normally only become narrower. ```text System capability ceiling ↓ Project ↓ Plan ↓ Task ↓ Run ``` A child scope should not grant itself authority denied by its parent. This should be separate from normal non-security configuration, where child scopes may legitimately override parent defaults. --- # 14. Account, Provider, and Model Management The vision requires: - one global token owner; - account selection per project; - account selection per plan; - account selection per task; - provider/model configurability. Recommended primitives: ```text Provider Model Account AccountPool AccountSelectionPolicy BudgetPolicy FallbackPolicy ``` Configuration should reference accounts by logical identity rather than copying credentials into workloads. Example: ```text Project: codingAccount = codex-main codingModel = default-coder Task 53: codingAccount = codex-secondary architectureResolver = high-reasoning ``` The account-management provider should be replaceable behind an adapter. The final provider choice should be validated in a dedicated integration specification rather than embedded in the domain model. --- # 15. Configuration Management K3s is not sufficient as AWP's configuration-management system. Kubernetes configuration can manage workloads, but it does not provide the product-level semantics required by AWP. AWP needs its own typed configuration registry. ## 15.1 Scope hierarchy ```text System ↓ Project ↓ Plan ↓ Task ↓ Run ``` --- ## 15.2 Required configuration behavior Each setting should define: - key; - type; - schema; - default; - valid values; - inherited value; - local override; - effective value; - mutability; - source; - explanation; - change history. UI example: ```text Max concurrent agents Effective value: 4 Defined at: Plan Project value: 8 System ceiling: 20 [ Edit ] ``` A read-only value should explain why it is read-only. --- ## 15.3 Configuration drift AWP should distinguish: - desired configuration; - applied configuration; - observed runtime configuration. A drift condition should be observable and actionable rather than silently repaired without history. --- # 16. Human-in-the-Loop and Autonomy Policy The user-facing 0–100 autonomy control is useful, but the backend should not encode autonomy as a single integer. The backend should use a generic policy engine. Recommended rule shape: ```text WHEN IF THEN ``` Examples: ```text WHEN architecture.changed THEN require_human_approval WHEN deployment.requested IF environment == production THEN require_human_approval WHEN security.finding IF severity >= high THEN pause WHEN merge.requested IF project == internal-tooling THEN autonomous WHEN agent.output.created IF output matches custom rule THEN require_human_approval ``` --- ## 16.1 Autonomy level as policy preset The 0–100 control should generate/edit policies rather than replace them. Possible UX interpretation: ```text 0 Autonomous 25 Major-risk gates 50 Architecture / security / production gates 75 Most decision points require approval 100 Exhaustive supervision ``` Advanced configuration exposes the actual rules. --- ## 16.2 Resolver decisions Fully autonomous mode requires explicit handling for cases where the active agent cannot safely decide. Recommended model: ```text DecisionRequired ↓ AutonomyPolicy ↓ Human required? / \ yes no ↓ ↓ Human ResolverPolicy ↓ ResolverModel ↓ structured Decision ↓ policy validation ↓ continue ``` Resolver output should be a durable structured decision object, not merely another chat message. --- # 17. Planning Model The current planning concept mixes independent dimensions. The planning UX should separate them. ## 17.1 Software plan The first planning stage answers: - What are we building? - Why? - Who is it for? - What are the constraints? - What already exists? - What is in/out of scope? - What is the target architecture? - What are the acceptance conditions? This should be produced interactively through brainstorming and interview. --- ## 17.2 Delivery strategy Recommended conceptual options: - Predictive; - Iterative; - Incremental; - Iterative + Incremental; - Continuous Flow; - Custom. "Waterfall" can be represented as a Predictive preset. "Agile" should not be treated as the opposite of Incremental. --- ## 17.3 Work management Keep these as distinct presets: - Scrum; - Kanban; - Scrumban; - Custom. Scrumban should not remove the need for Scrum and Kanban because the presets imply meaningfully different policies. Example semantics: ```text Scrum iteration = sprint commitment = sprint planning/review/retro enabled Kanban continuous pull explicit WIP limits no required sprint Scrumban continuous pull WIP limits selected Scrum planning/review practices Custom exposes underlying controls ``` --- ## 17.4 Release strategy Separate this from work management: - major/batched release; - incremental release; - continuous delivery; - continuous deployment; - custom. --- ## 17.5 Planning lifecycle Recommended UX flow: ```text Project Onboarding ↓ VISION ↓ GOLIVE ↓ Interactive Software Plan ↓ Delivery Configuration ├── delivery strategy ├── work management ├── release strategy ├── environments ├── quality policy └── autonomy policy ↓ Execution Preview ↓ Approval ↓ Factory ``` --- # 18. Project Management Model AWP should present itself as a project manager, not merely a low-level agent runner. The hierarchy should be navigable throughout the UI: ```text Project → Plan → Work item → Factory Run → Agent Run ``` Every object should be clickable wherever practical. Breadcrumbs should make relationships explicit. A user should be able to move from: ```text Agent → Factory Run → Task → Plan → Project ``` without searching for IDs. --- # 19. Factory Integration Boundary The factory provider should execute workflow graphs, but AWP should retain lifecycle meaning. Recommended boundary: ```text AWP Factory primitive │ FactoryProvider interface │ Provider adapter │ Factory engine ``` AWP owns: - why the FactoryRun exists; - project/plan/work relationship; - autonomy policy; - account/model policy; - scheduling policy; - human approvals; - lifecycle before and after factory execution; - product UI; - audit/event relationships. The factory provider owns execution mechanics such as: - workflow graph execution; - stage transitions; - provider-native retries; - stage outputs; - factory-native event streaming. This boundary should be formalized in an adapter contract. --- # 20. CI Architecture The CI vision is strong and should remain a differentiating AWP capability. The key idea is: ```text changed files ↓ affected components ↓ affected capabilities ↓ CI invariants ↓ required checks ↓ CI execution plan ``` Avoid literal path rules such as: ```text if .ts changed → typecheck ``` because configuration, shared packages, generated code, schemas, lockfiles, and build-system changes can affect TypeScript without changing ordinary source files. --- ## 20.1 Recommended CI primitives ```text CI ├── Provider ├── Pipeline ├── ChangeSet ├── ChangeClassifier ├── DependencyGraph ├── Capability ├── Check ├── Invariant ├── ExecutionPlan ├── Result ├── Resolver └── Optimizer ``` --- ## 20.2 CI invariants Examples: ```text Every pull request: compile affected code run affected tests satisfy applicable lint policy Never: run PHP tests for docs-only changes run unrelated frontend builds duplicate identical checks ``` The policy layer must determine correctness; optimization must not silently remove required verification. --- ## 20.3 CI optimizer The optimization agent may: - detect redundant checks; - identify checks that historically provide no value; - identify missing coverage; - suggest dependency relationships; - analyze historical runtime; - propose CI specification changes. It must not directly weaken CI. Its output should become a normal proposed change processed through AWP's own lifecycle. --- ## 20.4 CI provider boundary AWP should own: - CI semantics; - impact analysis; - invariants; - execution planning; - results and history; - resolver policy; - optimization policy. The underlying CI provider should execute the resulting jobs. ARC, where selected, should be considered an infrastructure mechanism for Kubernetes-hosted runner lifecycle rather than the CI semantics layer itself. --- # 21. CD and Deployment Architecture Recommended delivery model: ```text CI passed ↓ Artifact ↓ Release ↓ Environment ↓ Deployment ↓ Health evaluation / \ ok failure ↓ deterministic resolver ↓ still failing? ↓ agentic resolver ``` AWP owns: - release intent; - release identity; - approval; - environment; - deployment state; - rollback policy; - deployment health; - incident creation; - resolver selection. A CD provider should own the mechanical reconciliation/deployment procedure. **Review recommendation:** evaluate Flux as the Kubernetes CD/GitOps provider so AWP does not build its own reconciliation engine. --- # 22. Resolver Architecture The vision already contains a valuable pattern: ```text failure ↓ known mechanical solutions ↓ still broken? ↓ resolver agent ↓ new reusable solution ``` This should become a general AWP incident-resolution framework. Recommended primitives: ```text Incident Resolver ResolutionAttempt ResolutionRecipe ``` A resolver attempt should record: - incident classification; - selected resolver; - input state; - actions attempted; - result; - created/modified recipe; - approval requirement; - verification evidence. An agent-created resolver recipe should not become trusted infrastructure merely because it worked once. It should enter the normal AWP review/validation workflow. --- # 23. Cluster Architecture The cluster primitive should not expose Kubernetes internals as the primary user model. Recommended conceptual model: ```text Cluster ├── Machine │ ├── MachineCapability │ ├── Health │ ├── Workload* │ └── Queue ├── SchedulingPolicy └── PlacementDecision ``` --- ## 23.1 Machine capabilities Capabilities should be first-class and declarative. Example: ```text node-03 cpu: 32 memory: 128 GB gpu: none storage: 2 TB labels: factory: true ci: true ``` --- ## 23.2 Workload requirements Work should declare requirements rather than hard-code nodes. Example: ```text requires: cpu: 4 memory: 8Gi labels: factory: true prefers: architecture: amd64 forbids: production-node: true ``` AWP should record the placement decision and why the machine was selected. --- ## 23.3 Machine enrollment User model: ```text Cluster [+ Add Machine] ``` Workflow: ```text Connection → Preflight → Configure → Join → Verify → Ready ``` Preflight includes: - connectivity; - OS/architecture; - CPU/RAM/disk; - required ports; - existing runtime detection; - existing cluster membership; - compatibility. The user should not need to understand K3s commands. K3s belongs behind the adapter. --- # 24. Cluster Page UX The page should answer: 1. Is the execution infrastructure healthy? 2. How much capacity is available? 3. What is running where? 4. What is waiting, and why? Suggested summary: ```text Cluster Healthy Nodes 3 / 3 Ready Agents 7 running CI runners 2 running Queued 4 CPU 38 / 64 Memory 71 / 192 GB Storage 1.2 / 5 TB ``` Machine table: ```text Machine Health CPU RAM Disk Running Queue node-01 Ready 13/16 22/32 38% Agent #81 1 node-02 Ready 18/32 31/128 42% CI ×2 0 node-03 Ready 7/16 18/32 54% Agent ×3 3 ``` A critical UX feature should be **placement explainability**. Example: ```text Task #402 waiting Needs: CPU ≥ 8 RAM ≥ 32 GB factory=true node-01 ✗ RAM node-02 ✓ eligible node-03 ✗ RAM Waiting because: node-02 concurrency cap reached ``` "Queued: 1" without a reason is instrumentation, not useful observability. --- # 25. UI Architecture and Page Model The UI should be self-explanatory rather than narrating itself. Global UX principles: - visible hierarchy; - clickable relationships; - meaningful status language; - no raw JSON as primary UI; - progressive disclosure; - explainable waiting/blocking; - consistent object/detail patterns; - hover help for unfamiliar controls; - operational information presented in domain language. Each page should receive its own specification containing: - purpose; - user question answered by the page; - information architecture; - primary journey; - secondary journeys; - empty/loading/error states; - permissions; - data freshness; - interactions; - responsive behavior; - keyboard/accessibility behavior; - diagram/wireframe. --- # 26. Overview Page Primary question: > What needs my attention across AWP right now? Recommended content: - projects in progress; - plans at risk; - human approvals required; - blocked work; - cluster health; - AWP service health; - deployments at risk; - unresolved incidents. The overview should prioritize actionability over general statistics. --- # 27. Project Page Primary question: > Is this project progressing toward its goal, and where does it need intervention? Required surfaces: - GOLIVE progress; - active plans; - plan progress; - human-in-the-loop requests; - PR/release/CI/deployment queues where applicable; - CI health; - CD health; - current incidents; - current factory activity; - recent releases/deployments. --- # 28. Plan Page Primary question: > What is the plan, how far has it progressed, and what is executing right now? Required surfaces: - plan status; - delivery method; - waves/phases/tasks; - dependencies; - current FactoryRuns; - current AgentRuns; - blocked work; - approvals; - upcoming work; - completed evidence. The page must make concurrency visible. Example: ```text Wave 3 / 7 FactoryRun FR-42 Task 11 / 12 Agent Terra Account codex:zync Working Task 12 / 12 Agent Terra Waiting for review ``` --- # 29. Factory Run Page Primary question: > What is this factory execution doing, what has happened, and what is blocking completion? The dominant surface should be the execution graph. Concept: ```text ┌───────────────────────────────────────────────────────────────┐ │ Project / Plan / Wave 3 / FactoryRun FR-42 │ │ Running · 34m · 7/11 stages · 3 agents · 1 gate │ ├───────────────────────────────────────────────────────────────┤ │ │ │ ✓ Plan ──→ ✓ Implement A ──→ ● Review A ──┐ │ │ └──→ ✓ Implement B ──→ ● Test B ─────┼─→ Merge │ │ └──→ ● Implement C │ │ │ └─ Waiting │ │ │ ├──────────────────────────────────────────────┬────────────────┤ │ Activity │ Inspector │ │ 12:31 Agent A used git diff │ Review A │ │ 12:32 4 files changed │ Agent: Terra │ │ 12:33 Review started │ Task #31 │ │ │ [Open Agent] │ └──────────────────────────────────────────────┴────────────────┘ ``` Suggested tabs: ```text Overview | Graph | Changes | Checks | Activity | Artifacts ``` --- # 30. Agent Page Primary question: > What is this agent doing right now, what has it done, and what has it changed? The page should use a chat-like interaction model but enrich it with structured operations. Suggested structure: ```text ┌──────────────────────────────────────────────────────────────┐ │ Agent Terra · Working │ │ Project › Plan › Task › FactoryRun │ ├─────────────────────────────────────┬────────────────────────┤ │ Conversation │ Run │ │ │ Model │ │ assistant... │ Account │ │ │ Node │ │ [Tool] Read src/foo.ts │ Started │ │ [Tool] npm test │ Tokens │ │ │ Cost │ │ assistant... │ │ │ │ Changes │ │ │ +42 -13 │ ├─────────────────────────────────────┴────────────────────────┤ │ Chat | Tools | Diff | Files | Events │ └──────────────────────────────────────────────────────────────┘ ``` Tool calls should be structured UI objects. Diffs should be rendered as diffs. Raw provider logs can remain accessible for debugging but are not the default presentation. --- # 31. Specification System The project needs an authoritative spec system from the beginning. The existing proposed structure is directionally correct but risks duplication between domain and workflow files. Recommended structure: ```text spec/ ├── INDEX.md │ ├── architecture/ │ ├── principles.md │ ├── domain-model.md │ ├── module-boundaries.md │ ├── event-model.md │ ├── security.md │ ├── configuration.md │ └── adapter-contracts.md │ ├── domains/ │ ├── projects/ │ ├── planning/ │ ├── work/ │ ├── factory/ │ ├── agents/ │ ├── vcs/ │ ├── ci/ │ ├── releases/ │ ├── cd/ │ ├── deployments/ │ ├── cluster/ │ ├── accounts/ │ ├── autonomy/ │ └── incidents/ │ ├── workflows/ │ ├── project-onboarding.md │ ├── plan-to-production.md │ ├── factory-execution.md │ ├── ci-resolution.md │ └── deployment-resolution.md │ ├── ui/ │ ├── overview.md │ ├── project.md │ ├── plan.md │ ├── factory-run.md │ ├── agent.md │ ├── cluster.md │ └── settings.md │ ├── schemas/ │ ├── configuration/ │ ├── events/ │ └── adapters/ │ └── adr/ ├── 0001-modular-monolith.md ├── 0002-factory-provider-boundary.md └── ... ``` --- ## 31.1 Spec category definitions ### Architecture spec Defines system-wide constraints and invariants. Example: ```text architecture/security.md ``` answers: - how authority is modeled; - how capability inheritance works; - how credentials are referenced; - what an agent is allowed to do. ### Domain spec Defines what one domain is. Example: ```text domains/factory/ ``` answers: - what a FactoryRun is; - its states; - relationships; - commands; - events; - invariants. ### Workflow spec Defines interaction across domains. Example: ```text workflows/plan-to-production.md ``` answers: - how Plan, Work, Factory, CI, Release, Deployment interact. ### UI spec Defines how humans operate domain concepts. Example: ```text ui/factory-run.md ``` answers: - page purpose; - information hierarchy; - actions; - states; - journeys. ### ADR Records why an architectural decision was made. ADRs should not duplicate the full specification. They preserve decision history. --- # 32. Spec-as-Source-of-Truth Enforcement The authoritative specification should be: > **the latest merged spec on the main branch.** Feature branches may contain proposed future specs. Architecture-affecting implementation changes should update the corresponding specs in the same logical change. Recommended invariant: ```text Architecture/domain behavior changes ↓ affected spec identified ↓ spec updated ↓ implementation updated ↓ CI validates spec references/schemas ↓ spec + implementation merge atomically ``` Avoid requiring a speculative spec to land independently on main before implementation. The spec and implementation should become authoritative together. --- # 33. Spec Quality Requirements Every future domain spec should answer at least: 1. Purpose. 2. Scope. 3. Non-goals. 4. Primitive definitions. 5. IDs and identity. 6. State machine. 7. Relationships. 8. Commands. 9. Events. 10. Invariants. 11. Authorization. 12. Configuration. 13. Failure modes. 14. Retry/idempotency behavior. 15. Provider/adapter boundary. 16. Observability. 17. Persistence. 18. API expectations. 19. UI implications. 20. Migration/versioning behavior. 21. Open questions. 22. Acceptance criteria. A spec that only describes a happy-path UI is not implementation-ready. --- # 34. Recommended Delivery Sequence The original incremental plan should be reordered. ## Increment 0 — Foundation and self-hosting substrate Goal: make it possible for AWP to begin building AWP without recreating workstation insecurity. Include: - modular-monolith skeleton; - spec framework; - core IDs/types; - database/state model; - event/audit foundation; - identity/capability skeleton; - typed configuration registry; - adapter framework; - minimal Git provider; - minimal account/model provider; - K3s execution substrate; - isolated workload contract; - durable execution leases; - basic operational telemetry. No polished Cluster product surface is required yet. --- ## Increment 1 — First complete vertical slice Goal: prove one complete lifecycle. ```text Project ↓ Plan ↓ Task ↓ FactoryRun ↓ AgentRun on K3s ↓ ChangeSet ↓ Review ↓ Merge ``` Required characteristics: - durable state; - observable progress; - account/model selection; - isolated execution; - cleanup; - retries; - failure visibility; - enough UI to understand the run. No sophisticated planning UX is required yet. No production CD is required yet. --- ## Increment 2 — Real planning Add: ```text Project onboarding ↓ VISION ↓ GOLIVE ↓ Interactive software plan ↓ Delivery configuration ↓ Execution preview ↓ Approval ↓ Factory ``` This is when AWP begins to own planning properly. --- ## Increment 3 — Generic autonomy policy Introduce: - Policy; - Approval; - Decision; - ResolverPolicy. Start with presets for: - architecture; - merge; - production. Then generalize. --- ## Increment 4 — Full factory observability UX Deepen: - graph visualization; - live run status; - agent chat; - structured tool activity; - diffs; - files; - checkpoints; - retries; - relationships; - artifacts; - cost/token information. Important: the data/event model for this already existed in Increment 0/1. Increment 4 is primarily the productization of that observability. --- ## Increment 5 — CI control plane Add: - change classification; - dependency graph; - capability mapping; - invariants; - CI planning; - provider adapter; - result ingestion; - resolver; - optimizer. ARC or any runner manager remains execution infrastructure underneath the CI provider. --- ## Increment 6 — Release and deployment Add: - Artifact; - Release; - Environment; - Deployment; - deployment provider; - health evaluation; - rollback; - deployment resolver. Evaluate a GitOps/CD provider rather than implementing Kubernetes reconciliation inside AWP. --- ## Increment 7 — Cluster product surface K3s is already used. This increment adds the full user-facing cluster-management capability: - machine enrollment; - lifecycle; - labels/capabilities; - scheduler UX; - capacity; - health; - queues; - maintenance; - placement explainability. --- ## Increment 8 — Self-healing operations Add generic Incident/Resolver infrastructure. ```text Incident ↓ Known deterministic resolver ↓ Still failing? ↓ Agentic resolver ↓ Verified fix ↓ Reusable resolver proposal ↓ Normal AWP review workflow ``` --- ## Increment 9 — Productization Because AWP is intended to become usable by external customers, later work should explicitly address: - organizations; - users; - RBAC; - tenant isolation; - resource quotas; - retention; - audit export; - backup/restore; - upgrade/migration strategy; - stable public API; - stable adapter SDK; - installation/onboarding; - supportability. Do not force multi-tenancy into the first increments, but do not make architectural choices that make it impossible later. --- # 35. What Must Exist Before Coding the Factory The following should be considered architectural prerequisites: - primitive qualification rules; - Project/Plan/Work/FactoryRun/AgentRun relationships; - durable ID rules; - persisted execution lease semantics; - event envelope; - configuration hierarchy; - capability/authorization hierarchy; - Workspace abstraction; - adapter contract; - minimum K3s workload isolation contract; - failure/retry/idempotency conventions. Without these, the new factory risks becoming another collection of working scripts without a durable architecture. --- # 36. What AWP Should Explicitly Avoid Building Unless a dedicated architecture review proves otherwise, avoid implementing: - a custom Kubernetes distribution; - a custom generic Git server; - a custom CI runner autoscaler; - a custom model-provider OAuth/token platform; - a custom GitOps reconciliation engine; - a second factory workflow engine where an adapter can suffice; - a generic telemetry backend; - workstation automation that belongs in Overdeck; - provider-specific behavior in domain modules; - raw provider JSON as product UI. AWP should build the semantic layer that does not already exist: - lifecycle ownership; - project-manager UX; - planning UX; - policy; - primitive relationships; - observability semantics; - CI impact planning; - autonomy; - control-plane state; - cross-provider orchestration. --- # 37. Architectural Risks ## Risk 1 — Adapter leakage If provider-specific concepts appear directly in core domain code, AWP will become permanently coupled to the first provider. **Mitigation:** define capability-based adapter contracts before provider implementations. --- ## Risk 2 — "Everything is a primitive" becomes object inflation If every field becomes a primitive, the architecture becomes ceremonial and shallow. **Mitigation:** use the primitive qualification rule. --- ## Risk 3 — Event model postponed If observability is implemented only when the UI is built, early execution paths will be opaque. **Mitigation:** durable lifecycle events from Increment 0/1. --- ## Risk 4 — K3s treated as late infrastructure If agents still execute directly on workstations while AWP's core is developed, containment remains an optional retrofit. **Mitigation:** K3s execution substrate in Increment 0. --- ## Risk 5 — Control plane becomes execution engine If AWP itself starts implementing every CI/factory/CD detail, it recreates the maintenance problem it is meant to solve. **Mitigation:** enforce control-plane/execution-plane boundaries. --- ## Risk 6 — Configuration and secrets become mixed A UI-editable configuration matrix can become dangerous if credentials are represented as normal configuration. **Mitigation:** store logical credential references; keep secret material behind dedicated providers. --- ## Risk 7 — "Autonomous" becomes unreviewable Resolver models making invisible decisions would make the product impossible to audit. **Mitigation:** durable Decision primitives and policy validation. --- ## Risk 8 — Spec duplication Duplicating the same semantics across architecture, domain, workflow, and UI specs will reintroduce the source-of-truth problem. **Mitigation:** give every spec category a defined responsibility and link rather than restate authoritative rules. --- # 38. Architecture Decision Register The following decisions are mature enough to treat as provisional architectural decisions pending formal ADRs. | ID | Decision | Status | |---|---|---| | ADR-001 | AWP is an Agentic Software Delivery Control Plane | Recommended | | ADR-002 | AWP control plane starts as a modular monolith | Recommended | | ADR-003 | Agents do code/review/fix; AWP owns lifecycle mechanics | Vision requirement | | ADR-004 | Normal agent execution occurs in isolated K3s workloads | Vision requirement | | ADR-005 | Control-plane semantics are provider-independent | Recommended | | ADR-006 | Factory execution is behind a provider adapter | Recommended | | ADR-007 | Workspace is the domain abstraction; Git worktree is an implementation | Recommended | | ADR-008 | Durable lifecycle events exist before full observability UI | Recommended | | ADR-009 | Configuration inherits System → Project → Plan → Task → Run | Vision + review refinement | | ADR-010 | Security capabilities inherit downward and normally narrow | Recommended | | ADR-011 | Human-in-the-loop uses generic policy rules; 0–100 is a UX preset | Recommended | | ADR-012 | FactoryRun supports task/phase/wave/plan/adhoc scopes | Recommended | | ADR-013 | CI is modeled through change impact + capabilities + invariants | Vision requirement | | ADR-014 | CI optimizer proposes changes but cannot silently weaken policy | Vision requirement | | ADR-015 | Cluster product UI is late, cluster execution substrate is early | Recommended | | ADR-016 | Specs and implementation become authoritative together on main | Recommended | | ADR-017 | AWP builds semantic orchestration; commodity mechanics remain external where possible | Vision requirement | --- # 39. Open Decisions Requiring Dedicated Specs or ADRs These should not be guessed during implementation. ## Architecture - primary implementation language/runtime; - persistence database; - transaction boundaries; - command/event delivery mechanism; - whether any modules require independent workers from the start; - public/internal API strategy; - event retention strategy. ## Factory - exact Fabro integration contract; - how Fabro-native run IDs map to AWP FactoryRun IDs; - checkpoint semantics; - pause/resume semantics; - cancellation guarantees; - provider failure behavior. ## Git/VCS - GitHub-only initially versus generic VCS interface; - PR versus direct-merge policies; - branch naming; - merge queue ownership; - workspace storage in K3s; - artifact collection from workspaces. ## Accounts/models - final account-provider choice; - account failover; - sticky assignment; - quota/budget behavior; - shared-account concurrency; - refresh-token ownership. ## Cluster - K3s topology; - control-plane HA requirements; - storage class; - network policy; - ingress; - node trust/enrollment; - machine removal; - upgrades; - backup/restore. ## CI - source of dependency graph; - how projects declare capabilities; - how generated files/config files affect classification; - GitHub Actions workflow generation versus static workflow; - result reconciliation; - cache strategy. ## CD - deployment provider; - GitOps repository structure; - environment promotion; - rollback semantics; - health checks; - database migration coordination. ## Productization - tenancy model; - authentication; - customer installation model; - support boundaries; - telemetry/privacy defaults. --- # 40. Spec Creation Backlog This is the recommended order for turning the vision into implementation-grade specifications. ## Phase A — Architecture foundation ### SPEC-A01 — Architecture Principles Define: - control plane versus execution plane; - modular-monolith rule; - primitive qualification; - provider independence; - containment; - observability; - configuration; - spec authority. **Blocks:** almost everything else. --- ### SPEC-A02 — Canonical Domain Model Define IDs, primitives, relationships, ownership, and terminology. Include at minimum: - Project; - Plan; - WorkItem; - FactoryRun; - AgentRun; - Workspace; - ChangeSet; - Policy; - Approval; - Incident. **Blocks:** persistence, APIs, UI, factory. --- ### SPEC-A03 — Module Boundaries Define: - modules; - public interfaces; - dependencies; - forbidden dependencies; - ownership of database tables/types/events; - adapter placement. --- ### SPEC-A04 — Event and Audit Model Define: - event envelope; - event taxonomy; - causation/correlation; - retention; - ordering expectations; - replay expectations; - audit requirements. --- ### SPEC-A05 — Identity, Security, and Capability Model Define: - Principal; - workload identity; - roles/permissions; - narrowing capability inheritance; - credential references; - audit attribution; - agent restrictions. --- ### SPEC-A06 — Configuration Model Define: - scope hierarchy; - typed schemas; - inheritance; - overrides; - effective values; - read-only values; - drift; - history. --- ### SPEC-A07 — Durable Execution Protocol Define: - lease; - heartbeat; - ownership; - attempt; - retry; - timeout; - idempotency; - cancellation; - recovery. This should be considered mandatory before concurrent dispatch exists. --- ### SPEC-A08 — Adapter Contract Define common provider conventions: - provider identity; - version; - capability advertisement; - configuration schema; - health; - operations; - errors; - events; - timeouts; - cancellation; - compatibility. --- ## Phase B — First vertical slice ### SPEC-D01 — Projects ### SPEC-D02 — Plans and Work Hierarchy ### SPEC-D03 — Factory Runs ### SPEC-D04 — Agent Runs ### SPEC-D05 — Workspace/VCS ### SPEC-D06 — Accounts/Models ### SPEC-D07 — K3s Execution Workload ### SPEC-W01 — Task-to-Merge Workflow ### SPEC-UI01 — Project Page Minimum ### SPEC-UI02 — Plan Page Minimum ### SPEC-UI03 — Factory Run Minimum ### SPEC-UI04 — Agent Page Minimum --- ## Phase C — Planning ### SPEC-D08 — Project Onboarding ### SPEC-D09 — VISION ### SPEC-D10 — GOLIVE ### SPEC-D11 — Interactive Software Planning ### SPEC-D12 — Delivery Configuration ### SPEC-W02 — Planning-to-Factory Workflow ### SPEC-UI05 — Planning UX --- ## Phase D — Autonomy ### SPEC-D13 — Policy ### SPEC-D14 — Approval ### SPEC-D15 — Decision / Resolver Decision ### SPEC-W03 — Human-in-the-Loop Workflow ### SPEC-UI06 — Approval and Autonomy UX --- ## Phase E — Deep observability ### SPEC-D16 — Changes and Artifacts ### SPEC-D17 — Operational Activity Model ### SPEC-UI07 — Factory Graph ### SPEC-UI08 — Agent Chat/Tool/Diff UX --- ## Phase F — CI ### SPEC-D18 — CI Domain ### SPEC-D19 — Dependency Graph ### SPEC-D20 — Change Classification ### SPEC-D21 — CI Invariants ### SPEC-D22 — CI Resolver ### SPEC-D23 — CI Optimizer ### SPEC-W04 — Change-to-CI Workflow ### SPEC-UI09 — CI Page --- ## Phase G — Release/CD ### SPEC-D24 — Artifact ### SPEC-D25 — Release ### SPEC-D26 — Environment ### SPEC-D27 — Deployment ### SPEC-D28 — Deployment Resolver ### SPEC-W05 — Merge-to-Production Workflow ### SPEC-UI10 — Release/Deployment UX --- ## Phase H — Cluster management ### SPEC-D29 — Cluster ### SPEC-D30 — Machine ### SPEC-D31 — Capabilities ### SPEC-D32 — Placement/Scheduling ### SPEC-D33 — Machine Enrollment ### SPEC-W06 — Machine Enrollment Workflow ### SPEC-UI11 — Cluster Page ### SPEC-UI12 — Machine Detail --- ## Phase I — Incidents and self-healing ### SPEC-D34 — Incident ### SPEC-D35 — Resolver ### SPEC-D36 — Resolution Recipe ### SPEC-W07 — Incident-to-Resolution Workflow ### SPEC-UI13 — Incident UX --- # 41. Recommended First Spec Set Before implementation starts, the minimum useful architecture package should be: ```text spec/ ├── INDEX.md ├── architecture/ │ ├── principles.md │ ├── domain-model.md │ ├── module-boundaries.md │ ├── event-model.md │ ├── security.md │ ├── configuration.md │ ├── durable-execution.md │ └── adapter-contracts.md └── adr/ ├── 0001-control-plane.md ├── 0002-modular-monolith.md ├── 0003-k3s-execution-from-increment-zero.md └── 0004-workspace-abstraction.md ``` Only after this foundation is coherent should the factory vertical slice be specified in detail. --- # 42. Definition of "Ready for Implementation" A feature should not be considered implementation-ready until its spec defines: - authoritative terminology; - primitive relationships; - state machine; - ownership; - permissions; - configuration; - events; - idempotency/retries; - failure behavior; - provider boundary; - observability; - persistence; - UI implications; - acceptance criteria. For integration-heavy features, it must additionally define: - which behavior AWP owns; - which behavior the provider owns; - provider failure behavior; - provider replacement boundary; - provider-native IDs and AWP ID mapping; - synchronization/reconciliation behavior. --- # 43. Recommended Next Planning Action Do not begin by writing all domain specs independently. Create them in dependency order. The highest-value next artifact is: > **Architecture Foundation Specification Set** containing: 1. `architecture/principles.md` 2. `architecture/domain-model.md` 3. `architecture/module-boundaries.md` 4. `architecture/event-model.md` 5. `architecture/security.md` 6. `architecture/configuration.md` 7. `architecture/durable-execution.md` 8. `architecture/adapter-contracts.md` That package establishes the vocabulary and invariants that every later Project, Plan, Factory, Agent, CI, CD, Cluster, and UI specification can reference instead of redefining. After that, the first product specification set should cover the **Project → Plan → Task → FactoryRun → AgentRun → ChangeSet → Review → Merge** vertical slice. This ordering minimizes the risk that AWP begins accumulating working but incompatible subsystems before its architecture has stabilized. --- # 44. Final Architecture Position AWP should not become "Overdeck, redesigned." It should become a control plane with a deliberately small conceptual core: ```text Intent ↓ Plan ↓ Policy ↓ Work ↓ Execution ↓ Evidence ↓ Decision ↓ Delivery ``` The control plane knows **what should happen, why it should happen, who is authorized to make it happen, what actually happened, and what should happen next**. Providers know **how to perform specialized mechanics**. That boundary is the foundation for the product's autonomy, observability, security, configurability, and long-term modularity.