v0.20.3 align antigravity agent layering

.agents/agents.md

@@ -0,0 +1,64 @@
+# Deep Research Agent Team
+
+This file defines Antigravity roles. Do not put detailed skills or long process rules here; use `.agents/skills/` and `.agents/workflows/` for those.
+
+## Research Manager
+
+Primary model: Gemini 3 Flash.
+
+Responsibilities:
+
+- Keep the phase task list current.
+- Load the relevant rules, skills, and workflow.
+- Ask the user to switch models before heavyweight phase work.
+- Ensure artifacts are written under `projects/<slug>/`.
+- Stop at Phase 1 and Phase 3 approval gates.
+
+Must not:
+
+- Invent sources or claim searches without receipts.
+- Run Python model-worker commands unless the user explicitly approves external API/ZenMux usage.
+- Hide uncertainty or missing evidence.
+
+## Phase 0-1 Strategist
+
+Primary model: Claude Opus 4.6 (Thinking).
+
+Responsibilities:
+
+- Interpret user materials and intended audience.
+- Select the research method and success criteria.
+- Build the chapter architecture, hypotheses, and validation plan.
+- Produce `phase1/material_brief.md`, `framework.md`, `research_brief.md/json`, and search logs.
+
+## Evidence Analyst
+
+Primary model: Gemini 3.1 Pro (Low).
+
+Responsibilities:
+
+- Execute task-card research.
+- Use approved search tools and maintain `phase2/search_log.jsonl`.
+- Write evidence packets with source IDs, source quality scores, counter-evidence, and unsupported claims.
+- Draft chapters only from approved chapter briefs and compressed findings.
+
+## Chief Reviewer
+
+Primary model: Gemini 3.1 Pro (High).
+
+Responsibilities:
+
+- Audit logic, MECE structure, source quality, unsupported claims, and counter-evidence.
+- Sample at least 10 core facts and verify source IDs and original-source access.
+- Produce `phase3/critique.md` with a `go`, `rework`, or `fail` decision.
+
+## Final Editor
+
+Primary model: Claude Opus 4.6 (Thinking).
+
+Responsibilities:
+
+- Assemble the final Chinese report from approved drafts and sources.
+- Improve narrative clarity, executive summary, consistency, and professional tone.
+- Produce `phase4/final_zh.md`, `editorial_notes.md`, and `final_fact_check.md`.
+- Avoid adding new facts unless sources and search logs are added first.

.agents/skills/antigravity-surface-adapter/SKILL.md

@@ -32,7 +32,7 @@ This project treats Gemini-family research as high risk for false confidence. Fo
 
 ## Antigravity Model Plan
 
-Switch the Antigravity conversation model by phase:
+Roles are defined in `.agents/agents.md`. This skill only maps phase work to models:
 
 | Phase | Model | Purpose |
 |---|---|
@@ -64,7 +64,7 @@ uv run python scripts/dr.py finalize <slug> --no-pdf --no-docx
 ## Native Runbook
 
 1. Open the repository root in Antigravity.
-2. Start with Gemini 3 Flash as phase manager. Load this skill, `AGENTS.md`, `mckinsey-method`, `search-strategy`, `source-quality`, `evidence-table`, `citation-manager`, `length-budget`, and `output-hygiene`.
+2. Start with Gemini 3 Flash as Research Manager. Load `.agents/agents.md`, this skill, `AGENTS.md`, `mckinsey-method`, `search-strategy`, `source-quality`, `evidence-table`, `citation-manager`, `length-budget`, and `output-hygiene`.
 3. Create or confirm `projects/<slug>/` and the phase folders. Use Python `init` only for scaffolding if helpful.
 4. Phase 0-1: ask the user to switch to Claude Opus 4.6 (Thinking). Produce:
 

.agents/workflows/deep-research-native.md

@@ -5,6 +5,7 @@ Description: Run a biomedical Deep Research project in Antigravity using Antigra
 ## Step 0: Load Context
 
 - Load `AGENTS.md`.
+- Load `.agents/agents.md`.
 - Load `.agents/rules/deep-research-antigravity.md`.
 - Load `.agents/skills/antigravity-surface-adapter/SKILL.md`.
 - Load skills: `mckinsey-method`, `search-strategy`, `source-quality`, `evidence-table`, `citation-manager`, `length-budget`, `output-hygiene`.

AGENTS.md

