# AwoooP Implementation Roadmap

**Status**: Planning baseline
**Date**: 2026-05-01
**Owner**: AWOOOI / AwoooP platform workstream
**Primary ADRs**: ADR-106, ADR-107

## Purpose

This document is the implementation handoff for AwoooP, the AWOOOI Agent
Platform.

ADRs record architectural decisions. This roadmap translates those decisions
into execution phases, work items, acceptance gates, and Codex workflow
guidance.

## Executive Summary

AwoooP is the multi-tenant Agent Platform extracted from the AI capabilities
that first emerged inside AWOOOI.

AWOOOI is the first tenant and first runtime host. It is not the platform
boundary.

AwoooP must let current and future products share AI agents and communication
capabilities without copying project-specific code:

- AWOOOI: AIOps, SRE automation, K8s/MCP/Telegram workflows
- EwoooC / MOMO PRO: ecommerce and business analysis, market intelligence, LINE
  and Telegram workflows
- Tsenyang: existing Telegram webhook surface
- Bitan and future products: repeatable onboarding to shared AI capabilities

The approved direction is not a pure HTTP hub, not only an SDK, and not only a
shared config table. The approved direction is:

```text
AwoooP = Control Plane + Agent Runtime + MCP Gateway + Context Firewall
       + Communication Hub + Observability / Audit
```

## Core Decisions

### Product and Layout

- Product name: `AwoooP`
- Repository/package slug: `awooop`
- Existing AWOOOI tenant id remains `awoooi`
- Do not create empty runtime or package directories before implementation owns
  real code.
- `docs/awooop/` is allowed now because it contains concrete implementation
  planning artifacts.

Future code layout should be created only when each path owns real artifacts:

| Path | Create when | Owns |
|---|---|---|
| `packages/awooop-contracts/` | Contract schemas are ready to validate | JSON Schema / Pydantic / TS types |
| `packages/awooop-client/` | First downstream client integration begins | Python/TS SDK |
| `apps/awooop-runtime/` | Runtime shell separates from `apps/api` | Platform API and run orchestration |
| `apps/awooop-worker/` | Async workers are needed | Run state execution workers |
| `docs/awooop/` | Planning and implementation docs exist | Roadmaps, schema notes, runbooks |

### Storage

AwoooP v1 is PostgreSQL-first.

- PostgreSQL is source of truth for contracts, active revisions, tenant records,
  policy, MCP grants, budget, ACL, run state, approval, channel event, and audit.
- Redis is cache/watch/counter/coordination only.
- Prompt, JSON Schema, eval, and replay artifacts are stored by ref + SHA-256
  hash.
- Kubernetes CRDs are future runtime projection only, not the v1 control-plane
  source of truth.

### Six Contracts

| Contract | Purpose |
|---|---|
| Project / Tenant | Tenant identity, data boundary, budget, ACL, channels, approval gates |
| Agent | Versioned capability module, I/O schema, context domain, safety ceiling |
| MCP Gateway | Tool authorization, credential resolution, approval, result sanitization |
| Policy / Routing | Effective model/provider route, fallback, privacy and budget gates |
| Runtime / Run State | Durable async run lifecycle, shadow/canary/active, checkpoint/resume |
| Communication / Channel Event | Telegram/LINE/Slack/Email/API receive, verify, normalize, send |

## Migration Strategy

AwoooP must migrate by strangler fig, not big-bang replacement:

1. `shadow`: mirror events, write audit/trace only, no user response, no side
   effects.
2. `canary`: selected low-risk user-visible responses, no side effects by
   default.
3. `read_only`: read-only queries and business chat move first.
4. `suggest`: analysis and recommendations move next; approval still external.
5. `auto_remediate`: write/execute tools move only after Gateway, approval,
   replay, audit, and rollback evidence are green.

## Implementation Phases

### Phase 0 - Documentation Freeze

Goal: make future implementation unambiguous.

Status: in progress / mostly complete.

Work items:

- ADR-106: AwoooP architecture and migration strategy.
- ADR-107: AwoooP control-plane storage strategy.
- This roadmap.
- LOGBOOK entries for ADR-106/107 and roadmap.
- Task-routing lookup in `docs/12-agent-game-rules.md`.

Acceptance:

- `git diff --check` passes.
- No runtime code changes.
- No empty code directories.

### Phase 1 - Control Plane Schema Foundation

Goal: create the minimum PostgreSQL foundation for contract materialization.

Suggested work items:

- Add `awooop_contract_revisions`.
- Add active revision pointer tables.
- Add `awooop_projects` / tenant records.
- Add `awooop_artifact_refs`.
- Add `awooop_project_migration_state`.
- Add `project_id` strategy for existing AWOOOI records.
- Add tests for immutable published revisions and draft isolation.

Acceptance:

- Published contract revision is append-only.
- Runtime-facing reads cannot see mutable drafts.
- Every active revision has `revision_id` and `body_hash`.
- AWOOOI can be represented as `project_id=awoooi` without behavior changes.

### Phase 2 - Isolation and Namespace Hardening

Goal: make AWOOOI tenant-safe before sharing anything downstream.

Suggested work items:

- Prefix Redis sessions, budget, rate, and Telegram/Hermes keys with
  `project_id`.
- Add `project_id` columns where required for logs, audit, sessions, and
  approval records.
- Define `platform_resource` exceptions separately from tenant resources.
- Convert global resources such as Ollama failover state into explicit platform
  resources.
- Add regression tests for cross-project read/write rejection.

Acceptance:

