RedKey Team OS Design

Date: 2026-05-08 Status: Draft Owner: Justin / Atlas-Codex Scope: RedKey platform operating model, shared context system, and agent harness standards

RedKey already has most of the architecture described by the Team OS pattern: shared project context, durable memory, agent-readable routing, restart state, structured artifacts, and execution infrastructure. The gap is not capability. The gap is packaging and enforcement.

Today, Atlas-Codex can reconstruct project state from project-refs.yaml, docs/state.md, repo docs, Studio artifacts, Supabase agent_memory, and live project repos. That is more powerful than a simple shared Markdown Team OS, but it is harder for a new human or agent to understand.

This design adds a thin Team OS facade over the existing RedKey system: a clear entrypoint, context map, contribution workflow, retrieval discipline, and a path toward mechanical harness enforcement. The goal is to make RedKey feel as simple as "open the repo, ask, get the answer" without weakening the deeper Studio, Supabase, HCS, and agent runtime architecture underneath.

The Team OS article argues that most team knowledge already exists, but is inaccessible to both humans and agents because it is buried in Slack threads, personal notes, private setups, or tools nobody can search. The proposed solution is a shared context repo where every team function checks in relevant context and anyone can query it in natural language.

The useful pattern is not Claude Code-specific. The core claim is:

• Context must be shared, not personal.
• Context must be discoverable by agents.
• Decisions, customer context, implementation notes, and reusable queries should be captured close to the work.
• The system should reduce dependence on one person being online to answer historical context questions.

RedKey already follows this direction, but with a more advanced architecture:

• project-refs.yaml routes projects, clients, repos, Studio IDs, VPS paths, and status.
• docs/state.md gives the restart pointer for the current working set.
• Supabase agent_memory stores durable semantic memory.
• Studio artifacts store canonical product/project planning artifacts.
• Repo docs store RedKey platform specs, plans, setup docs, and playbooks.
• Bezel API and related services provide actual workflow execution, task claims, event reads, and HCS proof paths.

The remaining design problem is making this system legible and usable as a Team OS.

OpenAI's harness engineering pattern adds a sharper lesson: shared context is necessary, but not sufficient. Agent-first engineering works when the repository becomes both the system of record and the enforceable harness agents operate inside.

The relevant harness principles are:

• AGENTS.md should be a short table of contents, not a large instruction manual.
• Repository docs should be structured, indexed, and treated as the system of record.
• Plans, architecture notes, product specs, quality rules, generated references, and technical debt trackers should be versioned close to the code.
• Agent legibility is the goal: if an agent cannot inspect context, tools, app state, logs, metrics, or traces, that information effectively does not exist during the run.
• Architecture and taste should be encoded as mechanical checks: linters, structural tests, CI jobs, file-size limits, schema/naming conventions, and remediation instructions.
• Agents should be able to run the app, reproduce bugs, inspect UI state, query logs/metrics/traces, validate fixes, review changes, and iterate without relying on humans to paste context.
• Entropy needs recurring garbage collection: stale docs, weak patterns, inconsistent architecture, and accumulated technical debt should be scanned and repaired continuously.

RedKey already follows the broad philosophy, but OpenAI is cleaner on mechanical enforcement. The next bar for RedKey is to turn the Team OS facade into the front door for a broader RedKey Harness: context, tools, checks, verification, and cleanup loops that make agent work legible and enforceable.

RedKey should be precise about the word "agent."

Today, RedKey has:

• Atlas-Codex as an operating mode for Codex in this repo.
• Local Codex skills and repo instructions.
• RedKey/Bezel task and workflow infrastructure.
• Historical and planned named RedKey agents such as Jess, Mia, Priya, Quinn, and others.
• Agent-like project execution patterns driven through Codex sessions, Studio artifacts, and Bezel API concepts.

RedKey does not yet have production OpenAI Agents SDK agents or Codex-native agents that run as durable application services. We should not imply otherwise.