@@ -18,17 +18,6 @@
 - Skills 以 `.agents/skills` 为 canonical registry；adapter skill 目录由 `uv run python scripts/dr.py skills sync` 同步。
 - 默认工作链路为中文主写作；英文只保留在检索关键词、原文摘录、source title、DOI/URL 与来源笔记中。
 
-### 1.2 Antigravity native 例外
-
-Antigravity 可作为 native Deep Research 执行器使用，而不是只做 Python core 外壳。此时：
-
-- Antigravity 使用 `.agents/rules`、`.agents/skills`、`.agents/workflows` 执行研究，主要消耗 Antigravity 模型配额。
-- Gemini 3 Flash 只做流程管理；Phase 0-1 与 Phase 4 优先用 Opus；Phase 2 用 Gemini 3.1 Pro Low；Phase 3 用 Gemini 3.1 Pro High。
-- Python core 只做脚手架、资料抽取、确定性校验、引用和 PDF/DOCX 渲染；不得默认运行会触发 ZenMux/API 模型调用的 `run`、`research --execute-packets`、`research --assemble-chapters`。
-- 仍必须遵守本文的信源、证据、反方证据、字数和输出卫生规则。
-
----
-
 ## 2. 研究方法论（所有 agent 必须遵循）
 
 ### 2.1 麦肯锡核心原则
@@ -46,19 +35,6 @@ Antigravity 可作为 native Deep Research 执行器使用，而不是只做 Pyt
 - **反方证据优先**：每个 chapter 的研究必须主动搜索证伪性论点，不能只找支持证据
 - **数据可追溯**：所有数字、百分比、日期必须有来源 ID（如 `[src_042]`）
 
-### 2.2.1 反幻觉与检索回执
-
-Gemini / Antigravity / Gemini CLI 在研究任务中必须默认按"高幻觉风险模型"处理。所有 agent 必须遵守：
-
-- **没有工具回执，不得声称已搜索**：只有在本轮或当前 phase 明确执行过 `search` CLI、`scripts/search.py`、browser、MCP、curl 或同等检索工具，并保存 query / tool / timestamp / URL / title，才能写"已检索/已确认"。
-- **没有来源记录，不得写事实结论**：任何事实、数字、日期、公司管线、监管状态、临床结果、市场规模、专利状态必须能在 `sources.jsonl` 或 phase source ledger 中找到对应 `source_id`。
-- **不得把模型记忆当证据**：模型内置知识只能生成检索关键词或假设，不能作为正文证据。
-- **不得伪造不可访问来源**：若无法打开 PDF、网页、注册页或公告原文，必须标注"未能访问原文，仅作为发现线索"，不得提取具体数据。
-- **不得用二手摘要冒充原文**：搜索结果 snippet、AI summary、媒体转述只能作为发现入口；核心证据必须回到原文、官方记录、论文、专利或披露文件。
-- **必须保留检索轨迹**：每个 phase 至少写入 `phaseX/search_log.md` 或 `phaseX/search_log.jsonl`，记录关键词、工具、时间、命中源、筛除原因和下一步。
-- **必须显式承认不确定性**：找不到证据时写"未找到足够证据"，不得用模糊语气填补。
-- **自检问题**：每完成一段含事实的文字，问："这句话的来源 ID 是什么？原文在哪里？我真的打开/检索过它吗？"
-
 ### 2.3 字数配额（硬要求）
 
 | 报告类型 | 最小字数 | 建议章节数 |
@@ -89,7 +65,6 @@ Gemini / Antigravity / Gemini CLI 在研究任务中必须默认按"高幻觉风
 - **产出**：`phase1/material_brief.md` + `phase1/framework.md` + `phase1/research_brief.md/json`
 - **暂停点**：用户确认材料解读、研究方法、任务切分、检索策略和章节框架
 - **硬规则**：clarification 不只是问范围；必须固化报告用途、基调、成功标准、任务拆分、每个任务轴的 prompt/skills/search route，让低成本 worker 也能独立执行
-- **反幻觉产物**：必须生成 `phase1/search_log.md`，并在 `research_brief.json` 中记录所有已确认来源与待验证假设。未检索的判断只能标为 hypothesis。
 
 ### Phase 2：深度研究
 - **驱动命令**：`uv run python scripts/dr.py research <slug> --workers 6`
