RedKey Platform — Entity Model v2

Date: 2026-04-24 Status: Design complete, awaiting implementation spec Next step: Priya specs the implementation. Vikram architects the migration.

---

A foundational redesign of how RedKey models work. The current system has workflow_instances, UUIDs, and a flat execution model that can't express project lifecycles, department-agnostic work, or real control actions (cancel, hold, replace). This spec defines the clean model everything else builds on.

KV continues on the current model. This lands as Platform Phase 3.

---

1. Workers receive tasks only. Priya, Quinn, Vikram, and all worker agents never see project, stage, or phase structure. They receive a task with a self-contained brief and execute it. Operations roles (Claire, Engine, Justin) own the structure above tasks.

2. HCS topic ID is the entity ID. Every entity — project, stage, phase, task — has an HCS topic. The topic ID (0.0.XXXXX) is the primary key everywhere: Supabase tables, message payloads, dependency references, URLs. No UUIDs. Topic creation is always step one.

3. Supabase is current state, not a mirror. One row per entity showing where it is right now. The listener applies HCS events as state transitions. If you need history, read the HCS topic. If you need current state, read Supabase. cluster_events becomes an audit log only.

4. Control actions originate on-chain. Cancel, hold, resume — all HCS messages first. Supabase state follows from the listener. Writing status directly to Supabase is never a control action.

5. Stage types are configurable, not hardcoded. The taxonomy works for engineering, sales, marketing, finance. Stage vocabulary is defined per deployment via the definitions topic.

---

`` Project → Stage → Phase → Task ``

| Entity | What it is | Example | |---|---|---| | Project | The thing being built. Long-lived, outlives all execution. | Knowledge Vault AI | | Stage | A major lifecycle episode with a defined type. | Build, Design, Release, Qualify | | Phase | A logical chunk of work within a stage. Optional for simple stages. | Phase 1: Foundation | | Task | The atomic work item an agent executes. Self-contained brief. | Write schema migrations |

• One-off task: just a Task, no project or stage overhead
• Small feature: Project → Stage → Task (no phases)
• Full project: Project → multiple Stages → Phases → Tasks

---

Configurable per deployment. Published to the definitions topic. Examples:

Engineering: design | architect | planning | build | break_fix | release | feature | maintenance Sales: prospect | qualify | demo | proposal | negotiate | close | onboard Marketing: strategy | brief | produce | review | publish | analyze Finance: collect | reconcile | review | approve | file | report

Stage type definitions are published to HCS like agent and role definitions. The engine treats all stage types identically — it routes tasks, checks dependencies, advances state. Meaning is in the persona and the brief.

---

| Layer | Roles | What they see | |---|---|---| | Operations | coordinator (Claire), engine, exec (Justin) | Projects, stages, phases, tasks — create structure, advance state | | Execution | developer, reviewer, architect, ba, content, analyst, ... | Tasks only — self-contained brief, output path, prior output refs |

Role definitions include a role_type: operations | worker field.

---

| Logical name | What it is | |---|---| | definitions | Agent, role, stage-type, workflow template registry | | roles.coordinator | Operations queue — Claire | | roles.engine | Engine queue | | roles.exec | Justin exec review | | roles.developer | Work queue — Quinn | | roles.reviewer | Work queue — Vikram | | roles.architect | Work queue — Vikram | | roles.ba | Work queue — Priya | | agents.* | Per-agent status topics (unchanged) |

| Entity | Topic pattern | Created by | |---|---|---| | Project | 0.0.XXXXX | Justin / intake agent | | Stage | 0.0.XXXXX | Claire / coordinator | | Phase | 0.0.XXXXX | Engine / claire_spawn | | Task | 0.0.XXXXX | Engine |

Listener discovers dynamic topics by querying entity tables in Supabase each poll cycle.

---

`` project.created title, brief, client_id, created_by, stage_sequence[] project.stage_changed from_stage, to_stage project.on_hold reason project.resumed project.deferred reason, revisit_date project.cancelled reason project.complete ``

`` stage.created project_id, stage_type, title, step_snapshot[] stage.transition from_step, to_step, output_ref stage.on_hold reason stage.resumed stage.cancelled reason stage.superseded replaced_by: 0.0.XXXXX stage.complete ``

`` phase.created stage_id, project_id, name, depends_on: [0.0.XXXXX] phase.started phase.on_hold reason phase.resumed phase.cancelled reason phase.complete ``

`` task.created phase_id?, stage_id, project_id?, role, brief, depends_on: [0.0.XXXXX] task.assigned role, model_hint task.claimed agent, ts task.on_hold reason task.resumed task.blocked reason task.cancelled reason, replaced_by: 0.0.XXXXX task.complete output_ref, cost_usd, duration_seconds, agent ``