The official OpenAI Agents SDK docs define SDK agents as code-built applications that can plan, call tools, collaborate across specialists, and keep enough state to complete multi-step work. The SDK path is the right fit when RedKey owns orchestration, tool execution, approvals, runtime behavior, storage, state, and product integration. Agent Builder is a separate hosted workflow path and should only be used if RedKey specifically wants OpenAI-hosted workflow creation, publishing, and ChatKit deployment.

Design implication: RedKey Team OS and Harness should prepare the substrate for future Codex/OpenAI SDK agents, but Phase 1 should describe current reality as "agent-ready" rather than "agent-built."

1. Give humans and agents one obvious starting point for RedKey context. 2. Preserve current artifact routing: platform docs in the repo, client/product artifacts in Studio. 3. Keep docs/state.md short as a restart pointer, not a memory archive. 4. Make recurring context capture easy and consistent. 5. Support natural language retrieval across project status, decisions, specs, implementation notes, and lessons. 6. Keep the system portable enough that Codex, Claude Code, Cursor, or another agent can understand the context. 7. Define the first RedKey Harness standards for agent-legible tooling, verification, doc health, and recurring cleanup. 8. Move repeated review feedback and taste preferences into durable documentation or mechanical checks.

• Replace Supabase agent_memory.
• Replace Studio artifacts with Markdown mirrors.
• Move client/product canonical specs into repo docs.
• Build a new full UI for Team OS in this phase.
• Reorganize all existing docs before the entrypoint and workflows are proven.
• Require every RedKey-adjacent project repo to adopt the full harness immediately.
• Eliminate human judgment from product, architecture, release, or client decisions.

RedKey has the core Team OS primitives, but they are distributed.

| Capability | Current RedKey Mechanism | Status | | --- | --- | --- | | Project switchboard | project-refs.yaml | Strong | | Restart pointer | docs/state.md | Strong but growing long | | Durable memory | Supabase agent_memory via Doppler-backed scripts | Strong | | Platform specs/plans | docs/specs, docs/plans, docs/setup, docs/playbooks | Strong | | Product planning | Supabase studio_projects and studio_artifacts | Strong | | Agent operating profile | .codex/atlas-codex/OPERATING.md, MODEL.md, local skills | Strong | | Execution runtime | Bezel API, task claims, workflow events, HCS proofs | Strong | | OpenAI Agents SDK agents | Not yet built | Missing | | Durable Codex-native agent services | Not yet built | Missing | | Project-specific governance | B2BEA CSS/runtime audits, Bezel API smoke tests, PVA release gates | Medium | | Human onboarding | Scattered across files | Weak | | Team check-in ritual | Ad hoc memory/state updates | Weak | | Portable context map | Partial | Weak | | Doc freshness and cross-link checks | Mostly manual | Weak | | Recurring doc/tech-debt gardening | Ad hoc | Weak | | Standard per-repo app/log/metric/test harness | Project-speci

RedKey Team OS should be a facade, not a fork. RedKey Harness should be enforcement, not ceremony.

The repo should expose a simple context interface for humans and agents, while deeper sources of truth remain where they belong:

• Repo docs for RedKey platform/runtime standards and playbooks.
• Studio artifacts for Studio-managed client/product work.
• Supabase agent_memory for durable semantic memory and lessons.
• docs/state.md for the compact restart pointer.
• Project repos for implementation source.

The Team OS layer should point to these sources, explain when to use each, and provide capture workflows.

The Harness layer should encode the rules that matter into checks and repeatable workflows. Documentation should explain the principle; tooling should enforce the invariant when drift would be costly.

Add a root entrypoint:

``text TEAM_OS.md ``

Add a small docs area:

``text docs/team-os/ 00-start-here.md context-routing.md project-map.md capture-workflows.md weekly-checkins.md decision-log.md retrieval-guide.md harness-standards.md ``

Root-level orientation file for humans and agents.

Required content:

• What RedKey Team OS is.
• What this repo knows.
• Where active project state lives.
• Where to write different kinds of artifacts.
• How to ask Atlas useful questions.
• How to capture new context.
• What not to store in Markdown.

The short onboarding path.

Should answer:

• What should a new agent read first?
• What should a new human read first?
• What is the difference between RedKey, Bezel, Studio, Atlas, and project repos?
• What commands or files prove current state?