@@ -97,14 +72,12 @@ Gemini / Antigravity / Gemini CLI 在研究任务中必须默认按"高幻觉风
 - **产出**：`phase2/task_cards.json` + `packets/*.json` + `sources.jsonl` + `chapter_briefs/*.json` + `compressed_findings/*.json` + `drafts/chXX.md`
 - **不暂停**：全自动跑完
 - **防碎片化规则**：并发 worker 只写 evidence packet；`--build-briefs` 必须先收束为 chapter brief 和 compressed finding；章节正文必须从 compressed finding 写，不得把 packet 按顺序拼贴成报告
-- **反幻觉产物**：每个 packet 必须包含 `search_receipts`、`sources`、`counter_evidence`、`unsupported_claims`；没有 `search_receipts` 的 packet 不能进入 chapter brief。
 
 ### Phase 3：总编审校
 - **驱动命令**：`uv run python scripts/dr.py review <slug>`（`/dr-review` 只是薄封装）
 - **主导入口**：Python core deterministic review；dr-chief-editor/Gemini 可作为后续深度审校增强
 - **产出**：`projects/<slug>/phase3/critique.md`
 - **暂停点**：用户决策（修正 / 回炉 phase2 / 整体重来）
-- **反幻觉产物**：`critique.md` 必须抽查至少 10 条核心事实，逐条给出 source_id、原文状态和是否需要回炉。
 
 ### Phase 4：成稿
 - **驱动命令**：`uv run python scripts/dr.py finalize <slug>`
@@ -112,7 +85,6 @@ Gemini / Antigravity / Gemini CLI 在研究任务中必须默认按"高幻觉风
 - **默认链路**：final_zh.md → glossary/check(optional) → polish(optional) → citation_check → build_report
 - **兼容链路**：仅显式 `--legacy-translate` 时使用 final_en.md → translate → polish
 - **产出**：`phase4/final_zh.md` + `phase4/final_zh_polished.md`（可选）+ `phase4/*.pdf` + `phase4/*.docx`
-- **反幻觉产物**：终稿不得引入 Phase 2/3 中不存在的新事实；如需新增事实，必须先追加 sources 与 search_log，再写入正文。
 
 ---
 
@@ -209,18 +181,18 @@ uv run python scripts/dr.py methods list
 | Codex | `AGENTS.md` + `$CODEX_HOME` adapter（由 `scripts/deploy_adapters.py codex` 部署） | `uv run python scripts/dr.py ...` 或 `codex exec "$(uv run python scripts/dr.py prompt dr-run '<topic>')"` |
 | Claude Code | `.claude/skills/*/SKILL.md` | `/dr-run <slug-or-topic>` |
 | Gemini CLI | `GEMINI.md` + `.gemini/commands/dr/*.toml` | `/dr:run <slug-or-topic>` |
-| Antigravity | `.agents/rules` + `.agents/skills` + `.agents/workflows` | Gemini Flash 管流程，按 phase 切 Opus/Gemini，Python core 只做辅助 |
+| Antigravity | `.agents/agents.md` + `.agents/rules` + `.agents/skills` + `.agents/workflows` | 角色定义在 agents，强约束在 rules，技能在 skills，流程在 workflows |
 
 跨平台硬规则：
 
 - 除 Antigravity native 模式外，平台只做 surface adapter，不承载核心调度。
+- Antigravity 的角色定义放在 `.agents/agents.md`；不要把角色、技能和流程继续堆进本文件。
 - 不在平台 prompt 中手工并发写章节。
 - 不把平台 subagent 当默认并发机制。
 - 真实并发由 `scripts/runtime/workers.py` 的 worker pool 执行。
 - 真实模型选择由 `configs/models.yaml` 和 `scripts/runtime/roles.py` 执行。
 - 信息检索默认走 `scripts/search.py` / `SearchClient` / `search-gateway` skill；不得把 Tavily MCP、browser MCP 或平台 web search 作为默认路径，除非用户明确授权。
 - 搜索路由必须按任务类型选择：`evidence`=Exa highlights 受控证据发现，`fda/scholar/patents/news`=专用信源路径，`general`=宽泛发现和兜底；Tavily Research 只能作为阶段性 scan/enrichment/rework 输入，不能直接替代 evidence packet 或章节正文。
-- Antigravity native 可使用 `paperfoot/search-cli` 的 `search` 命令作为统一检索前台；但所有结果仍必须写入 search_log、sources.jsonl，并按 Tier/source-quality 评分。
 
 ---
 
