{
  "id": "2026-05-08-redkey-team-os-design-6291290228",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-08-redkey-team-os-design.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.748Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "RedKey Team OS Design",
  "summary": "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 Summary 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, a...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "RedKey Team OS Design",
      "level": 1,
      "body": "Date: 2026-05-08  \nStatus: Draft  \nOwner: Justin / Atlas-Codex  \nScope: RedKey platform operating model, shared context system, and agent harness standards"
    },
    {
      "title": "Summary",
      "level": 2,
      "body": "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.\n\nToday, 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.\n\nThis 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."
    },
    {
      "title": "Background",
      "level": 2,
      "body": "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.\n\nThe useful pattern is not Claude Code-specific. The core claim is:\n\n- Context must be shared, not personal.\n- Context must be discoverable by agents.\n- Decisions, customer context, implementation notes, and reusable queries should be captured close to the work.\n- The system should reduce dependence on one person being online to answer historical context questions.\n\nRedKey already follows this direction, but with a more advanced architecture:\n\n- `project-refs.yaml` routes projects, clients, repos, Studio IDs, VPS paths, and status.\n- `docs/state.md` gives the restart pointer for the current working set.\n- Supabase `agent_memory` stores durable semantic memory.\n- Studio artifacts store canonical product/project planning artifacts.\n- Repo docs store RedKey platform specs, plans, setup docs, and playbooks.\n- Bezel API and related services provide actual workflow execution, task claims, event reads, and HCS proof paths.\n\nThe remaining design problem is making this system legible and usable as a Team OS."
    },
    {
      "title": "Harness Engineering Comparison",
      "level": 2,
      "body": "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.\n\nThe relevant harness principles are:\n\n- `AGENTS.md` should be a short table of contents, not a large instruction manual.\n- Repository docs should be structured, indexed, and treated as the system of record.\n- Plans, architecture notes, product specs, quality rules, generated references, and technical debt trackers should be versioned close to the code.\n- 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.\n- Architecture and taste should be encoded as mechanical checks: linters, structural tests, CI jobs, file-size limits, schema/naming conventions, and remediation instructions.\n- 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.\n- Entropy needs recurring garbage collection: stale docs, weak patterns, inconsistent architecture, and accumulated technical debt should be scanned and repaired continuously.\n\nRedKey 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."
    },
    {
      "title": "Codex Agent Clarification",
      "level": 2,
      "body": "RedKey should be precise about the word \"agent.\"\n\nToday, RedKey has:\n\n- Atlas-Codex as an operating mode for Codex in this repo.\n- Local Codex skills and repo instructions.\n- RedKey/Bezel task and workflow infrastructure.\n- Historical and planned named RedKey agents such as Jess, Mia, Priya, Quinn, and others.\n- Agent-like project execution patterns driven through Codex sessions, Studio artifacts, and Bezel API concepts.\n\nRedKey does not yet have production OpenAI Agents SDK agents or Codex-native agents that run as durable application services. We should not imply otherwise.\n\nThe 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.\n\nDesign 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.\""
    },
    {
      "title": "Goals",
      "level": 2,
      "body": "1. Give humans and agents one obvious starting point for RedKey context.\n2. Preserve current artifact routing: platform docs in the repo, client/product artifacts in Studio.\n3. Keep `docs/state.md` short as a restart pointer, not a memory archive.\n4. Make recurring context capture easy and consistent.\n5. Support natural language retrieval across project status, decisions, specs, implementation notes, and lessons.\n6. Keep the system portable enough that Codex, Claude Code, Cursor, or another agent can understand the context.\n7. Define the first RedKey Harness standards for agent-legible tooling, verification, doc health, and recurring cleanup.\n8. Move repeated review feedback and taste preferences into durable documentation or mechanical checks."
    },
    {
      "title": "Non-Goals",
      "level": 2,
      "body": "- Replace Supabase `agent_memory`.\n- Replace Studio artifacts with Markdown mirrors.\n- Move client/product canonical specs into repo docs.\n- Build a new full UI for Team OS in this phase.\n- Reorganize all existing docs before the entrypoint and workflows are proven.\n- Require every RedKey-adjacent project repo to adopt the full harness immediately.\n- Eliminate human judgment from product, architecture, release, or client decisions."
    },
    {
      "title": "Current State",
      "level": 2,
      "body": "RedKey has the core Team OS primitives, but they are distributed.\n\n| Capability | Current RedKey Mechanism | Status |\n| --- | --- | --- |\n| Project switchboard | `project-refs.yaml` | Strong |\n| Restart pointer | `docs/state.md` | Strong but growing long |\n| Durable memory | Supabase `agent_memory` via Doppler-backed scripts | Strong |\n| Platform specs/plans | `docs/specs`, `docs/plans`, `docs/setup`, `docs/playbooks` | Strong |\n| Product planning | Supabase `studio_projects` and `studio_artifacts` | Strong |\n| Agent operating profile | `.codex/atlas-codex/OPERATING.md`, `MODEL.md`, local skills | Strong |\n| Execution runtime | Bezel API, task claims, workflow events, HCS proofs | Strong |\n| OpenAI Agents SDK agents | Not yet built | Missing |\n| Durable Codex-native agent services | Not yet built | Missing |\n| Project-specific governance | B2BEA CSS/runtime audits, Bezel API smoke tests, PVA release gates | Medium |\n| Human onboarding | Scattered across files | Weak |\n| Team check-in ritual | Ad hoc memory/state updates | Weak |\n| Portable context map | Partial | Weak |\n| Doc freshness and cross-link checks | Mostly manual | Weak |\n| Recurring doc/tech-debt gardening | Ad hoc | Weak |\n| Standard per-repo app/log/metric/test harness | Project-specific | Weak |\n| Agent-to-agent review loop | Available, not default | Weak |"
    },
    {
      "title": "Design Principle",
      "level": 2,
      "body": "RedKey Team OS should be a facade, not a fork. RedKey Harness should be enforcement, not ceremony.\n\nThe repo should expose a simple context interface for humans and agents, while deeper sources of truth remain where they belong:\n\n- Repo docs for RedKey platform/runtime standards and playbooks.\n- Studio artifacts for Studio-managed client/product work.\n- Supabase `agent_memory` for durable semantic memory and lessons.\n- `docs/state.md` for the compact restart pointer.\n- Project repos for implementation source.\n\nThe Team OS layer should point to these sources, explain when to use each, and provide capture workflows.\n\nThe 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."
    },
    {
      "title": "Proposed Information Architecture",
      "level": 2,
      "body": "Add a root entrypoint:\n\n```text\nTEAM_OS.md\n```\n\nAdd a small docs area:\n\n```text\ndocs/team-os/\n  00-start-here.md\n  context-routing.md\n  project-map.md\n  capture-workflows.md\n  weekly-checkins.md\n  decision-log.md\n  retrieval-guide.md\n  harness-standards.md\n```"
    },
    {
      "title": "TEAM_OS.md",
      "level": 3,
      "body": "Root-level orientation file for humans and agents.\n\nRequired content:\n\n- What RedKey Team OS is.\n- What this repo knows.\n- Where active project state lives.\n- Where to write different kinds of artifacts.\n- How to ask Atlas useful questions.\n- How to capture new context.\n- What not to store in Markdown."
    },
    {
      "title": "docs/team-os/00-start-here.md",
      "level": 3,
      "body": "The short onboarding path.\n\nShould answer:\n\n- What should a new agent read first?\n- What should a new human read first?\n- What is the difference between RedKey, Bezel, Studio, Atlas, and project repos?\n- What commands or files prove current state?"
    },
    {
      "title": "docs/team-os/context-routing.md",
      "level": 3,
      "body": "Canonical routing rules.\n\nThis should restate and expand the artifact routing contract:\n\n- RedKey platform/runtime work goes in repo docs.\n- Studio-managed product work goes in Studio artifacts.\n- Temporary exports go under `tmp/`.\n- Durable memories go to Supabase `agent_memory`.\n- Restart state goes to `docs/state.md`.\n- Secrets never go into docs or memory."
    },
    {
      "title": "docs/team-os/project-map.md",
      "level": 3,
      "body": "Human-readable companion to `project-refs.yaml`.\n\nThis should summarize active projects by:\n\n- Client\n- Product/project\n- Repo path\n- Studio project ID\n- Current status\n- Next action\n- Source of truth\n\nThis file should be generated or manually updated from `project-refs.yaml` and `docs/state.md`, not become an independent source of truth."
    },
    {
      "title": "docs/team-os/capture-workflows.md",
      "level": 3,
      "body": "Defines capture patterns for common context.\n\nRecommended capture types:\n\n- Product decision\n- Architecture decision\n- Customer/client signal\n- Implementation checkpoint\n- Incident or regression\n- Deployment note\n- Reusable lesson\n- Open question\n\nEach capture type should specify:\n\n- Where it goes\n- Required fields\n- Whether it also needs a durable memory write\n- Whether `docs/state.md` should change"
    },
    {
      "title": "docs/team-os/weekly-checkins.md",
      "level": 3,
      "body": "Recurring operating ritual.\n\nMinimal weekly check-in format:\n\n```markdown"
    },
    {
      "title": "Active Work",
      "level": 3,
      "body": "- ..."
    },
    {
      "title": "Decisions",
      "level": 3,
      "body": "- ..."
    }
  ],
  "html_path": "artifacts/2026-05-08-redkey-team-os-design-6291290228.html",
  "json_path": "artifacts/2026-05-08-redkey-team-os-design-6291290228.json"
}