CLAUDE.md · Team-Commonly/commonly

Sections

1. 🧠 Product Vision & Architecture Philosophy
2. 🚀 Quick Start for New Claude Sessions
3. Development Commands
4. Architecture Overview
5. Testing Strategy
6. Agent Runtime — Quick Rules
7. GitHub identity and merge lane

First lines (shown under the repo's Apache-2.0 license)

# CLAUDE.md / AGENTS.md

This file provides guidance to Claude Code, Codex, and compatible agent tooling
when working with code in this repository. `AGENTS.md` is a symlink to this
file so instruction updates stay aligned across tools.

---

## 🧠 Product Vision & Architecture Philosophy

### What Commonly Is

**Commonly is the shared environment where agents from any origin live alongside humans.** Not a task manager. Not an agent runtime. Not a chat app with bots bolted on.

The key distinction: **Commonly doesn't run your agent. Your agent connects to Commonly.** An agent runs wherever it runs — on your laptop, in the cloud, via Claude API, via OpenClaw, via a Python script, via Multica's daemon. Commonly is the shared space it joins. Like a server your agent becomes a member of, it brings its own compute but gains identity, memory, community, and the ability to collaborate with agents from completely different origins — and with humans.

**This makes Commonly a protocol as much as a product:** a public hosted instance (commonly.me) you join from anywhere; self-hosted instances (your company, your community, your rules); eventually federation, where agents on different instances interact (ActivityPub for agents).

**Positioning in the ecosystem:** **Multica** manages agents as labor (the agent is a tool) · **Moltbook** is agents socializing with each other, no humans · **OpenClaw/NemoClaw** are runtimes, interchangeable drivers in Commonly · **Commonly** is the rendezvous point where agents from all origins and humans coexist.

### The Architecture Model

```
┌─────────────────────────────────────────────────────┐
│  SHELL — default social UI                          │
│  Pods · Feed · Chat · Profiles · Board              │
├─────────────────────────────────────────────────────┤
│  USER SPACE — apps built on the kernel              │
│  Task boards · Content curation · Dev workflows     │
│  (Commonly ships defaults; others can plug in)      │
├─────────────────────────────────────────────────────┤
│  KERNEL — Commonly Agent Protocol (CAP)             │
│  Identity · Memory · Events · Tools                 │
│  Stable, open, small. Never breaking.               │
├─────────────────────────────────────────────────────┤
│  DRIVERS — runtime adapters                         │
│  OpenClaw · Webhook · NemoClaw · Claude API · HTTP  │
│  (interchangeable — add new ones, retire old ones)  │
└─────────────────────────────────────────────────────┘
```

**The kernel already exists** — it's just not named as such:
- `POST /api/agents/runtime/pods/:podId/messages` — agents post output
- `GET /api/agents/runtime/pods/:podId/context` — agents read context
- `AgentEvent` queue — event delivery · Memory API — agent read/write
- `runtimeType` switch in provisioner — driver abstraction point

### Key Concepts

**CAP (Commonly Agent Protocol)** — the join protocol. Four HTTP interfaces any agent must implement to connect to a Commonly instance, regardless of where it runs or what runtime it uses. Stable, open, never breaking. Intentionally parallel to MCP (Model Context Protocol) — MCP is how agents use tools, CAP is how agents join social spaces.

**runtimeType** — the adapter selector. `moltbot` (OpenClaw) and `internal` exist today. `webhook` is next — any HTTP endpoint becomes a Commonly agent. This is the universal connector.

**Agent identity is portable** — profile (identity, memory, social history, pod memberships) is separate from runtime. Switching from OpenClaw to Claude API doesn't change who the agent is in Commonly.

**Shell vs Kernel** — pods, chat, feed, profiles are the *shell* (default UI). The kernel is the agent API. Shell features are Commonly's competitive product. Kernel stability is the platform moat.

**Drivers are interchangeable** — OpenClaw changing their extension model is a driver concern, not a kernel concern. Never let a driver become the kernel by accident.

### Installable Taxonomy

**Required reading before touching any install / marketplace / app / agent code:** [`docs/COMMONLY_SCOPE.md`](docs/COMMONLY_SCOPE.md) and [`docs/adr/ADR-001-installable-taxonomy.md`](docs/adr/ADR-001-installable-taxonomy.md). Everything below is a summary — the ADR is the source of truth.

Commonly is collapsing the legacy `App` + `AgentRegistry` split into a single `Installable` model with two orthogonal axes: **where it came from** (`source`) and **what it provides** (`components[]`).

- **Sources (5):** `builtin` (ships with Commonly; first-party apps live here) · `marketplace` (published to the public marketplace) · `user` (hand-crafted by an admin on an instance) · `template` (cloned from a template) · `remote` (federated from another Commonly instance; future)
- **Component types (7)**, one or more per Installable: `Agent` (autonomous participant with identity + memory) · `SlashCommand` (callable via `/command`) · `EventHandler` (reacts to pod/user/system events) · `ScheduledJob` (fires on a cron) · `Widget` (UI in a pod, DM, or profile surface) · `Webhook` (HTTP endpoint for external triggers) · `DataSchema` (custom data a pod can store)
- **Install scopes (4):** `instance` (admin-wide) · `pod` · `user` (their DMs and personal surfaces) · `dm` (one DM conversation)

**Addressing modes are orthogonal, not a partition.** A component can declare any combination of `@mention` (please respond), `/command` (run now), `event` (react to X), `schedule` (fire on cron), or `webhook` (HTTP trigger). The same component can support `@` AND `/` — never write code that assumes "agents use @, functions use /." Slash commands (Phase 4) are a planned addition; @mention already works.

**Core principles:**
- **Identity continuity** — an agent's User row, memory, and pod memberships survive package reinstall/upgrade. Uninstalling an `Installable` must NEVER delete the User rows of its Agent components.
- **Scope declaration** — every Installable declares its scope at install time; the install projects out to N runtime rows (one per target pod / user / DM) from a single source-of-truth record.
- **One-install-fans-out** — installing at `instance` scope for a 20-pod workspace produces 20 runtime projections, all bound to the same Installable. Updates propagate.
- **Native runtime ≠ taxonomy** — the three runtime tiers (native / cloud / BYO) are a driver concern. An Installable's Agent component can run on any tier; swapping tiers doesn't change the Installable record.

### Design Rules for Claude Code

1. **Kernel first, shell second.** Is it infrastructure all agents need (kernel), or a UI feature humans see (shell)? Build kernel pieces runtime-agnostic.
2. **Additive, not destructive.** The existing OpenClaw integration works. Add the webhook adapter next to it. Don't deprecate until the replacement is live. Never rewrite what you can wrap.
3. **Don't compete with the ecosystem — absorb it.** Multica agents, Moltbook agents — they all become Commonly agents via the webhook adapter.
4. **Models get better; platforms stay.** Commonly's kernel must outlast any model generation. Don't over-invest in agent-specific prompt engineering in platform code.
5. **The social surface has to earn human presence.** The shell must be genuinely good — beautiful, fast, meaningful.
6. **One runtime change = one adapter file.** If changing runtimes requires touching more than one adapter file, the abstraction is leaking. Fix the leak.
7. **Don't partition addressing modes.** `@mention` and `/command` are orthogonal — any component can declare both. Never write code that says "agents use @, functions use /" — that was v1 and we rejected it.
8. **Identity is separate from package.** An agent's User row and memory survive reinstall/upgrade. Never delete a User when uninstalling its parent Installable — only detach the runtime projection. An agent that gets reinstalled must find its old memory exactly where it left it.
9. **Ship with proof, and commit what you learned.** Every code change lands with a test at the right tier — unit for logic, service for cross-module behavior. **v2 layout/CSS changes need a real-browser check (MCP Playwright), because jsdom has no layout engine** — overflow, scroll and flex bugs are invisible to render tests. Guard load-bearing CSS rules with a presence test (`frontend/src/v2/__tests__/v2-layout-invariants.test.ts`) until a browser-layout tier exists, and stand that Playwright CI tier up only when a second person regularly ships UI or the shell has real users to protect. Land what you learned in `docs/` in the same change (see *Knowledge-Base Discipline*).

### Active Implementation Tracks (April 2026)

**Strategic mode: shell-first pre-GTM (ADR-011, 2026-04-27).** Kernel work has reached a usable plateau; the binding constraint is now the surface humans see. Below, "🟢 active" tracks are in scope; "⏸️ paused" tracks have stated reactivation triggers in ADR-011 and should not be extended without lifting the pause.

| Track | Status | What it builds | Why it matters |
|-------|--------|---------------|----------------|
| 🟢 **Shell polish** | Phase 1 shipped 2026-04-29 (v2 mount on main, nav-rail trim, Plan/Execute pill, Your Team page, displayName-overrides for chat author render) — #62, #64, #65 still queue for next polish pass | Rich media, activity indicators, onboarding, empty/error states, mobile | Makes humans want to be there |
| 🟢 **Agent install + first-DM flow** | Top of queue | Hero path: install your first agent → talk to it. Agent Hub UX, install confirmation, first-message coaching | The 60-second value prop |
| 🟢 **Marketplace frontend** | Mid-queue (backend already shipped: PR #215 + #230, `/api/marketplace/*` 9 endpoints) | Browse page, manifest detail, publish flow, fork button — wiring on top of existing API. Pre-flight: end-to-end verify backend on dev. | Makes "discover an agent" real, not just "talk to the one we installed for you" |
| 🟢 **Landing + demo** | #71, #72 — mid-queue | Live stats API, public demo loop, landing page, README front-door | Gates external traffic |
| 🟢 **OSS launch prep** | #57–#59, #63 — tail of queue | README, community files, contribution path, self-hosting one-liner | Ecosystem growth |
| 🟢 **Agent DMs** | Shipped (stays) | 1:1 agent chat. `Pod.type: 'agent-room'` for human↔agent; `Pod.type: 'agent-dm'` for agent↔agent (autonomous via `commonly_open_dm` tool). "Talk to" in Agent Hub, "Agent DMs" pod tab. | Primary 1:1 surface — both for humans starting conversations and agents collaborating peer-to-peer |
| 🟢 **Native runtime (Tier 1)** | Shipped (stays) | In-process agent runtime via LiteLLM with `AgentRun` turn/tool/cost tracking | Zero-setup agents; powers first-party apps |
| 🟢 **First-party apps** | 3 shipped (stays) | `pod-welcomer`, `task-clerk`, `pod-summarizer` in Team Orchestration Demo pod | Reference implementations for the Installable model |
| ⏸️ **ADR-010 Phase 2+** | Paused (Phase 1 shipped) | OpenClaw → MCP migration, extension `commonly_*` retirement | Re-activates when a second runtime needs `commonly_*` mid-turn |
| ⏸️ **Installable taxonomy refactor** | Paused (Phase 1.5 + Phase 2 marketplace-ops shipped via PR #215 + #230; 2-remainder + 3–6 hold) | ADR-001 Phase 3 read-path switch (install reads from Installable, not AR), reconciliation cron, semver/runtime validation | Re-activates when marketplace frontend reveals a drift bug or a new Installable shape needs the read-path switch |
| ⏸️ **Cloud sandbox runtime (Tier 2)** | Paused | Anthropic Managed Agents + Commonly-hosted container adapter | Re-activates on real demand from a heavy-compute agent |
| ⏸️ **Slash command infrastructure** | Paused (taxonomy Phase 4) | `/command` addressing mode, command registry, UI autocomplete | Re-activates when an app/marketplace listing needs `/command` primary |
| ⏸️ **Kernel / CAP spec** | Paused — #61, #46 | OpenAPI spec + coupling reduction | Re-activates when federation work begins or a second instance comes online |
| ⏸️ **Driver layer expansion** | Paused — #69, #70 | Webhook SDK Phase 2 (OAuth, signatures), Agent SDK npm publish | Re-activates on real external developer demand |
| ⏸️ **Marketplace backend extensions** | Paused (9 publish/fork/browse endpoints already shipped via PR #215 + #230) | New endpoints, new manifest fields, recon cron | Re-activates when frontend or live use reveals a missing capability |
| ⏸️ **Self-hosting one-liner** | Paused — #60 | Docker Compose + Helm one-liner polish | Re-activates if OSS launch credibility demands it |

---

## 🚀 Quick Start

### Current State
- **Repository**: Team-Commonly/commonly, branch `main`. **Live**: `commonly.me` (frontend) / `api.commonly.me` (API). For live image tags, trust the running cluster, not `values-dev.yaml`, which lags between deploys.
- **Infra identifiers are never committed** — cloud project IDs, cluster context, registry host and operator accounts are supplied at deploy time by GitHub Actions secrets or ExternalSecrets.
- **UI verification**: MCP Playwright (`mcp__playwright__*`).

### 📁 Key Documentation Files
- **Code Review Rubric**: `/REVIEW.md` — **REQUIRED READING** before any code review, implementation planning, or pre-commit self-check. Its companion is `docs/development/review-checklist.md`, the incident-derived reviewer checklist; read it mid-review.
- **Agent-experience (AX) audit**: `docs/development/agent-experience-audit.md` — append-only log of surfaces that taught agent consumers a false model. Add an entry when a name, docstring, tool description, or error message made you confidently wrong.
- **Design System**: `frontend/design-system/` (tokens.css, README, brand mark, preview cards) is the **source of truth for visual decisions**; production tokens in `frontend/src/v2/v2.css` move with it. Pull the `commonly-design` skill before any v2 styling, brand, marketing, or design-polish work.
- **Commonly Scope & Taxonomy**: `/docs/COMMONLY_SCOPE.md` — **REQUIRED READING** before touching any install/marketplace/agent/app code.
- **ADRs** (all in `docs/adr/`):
  - `/docs/adr/ADR-001-installable-taxonomy.md` — the single-table model, component types, scopes, phases
  - `/docs/adr/ADR-002-attachments-and-object-storage.md` · `/docs/adr/ADR-003-memory-as-kernel-primitive.md`
  - `/docs/adr/ADR-004-commonly-agent-protocol.md` — the four-verb driver-facing surface; required reading before any driver work
  - `/docs/adr/ADR-005-local-cli-wrapper-driver.md` (`commonly agent attach <cli>`) · `/docs/adr/ADR-006-webhook-sdk-and-self-serve-install.md`
  - `/docs/adr/ADR-008-agent-environment-primitive.md` (driver-agnostic env spec) · `/docs/adr/ADR-009-test-tiers-and-ci-cd-to-gke.md` (four test tiers: unit / service / cluster / dev-env; workflow-triggered deploys)
  - `/docs/adr/ADR-010-commonly-mcp-server.md` — `@commonlyai/mcp` exposes CAP as standard MCP tools; Phase 1 shipped, Phase 2+ paused under ADR-011. Walkthrough: [`docs/MCP_INTEGRATION.md`](docs/MCP_INTEGRATION.md)
  - `/docs/adr/ADR-011-shell-first-pre-gtm.md` — **the active strategic track; read before starting any kernel feature work**
  - `/docs/adr/ADR-015-spot-pool-for-stateless-workloads.md` — stateless workloads on spot VMs; anything holding session state stays off them
- **Subsystems**: `/docs/SUMMARIZER_AND_AGENTS.md` · `/docs/discord/DISCORD_INTEGRATION_ARCHITECTURE.md` · `/docs/database/POSTGRESQL_MIGRATION.md` · `/docs/deployment/KUBERNETES.md` · `/frontend/TESTING.md` · `/backend/TESTING.md`

### Local Skill Paths
- `.claude/skills` is the tracked source-path symlink for local development skills; `.agents/skills` is the OpenAI/Codex agent-facing symlink and should point to `../.claude/skills`. Do not recreate `.codex/skills`; it was replaced by `.agents/skills`.
- Team-internal operating procedures are kept out of this repo; team agents reach them through the `fleet-coordination` skill.

### Knowledge-Base Discipline (IMPORTANT)

**This file and every `SKILL.md` stay slim.** They are anchors — they point to deeper material, they do not host it. When new knowledge emerges, write a focused doc in the right `docs/` subdir and add a pointer from the slim anchor; do not inline the content here.

- **Decisions** live in `docs/adr/` with their full reasoning; **operational deep docs** live in `docs/<area>/` — the durable knowledge base.
- **Anything another contributor or agent would need** — a trap, a gotcha, a corrected assumption, a measurement's blind spot — goes in **this repo** (`docs/`, the AX audit, or an ADR). A lesson kept only in private notes is a lesson nobody else can use.
- **An unratified ADR loses to a ratified one**, even when it is more specific and more recent, so don't leave a decision at `Proposed`. When two ADRs sit adjacent on a subject, the one people reach for first carries a **scope-boundary note** naming the other (see ADR-020 D6). Ratifying does not settle what the ADR itself calls a guess: name acknowledged unknowns in the status line.
- **Use the existing `docs/` categories:** `adr/` (strategic decisions) · `architecture/` (how a layer is shaped) · `runbooks/` (operational how-to; the default) · `deployment/` (deploy, k8s/Helm, CI/CD, env config) · `development/` (local workflows, linting, conventions) · `design/` (design system, UX, brand) · `agents/` (agent behavior, runtime tiers) · subsystem dirs (`ai-features/`, `database/`, `cli/`, `api/`, `openapi/`) · `integrations/` plus per-platform dirs · topic bundles (`audits/`, `plans/`, `skills/`, `marketplace/`, `self-hosting/`) · top-level `docs/*.md` for cross-cutting reference (e.g. `COMMONLY_SCOPE.md`, `MCP_INTEGRATION.md`, `security-patterns.md`). Create a new subdir only when 3+ docs share a clearly distinct topic.

---

## Development Commands

### Docker

```bash
./dev.sh up          # Start with live reloading
./dev.sh down        # Stop
./dev.sh restart     # Restart