@@ -237,7 +209,6 @@ uv run python scripts/dr.py methods list
 - API 密钥**只存** `secrets.env`（已入 gitignore），禁止硬编码到任何 agent/skill/command
 - 字体文件（~140MB）不入 git，通过 `download-fonts.sh` 获取
 - `bash` 权限默认 `ask`，仅允许 `python *` / `pandoc *` / `ls *` / `cat *` / `curl *` 自动执行
-- Antigravity 项目范围内可给予较高权限，但只应写当前 workspace；跨 workspace、全局设置、删除文件、git reset/clean、密钥读取和外部网络批量下载仍需用户明确批准。
 
 ---
 
@@ -253,14 +224,7 @@ uv run python scripts/dr.py methods list
 6. `--assemble-chapters` 后存在 `phase2/drafts/chXX.md` 和必要时的 `phase2/chapter_errors/*.json`。
 7. `scripts/v020_regression.py` 输出 `v0.20 regression PASS`。
 
-Antigravity native 模式的验证锚点是研究产物与检索回执：
-
-1. `.agents/rules/deep-research-antigravity.md` 被启用或明确 at mention。
-2. Phase 0-1 存在 `phase1/search_log.md`、`phase1/research_brief.md/json`、`phase1/unsupported_claims.md`。
-3. Phase 2 存在 `phase2/search_log.jsonl`、`phase2/packets/*.json`、`phase2/sources.jsonl`、`phase2/chapter_briefs/*.json`、`phase2/drafts/chXX.md`。
-4. 每个 packet 包含 `search_receipts`、`sources`、`counter_evidence`、`unsupported_claims`。
-5. Phase 3 `critique.md` 包含至少 10 条核心事实 source audit。
-6. Phase 4 存在 `final_fact_check.md`，且终稿未引入无来源新事实。
+Antigravity native 模式的验收锚点由 `.agents/workflows/deep-research-native.md` 定义。
 
 ---
 
@@ -272,7 +236,7 @@ Antigravity native 模式的验证锚点是研究产物与检索回执：
 2. ❌ 在缺乏 2 个独立信源时仍给出绝对化结论
 3. ❌ 使用"据报道""有专家认为"等未指明来源的表述
 4. ❌ 编造或虚构数据、URL、DOI
-5. ❌ 声称"已搜索/已验证/官网显示"但没有工具回执和 search_log
+5. ❌ 声称"已搜索/已验证/官网显示"但没有工具回执和检索记录
 6. ❌ 用搜索摘要、AI summary、snippet 冒充原文证据
 7. ❌ 写空洞的套话（"随着科技的发展""在大数据时代"）
 8. ❌ 忽略反方观点，只收集支持证据

PLAN.md

@@ -760,3 +760,16 @@ OpenCode 的坑：如果只是在主会话里装样子地写"让 X agent 做"，
   - `.agents/skills/antigravity-surface-adapter/SKILL.md` 加入 phase artifacts、fact-audit、权限建议和检索日志要求。
   - 新增 `.agents/workflows/deep-research-native.md`，把四阶段 native research 写成可执行 workflow，并在每阶段设 gate。
   - `scripts/deploy_adapters.py antigravity` 同步部署 workflows；已有文件继续默认跳过，`--force` 才备份覆盖。
+
+- 2026-05-07 v0.20.3 Antigravity rule/agent/skill separation：**按 Antigravity 最佳实践重新分层**
+
+  **设计结论**：
+  - `AGENTS.md` / `GEMINI.md` 是跨工具/Antigravity 项目规则，不应承担角色定义、技能手册和详细流程。
+  - `.agents/agents.md` 用于 Antigravity 角色团队定义；`.agents/rules` 放强约束；`.agents/skills` 放可复用技能；`.agents/workflows` 放 slash workflow 和阶段编排。
+  - 继续保留反幻觉约束，但从 `AGENTS.md` 的长段落中移出，由 Antigravity rule/skill/workflow 承载，避免根规则膨胀影响遵从性。
+
+  **已落地**：
+  - 新增 `.agents/agents.md`，定义 Research Manager、Phase 0-1 Strategist、Evidence Analyst、Chief Reviewer、Final Editor。
+  - 瘦身 `AGENTS.md`，只保留跨平台研究底线与分层指引。
+  - `antigravity-surface-adapter` skill 和 `deep-research-native` workflow 改为引用 `.agents/agents.md`。
+  - `scripts/deploy_adapters.py antigravity` 同步部署 `.agents/agents.md`，默认跳过已有文件，`--force` 才备份覆盖。