- Tenant-scoped data cannot be read without matching `project_id`.
- Platform resources are explicitly allowed and audited.
- No prompt text is trusted as the data isolation boundary.

### Phase 3 - Contract Packages and Validators

Goal: make the six contracts executable rather than prose-only.

Suggested work items:

- Create `packages/awooop-contracts/` only when validators are implemented.
- Define JSON Schema/Pydantic models for the six contracts.
- Define envelope schemas for platform invocation, MCP tool call, run state, and
  channel events.
- Add output schema validator middleware design.
- Add golden fixtures for valid and invalid contracts.

Acceptance:

- Contract validation fails closed.
- LLM output that fails schema validation cannot reach channel adapters.
- Prompt/schema refs require SHA-256 hashes.

### Phase 4 - Platform Shell in Shadow Mode

Goal: build the first runtime shell without replacing legacy behavior.

Suggested work items:

- Add `/v1/platform/runs` shell around existing AWOOOI logic.
- Generate `run_id` and `trace_id`.
- Resolve project and agent contract revisions.
- Resolve `EffectivePolicy` without changing provider behavior.
- Write run state transitions and audit.
- Mirror selected AWOOOI events into AwoooP shadow mode.

Acceptance:

- Shadow runs produce audit and trace.
- Shadow runs never send user-visible responses.
- Shadow runs never call write/execute/destructive tools.
- Legacy AWOOOI behavior remains unchanged.

### Phase 5 - MCP Gateway First Slice

Goal: move tool authorization behind a real Gateway.

Suggested work items:

- Define MCP Gateway tables for tool registry, grants, credentials refs, and
  audit.
- Wrap current read-only MCP tools behind Gateway checks.
- Enforce `Project AND Agent AND Tool AND Environment AND Approval`.
- Sanitize tool results before model context.
- Record tool call `trace_id`, `run_id`, credential ref, latency, result status.

Acceptance:

- Agents never see raw credentials.
- Read-only tools are auditable by `trace_id`.
- Write/execute tools stay blocked until later phases.

### Phase 6 - EwoooC Read-Only Tenant Onboarding

Goal: validate AwoooP with a real downstream tenant without high-risk actions.

Suggested work items:

- Create `project_id=ewoooc`.
- Register `openclaw-biz` as a specialized agent contract.
- Register market-intelligence tools as read-only MCP Gateway tools.
- Add a read-only platform client path.
- Mirror EwoooC bot/business-analysis events into shadow/canary.

Acceptance:

- EwoooC can run read-only AwoooP shadow/canary without touching AWOOOI data.
- Business-agent context cannot access infra-only AWOOOI context.
- Budget and audit are project-scoped.

### Phase 7 - Communication Hub Increment

Goal: standardize channels without breaking existing bots.

Suggested work items:

- Define `ConversationEvent` and `OutboundMessage` tables.
- Mirror Telegram inbound events first.
- Add progressive status feedback policy for async runs.
- Keep existing bot handlers authoritative until canary passes.
- Add adapter-level escaping, redaction, idempotency, and delivery audit.

Acceptance:

- Channel adapters do not call LLM or MCP.
- Async runs can produce progress updates.
- Duplicate channel retries do not create duplicate runs.

### Phase 8 - Suggest and Controlled Write Paths

Goal: graduate from read-only to proposal and then controlled execution.

Suggested work items:

- Enable `suggest` mode for selected AWOOI SRE flows.
- Add approval resume for `WAITING_APPROVAL`.
- Add dry-run and rollback evidence gates.
- Move low-risk write paths only after Gateway and audit evidence are stable.

Acceptance:

- `WAITING_APPROVAL` resumes without replaying the whole task.
- Rejected or expired approvals fail with structured failure codes.
- Write/execute paths are blocked by default and feature-flagged.

## Codex Workflow Recommendation

Use a new Codex conversation for implementation, but keep the working directory
at the monorepo root:

```text
/Users/ogt/awoooi
```

Do not start from a new project directory until `apps/awooop-runtime` or
`packages/awooop-*` actually exists and owns code.

Recommended implementation kickoff prompt:

```text
Read AGENTS.md, docs/12-agent-game-rules.md, docs/LOGBOOK.md newest entry,
docs/adr/ADR-106-agent-platform-architecture.md,
docs/adr/ADR-107-awooop-control-plane-storage.md, and
docs/awooop/IMPLEMENTATION-ROADMAP.md.

Start Phase 1 only: design and implement the minimum PostgreSQL control-plane
schema foundation for AwoooP contract revisions. Do not create runtime APIs,
do not change provider behavior, do not move Telegram/LINE webhooks, and do not
create empty AwoooP code directories.
```

If the current worktree is dirty, prefer a clean branch or clean worktree before
runtime implementation. Documentation-only planning can remain in this thread.

## First Implementation Slice

The first code slice should be deliberately boring:

1. DB migration for contract revisions and active pointers.
2. Pydantic/SQLAlchemy models for contract revisions.
3. Repository/service methods for draft, publish, activate, and read active.
4. Tests for immutability and draft isolation.
5. LOGBOOK update.

Do not start with MCP Gateway, Telegram Hub, or model routing. Those are more
visible, but they depend on the contract source of truth.

## References

- `docs/adr/ADR-106-agent-platform-architecture.md`
- `docs/adr/ADR-107-awooop-control-plane-storage.md`
- `docs/adr/ADR-105-mcp-agent-loop-governance.md`
- `docs/12-agent-game-rules.md`
- `docs/LOGBOOK.md`