# Implementation Plan

Last updated: 2026-05-14.

## Phase 0. Architecture baseline

Status: done in `97d98a7`.

Deliverables:

- architecture document;
- UX flow;
- Tasker API audit;
- MCP tools contract;
- threat model;
- implementation plan.

Exit criteria:

- agreed capability model;
- agreed no-delete MVP boundary;
- agreed Launcher/Tasker/Gateway ownership split.

## Phase 1. Agent Gateway skeleton

Status: done in `e95cb3a`, `112522c`, `14c5f49`, `9f40207`, and the MCP transport slice. Initial service, migrations, persistence endpoints, token hashing, bearer-token session auth, product tool endpoints, local Postgres compose, and Gateway smoke checks are implemented.

Create standalone service with:

- Dockerfile;
- compose for local dev;
- health endpoint;
- env validation;
- database migrations;
- agent/token/grant/audit tables;
- opaque token hashing;
- idempotency-key storage.

Tasker writes are available through the narrow internal adapter; Gateway still must not call raw Plane routes.

## Phase 2. Launcher entitlement projection

Launcher changes:

- add Operational Core module entitlement `codex_agents`;
- open contour Operational Core dropdown becomes modal;
- enterprise access modal gets `Operational Core modules`;
- access check exposes whether user can use Codex agents.

Acceptance:

- root/admin can enable/disable Codex agents per user/client;
- blocked user loses entitlement;
- audit records entitlement changes.

## Phase 3. Tasker feature UI

Tasker changes:

- `Workspace settings -> Features` shows Codex agents when entitlement exists;
- reusable NODE.DC round toggle/checker component is extracted if needed;
- feature card opens agent management UI;
- create/revoke agent calls Agent Gateway;
- setup instruction panel displays pairing flow.

Acceptance:

- no entitlement means no feature card;
- entitlement means feature card appears;
- revoked agent disappears or becomes disabled;
- design follows NODE.DC glass/checker canon.

## Phase 4. Tasker internal adapter

Tasker changes:

- internal `/api/internal/nodedc/agent/...` namespace;
- token auth using NODE.DC internal token;
- project/state/label/member context endpoint;
- issue create/update/move/comment endpoints;
- structured block update endpoint;
- existing workspace member add-to-project endpoint;
- delete/archive rejection.

Acceptance:

- adapter works without exposing raw Plane API;
- adapter rejects ungranted project;
- adapter rejects delete/archive;
- adapter validates labels/states/assignees.

Status: initial product slice done in Tasker commit `2ae353c`. Implemented project resolution/context, issue search/create/update/move/comment/label/assign, agent bot actor metadata, and internal token auth. `add_existing_project_member` remains planned behind the explicit `project:member:add_existing` scope.

## Phase 5. MCP server

Agent Gateway changes:

- MCP endpoint;
- tool schemas from `docs/MCP_TOOLS_CONTRACT.md`;
- token auth;
- scope checks per tool;
- idempotency per write;
- audit per call;
- generated instruction pack.

Acceptance:

- local Codex can list projects;
- local Codex can create a card;
- local Codex can update structured blocks;
- local Codex can move card state;
- local Codex cannot delete/archive.

Status: initial product slice implemented. `/mcp` supports JSON-RPC `initialize`, `ping`, `tools/list`, and `tools/call`. REST product endpoints and MCP tools share the same runtime, scope checks, grant checks, and Tasker adapter calls. `npm run smoke:mcp:e2e` verifies real local Tasker writes.

## Phase 6. Agent identity

Tasker/Gateway integration:

- create or map dedicated agent bot identity;
- display owner user and agent name;
- write audit metadata;
- preserve standalone Tasker behavior when gateway is disabled.

Acceptance:

- Tasker history shows agent-originated writes;
- owner can revoke agent;
- blocked owner disables agent.

## Phase 7. Reporting mode

Add enterprise-oriented work-session tools:

- start work session;
- update active card;
- finish work session;
- stale report indicators;
- last activity panel.

Acceptance:

- admin can see connected/stale agents;
- voluntary mode still works;
- reporting mode does not pretend to enforce unmanaged local Codex.

## Phase 8. Security acceptance

Checklist:

- token revoke immediate;
- blocked/annulled owner disables token;
- project scope escape denied;
- raw Tasker API inaccessible;
- delete/archive denied;
- duplicate idempotency key returns same result;
- audit written for every write;
- rate limit enforced;
- secrets absent from generated files.

## MVP cut

MVP includes:

- Launcher entitlement;
- Tasker feature UI;
- Agent Gateway token/grant/audit;
- MCP tools for read/create/update/move/comment/label/assign/structured blocks;
- no deletion;
- no arbitrary proxy;
- no hosted Codex execution.

MVP excludes:

- hosted agent runner;
- workspace invites;
- project creation;
- deletion/archive;
- billing;
- mandatory reporting enforcement for unmanaged local Codex.