# AWP - Agent Work Platfoem I want you to extract old conversations requests i made about overdeck, and find my actual wording for it: most of what i am mentioning here I already asked for and just was never done. and since i never made a clear document like this one where I am naming all features and workflows and design desicions, It was all lost in the logs somewhere. This is what this document is meant to replace, all the things that were lost should no longer be lost since my words are here in one file. I want to redesign Overdeck to a new project. Overdeck was a nice experiment and i DO want to keep all working parts of it, and our special features. but: UI Is a constant mess Observability is missing Factory is not autonomous Overdesk's Security was non existing - since i wanted to have this also operate my workstation i let agents have too much access to my workstation. I don't want this anymore. I only needed it to operate my workstation because I was running agentic work on the workstation, and now that agentic work will fully move to AWP it will no longer be relevant. Incidents of workstation frozen become irrelevant. Containment is now a higher priority, after having a lot of pain from agents doing whatever the hell they wanted on my workstation - all agents already moving to podman. and with the hew AWP they will all move permanently to K3s and will no longer run on my laptop. The problem with overdeck is that overdeck started with no planning and no architecture. it was just a combination of a bunch of tools that i already had working and all over my workstation, and i just wanted to consolidate them into one thing. and then slowly it turned into a full agentic operating system. ### Workflows i am looking for: [ Project Management ] Add project onboarding : Generate GOLIVE VISION Project view must show: GOLIVE stats Plans and their progress Need Your Attention (Human in the loop) [ Interactive plan Making ] Software plan [plan the software to details interactively via brainstorming + interview] -> Delivery plan [choice between kanban/scrum/scrumban/cusrom, choice of deployment, choice between incremental/agile/etc delivery, etc, etc,] [ Observable software factory ] The platform will take care of all git worktrees, launch each agent in it's own worktree -> agentic and mechanical coding/reviewing workflows and graphs -> code shipped to the platform and the platform takes code forward to merge, when merge completes starts next task in the plan until completed the entire plan. according to plan workflow or graph. [ Human in the loop ] Adjustable criteria that demand human in the loop. Ranging from 0 (Agent makes all desicions) and 100 (every small mismatch must be user managed) and everything in between should be configurable [ Support K3s ] To run agents, CI, CD Cluster management UI, simple Enrollment of new machine to cluster (Need to brainstorm this separatley) - Should be as simple as click [+ ADD MACHINE] and then it would ask for ssh credentials and do everything by itself. make machine enrollment an AWP primitive AWP │ ├── Cluster primitive │ ├── Machine enrollment │ ├── Machine lifecycle │ ├── Labels/capabilities │ └── Desired state │ └── K3s adapter └── Kubernetes API / node provisioning machinery make machine capabilities first-class. For example: node-03 CPU: 32 RAM: 128 GB GPU: none storage: 2 TB labels: factory=true ci=true Then scheduling decisions become declarative rather than hard-coded. The flow: Cluster → Add Machine User enters: hostname/IP SSH username authentication method/key optional machine labels/role AWP performs preflight: SSH connectivity OS/architecture CPU/RAM/disk required ports existing Kubernetes/container runtime detection whether machine is already enrolled elsewhere AWP installs/configures the required K3s node. Node joins the cluster. AWP verifies: node Ready networking storage scheduling required runtime capabilities Machine becomes visible in Cluster. The user should not need to understand K3s commands. [ CI / CD Observability ] Overdeck should own the CI and CD cycle, integrate with each project [ Fully integratable with AI Agents ] overdeck currently has hundreds of CLI tools. they will all need triage and reorganization, deduplication and come under a new "operating system" of tools , that will have a "aw*" prefix. instead of ship.sh you have awship. instead of desk-ctl you have awctl, etc. An agent will still need to be able to control AWP via the cli , and some specific agents will also need MCP. ### Features i can not live without: Global Account management. with one token owner. (According to recent spec) Account Selection per project, per plan, per task Configurability I need to be able to configure everything from within the UI. Settings should be on all levels, System, Project, Plan, Task Observability Factory view that will show me the progress in real time, clicking on the agent opens a chat-like UI interface with tool use log and diff viewer, not a json raw dump. Agentic "Chat" UX with a tool use log and a diff viewer, similar to any other browser ai chat interface. ### Architecture: The old architecture is a mess. overdeck started as just a literal consolidation of a bunch of unrelated projects i had on my workstation and did not really have a central plan, central architecture, etc. i tried enforcing modularity but it was nonsensical, since legacy code dominated and it was a maintenance hazard on every step. The new architecture should start as a modular monolith from scratch, unless you think this is not the correct architectural structure for a program like this. Work has to be with strict coding standards , I want you to emulate the coding standards of @~/Projects/platform/ and also reuse as much of the modules from there as possible. The UI will be built using facebook/astrix components, with a few exceptions for components they just literally dont have, which we will use our deck-ui components that already exist. I want to rebuild as little code as possible. This new project is not Rebuildint Overdeck. It is restructuring it completely. I dont want to rebuild anything existing. there is https://github.com/fabro-sh/fabro for factory. there is ARC for CI, k3s for load balancing, there's Subrouter for account management, etc. I want to fully explore the FOSS (MIT/Apache2) integration possibilities before considering rebuilding anything from scratch. AWP becomes a thin UI and UX layer on top of existing proven battle hardend infrastructure. We will probably have to rebuild SOME of it, specially the unbuilt parts like the project management, workflow selection, Interactive plan Making, but I am not 100% sure we will, if you find a decent enough primitives for it - we will only have to rebuild the UI for this. AWP should own the entire lifecycle of software development. from the planning phase, AWP owns the plan. We make it in a designated UX that we will have to brainstorm, that will be a back and forth interview and chat with the engineer to clarify intent and scale, then continue to planning the delivery method (choosing between waterfall/incremental delivery, choosing between scrum/kan/scrumban/custom , and such) then the plan gets approved, then transferred to the factory for processing, then AWP owns the CI process, (by thin layer to ARC) so we have full observability to the CI, then orchestrating to CD, and we have full lifecycle ownership. AWP does all the git, from worktree creation to merging and all the cleanup, agent remains with the job it was meant to do: Writing code. Reviewing code. Fixing code. The orchestration of the workflow: Code gets written, reviewed, and shipped, must be a part of the factory which we should have full observability of in the UI, and then the delivery is on AWP. if there are deployment or CI issues, we must have AWP automated self improving agents configured (per project) in addition to existing deployment-untangling stack of scripts, (that we can already take from overdeck) and if the mechanical automatic deployment fixing scripts did not work, a resolver agent starts up to clean up the mess, create a new script for the stack, and uses it to fix deployment. The same with CI, if there is any CI blocker, a resolver agent will do a similar workflow to resolve it, if an existing stack of solutions did not work. overall this needs to be a system with full autonomy in potential but not by mandate. User must be able to configure autonomy level per project, and decide when needs to be a human in the loop according to different criteria. for example, architecture, implementation, test modification, security findings, merge, staging , production and other configurable custom hooks for human involvement. it must be fully modular and with adapters, imprtable capabilities, and overall be like a lego, or a template, that you can use for any project and any capability later. If i would want to have a human in the loop every time that an agent is using "em dash" i could just set that up. for anything i would want to. human in the loop must be fully configurable. and also potentially fully autonomous Fully autonomous means that no desicions are left for user. if an agent genuinely can not make a desicion (because for examlpe we are using gpt-5.6-luna for coding) so the desicion in fully autonomous mode will be made by a resolver model, that will be a higher model like Sol. AWP stops being relevant to my local ecosystem, it starts being it's own thing. It should be a product I can offer later to customers. I have already few first beta testers. AWP ┌──────────────────┐ │ CONTROL PLANE │ │ │ │ Projects │ │ Plans │ │ Work │ │ Policies │ │ Factory Runs │ │ CI/CD │ │ Configuration │ │ Audit/Events │ └────────┬─────────┘ │ adapters ┌─────────────────┼─────────────────┐ │ │ │ ▼ ▼ ▼ Fabro GitHub Subrouter Factory Git/VCS Accounts │ │ │ └──────────┬──────┴──────────┬──────┘ ▼ ▼ K3s ARC execution plane CI runners │ agents/jobs # Everything is a primitive Project Repo Workflow Graph agent provider model and everything else i want to have everything as primitives, as per the platform modules coding philosophy. This needs to be fully configurable. Communications become a primitive first communication channels i want should be Botmaster cli, which will remain separate from this project, and systray that will remain separate from this project. these 2 will remain in overdeck. overdeck will stay my own personal toolkit frankeinstein that already exists and i just did not replace yet with something else. so botmaster and systray are not migrating from overdeck. And probably a bunch of other things that i did not mention here, are also not migrating. AWP is becoming an agentic OS, Agentic Software Delivery Platform, Factory control plane. It started as just a bunch of tools i built and made them into one. if later consumer will want to add email, crm, or anything else, it would be just as simple as adding an adapter to the communication primitive # Everything is configurable Full settings matrix for configuring everything that you can put in the json files, all configs from all levels should be accessible to view and edit via the web ui. Some configurations are genuinely untouchable or would break things if touched - these should remain grayed out and view only, with explanation in the UI about WHY it is like that. # UI & UX Preferences The UI should be self explanatory, not narrating. Hover tooltips over all elements to explain their purpose. not narrate their existense. The UX should be clear and easy to use, well thought of with ux-researcher skill. Each page needs to have it's own spec and full design diagram with User Journeys of this page explained in the spec ## Project specifications # Spec as source of truth Overdeck had no main set of specs, basically. we patched things up and no central source of truth of the design existed. AWP will have a main spec, as source of truth, protected by the CI. With every architectural change, the spec should be changed as well. Specs should always be on main origin, if a new spec is created the spec must land on main origin. Need to brainstorm about the type of spec and the structure. i am considering an INDEX.md file with smaller specs for each module, page and major feature This is a proposed folder structure, but feel free to roast it: spec/ INDEX.md architecture/ INDEX.md primitives.md lifecycle.md adapters.md domains/ projects.md planning.md factory.md ci.md cd.md cluster.md accounts.md configuration.md autonomy.md ui/ INDEX.md overview.md project.md plan.md factory-run.md agent.md cluster.md workflows/ planning.md delivery.md ci.md deployment.md resolution.md # Agents doing only code, AWP is doing the rest Agents only job is to write code, review code, fix code. the rest of the work should be owned by AWP. The plan creating interface, the CI, CD, and all the rest of the lifecycle of project management and software development owned by AWP. # Project manager, not simply orchestrator This should be the interface of the project manager, talking in project management UX. Control over different Delivery styles, see all tasks of the project, see all plans in motion, see all factory sessions currently working, each should be associated agent -> factory run -> plan -> project , the UI should have easily navigable UX with breadcrumbs and with clickable primitives, when clicking on a factory run you go to factory run page, when you click on an agent you go to agent chat interface, when you click on project you go to project overview page, when you click on plan you go to plan page. plan page should include a full task list with ## Pages Overview Projects progress Human in the loop Cluster health AWP Health Agents All currently running agents. Each agent: Where it is running? (which node on k3s) What is it's task, Factory run, Model, account, started on, status [working/idle/waiting/error] Stats of active agents over time, token usage per model, error rates [24h, 3d, 7d, 14d, 30d] Project GOLIVE progress Human in the loop Plans, each plan and it's progress PR/Release/CI/Deployment Queues (Whichever relevant to the project) CI Health CD Health Plan Plan status Waves/Phases/Tasks breakdown Click on wave/phase/task -> See status + which factory run is/was on it + click on factory goes to factory run, --- it depends really. if the factory is running on just one task? or one phase? Or one wave? It needs to be aware. if there is currently one agent working on a certain task, and another agent working on another task, the UI should show this, and clicking on each agent would take you to it's log chat page. Example: [ Wave 3/7, (Factory run _5j13mlx_ ) Task 11/12 (Agent gpt-5.6-terra/low(codex:zync)) ] Factory Run Progress view, similar to what we have in overdeck , only with full observability. I want to find the exact wording i wrote for overdeck (that got ignored and never developed) about how i actually want to see factory runs UI, and this is a good chance to redesign it in my vision. Agent Agentic chat interface, it is a regular chat interface, you can take it from this template : https://facebook.github.io/astryx/sandbox/templates/ai-chat/ Cluster “Is my execution infrastructure healthy, and what is it currently doing?” Cluster machines overview with cpu/mem/hdd/loads/queues/currently running for each machine in the cluster This page should show what is running where, health, queues, and i need your recommendations what else to add here. this page should be it's own brainstorm. # Configuration management Overdeck had a serious problem where the local-gate and other offloading scripts had constant configuration management issues, config drifts, auth token duplicate refresh issues, and other problems that we need to design around AWP infrastructure should be robust and you should advise me how we should take care of configuration management. is k3s enough? OR do we need another foss software for this? Or do we really need to rebuild our own # CI/CD for AWP Should also be managed by AWP, AWP will be the first project under AWP. The CI should be designed from scratch to be efficient. should take into account all the lessons learned from /ci-cd-expert and also make sure that no redundant checks in the CI. for example. no typescript changes? no typecheck running. docs only change? no builds/typechecks, basically only the relevant parts need to be tested, and this design needs to happen from scratch and this design needs to be also enforced on all the CI of all the projects, by making ci primitives. Layer 1 — Change classification Given a commit: changed: src/foo.ts src/bar.ts README.md AWP determines affected capabilities: typescript → yes docs → yes php → no frontend → yes database → no Layer 2 — CI invariants Examples: Every PR must: compile affected code run affected tests satisfy lint rules Never: run PHP tests for docs-only changes run frontend build for unrelated infrastructure changes duplicate identical checks Layer 3 — Dependency graph Instead of manually maintaining: if: changed src/foo.ts: run foo-test model CI as a graph: files ↓ components ↓ capabilities ↓ checks Then impact analysis determines which checks are required. This makes the CI itself composable and reusable between projects. # Self improving CI by a CI Optimization Expert agent ┌── deterministic invariants Changed code ────┤ └── dependency/impact analysis ↓ CI plan ↓ execute ↓ optimization agent ↓ propose improvements The optimization agent can: detect redundant checks identify consistently unnecessary jobs propose new invariants identify missing coverage suggest dependency relationships analyze historical CI performance propose changes to the CI specification But its proposals should themselves go through the normal AWP workflow. That gives you a self-improving CI system without allowing an AI agent to silently weaken CI. # CI optimization should itself be an AWP project primitive CI ├── Provider ├── Pipeline ├── Check ├── Invariant ├── Change classifier ├── Dependency graph ├── Resolver └── Optimizer all independently configurable. Then a project can have: CI Policy TypeScript typecheck: required test: affected build: affected Documentation markdown validation: required build: prohibited Security dependency scan: required # Incremental delivery plan Increment 0 — Foundation + AWP builds AWP modular-monolith skeleton spec system identity configuration event model adapter framework Postgres/state K3s execution substrate basic workload isolation Subrouter adapter Git adapter No big Cluster UI. But every agent is already isolated. Increment 1 — First complete vertical slice Project ↓ Plan ↓ Task ↓ Factory Run ↓ Agent Run in K3s ↓ ChangeSet ↓ Review ↓ Merge Fabro behind Factory. Minimal observability exists now. This is the first genuine AWP. Increment 2 — Real planning Exactly your plan: Onboarding → VISION → GOLIVE → Interactive software plan → Delivery configuration → Approval → Factory Increment 3 — Autonomy policy Policy Approval Decision Resolver Architecture / merge / production presets initially. Increment 4 — Full factory UX Now deepen: graphs agent chat tool calls diffs relationships live state retries checkpoints artifacts cost Increment 5 — CI control plane change classification dependency graph CI policy checks GitHub Actions provider ARC runners resolver optimizer Increment 6 — Release/CD Artifact Release Environment Deployment Flux adapter rollback health Increment 7 — Cluster product surface K3s has existed since Increment 0. Now expose: machine enrollment machine lifecycle scheduler UX capabilities capacity queues health maintenance placement explainability Increment 8 — Self-healing and operations Incident known deterministic resolver agentic resolver new resolver proposal approval resolver library improvement Increment 9 — Productization Use platform-modules primitives to create: Organizations Users RBAC tenant isolation quotas retention backup/restore upgrade/migrations audit export API/SDK stability ##### Missing What is missing from this plan? You must recommend me first.