@team-agent/installer 0.1.1 → 0.1.3

package/README.md

@@ -1,201 +1,179 @@
-# TeamSpec Agent Mode
+**English** | [中文](https://github.com/Florious95/team-agent/blob/main/README.zh.md)
 
-Document-driven CLI runtime for launching and coordinating Codex CLI workers from a leader conversation.
+# Team Agent
 
-The product and engineering boundary is defined in [`docs/team-agent-foundation-and-boundaries.md`](docs/team-agent-foundation-and-boundaries.md). Agents express semantic intent; the runtime owns team startup, delivery, state, diagnostics, secret safety, and the coordinator daemon.
+> Talk once. Ship a team.
 
-## Install
+A multi-agent runtime for Claude Code and Codex CLI where **the lead does the orchestration** — you describe a goal in plain language and it builds a team across providers, runs the work, and reports back.
 
-For normal users:
+No DAG. No YAML. No Kanban. Just a conversation.
 
 ```bash
 npx @team-agent/installer@latest install
 ```
 
-The installer probes `TEAM_AGENT_PYTHON`, `python3`, then `python`, copies the runtime to
-`~/.team-agent/runtime/<version>/`, writes wrappers under `~/.local/bin/`, runs
-`team-agent install-skill --target all`, and then runs `team-agent doctor`.
+**Important:** the lead Claude/Codex conversation must run inside a
+tmux-managed pane. The easiest path is `team-agent claude` or
+`team-agent codex`; existing tmux layouts also work. A plain terminal without a
+tmux pane is not enough, because teammates need a concrete pane target to send
+verified messages back to the lead.
 
-Source checkout install, for development:
+---
 
-```bash
-python3 scripts/install.py --prefix "$HOME/.local"
-export PATH="$HOME/.local/bin:$PATH"
-team-agent doctor
-team-agent install-skill --target all
-```
+## Why this exists
 
-Runtime dependencies:
+You have a $20 Claude subscription. It's day 18 of the month. You're out of credits but you still have work to ship.
 
-- `tmux` 3.3+
-- Codex CLI command: `codex`
-- Provider auth owned by the provider CLI
+You could pay $200. You could switch to a cheaper model and lose Claude's taste. You could wait until the 1st.
 
-## Quick Start
+Or you could let Claude stay the lead — designing tasks, coordinating, reviewing — while Codex or a third-party-API-routed Claude handles implementation. Same conversation, ~10x cheaper, no quality loss.
 
-Start the user-facing leader from a tmux-managed pane before starting a real team. The short
-entry points are:
+That's one of the things this is for. **The lead stays Claude. The hands can be anyone.**
 
-```bash
-team-agent codex
-team-agent claude
-```
+---
 
-Arguments after the provider name pass through to the provider CLI:
+## What it actually does
 
-```bash
-team-agent codex --dangerously-bypass-approvals-and-sandbox
-team-agent claude --dangerously-skip-permissions
-```
+Install once. Then in any Claude Code or Codex CLI conversation, say something like:
 
-If these commands run outside tmux, they create or attach a tmux leader session in the current
-directory. If they run inside tmux, they exec the provider in the current pane. Existing tmux
-layouts, including Finder/Ghostty right-click launchers, are also supported: the requirement is
-that `team-agent quick-start` runs from the leader's current tmux pane so worker-to-leader
-messages have a concrete, verifiable target.
+> "Build a small SaaS for tracking client feedback — backend, frontend, tests, and acceptance criteria."
 
-Create a directory containing role docs, then run:
+The lead figures out:
 
-```bash
-team-agent quick-start <agents_dir>
-```
+- What roles you need (and how rich each role's definition should be)
+- Which provider each role should run on (Claude for taste, Codex for logic, third-party for cost)
+- How teammates communicate (peer-to-peer, with shared task lists)
+- When to escalate decisions back to you
 
-The command prepares the current workspace team, starts workers, waits for readiness, and starts the per-workspace `team-agent-coordinator` daemon. When it prints `ready:` and `ready_signal`, startup is complete; do not add sleep/status polling unless diagnosing a failure. Detailed logs stay under the workspace team files.
+It then spawns the team, runs the work, and reports back. You stay in the same conversation the whole time. Teammates show up in separate terminal windows so you can watch what each is doing without leaving the lead.
 
-By default, loose role docs are copied into `.team/current/`. To keep multiple teams in one workspace, give each generated team an explicit id, or pass an existing team directory directly:
+Close your terminal. Come back tomorrow. The team is still there. Open Claude Code again — pick up where you left off.
 
-```bash
-team-agent quick-start ./roles-alpha --team-id alpha
-team-agent quick-start .team/research
-```
+---
 
-`quick-start` is the fresh startup path. If Team Agent finds stored worker context for the same runtime session, it stops before launching blank workers and tells you to either resume with `restart` or explicitly accept a fresh start with `--fresh`:
+## What makes it different
 
-```bash
-team-agent restart . --team team-alpha
-team-agent quick-start .team/alpha --fresh
-```
+There are good multi-agent tools today. Each picks a different tradeoff:
 
-Role docs can omit `model` for subscription workers. Team Agent fills defaults from `TEAM.md` `provider_models`, then built-in defaults (`codex: gpt-5.5`, `claude/claude_code: claude-sonnet-4-6`). Put a role-level `model` only when that worker intentionally uses a different model.
+|                            | Form               | You configure                  | Lead                                  | Where it runs       |
+| -------------------------- | ------------------ | ------------------------------ | ------------------------------------- | ------------------- |
+| **agent-teams-ai** (871★)  | Electron app       | Roles + provisioning prompt in UI | "CTO" watches Kanban               | Desktop app         |
+| **omo** (54.9k★)           | OpenCode plugin    | `ultrawork` command word       | Sisyphus, fixed roles                 | OpenCode TUI        |
+| **CCB** (2.5k★)            | CLI + TOML         | `.ccb/ccb.config` per team     | None (you compose)                    | tmux                |
+| **ClawTeam** (3.3k★)       | CLI + prompt inject | TOML team templates            | None                                  | tmux + Web UI       |
+| **Team Agent** (this)      | MCP runtime        | Nothing                        | The native Claude/Codex you're already talking to | Your existing terminal |
 
-Send work and inspect state:
+The lead in this project isn't a special "orchestrator agent" with its own personality. **It's just Claude (or Codex)** — the same one you'd talk to about anything else, now with the ability to spawn and manage teammates.
 
-```bash
-team-agent send <agent_id> "<message>"
-team-agent send --watch-result <agent_id> "<message>"
-team-agent status
-team-agent status <agent_id>
-team-agent approvals
-team-agent inbox <agent_id>
-team-agent shutdown --keep-logs
-team-agent restart .
-team-agent restart . --team <session_name_or_team_name>
-team-agent start-agent <agent_id> --workspace .
-```
+This matters because:
 
-`team-agent send` waits for `visible` delivery by default and exits non-zero if the target terminal does not show the unique token before timeout. Use `--no-wait` only when deliberately accepting injected-but-unverified delivery.
-Use `team-agent send --watch-result ...` for normal task dispatch: the command returns after verified delivery, registers a result watcher, and the coordinator collects the eventual result and notifies the leader.
+- **Orchestration scales with model intelligence**, not with framework features. When Claude 5 ships, the lead gets smarter automatically. No update required on our side.
+- **The lead can build any team for any task**, not just predefined coding roles. We've run academic paper revisions, multi-role brainstorming sessions, even adversarial games like Werewolf — none of them programmed, all of them composed by the lead in conversation.
+- **You give up the orchestration UI**, you gain the ability to ship work whose specifics you couldn't have specified up front.
 
-`team-agent status` includes result-store counts plus each worker's `session_id`, capture method, and attribution confidence when available. `team-agent shutdown` makes a final session capture attempt before killing tmux. `team-agent restart <workspace>` resumes workers with stored provider-native session ids; if the workspace has more than one restartable team, it fails closed and lists candidates until you pass `--team`. Workers with missing `session_id` are started fresh and logged as `restart.fresh_spawn`. `team-agent start-agent <agent_id> --workspace .` is the narrow repair path for one missing worker window; it resumes that worker when possible, starts it fresh otherwise, and leaves other workers running.
+---
 
-Use `team-agent approvals [agent_id]` to inspect pending provider/MCP approval prompts without copying worker terminal pages into the leader context.
+## How it works (briefly)
 
-## Role Docs
+Three design choices make this possible:
 
-Role docs are Markdown files with YAML front matter:
+**1. The orchestration layer is the lead.** No external workflow engine. The lead reasons about role definitions, dispatches via MCP tools, and adjusts the team in real time from your conversation. Add a teammate mid-flow, change someone's role, dissolve a team — all in plain language.
 
-```yaml
----
-name: implementer
-role: Implementation Engineer
-provider: codex
-model: gpt-5.5
-auth_mode: subscription
-profile: codex-default
-tools:
-  - fs_read
-  - fs_write
-  - execute_bash
-  - mcp_team
----
-```
+**2. Transport is infrastructure, identity is persistent.** Teammates run as long-lived `claude` or `codex` processes with stable session IDs. When a window dies, the runtime respawns it and restores state — without that event ever entering any agent's context. Identity is injected at the system-prompt level, not via fragile chat-history hacks.
 
-For quick-start teams, put role docs under `agents/` and keep `TEAM.md` at the team root. A root `TEAM.md` is team configuration, not a worker role, and does not create a leader pane. Quick-start generated files stay under the selected team directory, such as `.team/current/` or `.team/alpha/` (`team.spec.yaml`, `team_state.md`), instead of the workspace root.
+**3. Standards over inventions.** MCP for tool calls, Skill files for role definitions. Anything the broader ecosystem ships, this picks up automatically.
 
-Team-level switches live in `TEAM.md` front matter:
+For the full design philosophy and boundaries, see [`docs/team-agent-foundation-and-boundaries.md`](./docs/team-agent-foundation-and-boundaries.md).
 
-```yaml
----
-name: demo-team
-dangerous_auto_approve: false
-display_backend: ghostty_window
-fast: false
-tick_interval_sec: 2
-push_min_interval_sec: 60
-stuck_timeout_sec: 300
-worker_to_worker: true
 ---
+
+## Quick start
+
+### Install
+
+```bash
+npx @team-agent/installer@latest install
 ```
 
-If `display_backend` is omitted, quick-start defaults to `ghostty_window`. Use `display_backend: none` only for headless or CI runs.
-Ghostty display windows use one linked tmux session per worker, so each visible window keeps an independent active tmux window while runtime injection still targets the base worker window.
-When the leader Codex/Claude process itself was started with `--dangerously-bypass-approvals-and-sandbox` or `--dangerously-skip-permissions`, Team Agent treats worker launch, restart, and single-agent repair as already authorized and passes the matching dangerous permission mode through.
+This sets up the MCP server, registers the Team Agent skill, and wires it into your Claude Code / Codex CLI config.
+
+Source checkout install:
+
+```bash
+git clone https://github.com/Florious95/team-agent.git team-agent
+cd team-agent
+npm exec --yes --package . -- team-agent-installer install
+```
 
-Secrets must stay in profile files ignored by git. Role docs and manifests carry profile references only. Agents must not read raw profile env files into context; use `team-agent profile show <name> --workspace . --json` or `team-agent profile doctor <name> --workspace . --json` for redacted diagnostics.
+### Use
 
-For third-party compatible APIs, the leader should generate a local fillable profile instead of asking for secrets in chat:
+Start the lead inside tmux. The shortcut commands create or attach a tmux
+leader session when needed:
 
 ```bash
-team-agent profile init deepseek --auth-mode compatible_api --workspace .
+team-agent claude
+team-agent codex
+```
+
+If you already use tmux/Ghostty/Finder layouts, keep using them; the hard
+requirement is that the visible lead conversation has a tmux pane. Then talk to
+the lead:
+
 ```
+You:   I want to refactor this codebase, split it into a monorepo,
+       and add proper test coverage. Help me plan and run this.
 
-This creates `.team/current/profiles/deepseek.env` and `.team/current/profiles/deepseek.example.env` with blank values:
+Lead:  [proposes a team — refactor architect (Claude), code mover (Codex),
+        test author (Claude), reviewer (Codex). Surfaces the tradeoffs,
+        waits for your confirmation.]
 
-```env
-AUTH_MODE=compatible_api
-PROFILE_NAME=deepseek
-BASE_URL=
-API_KEY=
-MODEL=
+You:   Go.
 ```
 
-Fill the `.env` file locally, then reference only the profile name from role docs:
+That's it. Teammates appear in separate windows. The lead reports progress, raises decisions when needed, and shuts everything down when you say so.
+
+### Stop / resume
 
-```yaml
-provider: claude_code
-auth_mode: compatible_api
-profile: deepseek
 ```
+You:   Close the team for now.
+Lead:  [Saves state, closes panes. ~2 seconds.]
 
-For `compatible_api`, `MODEL=` in the profile is a valid model source. If both the role doc and profile define a model, they must match exactly; otherwise preflight fails before startup. Team Agent loads that profile during quick-start, launch, restart, and start-agent. Secret values are written only to per-worker runtime env files under `.team/runtime/provider-env/` and are not printed in CLI output, event logs, role docs, or compiled specs. Compatible API workers inherit the current shell proxy/CA environment by default, because some teams intentionally route third-party APIs through a proxy. Claude compatible API workers use a Team Agent managed `CLAUDE_CONFIG_DIR`, so user-level Claude subscription settings cannot re-inject Anthropic proxy variables into third-party API sessions. That managed config is pre-seeded with non-secret onboarding, theme, and workspace trust state so a fresh isolated Claude worker does not stop at first-run setup. Startup smoke checks expose whether the profile used an ambient proxy or a profile proxy; if the proxy cannot reach `BASE_URL`, quick-start returns a redacted blocker and lets the user choose whether to fix the proxy, set `HTTPS_PROXY=`/`HTTP_PROXY=` in that profile, or set `PROXY_MODE=direct` in that profile to bypass proxy only for that worker. Subscription workers keep the native provider settings and environment.
-When diagnosing profile state, run `team-agent profile show deepseek --workspace . --json`; it reports non-secret values and secret-key presence without printing secret values. Do not inspect `.team/current/profiles/*.env` or `.team/runtime/provider-env/*.env` through an Agent.
+(next day)
 
-## Runtime
+You:   Continue yesterday's refactor team.
+Lead:  [Restores teammates from saved sessions. ~2 seconds. Same context.]
+```
 
-Worker-to-leader messages are stored in SQLite, rendered as human-readable text, and pushed into the attached leader pane by the runtime/coordinator path. Delivery states distinguish `accepted`, `target_resolved`, `injected`, `visible`, `submitted`, `failed`, and `ambiguous`. Direct leader delivery only reports `submitted` after the rendered token is observed in the pane and the runtime sends `Enter`; `visible` alone is only a pre-submit observation.
+---
 
-Agent-facing MCP tools keep context thin: `send_message` takes only `to` and `content`, and `report_result` takes `summary` plus optional status/details. Sender, task id, ack policy, result schema fields, delivery ids, and verification metadata are filled or stored by the runtime. If a provider fails to pass `TEAM_AGENT_ID`, MCP infers the worker from the active task/message state and falls back to an explicit `unknown` sender rather than misrouting the message as leader. Message targets are team-scoped: use `leader`, a teammate agent id, or `*` for all other team members.
+## What works today
 
-Final results are stored through `report_result`; that call also attempts an immediate leader notification through the same verified/fallback delivery path. `team-agent collect` remains the authoritative state-update path, and `team-agent inbox` is message history only, not a final-result intake. `team-agent status --json` exposes `results.total`, `results.uncollected`, `results.collected`, `results.invalid`, and `results.by_status`.
+Verified across multiple real workflows:
 
-The coordinator automatically clears known Team Agent control-plane MCP prompts such as `team_orchestrator.report_result` and `team_orchestrator.send_message`. It uses session-scoped approval, verifies the prompt disappeared after submission, retries boundedly when Enter/selection does not take, and records the result in the event log. Non-allowlisted tools stay visible through `team-agent approvals`.
+- **Cross-vendor mixed teams** — Claude leading, Codex implementing, third-party-API Claude on tests
+- **Web development teams** — 5 roles: frontend / backend / contract / requirements / testing
+- **Academic collaboration** — 5-stage paper revision with adversarial reviewers and consensus mechanism
+- **Game / experimental** — 4-round "Who's the Spy" experiments (1 lead + 4 players, fully autonomous, surfaced a real LLM theory-of-mind observation)
+- **Emergent recovery** — leads automatically pressing enter on Codex permission prompts; teams surviving pane closures and resuming the next day
+- **Dialog-driven team mutation** — adding teammates mid-flow, changing roles, dissolving a team, all without leaving the lead's conversation
 
-Raw worker terminal inspection is blocked in the ordinary black-box workflow. The hidden `team-agent peek` diagnostic refuses to run unless the caller provides `--allow-raw-screen` after explicit user authorization, and still requires exactly one bounded selector: `--head N`, `--tail N`, or `--search TEXT`.
+---
 
-Worker-to-worker messages are allowed within the current team. The runtime resolves recipients only from the current leader plus agents in the team spec/runtime state; `*` broadcasts to that set and excludes the sender.
+## Supported leads and teammates
 
-The main help intentionally shows only the black-box surface. Low-level commands remain available through:
+| Role     | Claude Code (subscription) | Claude Code (third-party API) | Codex CLI |
+| -------- | -------------------------- | ----------------------------- | --------- |
+| Lead     | ✓                          | ✓                             | ✓         |
+| Teammate | ✓                          | ✓                             | ✓         |
 
-```bash
-team-agent advanced --help
-```
+Any teammate can be backed by a different provider/tier than the lead. The runtime handles auth, session lifecycle, and resume per teammate independently.
 
-## Acceptance
+---
 
-```bash
-PYTHONPATH=src python3 scripts/run_regression_tests.py --iterations 3
-PYTHONPATH=src python3 tests/run_tests.py
-cargo test --manifest-path crates/team-agent-core/Cargo.toml
-```
+## Status
+
+**Beta.** Working in real use, but expect rough edges in less common configurations. Issues and PRs welcome.
+
+## License
 
-Real provider smoke requires installed and authenticated provider CLIs. A skipped real provider smoke is not production acceptance.
+AGPL-3.0-or-later. Commercial licensing available on request.

package/README.zh.md

@@ -0,0 +1,175 @@
+[English](https://github.com/Florious95/team-agent/blob/main/README.md) | **中文**
+
+# Team Agent
+
+> 说一次。一个 team 跑起来。
+
+为 Claude Code 和 Codex CLI 设计的多 agent 运行时。**编排由 lead 自己完成**——你用自然语言描述目标,它跨厂商组建团队、执行工作、汇报结果。
+
+没有 DAG。没有 YAML。没有 Kanban。只有对话。
+
+```bash
+npx @team-agent/installer@latest install
+```
+
+**重要:** 主 Agent，也就是 lead 所在的 Claude/Codex 对话，必须运行在
+tmux 管理的 pane 里。最省心的方式是 `team-agent claude` 或
+`team-agent codex`；你自己已有的 tmux/Ghostty/Finder 分屏布局也可以。普通非
+tmux 终端不够，因为队员向 lead 回传消息时必须有一个明确、可验证的 pane 目标。
+
+---
+
+## 为什么做这个
+
+你有 $20 的 Claude 订阅。月中 18 号,额度用完了,但还有活要交。
+
+你可以升级到 $200(贵)。可以切到更便宜的模型(损失 Claude 的品味)。可以等 1 号重置(影响工作)。
+
+或者你可以让 Claude 继续当 lead——梳理任务、协调、验收——把执行外包给 Codex 或者第三方 API 接入的 Claude。同一个对话,十分之一的成本,质量不下降。
+
+这是这个工具的用法之一。**Lead 还是 Claude,执行者可以是任何人。**
+
+---
+
+## 它具体在做什么
+
+装一次。然后在任何 Claude Code 或 Codex CLI 对话里说类似这样:
+
+> "做一个小型 SaaS 来追踪客户反馈——前后端、测试、验收标准都要。"
+
+Lead 自己想清楚:
+
+- 需要哪些角色,每个角色的定义应该多丰富
+- 哪个角色用哪个 provider(Claude 写前端、Codex 写后端逻辑、第三方 API 跑测试节省成本)
+- 队员之间怎么通信(P2P + 共享任务列表)
+- 什么决策需要回来问你
+
+然后它 spawn 队员、跑工作、汇报。**你全程在同一个对话里**。队员在独立终端窗口里跑,你可以随时切过去看每个人在做什么。
+
+关电脑回家。明天打开 Claude Code 接着说一句"继续昨天那个 team",team 还在,session 状态完整,从昨晚那里接着干。
+
+---
+
+## 和现有方案的差异
+
+市面上已经有几个好的多 agent 工具,各自选了不同的 trade-off:
+
+|                              | 形态                | 你要配置的东西                 | Lead                                | 跑在哪里        |
+| ---------------------------- | ------------------- | ------------------------------ | ----------------------------------- | --------------- |
+| **agent-teams-ai** (871★)    | Electron 桌面应用   | UI 里写 roles + provisioning prompt | "CTO" 看 Kanban                   | 桌面应用        |
+| **omo** (54.9k★)             | OpenCode 插件       | `ultrawork` 命令词             | Sisyphus,角色固定                  | OpenCode TUI    |
+| **CCB** (2.5k★)              | CLI + TOML          | 每个 team 一份 `.ccb/ccb.config` | 无(你自己组队)                   | tmux            |
+| **ClawTeam** (3.3k★)         | CLI + prompt 注入   | TOML team 模板                 | 无                                  | tmux + Web UI   |
+| **Team Agent**(本项目)      | MCP 运行时          | 不需要配置                     | 你本来就在对话的 Claude/Codex       | 你现有的终端    |
+
+本项目的 lead **不是**一个有特定 personality 的 "orchestrator agent",**就是** Claude(或 Codex)——你平时聊天用的那个,加上 spawn 和管理队员的能力。
+
+为什么这件事重要:
+
+- **编排能力随模型能力提升**,不随框架 feature 增加。Claude 5 一出,lead 自动变聪明,不需要我发版。
+- **Lead 可以为任何任务组建任何 team**,不限于预设的开发角色。我们已经跑通了学术论文修订、多角色头脑风暴、对抗类游戏("谁是卧底"4 局连测)——这些场景都不是预编程的,**全部是 lead 在对话中现场组建出来的**。
+- **你放弃了编排 UI,换来"交付你原本无法精确描述的工作"的能力**。
+
+---
+
+## 工作原理(简要)
+
+三件事让它能跑起来:
+
+**1. 编排层就是 lead。** 没有外部 workflow engine。Lead 自己推理角色定义、通过 MCP 调度、根据你的对话实时调整 team。运行中加队员、改角色、解散 team——全部用自然语言。
+
+**2. Transport 是基础设施,身份是持久的。** 队员是长寿命的 `claude` 或 `codex` 子进程,有稳定的 session ID。窗口挂了运行时自己拉起来恢复状态——**整个过程不进入任何 agent 的上下文**。身份在 system prompt 层注入,不是塞在对话历史里的脆弱 hack。
+
+**3. 用标准协议,不发明协议。** 用 MCP 做工具调用,用 Skill 文件做角色定义。生态发什么,本项目自动获得什么。
+
+完整设计哲学和边界,见 [`docs/team-agent-foundation-and-boundaries.md`](./docs/team-agent-foundation-and-boundaries.md)。
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+npx @team-agent/installer@latest install
+```
+
+会自动设置 MCP server、注册 Team Agent skill、写入 Claude Code / Codex CLI 配置。
+
+源码安装:
+
+```bash
+git clone https://github.com/Florious95/team-agent.git team-agent
+cd team-agent
+npm exec --yes --package . -- team-agent-installer install
+```
+
+### 使用
+
+在 tmux 内启动 lead。下面两个快捷命令会在需要时创建或附着到 tmux leader
+session:
+
+```bash
+team-agent claude
+team-agent codex
+```
+
+如果你已经有自己的 tmux/Ghostty/Finder 分屏布局,可以继续用;硬要求只是可见的
+lead 对话必须有 tmux pane。然后在对话里:
+
+```
+你:    我想重构这个代码库,拆成 monorepo,加测试覆盖。帮我规划并执行。
+
+Lead:  [提议一个 team:重构架构师 (Claude)、代码搬运工 (Codex)、
+        测试作者 (Claude)、reviewer (Codex)。把 trade-off 说清楚后等你确认]
+
+你:    开始。
+```
+
+完事。队员窗口出现,lead 推进工作、需要决策时停下来问你,你说"关掉"就关掉。
+
+### 关闭 / 恢复
+
+```
+你:    先把 team 关了。
+Lead:  [保存状态、关闭 pane,约 2 秒]
+
+(第二天)
+
+你:    继续昨天那个重构 team。
+Lead:  [从保存的 session 恢复队员,约 2 秒,同样的上下文]
+```
+
+---
+
+## 当前已验证的能力
+
+在多种真实工作流下验证过:
+
+- **跨厂商混合 team**——Claude 当 lead,Codex 实现,第三方 API 接入的 Claude 跑测试
+- **Web 开发 team**——5 角色:前端 / 后端 / 契约 / 需求分析 / 测试
+- **学术协作**——5 阶段论文修订工作流,审稿人和研究者对抗 + 共识机制
+- **博弈 / 实验**——4 局"谁是卧底"实验(1 lead + 4 玩家全自治,意外跑出了关于 LLM theory-of-mind 的真实观察)
+- **Emergent 恢复**——lead 自己识别 Codex 权限确认 prompt 并按 enter;窗口关闭后第二天接着用
+- **对话驱动的 team 变更**——运行中加队员、改角色、解散 team,全在 lead 的对话里完成
+
+---
+
+## 支持的 lead 和 teammate
+
+| 角色     | Claude Code(订阅制) | Claude Code(第三方 API) | Codex CLI |
+| -------- | -------------------- | ------------------------ | --------- |
+| Lead     | ✓                    | ✓                        | ✓         |
+| Teammate | ✓                    | ✓                        | ✓         |
+
+任何队员可以用和 lead 不同的 provider/tier。运行时分别处理每个队员的认证、session 生命周期、resume。
+
+---
+
+## 项目状态
+
+**Beta**。已经在真实工作流里跑通,但不常见的配置可能有粗糙的地方。欢迎 issue 和 PR。
+
+## License
+
+AGPL-3.0-or-later。商业 license 可联系协商。

package/docs/README.md

@@ -0,0 +1,10 @@
+# Documentation
+
+Public entry points:
+
+- [`github-release.md`](github-release.md): GitHub upload, NPM publish, NPM install, and source install workflow.
+- [`team-agent-foundation-and-boundaries.md`](team-agent-foundation-and-boundaries.md): product and engineering boundary.
+- [`architecture.md`](architecture.md): runtime architecture notes.
+- [`team-agent-rust-core-boundaries.md`](team-agent-rust-core-boundaries.md): Rust core boundaries.
+
+Historical implementation reports remain in this directory for traceability.