# AWP I0 / I1 Parallel Implementation Plan **Date:** 2026-08-20 **Status:** **BINDING IMPLEMENTATION COORDINATION PLAN** **Prerequisite:** [`AWP-SPECIFICATION-FINALIZATION-2026-08-20.md`](AWP-SPECIFICATION-FINALIZATION-2026-08-20.md) ## Purpose Start implementation without recreating the multi-agent collision and context-rot problems AWP is intended to solve. This plan divides I0/I1 into **path-owned, dependency-aware lanes**. Parallelism is allowed only when agents do not share write authority over the same implementation surface. ## Canonical Sequence AWP numbering remains: ```text I0 Foundation / self-hosting substrate I1 First complete vertical slice ``` The **first development agent starts I0**, because I1 depends on I0's final identities, persistence, application seams, provider boundaries and execution substrate. We do not skip directly to an I1 application implementation with temporary foundations. ## Concurrency Model ```text WAVE 0 — BOOTSTRAP CONVERGENCE A0 Core bootstrap (single writer to root/runtime layout) E Overdeck/source harvest (docs/evidence only; may run immediately in parallel) A0 scaffold contract lands | +----------------+----------------+ | | | v v v WAVE 1 A Core B Providers C Execution domain/data account/Git DBOS/K8s/ARC | | | +---------+------+--------+-------+ | | v v WAVE 2 D UI I1 integration proofs against stable contracts | v WAVE 3 I1 end-to-end convergence Project -> Merge dogfood ``` UI work may start during Wave 1 as soon as A publishes stable contract/type fixtures; it must not invent alternate domain state. ## Non-Conflict Rules 1. Every agent works in a fresh branch/worktree from the declared convergence commit. 2. One lane owns one path family. 3. Root workspace manifests/config are **single-writer** until bootstrap is landed. 4. Other lanes request root/config changes through their progress record rather than editing them concurrently. 5. Domain types are owned by Lane A. Provider/UI lanes consume them; they do not fork them. 6. Approved `docs/mockups/i1/` files are read-only implementation authority unless an explicit owner design amendment is opened. 7. Canonical specs may only change in an implementation PR when new evidence materially requires it; the PR must include the Decision/evidence. 8. No lane merges another lane's branch or rebases/force-pushes another lane's branch. 9. Every lane keeps a durable progress file so a crashed conversation can resume without chat history. ## Target Repository Layout Established by A0 A0 owns establishment of the initial layout. Exact naming may vary only if canonical module-boundary specs require a correction. ```text apps/ gateway/ control-plane/ web/ packages/ contracts/ domain/ application/ persistence/ config/ observability/ providers/ account-subrouter/ vcs-github/ workflow-dbos/ workspace-kubernetes/ factory-fabro/ agent-acp/ ci-github/ infra/ k8s/ arc/ tests/ architecture/ integration/ security/ tools/ preflight/ docs/ progress/ ``` The root package/workspace configuration should use package globs so later lanes can add their owned packages without repeatedly modifying root manifests. ## Lane A0 — Bootstrap / Convergence Commit **Owner:** Development Agent 1 initially. **Parallel with:** Lane E only. **Write authority:** root configuration and common skeleton. ### Owns ```text package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig*.json eslint/prettier/lint/typecheck/test configuration apps/gateway/** initial skeleton apps/control-plane/** initial skeleton packages/contracts/** initial skeleton packages/domain/** initial skeleton packages/application/** initial skeleton packages/persistence/** initial skeleton packages/config/** initial skeleton packages/observability/** initial skeleton tests/architecture/** docs/progress/i0-a-core.md ``` ### Delivers - Node/pnpm/TypeScript baseline compatible with current Platform source; - workspace/module skeleton matching architecture specs; - dependency-boundary tests that can fail on forbidden imports; - final I0/I1 IDs/value types sufficient for downstream package compilation; - test/lint/typecheck/build commands; - empty provider interfaces/test-double seams, not provider implementations; - PostgreSQL/Drizzle migration/repository skeleton without premature domain behavior; - first durable progress record. ### Convergence Point C0 All later code lanes branch from the A0 commit where: ```text pnpm install pnpm typecheck pnpm test pnpm lint architecture-boundary tests ``` pass in the intended development environment. ## Lane A — Core Domain / Persistence / Application **Starts:** after C0. **May run parallel with:** B, C, D, E. **Write authority:** canonical business state and persistence only. ### Owns ```text packages/contracts/** packages/domain/** packages/application/** packages/persistence/** packages/config/** only for domain/application config semantics tests/domain/** tests/application/** tests/persistence/** docs/progress/i0-a-core.md ``` ### I0 scope - stable IDs/types for Project, ProjectVision, Goal, Plan, Task, FactoryRun, AgentRun, Attempt, Workspace, ChangeSet, Review; - Task dependency DAG validation; - dependency-safe Queue legality and legal-placement calculations; - lifecycle transition functions; - transaction/event/audit application patterns; - Principal/capability skeleton; - Connection/CredentialReference abstractions; - repository interfaces and Drizzle mappings required for I1; - deterministic fixtures consumed by UI/provider lanes. ### Does not own Provider SDK code, Kubernetes manifests/adapters, DBOS implementation, UI rendering, GitHub-specific behavior. ## Lane B — Provider / Account / VCS Boundary **Starts:** after C0. **May run parallel with:** A, C, D, E. ### Owns ```text packages/providers/account-subrouter/** packages/providers/vcs-github/** packages/providers/factory-fabro/** packages/providers/agent-acp/** tests/providers/account-subrouter/** tests/providers/vcs-github/** tests/providers/factory-fabro/** tests/providers/agent-acp/** docs/progress/i0-b-providers.md ``` ### Scope - exact Platform/Subrouter consumer proof and version pins within owned packages; - AccountProvider mapping and explicit force-account authorization input; - Attempt provenance mapping; - GitHub VCS read/write mapping with trusted publication interface boundary; - Fabro FactoryRun provider mapping; - ACP AgentRun/session mapping; - provider error/idempotency/reconciliation tests with fakes where live environment is unavailable. ### Hard boundary B consumes Lane A contracts. It may not create provider-shaped domain types or move publication authority into AgentRun code. ## Lane C — Durable Execution / Workspace / CI Infrastructure **Starts:** after C0. **May run parallel with:** A, B, D, E. ### Owns ```text packages/providers/workflow-dbos/** packages/providers/workspace-kubernetes/** packages/providers/ci-github/** infra/k8s/** infra/arc/** tests/integration/dbos/** tests/integration/workspace/** tests/integration/arc/** tests/security/execution/** tools/preflight/** docs/progress/i0-c-execution.md ``` ### Scope - DBOS workflow adapter and crash/recovery/idempotent side-effect harness; - Kubernetes WorkspaceProvider using Pod/PVC/ServiceAccount/NetworkPolicy/RuntimeClass; - durable WIP/checkpoint semantics; - gVisor profile and explicit compatibility evidence; - Dev Container execution-profile resolution evidence where required; - ARC runner-scale-set manifests/proof; - execution-plane security tests; - no reusable Git publication credentials in execution/runner environments. ### Hard boundary C does not define Task/FactoryRun business lifecycle; it implements provider mechanics behind Lane A interfaces. ## Lane D — I1 Web UI **Starts:** after C0 plus stable read-model/fixture contract from Lane A. **May run parallel with:** A, B, C, E. ### Owns ```text apps/web/** packages/ui-awp/** if a reusable AWP-owned UI package is required tests/ui/** tests/e2e/ui/** docs/progress/i1-d-ui.md ``` ### Visual authority ```text docs/mockups/i1/u1-project.html docs/mockups/i1/u1-final.css docs/plans/AWP-U2-FACTORYRUN-HIGH-FIDELITY-BRIEF.md docs/mockups/i1/u2-factory-active.html docs/mockups/i1/u3-waiting-failure-retry.html docs/mockups/i1/u4-review.html docs/mockups/i1/u5-ready-to-merge.html docs/mockups/i1/u6-completed.html docs/mockups/i1/awp-i1-final.css ``` ### Scope - final AWP shell and navigation; - U1 Project Overview; - U2/U3 FactoryRun active/recovery states; - U4/U5/U6 ChangeSet/Review lifecycle states; - accessible Task dependency presentation; - loading/error/stale/permission states required by page specs; - URL-restorable page/tab/selection state; - typed mock/read-model adapter initially, then application API integration at convergence. ### Hard boundary UI must not duplicate Queue legality or lifecycle rules client-side as authority. It may preview legal behavior but server/application validation remains canonical. ## Lane E — Overdeck Harvest / Evidence **Starts:** immediately. **May run parallel with:** every implementation lane. **Recommended environment:** a separate conversation with authorized Overdeck/workstation access. ### Owns only ```text docs/evidence/overdeck-i0-i1/** docs/progress/i0-e-overdeck-harvest.md ``` ### Scope Inspect current canonical Overdeck source and record exact: ```text path commit capability current behavior/failure handling debt/coupling target AWP seam disposition verification evidence ``` for repository/workspace, trusted publication, K3s/offload, Factory/Fabro, account/model routing, auth/audit/realtime/health, CI runner/check, cleanup/recovery/checkpoint and control-surface helpers. E must not modify AWP implementation code. Its findings can trigger a Decision/change request for another lane. ## Conflict Matrix | Path / concern | A | B | C | D | E | |---|---:|---:|---:|---:|---:| | root package/workspace config | **A0 only** | no | no | no | no | | contracts/domain/application | **owner** | consume | consume | consume | no | | persistence | **owner** | no | no | consume API | no | | account/Git/Fabro/ACP adapters | consume interfaces | **owner** | no | no | evidence only | | DBOS/K8s/ARC adapters/infra | consume interfaces | no | **owner** | no | evidence only | | web/UI | no | no | no | **owner** | no | | approved mockups | read-only | read-only | read-only | read-only | read-only | | Overdeck evidence | read | read | read | read | **owner** | ## Integration / Landing Order ### C0 — Bootstrap Lane A0 lands first. ### C1 — I0 contracts Lane A lands stable domain/application/persistence baseline. B/C/D rebase **their own** branches onto the landed commit; no cross-agent branch rewriting. ### C2 — Provider + execution B and C can land independently if their contract tests pass against current main. If both require a contract change, Lane A owns the shared contract patch. ### C3 — UI D lands once application read models/commands used by I1 are stable. Mock fixtures must match canonical contract shape. ### C4 — I0 Exit Require: ```text build/typecheck/lint/tests green architecture boundary checks green Platform consumer pins verified provider adapter source-fit recorded DBOS/Workspace/ARC live proofs green where environment exists security mitigation tests green for active I0 surface no normal agent path depends on workstation authority ``` Unavailable external evidence remains an explicit blocker for the subsystem that requires it. ### C5 — I1 Vertical Slice Converge on one dogfood path: ```text Project + ProjectVision + Goal -> Plan -> dependency-aware Task/Queue -> FactoryRun -> AgentRun/Attempt on isolated Workspace -> preserved WIP/retry -> ChangeSet -> independent Review -> required evidence -> trusted Merge ``` The U1–U6 states are the acceptance journey. ## Durable Progress Contract Every lane maintains: ```text docs/progress/.md ``` with: ```text branch/worktree base/convergence commit owned paths completed tasks current task commands/tests run + results new evidence/Decisions blocked items exact next task latest pushed commit ``` Update and push this record at least at every meaningful checkpoint so another agent can resume without chat context. ## Branch Naming Recommended: ```text impl/i0-a-core impl/i0-b-providers impl/i0-c-execution impl/i1-d-ui evidence/i0-e-overdeck-harvest ``` A0 may start as `impl/i0-a-bootstrap` and continue into `impl/i0-a-core` only if no other lane has branched from its unlanded history. Prefer landing C0 first. ## Development Agent 1 The first implementation thread is Lane A0/A. Copy/paste instructions are maintained in: [`AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md`](AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md) After C0 lands, launch B/C/D/E as separate conversations using this plan and strict path ownership. ## Definition of Parallel Safety Two lanes are parallel-safe only when all are true: ```text different owned paths no shared root/config writer stable consumed interface or explicit dependency on convergence commit no one edits approved mockups/spec authority casually landing either lane first does not invalidate the other's semantics ``` If that cannot be proven, serialize at the next convergence point.