diff --git a/README.md b/README.md
index 17ee8e0..1a598db 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,182 @@
-# team
+# ISOS Agent Teams
 
-ISOS Agent Teams
\ No newline at end of file
+通用 AI Agent Teams 软件研发模板，支持多角色 AI Agent（Claude Code / GLM）在 tmux 中并行协作开发。
+
+## 项目简介
+
+ISOS 是一套基于 Claude Code 的多人 Agent 协作开发框架：
+
+- **项目经理** 分发任务、跟踪进度
+- **后端开发** 实现 FastAPI + SQLite 服务端
+- **前端开发** 实现 Svelte 5 + PyWebView 桌面端
+- **测试工程师** 编写全级别测试并分析覆盖率
+- **对话监控** 实时跟踪各 Agent 的输入/输出
+
+所有角色在 tmux 面板中并行运行，通过共享任务列表和消息系统协调。
+
+## 技术栈
+
+| 组件 | 技术 | 说明 |
+|------|------|------|
+| 语言 | Python 3.12+ / TypeScript | 后端 Python，前端 TypeScript |
+| 包管理 | uv / npm | Python 用 uv，前端用 nvm + npm |
+| 服务端 | FastAPI + SQLite | REST API、数据存储 |
+| 桌面端 | PyWebView + Svelte 5 | 本地 UI、SQLite |
+| 版本控制 | Jujutsu (jj) | 与 git 并存，主分支 `trunk` |
+| 协作工具 | tmux + Claude Code | 多面板并行 Agent |
+
+## 目录结构
+
+```
+docs/           # 项目文档（需求、设计、架构、测试、运维）
+team/           # 团队规范（Git、jj、Svelte、tmux）
+scripts/        # 工具脚本（tmux 团队空间、监控、消息通知）
+.claude/        # Claude Code 配置
+  agents/       # Agent 角色定义
+  commands/     # 斜杠命令
+prompts/        # 角色提示词
+member/         # 成员对话记录
+memory/         # 跨会话经验记忆
+tasks/          # 任务文档
+specs/          # speckit 功能规格
+.specify/       # speckit 配置
+```
+
+## 快速开始
+
+### 1. 环境准备
+
+```bash
+# 克隆项目
+jj clone <仓库地址> workspace && cd workspace
+
+# Python 环境（需 uv）
+uv python install 3.12
+
+# 前端环境（需 nvm）
+nvm install --lts
+```
+
+详细环境搭建见 [`docs/管理-开发环境搭建.md`](docs/管理-开发环境搭建.md)。
+
+### 2. 启动 Agent 团队
+
+```bash
+# 在 tmux 中启动 5 面板团队工作空间
+/isos-tmux-team
+```
+
+布局如下：
+
+```
++----------+----------------------+--------------------+
+|          |  Pane 2  (后端)      |  Pane 3  (前端)    |
+|  Pane 1  +----------------------+--------------------+
+|  (项目)  |  Pane 4  (测试)      |  Pane 5  (对话)    |
+|          |                      |                    |
++----------+----------------------+--------------------+
+```
+
+也可手动启动单个角色：
+
+```bash
+/isos-pm          # 项目经理
+/isos-backend     # 后端开发
+/isos-frontend    # 前端开发
+/isos-test        # 测试工程师
+```
+
+### 3. 常用命令
+
+```bash
+# 提交并推送（jj 工作流）
+/isos-pr
+
+# 文档相关
+/isos-doc-需求    # 需求文档
+/isos-doc-架构    # 架构文档
+/isos-doc-设计    # 设计文档
+/isos-doc-测试    # 测试文档
+/isos-doc-运维    # 运维文档
+
+# 工具
+/isos-tmux-monitor   # tmux 监控面板
+/isos-pdf2md         # PDF 转 Markdown
+/isos-md-export      # Markdown 导出 docx/pdf
+```
+
+### 4. 开发验证
+
+```bash
+# 服务端 (cd apps/server)
+uv run mypy src/ --strict
+uv run pytest
+ruff format --check . && ruff check .
+
+# 桌面端 (cd apps/desktop)
+uv run mypy src/ --strict
+uv run pytest
+ruff format --check . && ruff check .
+```
+
+## 角色阅读指引
+
+### 项目经理
+
+1. [`docs/12-管理-项目.md`](docs/12-管理-项目.md) — 项目管理、里程碑、工作流程
+2. [`docs/03-功能列表.md`](docs/03-功能列表.md) — 功能需求列表
+3. [`docs/管理-Agent-Team分工及提示词.md`](docs/管理-Agent-Team分工及提示词.md) — Agent 分工
+4. [`team/tmux.md`](team/tmux.md) — tmux 协作规范
+
+### 架构师
+
+1. [`docs/07-系统架构.md`](docs/07-系统架构.md) — 系统架构图、模块划分
+2. [`docs/08-数据库设计.md`](docs/08-数据库设计.md) — 数据模型
+3. [`docs/09-API契约.md`](docs/09-API契约.md) — API 接口定义
+4. [`docs/11-工程规范.md`](docs/11-工程规范.md) — 术语表、工程规范
+
+### 产品经理
+
+1. [`docs/01-用户需求.md`](docs/01-用户需求.md) — 用户需求、项目目标
+2. [`docs/02-产品需求.md`](docs/02-产品需求.md) — 非功能性需求、约束
+3. [`docs/04-用户故事.md`](docs/04-用户故事.md) — 用户故事
+
+### 开发者
+
+1. [`docs/管理-开发入门.md`](docs/管理-开发入门.md) — 开发入门指引
+2. [`docs/管理-开发环境搭建.md`](docs/管理-开发环境搭建.md) — 环境配置
+3. [`team/svelte.md`](team/svelte.md) — Svelte 5 开发指南
+4. [`team/desktop-编码规范.md`](team/desktop-编码规范.md) — Desktop 编码规范
+5. [`team/git.md`](team/git.md) / [`team/jj.md`](team/jj.md) — 版本控制规范
+
+### 测试工程师
+
+1. [`docs/10-测试-方案.md`](docs/10-测试-方案.md) — 测试策略（含各级别定义）
+2. [`docs/测试-计划.md`](docs/测试-计划.md) — 测试计划
+3. [`docs/测试-用例.md`](docs/测试-用例.md) — 测试用例
+4. [`docs/测试-单元.md`](docs/测试-单元.md) — 单元测试标准
+
+### 运维工程师
+
+1. [`docs/运维-部署实施.md`](docs/运维-部署实施.md) — 部署方案
+2. [`docs/运维-发布日志.md`](docs/运维-发布日志.md) — 版本变更历史
+3. [`docs/运维-故障排除.md`](docs/运维-故障排除.md) — 问题排查
+4. [`docs/运维-安全审计.md`](docs/运维-安全审计.md) — 安全策略
+5. [`docs/运维-性能基准.md`](docs/运维-性能基准.md) — 性能基准
+
+## 文档索引
+
+完整文档目录见 [`docs/README.md`](docs/README.md)，团队规范见 [`team/README.md`](team/README.md)。
+
+## 核心约束
+
+- **模块独立**: `apps/server` 和 `apps/desktop` 各有独立环境，禁止跨模块代码引用，仅通过 API 通信
+- **每个 PR 只改一个模块**，标题格式：`[模块] 描述`
+- **提交类型使用中文**: `功能`、`修复`、`维护`、`文档` 等，详见 [`team/git.md`](team/git.md)
+- **禁止 AI 签名**: 提交消息中不添加 `Co-Authored-By` 等标识
+- **完整类型注解**: mypy strict 模式，禁止 `Any`
+- **文档文件中文命名**: `docs/` 下所有 `.md` 使用中文文件名
+
+## 许可证
+
+见 [LICENSE](LICENSE)。