NODEDC_TASKMANAGER_CODEXAPI/docs/IMPLEMENTATION_PLAN.md

Implementation Plan

Last updated: 2026-05-14.

Phase 0. Architecture baseline

Status: current phase.

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

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.

No Tasker writes yet.

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.

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.

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.