README.md

@@ -120,7 +120,7 @@ uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 ```
 
-Antigravity 部署不会修改全局设置。若目标工作区已有同名 rule/skill/workflow 文件，默认跳过；只有显式加 `--force` 时才会先生成 `.bak` 备份再覆盖。
+Antigravity 部署不会修改全局设置。若目标工作区已有同名 agents/rule/skill/workflow 文件，默认跳过；只有显式加 `--force` 时才会先生成 `.bak` 备份再覆盖。
 
 部署到新环境后自检：
 

docs/platform-adapters.md

@@ -134,6 +134,7 @@ gemini
 
 本项目已提供 Antigravity 入口：
 
+- `.agents/agents.md`：Antigravity 角色定义，只定义 Research Manager / Strategist / Analyst / Reviewer / Final Editor 等角色。
 - `.agents/skills/antigravity-surface-adapter/SKILL.md`：Antigravity 专用执行说明。
 - `.agents/rules/deep-research-antigravity.md`：workspace rule，约束其优先使用 Antigravity 模型配额，避免主流程落回 ZenMux。
 - `.agents/workflows/deep-research-native.md`：可按 slash workflow 执行的四阶段研究流程与反幻觉 gate。
@@ -146,7 +147,7 @@ uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 ```
 
-该命令只写 workspace-local `.agents/skills`、`.agents/rules` 和 `.agents/workflows`，不修改全局 Antigravity/Gemini 设置；已有文件默认跳过，`--force` 才会备份为 `.bak` 后覆盖。
+该命令只写 workspace-local `.agents/agents.md`、`.agents/skills`、`.agents/rules` 和 `.agents/workflows`，不修改全局 Antigravity/Gemini 设置；已有文件默认跳过，`--force` 才会备份为 `.bak` 后覆盖。
 
 本项目调用方式：
 
