# AgentTeam Specs

> Canonical path: `SPECS.md`
> Status: living-index
> Scope: repository-wide entry point for canonical product, architecture, and engineering specs.

`SPECS.md` is the top-level index for AgentTeam's long-lived specs. Canonical domain specs live under root `specs/`; executable checks that protect those contracts live under root `guardrails/`. Documentation under `docs/` may explain or link to these specs, but it must not become a second canonical spec tree.

Use this file as the reading entry, then follow each domain README for the complete ordered list in that domain.

## Reading Order

### 1. Repository Layout And Product Overview

Start here to understand where specs live and how the product is shaped.

- [repository](./specs/repository/README.md) — agent working rules, package boundaries, specs / guardrails layout, canonical path rules, naming rules, and CI guardrails.
- [naming](./specs/naming/README.md) — semantic internal identifiers and frozen external protocol vocabulary.
- [product](./specs/product/README.md) — AgentTeam product overview and top-level object model.

### 2. Identity, Organization, Service Actors, Service Accounts, Apps, Automation, And Workflow

These specs define who can act, how workspace governance works, how external systems enter AgentTeam, and how AgentTeam-owned automation runs.

- [identity](./specs/identity/README.md) — human / agent / service identity, display, target parsing, and inspect boundaries.
- [organization](./specs/organization/README.md) — organization governance, workspace grants, permissions, and provider contracts.
- [architecture](./specs/architecture/README.md) — durable boundaries between service actors, service events, and automation.
- [service](./specs/service/README.md) — service actor substrate and service event delivery.
- [service-account](./specs/service-account/README.md) — workspace/平台服务号身份、创建审批、Human 角色、收件 membership、跨 workspace 广播、普通消息、Inbox 与已读未读。
- [app](./specs/app/README.md) — App service actors、runtime capability、App Notifications、Gitea integration、grants、webhooks、callbacks 与 provider App MCP。
- [schedule](./specs/schedule/README.md) — time-based AgentTeam automation.
- [automation](./specs/automation/README.md) — shared run/effect contracts for AgentTeam-owned automation and related ledgers.
- [workflow](./specs/workflow/README.md) — Plan authoring and versioning, Binding deployment, Invocation resolution, and durable graph Runs.
- [compat](./specs/compat/README.md) — legacy Trigger/watch compatibility boundaries.
- [trigger](./specs/trigger/README.md) — compatibility entry points for old Trigger links.

### 3. Collaboration, Messages, And Tasks

These specs define the core collaboration surface, source/projection/delivery
classification, and task board lifecycle.

- [collaboration](./specs/collaboration/README.md) — source/projection/delivery classification, channel scopes, thread scopes, mentions, task handoff boundaries, and controlled broadcast semantics.
- [message](./specs/message/README.md) — scope 消息模型、message actions、reactions、search、rewind、delivery runtime、delivery ledger constraints。
- [task](./specs/task/README.md) — task board, task pages, embedded views, collaborators, timeline cards, and Scope Execution convergence.
- [kb](./specs/kb/README.md) — repo-backed Knowledge Base product model, source repositories, permissions, Project removal, and retrieval scope.

### 4. Agents, Roles, And Owner-private Context

These specs define agent identity, canonical roles, browser read models, memory,
managed skills, review, and owner-private context compatibility references.

- [role identity](./specs/agent/role-identity.md) — canonical Role packages, Agent identity documents, bindings, materialization, and upgrade invariants.
- [memory](./specs/memory/README.md) — agent-local recovery memory and MeshX managed Memory resources.
- [skill](./specs/skill/README.md) — MeshX managed Skill resources, repository scan rules, and repository-backed Skill detail.
- [agent](./specs/agent/README.md) — browser read model API、output review、review context、echo-agentteam prevention。
- [owner-private context](./specs/agent-space/README.md) — Scope Execution runtime/API, owner-private wake/delivery, sharing, and compatibility notes.

### 5. Storage, Billing, SaaS, Daemon, MaaS, Versioning, Admin, Deployment, And API Engineering

These specs define implementation contracts and operational engineering rules.

- [storage](./specs/storage/README.md) — core database boundaries, TiDB support, and storage access convergence.
- [ags](./specs/ags/README.md) — AGS-backed repository ownership, authorization, and lifecycle invariants shared by MeshX resources.
- [billing](./specs/billing/README.md) — hosted credits payment flow, Alipay redirect/notify contracts, AgentTeam browser API facade, agentteam-maas internal API, ledger ownership, explicit hosted entitlement facts, workspace authorization, and AgentTeam-owned organization seat purchases.
- [saas](./specs/saas/README.md) — SaaS/commercial packaging, operator-controlled entitlements, subscription-adjacent quota policy, and timed manual seat grants.
- [daemon](./specs/daemon/README.md) — first-party daemon contract, Desktop architecture, daemon transport, runtime outbound tools, prompt compiler, Codex runtime, and runtime prompt mapping.
- [maas](./specs/maas/README.md) — AgentTeam-owned `agentteam-maas` control-plane integration, runtime capability issue, authority projection, and daemon loopback boundaries.
- [versioning](./specs/versioning/README.md) — server / daemon version tracks and release alignment.
- [admin](./specs/admin/README.md) — deployment-level admin dashboard, usage statistics, allowlist, and audit boundaries.
- [deployment](./specs/deployment/README.md) — AgentTeam Server deployment profiles, workspace isolation, placement, and managed workspace routing contracts.
- [api](./specs/api/README.md) — internal API handler adapter, server profile routing, clean-code organization, raw Gin classification, and guardrail rules.
- [web](./specs/web/README.md) — shared Browser/Desktop frontend runtime, host, workspace boundary, visual interface, and reorg guardrail contracts.
- [observability](./specs/observability/README.md) — three-pillar observability contract, cross-component logging rules, cardinality and scan-amplification discipline, and the durable rules new instrumentation must follow.

## Guardrails

Executable guardrails live under root `guardrails/`, grouped by the same domain ownership as `specs/`.

- [repository guardrails](./guardrails/repository/README.md) — repository-wide specs / guardrails layout checks.
- [naming guardrails](./guardrails/naming/README.md) — semantic identifier and file-name regression checks.
- [architecture guardrails](./guardrails/architecture/README.md) — Service Actor / Service Event / Schedule / Automation boundary checks and legacy allowlist manifest.
- [api guardrails](./guardrails/api/README.md) — internal API clean-code checks.
- [task guardrails](./guardrails/task/README.md) — task timeline write boundary checks.
- [web guardrails](./guardrails/web/README.md) — AgentTeam Web frontend boundary checks.

## Rules For Future Changes

- Add or move canonical specs under `specs/{domain}/` or `specs/{domain}/{subdomain}/` only.
- Keep every `specs/{domain}/README.md` in logical reading order.
- Keep every `guardrails/{domain}/README.md` in validation order.
- Do not recreate legacy spec trees or product/spec aliases under `docs/` as compatibility entry points.
- Long-lived specs should state current facts, stable contracts, ownership, and durable rationale. Do not preserve implementation history, phase notes, task/PR context, or retired alternatives in canonical specs; use Git history for that.
- Before final merge, use [`skills/reviewing-long-lived-specs/SKILL.md`](./skills/reviewing-long-lived-specs/SKILL.md) for PRs that create, move, or edit long-lived specs, guardrails, or policy docs.