@@ -165,7 +166,7 @@ uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 4. 给 Agent Manager 一个明确任务：
 
 ```text
-请加载 .agents/skills/antigravity-surface-adapter/SKILL.md 和 AGENTS.md。
+请加载 .agents/agents.md、.agents/rules/deep-research-antigravity.md、.agents/skills/antigravity-surface-adapter/SKILL.md 和 AGENTS.md。
 用 Gemini 3 Flash 做流程管理，按 skill 要求在需要时提示我切换模型。
 研究主题："ADC 全球竞争格局"，slug: adc-global-landscape，method: mckinsey_market。
 请先创建/确认项目目录，然后进入 Phase 0-1，并在生成 phase1/framework.md 和 research_brief 后暂停。
@@ -178,7 +179,7 @@ uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 - 不要默认运行 `dr.py run`、`research --execute-packets`、`research --assemble-chapters`，这些会把主流程重新导向 Python/ZenMux。
 - Python core 可用于 `init/status/skills validate/finalize/render` 等辅助动作。
 - 若本机安装了 `paperfoot/search-cli` 的 `search` 命令，Antigravity Phase 0-2 可优先用 `search agent-info`、`search ... --json` 做统一检索入口。
-- 不建议依赖 SOUL.md：它不是 Antigravity 官方 Deep Research 约束入口。本项目用 `AGENTS.md`、`.agents/rules` 和 `.agents/skills` 三层约束即可。
+- 不建议依赖 SOUL.md：它不是 Antigravity 官方 Deep Research 约束入口。本项目用 `AGENTS.md`、`.agents/agents.md`、`.agents/rules`、`.agents/skills` 和 `.agents/workflows` 分层约束。
 
 ## Model Strategy Across Platforms
 

scripts/deploy_adapters.py

@@ -20,6 +20,7 @@ from scripts.runtime.skills import SkillRegistry
 CODEX_TEMPLATE = REPO_ROOT / "codex_adapter_templates" / "codex"
 ANTIGRAVITY_RULES_DIR = REPO_ROOT / ".agents" / "rules"
 ANTIGRAVITY_WORKFLOWS_DIR = REPO_ROOT / ".agents" / "workflows"
+ANTIGRAVITY_AGENTS_FILE = REPO_ROOT / ".agents" / "agents.md"
 
 
 @dataclass
@@ -131,6 +132,27 @@ def copy_antigravity_workflows(dst: Path, *, force: bool, dry_run: bool = False)
     return result
 
 
+def copy_antigravity_agents_file(dst: Path, *, force: bool, dry_run: bool = False) -> DeployResult:
+    result = DeployResult(platform="agents", target=dst)
+    if not ANTIGRAVITY_AGENTS_FILE.exists():
+        return result
+    target = dst / "agents.md"
+    if target.exists() and not force:
+        result.skipped.append(target)
+        return result
+    result.planned.append(target)
+    if dry_run:
+        return result
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists() and force:
+        backup = target.with_name("agents.md.bak")
+        shutil.copy2(target, backup)
+        result.backups.append(backup)
+    shutil.copy2(ANTIGRAVITY_AGENTS_FILE, target)
+    result.written.append(target)
+    return result
+
+
 def deploy_codex(
     *,
     target: Path | None = None,
@@ -162,6 +184,7 @@ def deploy_antigravity(
     target: Path | None = None,
     force: bool = False,
     skip_skills: bool = False,
+    skip_agents: bool = False,
     skip_rules: bool = False,
     skip_workflows: bool = False,
     dry_run: bool = False,
@@ -175,6 +198,8 @@ def deploy_antigravity(
     """
     workspace = (target or repo_root).expanduser()
     parts: list[DeployResult] = []
+    if not skip_agents:
+        parts.append(copy_antigravity_agents_file(workspace / ".agents", force=force, dry_run=dry_run))
     if not skip_skills:
         parts.append(copy_registered_skills(workspace / ".agents" / "skills", force=force, dry_run=dry_run))
     if not skip_rules:
@@ -213,6 +238,7 @@ def build_parser() -> argparse.ArgumentParser:
     antigravity = sub.add_parser("antigravity", help="Deploy Antigravity workspace rules and skills")
     antigravity.add_argument("--target", type=Path, help="Workspace root; defaults to this repository")
     antigravity.add_argument("--force", action="store_true", help="overwrite existing files and create .bak backups")
+    antigravity.add_argument("--skip-agents", action="store_true", help="do not copy role definitions into target/.agents/agents.md")
     antigravity.add_argument("--skip-skills", action="store_true", help="do not copy canonical skills into target/.agents/skills")
     antigravity.add_argument("--skip-rules", action="store_true", help="do not copy workspace rules into target/.agents/rules")
     antigravity.add_argument("--skip-workflows", action="store_true", help="do not copy workflows into target/.agents/workflows")
@@ -226,6 +252,7 @@ def main() -> int:
         result = deploy_codex(
             target=args.target,
             force=args.force,
+            skip_agents=args.skip_agents,
             skip_skills=args.skip_skills,
             dry_run=args.dry_run,
             include_config=args.include_config,

tests/test_adapter_deploy.py

@@ -57,6 +57,7 @@ def test_deploy_antigravity_writes_workspace_rules_and_skills(tmp_path: Path) ->
     result = deploy_antigravity(target=target, repo_root=REPO_ROOT)
 
     assert result.written
+    assert (target / ".agents" / "agents.md").exists()
     assert (target / ".agents" / "rules" / "deep-research-antigravity.md").exists()
     assert (target / ".agents" / "workflows" / "deep-research-native.md").exists()
     assert (target / ".agents" / "skills" / "antigravity-surface-adapter" / "SKILL.md").exists()
@@ -77,6 +78,19 @@ def test_deploy_antigravity_skips_existing_files_by_default(tmp_path: Path) -> N
     assert not existing.with_name("deep-research-antigravity.md.bak").exists()
 
 
+def test_deploy_antigravity_skips_existing_agents_file_by_default(tmp_path: Path) -> None:
+    target = tmp_path / "workspace"
+    existing = target / ".agents" / "agents.md"
+    existing.parent.mkdir(parents=True)
+    existing.write_text("custom agents\n", encoding="utf-8")
+
+    result = deploy_antigravity(target=target, repo_root=REPO_ROOT)
+
+    assert existing.read_text(encoding="utf-8") == "custom agents\n"
+    assert existing in result.skipped
+    assert not existing.with_name("agents.md.bak").exists()
+
+
 def test_deploy_antigravity_force_backs_up_existing_files(tmp_path: Path) -> None:
     target = tmp_path / "workspace"
     existing = target / ".agents" / "rules" / "deep-research-antigravity.md"