v0.20.2 harden antigravity research workflow

2026-05-07 12:57:11 +08:00
parent 68e45bcf41
commit e991b26af9
11 changed files with 532 additions and 33 deletions
@@ -0,0 +1,34 @@
 # Deep Research Antigravity Rule
 When operating this repository from Google Antigravity, use Antigravity as the primary Deep Research executor and use the repository as the method, artifact, and validation framework.
 ## Non-Negotiables
 - Use Antigravity's model quota for main research work.
 - Do not default to Python core model-worker commands such as `run`, `research --execute-packets`, or `research --assemble-chapters`, because they may route work through ZenMux/API credits.
 - It is acceptable to write phase artifacts directly in Antigravity when following the project skills and evidence schema.
 - Use `.agents/skills/antigravity-surface-adapter/SKILL.md` whenever the user asks for Antigravity usage, phase execution, model planning, or quota planning.
 - Keep all research outputs under `projects/<slug>/`.
 - Use Python scripts only for scaffolding, deterministic checks, citation/report rendering, status, and local material processing unless the user explicitly approves external model/API usage.
 ## Anti-Hallucination Contract
 - No tool receipt, no search claim. The agent may not write that it has searched, checked, verified, or confirmed anything unless a search/browser/terminal/MCP tool call actually happened and the result is logged.
 - No source ID, no factual claim. Every concrete fact in drafts must map to a `source_id` in `sources.jsonl` or the current phase ledger.
 - No snippet laundering. Search result snippets, AI summaries, and memory are only leads; they cannot support final claims.
 - Failed access must be explicit. If a page, PDF, registry, patent, or filing cannot be opened, mark it as inaccessible and do not quote exact values from it.
 - Each phase must maintain `phaseX/search_log.md` or `phaseX/search_log.jsonl`.
 - Each evidence packet must include `search_receipts`, `sources`, `counter_evidence`, and `unsupported_claims`.
 - When evidence is thin, write "该观点证据不足，待进一步验证" rather than smoothing over the gap.
 ## Quota Discipline
 - Surface manager: Gemini 3 Flash.
 - Phase 0-1: Claude Opus 4.6 (Thinking).
 - Phase 2: Gemini 3.1 Pro (Low).
 - Phase 3: Gemini 3.1 Pro (High), with fallback to another model only if quality is inadequate.
 - Phase 4: Claude Opus 4.6 (Thinking).
 ## Pause Points
 Pause after Phase 1 and Phase 3. Ask the user to confirm the framework or critique decision before moving to the next major phase.
@@ -0,0 +1,140 @@
 ---
 name: antigravity-surface-adapter
 description: Guides Google Antigravity to run Deep Research natively with Antigravity model quotas, while using this repository's skills, source standards, artifacts, and optional Python utilities for validation/rendering.
 ---
 # Antigravity Deep Research Adapter
 Use this skill when the user asks to run, plan, review, or finalize a Deep Research project from Google Antigravity.
 ## Core Rule
 Antigravity is the research operator. Use Antigravity's own model selector and task execution to perform the research phases. Python core is an auxiliary toolbox for project scaffolding, deterministic checks, citation/report rendering, and status inspection; do not let it silently route the main research through ZenMux unless the user explicitly asks.
 The Deep Research method still comes from this repo:
 - Follow `AGENTS.md` for evidence, source tiers, word budgets, pause points, and output hygiene.
 - Load project skills from `.agents/skills/*` as needed.
 - Write all artifacts under `projects/<slug>/`.
 - Keep claims traceable to source IDs in `sources.jsonl`.
 ## Anti-Hallucination Contract
 This project treats Gemini-family research as high risk for false confidence. Follow these rules mechanically:
 1. No tool receipt, no search claim. Do not write "I searched", "confirmed", "official data shows", or similar unless the tool call happened and is recorded.
 2. No source ID, no factual claim. Every concrete fact needs a `source_id`.
 3. Search snippets are leads, not evidence. Open the original paper, filing, registry, patent, guideline, or company disclosure before citing.
 4. Failed access is a finding. Write that the source could not be opened; do not infer exact numbers from inaccessible pages.
 5. Log all searches in `phaseX/search_log.md` or `phaseX/search_log.jsonl`.
 6. Keep an `unsupported_claims` list. It is better to expose uncertainty than to make the report look complete.
 7. Before finishing each phase, sample at least 10 factual claims and verify that each has a source ID and opened source.
 ## Antigravity Model Plan
 Switch the Antigravity conversation model by phase:
 | Phase | Model | Purpose |
 |---|---|
 | Surface management | Gemini 3 Flash | Read skills, maintain task list, move phase by phase, run light shell commands, collect artifacts. |
 | Phase 0-1 | Claude Opus 4.6 (Thinking) | Material interpretation, strategic framing, research method choice, bold hypotheses, chapter architecture. |
 | Phase 2 | Gemini 3.1 Pro (Low) | Evidence collection, chapter research packets, first-pass chapter drafts. |
 | Phase 3 | Gemini 3.1 Pro (High) | Independent critique, counter-evidence review, logic and evidence gap analysis. |
 | Phase 4 | Claude Opus 4.6 (Thinking) | Final Chinese editorial integration, executive summary, wording quality, final consistency pass. |
 Gemini 3 Flash should remain the phase manager. It can ask the user to switch to the phase model before heavy thinking, then resume management after the phase artifact is written.
 ## Python Core Boundary
 Use Python core only when it helps without taking over the research model budget:
 - Good: scaffold folders, parse local materials, validate sources/citations, render PDF/DOCX, show status.
 - Risky: `research --execute-packets`, `run`, or any command that calls model workers through `configs/models.yaml`.
 - If a command would call model workers, ask the user first and state that it may use ZenMux/API credits instead of Antigravity quota.
 Safe utility examples:
 ```bash
 uv run python scripts/dr.py init "研究主题" --slug <slug> --method <method>
 uv run python scripts/dr.py status <slug>
 uv run python scripts/dr.py skills validate
 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`.
 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:
 - `phase1/material_brief.md`
 - `phase1/framework.md`
 - `phase1/research_brief.md`
 - `phase1/research_brief.json`
 - `phase1/search_log.md`
 - `phase1/unsupported_claims.md`
 5. Pause for user confirmation.
 6. Phase 2: ask the user to switch to Gemini 3.1 Pro (Low). Build evidence packets and chapter drafts without Python model workers:
 - `phase2/task_cards.json`
 - `phase2/packets/*.json`
 - `phase2/sources.jsonl`
 - `phase2/chapter_briefs/*.json`
 - `phase2/compressed_findings/*.json`
 - `phase2/drafts/chXX.md`
 - `phase2/search_log.jsonl`
 - `phase2/unsupported_claims.md`
 7. Phase 3: ask the user to switch to Gemini 3.1 Pro (High). Produce `phase3/critique.md`, with explicit go/rework/fail decision and a source-audit table for at least 10 core facts.
 8. Pause for user decision.
 9. Phase 4: ask the user to switch to Claude Opus 4.6 (Thinking). Produce `phase4/final_zh.md`, `phase4/editorial_notes.md`, and `phase4/final_fact_check.md`. Use deterministic renderers afterward for PDF/DOCX.
 ## Search Strategy
 If the `search` CLI from `paperfoot/search-cli` is installed, prefer it as the Antigravity-native search front door:
 ```bash
 search agent-info
 search search -q "CRISPR clinical trial 2025" -m academic --json
 search search -q "BRCA1 gene patent" -m patents --json
 search search -q "FDA warning letter CAPA pharmaceutical" -m general --json
 search search -q "biotech market update 2026" -m news --json
 ```
 Useful modes for this repo: `academic`, `scholar`, `patents`, `news`, `deep`, `extract`, `similar`, and `general`.
 Do not treat synthesized search answers as evidence. Every important claim still needs source IDs, tier rating, source score, and preferably original PDFs/pages or official records.
 If `search` is not installed, use the existing project search tools or Antigravity browser, but keep the same source-tier discipline.
 ## Suggested Antigravity Permissions
 Within this workspace, the user may allow:
 - `read_file(<workspace>)`
 - `write_file(<workspace>)`
 - `command(uv run python scripts/)`
 - `command(search)`
 - `command(pandoc)`
 Keep these as Ask/Deny unless the user explicitly allows them:
 - writes outside the workspace
 - global Antigravity/Gemini settings
 - destructive git commands
 - reading `secrets.env`
 - broad downloads or package installs
 ## What To Report Back
 Always report concrete artifact paths:
 - `projects/<slug>/phase1/research_brief.md`
 - `projects/<slug>/phase2/task_cards.json`
 - `projects/<slug>/phase2/packet_errors/` if present
 - `projects/<slug>/phase3/critique.md`
 - `projects/<slug>/phase4/*.pdf` and `*.docx`
 If a phase fails, report the failing artifact and the rework plan. Do not hide model switches, quota-sensitive steps, or missing evidence.
@@ -0,0 +1,55 @@
 # Deep Research Native Workflow
 Description: Run a biomedical Deep Research project in Antigravity using Antigravity model quota, with explicit anti-hallucination gates and source receipts.
 ## Step 0: Load Context
 - Load `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`.
 - Confirm topic, slug, report type, target audience, method, output length, and allowed search tools.
 Gate: do not proceed if the topic, slug, and report purpose are unclear.
 ## Step 1: Phase 0-1 With Opus
 - Ask the user to switch the conversation model to Claude Opus 4.6 (Thinking).
 - Create project folders under `projects/<slug>/`.
 - Read user materials and write `phase1/material_brief.md`.
 - Run real searches and log them in `phase1/search_log.md`.
 - Write `phase1/framework.md`, `phase1/research_brief.md`, and `phase1/research_brief.json`.
 - Write `phase1/unsupported_claims.md` for hypotheses not yet evidenced.
 Gate: pause for user confirmation. Do not enter Phase 2 before approval.
 ## Step 2: Phase 2 With Gemini 3.1 Pro Low
 - Ask the user to switch the conversation model to Gemini 3.1 Pro (Low).
 - Build `phase2/task_cards.json`.
 - For each task card, run real searches and append `phase2/search_log.jsonl`.
 - Write `phase2/packets/*.json`; every packet must contain `search_receipts`, `sources`, `counter_evidence`, and `unsupported_claims`.
 - Build `phase2/chapter_briefs/*.json` and `phase2/compressed_findings/*.json`.
 - Write `phase2/drafts/chXX.md` only from chapter briefs and compressed findings.
 Gate: do not draft a chapter from memory or snippets. Every concrete claim needs a source ID.
 ## Step 3: Phase 3 With Gemini 3.1 Pro High
 - Ask the user to switch the conversation model to Gemini 3.1 Pro (High).
 - Review framework, packets, sources, chapter briefs, and drafts.
 - Write `phase3/critique.md`.
 - Include a source-audit table for at least 10 core facts.
 - Mark decision as `go`, `rework`, or `fail`.
 Gate: pause for user decision after critique.
 ## Step 4: Phase 4 With Opus
 - Ask the user to switch the conversation model to Claude Opus 4.6 (Thinking).
 - Write `phase4/final_zh.md` from approved drafts and sources only.
 - Write `phase4/editorial_notes.md`.
 - Write `phase4/final_fact_check.md`, listing any unresolved or downgraded claims.
 - Use deterministic renderer tools afterward for PDF/DOCX.
 Gate: final output cannot introduce new facts without adding sources and search logs first.
@@ -18,6 +18,15 @@
 - 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 必须遵循）
@@ -37,6 +46,19 @@
 - **反方证据优先**：每个 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 字数配额（硬要求）
 | 报告类型 | 最小字数 | 建议章节数 |
@@ -67,6 +89,7 @@
 - **产出**：`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`
@@ -74,12 +97,14 @@
 - **产出**：`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>`
@@ -87,6 +112,7 @@
 - **默认链路**：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，再写入正文。
 ---
@@ -183,17 +209,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 | 打开仓库后由 Agent Manager 运行终端命令 | 要求 agent 运行 `uv run python scripts/dr.py ...` |
+| Antigravity | `.agents/rules` + `.agents/skills` + `.agents/workflows` | Gemini Flash 管流程，按 phase 切 Opus/Gemini，Python core 只做辅助 |
 跨平台硬规则：
- 平台只做 surface adapter，不承载核心调度。
+- 除 Antigravity native 模式外，平台只做 surface adapter，不承载核心调度。
 - 不在平台 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 评分。
 ---
@@ -210,12 +237,13 @@ 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、密钥读取和外部网络批量下载仍需用户明确批准。
 ---
 ## 9. 如何判断是否走了 Python Core
-不要用“平台是否 spawn subagent”作为成功标准。v0.20 的验证锚点是 Python runtime 产物：
+不要用“平台是否 spawn subagent”作为成功标准。Python-core 模式的验证锚点是 Python runtime 产物：
 1. `uv run python scripts/dr.py status <slug>` 能看到 phase 状态。
 2. Phase 2 存在 `phase2/task_cards.json`。
@@ -225,6 +253,15 @@ 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`，且终稿未引入无来源新事实。
 ---
 ## 10. 禁止事项（negative instructions）
@@ -235,10 +272,12 @@ uv run python scripts/dr.py methods list
 2. ❌ 在缺乏 2 个独立信源时仍给出绝对化结论
 3. ❌ 使用"据报道""有专家认为"等未指明来源的表述
 4. ❌ 编造或虚构数据、URL、DOI
-5. ❌ 写空洞的套话（"随着科技的发展""在大数据时代"）
+5. ❌ 声称"已搜索/已验证/官网显示"但没有工具回执和 search_log
-6. ❌ 忽略反方观点，只收集支持证据
+6. ❌ 用搜索摘要、AI summary、snippet 冒充原文证据
-7. ❌ 对输出字数"打折"（综述 <10000 字、研究 <30000 字必须返工）
+7. ❌ 写空洞的套话（"随着科技的发展""在大数据时代"）
-8. ❌ 在正文中使用未在术语表中定义的专业缩写（首次出现需全称+缩写）
+8. ❌ 忽略反方观点，只收集支持证据
 9. ❌ 对输出字数"打折"（综述 <10000 字、研究 <30000 字必须返工）
 10. ❌ 在正文中使用未在术语表中定义的专业缩写（首次出现需全称+缩写）
 ---
@@ -1,14 +1,30 @@
 # Gemini CLI Project Instructions
-This repository is Deep Research v0.20.
+This repository is Deep Research v0.20. Gemini must assume it is high-risk for hallucination and false confirmation in research tasks.
- Python core is the source of truth: `scripts/dr.py`, `scripts/runtime/**`, `configs/models.yaml`, `.agents/skills`.
+## Load Order
- Gemini CLI is a surface adapter. Do not perform core orchestration in the chat thread.
+
- Use `.gemini/commands/dr/*.toml` commands or run `uv run python scripts/dr.py ...` directly.
+- Treat `AGENTS.md` as the cross-platform rule source.
 - For Antigravity-native work, also follow `.agents/rules/deep-research-antigravity.md` and `.agents/skills/antigravity-surface-adapter/SKILL.md`.
 - Use `/memory show` or equivalent context inspection when behavior seems inconsistent.
 ## Non-Negotiable Research Integrity
 - Never claim "searched", "verified", "confirmed", "officially shows", or "according to source" unless a tool was actually executed in this session or current phase and the result is logged.
 - Every factual claim with a number, date, company, product, clinical phase, regulatory status, market size, patent status, or quote needs a `source_id`.
 - Search snippets, AI summaries, and model memory are discovery aids only. They are not evidence.
 - If you cannot open the original source, write "未能访问原文，仅作为发现线索" and do not extract exact values from it.
 - Maintain a phase search log: query, tool, timestamp, URL/title, selected/rejected status, and reason.
 - Prefer saying "未找到足够证据" over filling gaps.
 ## Platform Mode
 - Gemini CLI is normally a Python-core surface adapter. Use `.gemini/commands/dr/*.toml` or run `uv run python scripts/dr.py ...`.
 - Antigravity is the exception: it should use its own model quota and skills to execute research natively; Python scripts are auxiliary unless the user explicitly approves model-worker/API usage.
 - Keep formal research outputs Chinese-first. Search keywords, source titles, excerpts, DOI/URL and raw notes may remain English.
 - Do not modify `projects/**` unless the user is intentionally running a research project.
-Typical commands:
+## Typical Python-Core Commands
 ```bash
 uv run python scripts/dr.py run "研究主题" --slug <slug> --method mckinsey_market
@@ -1,7 +1,7 @@
 # Deep Research 系统方案（Python Core + 多平台 Adapter）
 > 本文件是整套方案的**单一真实源**，中断后续接时从此文件恢复上下文。
-> 最后更新：2026-05-05
+> 最后更新：2026-05-07
 > 实施阶段：v0.20 — Skill-driven Python core 重构
 ---
@@ -35,6 +35,7 @@
 | 交互节奏 | Phase 1 末、Phase 3 末强制确认 |
 | 并发执行 | Python task-card worker pool（平台 subagent 仅作可选表层能力） |
 | 中文字体 | **思源宋体 + 思源黑体 + 霞鹜文楷**，通过 `download-fonts.sh` 自动拉取 |
 | Antigravity 适配 | 使用 `.agents/rules` + `.agents/skills` 指导 Antigravity 原生执行 Deep Research；Gemini Flash 管流程，Opus/Gemini Pro 分 phase 执行，Python core 退为辅助工具 |
 ---
@@ -59,6 +60,19 @@
 **Cache 行为**：Claude 走 `@ai-sdk/anthropic` 会自动打 `cache_control` 断点，zenmux 的 Anthropic 端点完整支持 4 种 cache 模式。Opus 4.7 cache read 价格仅 0.5 USD/M tokens（对比输入价 25 USD/M，节省 98%）。验证方法见 `AGENTS.md` §6.5。
 ### 2.1 Antigravity 原生模型策略
 Antigravity 当前可选 models 包括 Gemini 3.1 Pro (High/Low)、Gemini 3 Flash、Claude Sonnet 4.6 (Thinking)、Claude Opus 4.6 (Thinking) 与 GPT-OSS 120B。Codex 使用经验显示，若 Antigravity 仍默认调用 Python core model workers，研究主流程容易回到 ZenMux，并且 packet/chapter assembly 有碎片化风险。因此 Antigravity 采用 native 模式：用 skill 指导 Antigravity 自身模型按 phase 写产物，Python core 只负责脚手架、确定性校验、引用和出稿。
 默认策略：
 - Surface manager：Gemini 3 Flash，负责读 skill、维护 task list、推进 phase、跑轻量命令和收集 artifact。
 - Phase 0-1：Claude Opus 4.6 (Thinking)，负责材料解读、研究方法选择、大胆假设、章节架构和成功标准。
 - Phase 2：Gemini 3.1 Pro (Low)，负责证据包、反方证据、chapter brief、初稿，优先追求速度和可控成本。
 - Phase 3：Gemini 3.1 Pro (High)，先做总编审校和证伪；若质量不足，再人工决定是否换模型复核。
 - Phase 4：Claude Opus 4.6 (Thinking)，负责最终中文统稿、Executive Summary、表达质量和交付一致性。
 - Python core 禁止默认接管 `run/research --execute-packets/assemble-chapters`；只有用户明确授权外部模型/API 消耗时才运行。
 ---
 ## 3. 完整架构
@@ -69,7 +83,7 @@ v0.20 后，核心编排从平台 prompt 迁移到项目自有 Python runtime：
 - `scripts/dr.py` 是稳定入口：`init`、`frame`、`run`、`research`、`review`、`finalize`、`skills`、`models`。
 - `scripts/runtime/*` 负责 role/task 模型解析、skill registry、task cards、packet schema、manifest 更新。
- `.agents/skills` 是 canonical skill registry；`.opencode/skills` 等 adapter 目录由 `dr.py skills sync` 生成。
+- `.agents/skills` 是 canonical skill registry，也是 Antigravity 默认 workspace skill 目录；`.opencode/skills` 等 adapter 目录由 `dr.py skills sync` 生成。
 - OpenCode/Codex/Claude Code 只作为 surface adapter，调用 Python CLI，不再承载默认并发调度。
 - Phase 2 默认生成 `phase2/task_cards.json` 与 `phase2/packets/*.json`，减少长上下文传递。
 - Phase 2 在正式写章前生成 `phase2/chapter_briefs/*.json`，先把并发证据收束为章节主线，降低碎片化。
@@ -78,6 +92,7 @@ v0.20 后，核心编排从平台 prompt 迁移到项目自有 Python runtime：
 - Phase 4 默认中文原生：`final_zh.md -> build_report`，legacy 英译中链路仅由 `--legacy-translate` 显式启用。
 - Phase 1 必须选择 `research_method`，由 `configs/research_methods.yaml` 决定框架方法和 Phase 2 task axes；MECE 不再是唯一默认。
 - 用户提供资料入口已支持 `input_materials` / `phase0/inputs` / `phase0/extracted`；PDF 文本抽取与 FireRed OCR 扫描件识别已先行落地，DOCX/PPTX/表格结构化继续放入 v0.21。
 - Antigravity 入口已落地：`.agents/rules/deep-research-antigravity.md` 约束其优先使用 Antigravity 模型配额，`.agents/skills/antigravity-surface-adapter` 提供 native runbook、模型切换和搜索策略。
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -715,3 +730,33 @@ OpenCode 的坑：如果只是在主会话里装样子地写"让 X agent 做"，
  - `scripts/runtime/tasks.py` 把 `evidence` 纳入合法 search route，并更新主要 task axes 的默认路由。
  - `scripts/runtime/workers.py` 的 `ProjectSearchProvider` 支持 `evidence` route。
  - `skills/search-gateway`、`skills/search-strategy`、`docs/search-playbook.md`、`README.md`、`AGENTS.md` 同步记录搜索分工，避免后续又回到 Tavily MCP 或中文长句搜索。
 - 2026-05-07 v0.20.1 Antigravity native adapter：**用 Antigravity 模型配额执行研究**
  **设计结论**：
  - Antigravity 官方机制以 `.agents/skills`、`.agents/rules`、Rules/Workflows、Task Groups 和 browser subagent 为核心；本项目在 Antigravity 中采用 skill-driven native research，而不是默认调用 Python core model workers。
  - `AGENTS.md` 继续作为跨平台总规则；Antigravity 专项约束放到 workspace rule 和 skill，避免引入非官方 SOUL.md 作为项目真源。
  - Opus 额度有限但大局观强，优先用于 Phase 0-1 和 Phase 4；Gemini 3 Flash 做流程管理，Gemini 3.1 Pro Low/High 分别用于 Phase 2/3。
  - `paperfoot/search-cli` 可作为 Antigravity 原生检索前台：多 provider、14 modes、JSON/exit code 友好；但不得替代本项目 source tier 与 source-quality 评分。
  **已落地**：
  - 新增 `.agents/skills/antigravity-surface-adapter/SKILL.md`，定义 Antigravity native runbook、pause points、artifact 汇报、模型切换表和 `search-cli` 使用建议。
  - 新增 `.agents/rules/deep-research-antigravity.md`，要求 Antigravity 优先使用自身模型配额，Python core 只做脚手架、确定性校验、引用和出稿。
  - 撤回 `configs/models.yaml` 中 Antigravity 专用 ZenMux profile，避免误导主流程继续走 Python/ZenMux。
  - `docs/platform-adapters.md`、`README.md`、测试用例同步更新。
 - 2026-05-07 v0.20.2 Antigravity/Gemini research integrity hardening：**反幻觉、反假搜索、workflow gates**
  **设计结论**：
  - Gemini/Gemini CLI/Antigravity 在 deep research 中必须默认视为高幻觉风险模型；项目规则要把"诚实暴露不确定性"写成硬门槛，而不是依赖模型自觉。
  - `GEMINI.md` 适合放短而硬的项目级行为约束，并通过层级 context 与 imports 承接 `AGENTS.md`。
  - Antigravity `rules` 适合放 Always-On 约束；`workflows` 适合固化 Phase 0-4 执行顺序、人工暂停点和质量 gates。
  - Claude/Claude Code 最佳实践可借鉴：根指令要短、具体、可执行，长流程拆到 rules/skills/workflows，避免巨型上下文降低遵从性。
  **已落地**：
  - `AGENTS.md` 新增 Antigravity native 例外、检索回执、source_id、search_log、unsupported_claims 等反幻觉硬规则。
  - `GEMINI.md` 重写为短约束：禁止假搜索、禁止无 source_id 事实、要求 search log，并区分 Gemini CLI 与 Antigravity native。
  - `.agents/rules/deep-research-antigravity.md` 加入 Anti-Hallucination Contract。
  - `.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` 才备份覆盖。
@@ -95,13 +95,13 @@ uv run python scripts/build_report.py <slug> --engine quarto    # Quarto/xelatex
 ### 多平台兼容
-v0.20 后，所有平台都是 surface adapter，核心调度只在 Python core 中执行。详细调用方式见 `docs/platform-adapters.md`。
+v0.20 后，OpenCode/Codex/Claude Code/Gemini CLI 都是 Python core 的 surface adapter。Antigravity 走 native 模式：用 `.agents/skills` 指导其自身模型按 phase 执行研究，Python core 只做辅助。详细调用方式见 `docs/platform-adapters.md`。
 - OpenCode：使用 `.opencode/commands/*.md` 薄封装 Python CLI。
 - Codex：使用 `AGENTS.md` + 部署到 `$CODEX_HOME` 的 adapter 文件，优先用 GPT 系列做代码/测试/审阅。
 - Claude Code：使用 `.claude/skills/*/SKILL.md`，优先用 Opus/Sonnet 做访谈、结构讨论和中文风格审阅。
 - Gemini CLI：使用 `GEMINI.md` 与 `.gemini/commands/dr/*.toml`，优先用 Gemini 做长上下文、多模态和替代框架审阅。
- Antigravity：作为 Agent Manager 打开仓库，要求 agent 在终端运行 `uv run python scripts/dr.py ...`。
+- Antigravity：作为 Agent Manager 打开仓库，使用 `.agents/rules` + `.agents/skills` 指导其用 Antigravity 模型配额原生执行 Deep Research；Python core 只做脚手架、校验、引用和出稿辅助。
 部署 Codex adapter（不在仓库内创建 `.codex`）：
@@ -113,6 +113,15 @@ Codex adapter 会写到 `$CODEX_HOME` 或 `~/.codex`；已有文件会在 `--for
 安全默认：部署脚本不会复制 `config.toml`，避免覆盖用户级 Codex 配置。只有明确需要安装本项目 bundled profile 时，才使用 `--include-config`。
 部署 Antigravity workspace adapter（只写目标工作区 `.agents/`，默认不覆盖已有文件）：
 ```bash
 uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace --dry-run
 uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 ```
 Antigravity 部署不会修改全局设置。若目标工作区已有同名 rule/skill/workflow 文件，默认跳过；只有显式加 `--force` 时才会先生成 `.bak` 备份再覆盖。
 部署到新环境后自检：
 ```bash
@@ -135,7 +144,7 @@ uv run python scripts/dr.py review <slug>
 uv run python scripts/dr.py finalize <slug>
 ```
-OpenCode/Codex/Claude Code/Antigravity/Gemini CLI adapter 只包装这些 CLI，不再承担核心调度或模型选择。
+OpenCode/Codex/Claude Code/Gemini CLI adapter 只包装这些 CLI，不再承担核心调度或模型选择。Antigravity 是例外：它优先按 `.agents/skills/antigravity-surface-adapter` 用自身模型配额执行研究，避免主流程重新落回 ZenMux。
 模型与搜索 API 选择见：
 - `docs/model-playbook.md`
@@ -177,7 +186,7 @@ uv run python scripts/search.py "FDA warning letter CAPA deviation change contro
 uv run python scripts/search.py "dual-target siRNA GalNAc" --route patents
 ```
-v0.20 搜索分工：`evidence` 用 Exa highlights 做受控候选证据发现；`scholar/patents/news/fda` 保留专用路由；`general` 只做宽泛发现和兜底；Tavily Research 作为 Phase1 初扫、薄弱章节补证据和 Phase3 回炉工具，结果必须存盘、评分、去重后再进入 evidence packet。
+v0.20 搜索分工：`evidence` 用 Exa highlights 做受控候选证据发现；`scholar/patents/news/fda` 保留专用路由；`general` 只做宽泛发现和兜底；Tavily Research 作为 Phase1 初扫、薄弱章节补证据和 Phase3 回炉工具，结果必须存盘、评分、去重后再进入 evidence packet。Antigravity 原生流程可优先使用 `paperfoot/search-cli` 的 `search` 命令作为统一检索前台，但所有结论仍必须回到本项目 Tier/source-quality 体系。
 ---
@@ -344,7 +353,7 @@ Opus 4.7 cache 读取价格 0.5 USD/M tokens（对比输入 25 USD/M，节省 98
 ### 系统侧（下一阶段）
 - [x] Python core `init/frame/research/review/finalize/status` 骨架
 - [x] OpenCode/Codex/Claude Code/Gemini CLI wrapper
- [ ] Antigravity 专用工作流模板（等待官方本地配置格式稳定）
+- [x] Antigravity 专用 workspace rule + skill，按 Antigravity 模型配额原生执行研究
 - [x] 用户资料导入基础能力：PDF 文本抽取 + FireRed OCR 扫描件识别 + phase0 落盘
 - [ ] 用户资料导入增强：DOCX / PPTX / 表格抽取 / 版面结构化
 - [ ] PDF reporting 包继续拆分：字体、宽表、引用、渲染验证
@@ -499,5 +508,6 @@ direnv allow
 - **v0.3** (2026-04-20) — 修正 v0.2 模型名（回到 Opus 4.7 / Sonnet 4.6 / Gemini 3.1 Pro / GPT-5.4 Pro 等真实 slug）；改 venv + requirements.txt 跨平台方案（macOS + Debian）；新增 `scripts/setup.sh`、`scripts/activate.sh`
 - **v0.13** (2026-05-02) — `build_report.py` 新增 `--engine quarto` 选项：Quarto 1.9 + xelatex 引擎，解决 ReportLab 超宽表格渲染 bug（`negative availWidth`/`NoneType` 问题）；`report-template.py` 同步修复（`render_table_blocks` 分块 + 等宽列强制分配）；README 补充双引擎安装指南与排错
 - **v0.20** (2026-05-05) — Skill-driven Python core 重构启动：新增 `scripts/runtime/*`、`scripts/dr.py init/frame/run/research/review/skills`、task-type 模型映射、中文原生 finalize 默认路径和 `scripts/reporting/*` 报告模块；OpenCode/Codex/Claude Code/Gemini CLI 命令降级为 Python CLI wrapper。
 - **v0.20.1** (2026-05-07) — Antigravity-native adapter：新增 `.agents/rules/deep-research-antigravity.md`、`.agents/skills/antigravity-surface-adapter`，按 Gemini Flash 管理、Opus/Gemini 分 phase 执行研究；Python core 退为辅助工具。
 见 `PLAN.md` §12 了解完整变更历史。
@@ -1,10 +1,10 @@
 # v0.20 Platform Adapters
-> v0.20 的唯一核心入口是 Python core：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml`、`.agents/skills`。所有 IDE/CLI agent 只做 surface adapter。
+> v0.20 的默认核心入口是 Python core：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml`、`.agents/skills`。Antigravity 例外：它使用 `.agents/skills` 与 `.agents/rules` 走 native Deep Research，让 Antigravity 模型配额承担主要研究工作。
 ## Shared Rule
-不要让平台 agent 自己调度 Phase 2 并发、模型选择或上下文压缩。平台只负责：
+除 Antigravity native 模式外，不要让平台 agent 自己调度 Phase 2 并发、模型选择或上下文压缩。默认平台只负责：
 - 运行 `uv run python scripts/dr.py ...`
 - 展示产物路径与失败包
@@ -24,6 +24,8 @@ uv run python scripts/dr.py review <slug>
 uv run python scripts/dr.py finalize <slug>
 ```
 Antigravity 不走这条最小链路作为默认研究主流程；详见下方 Antigravity 章节。
 ## OpenCode
 官方机制：OpenCode 支持 `.opencode/commands/*.md` 自定义命令；文件名就是 slash command，内容是 prompt，frontmatter 可指定 `agent`、`model`、`subtask`。OpenCode 也支持 primary/subagent 两类 agent，但 v0.20 不再把平台 subagent 当默认并发机制。
@@ -128,26 +130,55 @@ gemini
 ## Antigravity
-官方公开资料把 Antigravity 定位为 agent-first IDE：agent 可访问 editor、terminal、browser，并可并行规划、执行、验证。它适合把开发者提升为 Agent Manager，但不适合让每个 Antigravity agent 自己维护 Deep Research 的状态机。
+官方资料显示，Antigravity 是 agent-first IDE：主 Agent 可跨 editor、terminal、browser 工作；浏览器操作由 browser subagent 执行；Agent Manager 可管理多个任务流和 artifacts。基于 Codex 的 skill-driven 经验，本项目在 Antigravity 中不再默认把研究主流程交给 Python model workers，而是让 Antigravity 用自己的模型配额按 phase 执行研究。
 本项目已提供 Antigravity 入口：
 - `.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。
 - `.agents/skills/*`：Antigravity 官方默认 skill 目录，直接复用本项目 canonical skill registry。
 部署到另一个 Antigravity workspace：
 ```bash
 uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace --dry-run
 uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
 ```
 该命令只写 workspace-local `.agents/skills`、`.agents/rules` 和 `.agents/workflows`，不修改全局 Antigravity/Gemini 设置；已有文件默认跳过，`--force` 才会备份为 `.bak` 后覆盖。
 本项目调用方式：
 1. 在 Antigravity 打开仓库根目录。
-2. 确认 agent 能读 `AGENTS.md`。
+2. 在 Customizations / Rules 中确认 workspace rule 已启用；若未自动启用，手动 at mention `deep-research-antigravity` 或直接引用该文件。
-3. 给 Agent Manager 一个明确任务：
+3. 选择模型：
 | Phase / 工作 | Antigravity model | 用法 |
 |---|---|---|
 | Surface 管理、读 skill、状态推进 | Gemini 3 Flash | 管任务清单、跑轻量命令、收集 artifact |
 | Phase 0-1 材料解读、框架规划 | Claude Opus 4.6 (Thinking) | 大局观、研究假设、章节结构 |
 | Phase 2 证据包与章节草稿 | Gemini 3.1 Pro (Low) | 质量/速度均衡，按 skill 写 artifacts |
 | Phase 3 总编审校 | Gemini 3.1 Pro (High) | 先试高强度 Gemini，不行再换 |
 | Phase 4 最终统稿 | Claude Opus 4.6 (Thinking) | 保证中文终稿和交付质量 |
 4. 给 Agent Manager 一个明确任务：
 ```text
-请只作为 surface adapter，不要自行调度研究 agent。
+请加载 .agents/skills/antigravity-surface-adapter/SKILL.md 和 AGENTS.md。
-在终端运行：
+用 Gemini 3 Flash 做流程管理，按 skill 要求在需要时提示我切换模型。
-uv run python scripts/dr.py run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market
+研究主题："ADC 全球竞争格局"，slug: adc-global-landscape，method: mckinsey_market。
-然后汇报生成的项目目录、framework 路径和下一步命令。
+请先创建/确认项目目录，然后进入 Phase 0-1，并在生成 phase1/framework.md 和 research_brief 后暂停。
 ```
 使用建议：
 - Antigravity 的 Gemini/Opus/Gemini Computer Use/Browser 能力适合可视化 QA、PDF/HTML 预览、跨文件审阅。
- 如果 Antigravity 提供 Opus 和 Gemini 模型，优先用它们做“表层审阅/交互”，不要替代 Python core 的 role/task 模型。
+- Opus 额度有限，但 Phase 0-1 和 Phase 4 的价值最高，优先花在框架和终稿，不花在 routine 管理。
- 对高成本/长任务，要求 Antigravity 先 dry-run，再运行真实 `--execute-packets`。
+- 不要默认运行 `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` 三层约束即可。
 ## Model Strategy Across Platforms
@@ -157,9 +188,9 @@ uv run python scripts/dr.py run "ADC 全球竞争格局" --slug adc-global-lands
 | Codex | GPT 系列用于代码、测试、schema、review | `configs/models.yaml` |
 | Claude Code | Opus/Sonnet 用于访谈、中文风格、结构讨论 | `configs/models.yaml` |
 | Gemini CLI | Gemini 用于长上下文、多模态、框架审阅 | `configs/models.yaml` |
-| Antigravity | Gemini/Opus 用于 IDE agent、browser/PDF QA | `configs/models.yaml` |
+| Antigravity | Gemini Flash/Opus/Gemini Pro 分 phase 执行研究 | `.agents/skills` + Antigravity model selector |
-核心原则：平台模型负责“怎么帮用户操作项目”，ZenMux/Python role 模型负责“研究任务用哪个模型执行”。
+核心原则：除 Antigravity 外，平台模型负责“怎么帮用户操作项目”，ZenMux/Python role 模型负责“研究任务用哪个模型执行”。Antigravity 专门走 native 模式，以消耗 Antigravity 自身模型配额并降低 Python-core 碎片化风险。
 ## Sources
@@ -168,3 +199,14 @@ uv run python scripts/dr.py run "ADC 全球竞争格局" --slug adc-global-lands
 - Claude Code skills/slash commands: https://code.claude.com/docs/en/slash-commands
 - Gemini CLI custom commands: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md
 - Google Antigravity announcement: https://blog.google/products-and-platforms/products/gemini/gemini-3/
 - Google Antigravity rules/workflows: https://antigravity.google/docs/rules-workflows
 - Google Antigravity skills: https://antigravity.google/docs/skills
 - Google Antigravity models: https://antigravity.google/docs/models
 - Google Antigravity permissions: https://antigravity.google/docs/agent-permissions
 - paperfoot/search-cli skill: https://github.com/paperfoot/search-cli/blob/master/SKILL.md
 - Gemini CLI GEMINI.md context: https://geminicli.com/docs/cli/gemini-md/
 - Gemini CLI GEMINI.md examples issue: https://github.com/google-gemini/gemini-cli/issues/9241
 - Practical GEMINI.md hierarchy: https://medium.com/google-cloud/practical-gemini-cli-instruction-following-gemini-md-hierarchy-part-1-3ba241ac5496
 - Claude Code best-practice CLAUDE.md: https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md
 - Claude MD guide: https://github.com/MuhammadUsmanGM/claude-code-best-practices/blob/main/guides/claude-md-guide.md
 - Writing a good CLAUDE.md: https://www.humanlayer.dev/blog/writing-a-good-claude-md
@@ -18,6 +18,8 @@ if str(REPO_ROOT) not in sys.path:
 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"
@dataclass
@@ -105,6 +107,30 @@ def copy_registered_skills(dst: Path, *, force: bool, dry_run: bool = False) ->
    return result
 def copy_antigravity_rules(dst: Path, *, force: bool, dry_run: bool = False) -> DeployResult:
    result = DeployResult(platform="rules", target=dst)
    if not ANTIGRAVITY_RULES_DIR.exists():
        return result
    part = copy_tree_contents(ANTIGRAVITY_RULES_DIR, dst, force=force, dry_run=dry_run)
    result.written.extend(part.written)
    result.skipped.extend(part.skipped)
    result.planned.extend(part.planned)
    result.backups.extend(part.backups)
    return result
 def copy_antigravity_workflows(dst: Path, *, force: bool, dry_run: bool = False) -> DeployResult:
    result = DeployResult(platform="workflows", target=dst)
    if not ANTIGRAVITY_WORKFLOWS_DIR.exists():
        return result
    part = copy_tree_contents(ANTIGRAVITY_WORKFLOWS_DIR, dst, force=force, dry_run=dry_run)
    result.written.extend(part.written)
    result.skipped.extend(part.skipped)
    result.planned.extend(part.planned)
    result.backups.extend(part.backups)
    return result
 def deploy_codex(
    *,
    target: Path | None = None,
@@ -131,6 +157,33 @@ def deploy_codex(
    return _merge_results("codex", codex_home, parts)
 def deploy_antigravity(
    *,
    target: Path | None = None,
    force: bool = False,
    skip_skills: bool = False,
    skip_rules: bool = False,
    skip_workflows: bool = False,
    dry_run: bool = False,
    repo_root: Path = REPO_ROOT,
 ) -> DeployResult:
    """Deploy Antigravity workspace rules and skills into a workspace root.
    This intentionally deploys to a workspace-local `.agents` directory, not
    global Antigravity/Gemini settings, so existing user configuration is not
    touched. Existing files are skipped unless `force=True`.
    """
    workspace = (target or repo_root).expanduser()
    parts: list[DeployResult] = []
    if not skip_skills:
        parts.append(copy_registered_skills(workspace / ".agents" / "skills", force=force, dry_run=dry_run))
    if not skip_rules:
        parts.append(copy_antigravity_rules(workspace / ".agents" / "rules", force=force, dry_run=dry_run))
    if not skip_workflows:
        parts.append(copy_antigravity_workflows(workspace / ".agents" / "workflows", force=force, dry_run=dry_run))
    return _merge_results("antigravity", workspace, parts)
 def print_result(result: DeployResult) -> None:
    action = "planned" if result.planned and not result.written else "written"
    print(f"{result.platform} adapter deployment")
@@ -156,6 +209,14 @@ def build_parser() -> argparse.ArgumentParser:
    codex.add_argument("--skip-skills", action="store_true", help="do not copy canonical skills into target/skills")
    codex.add_argument("--include-config", action="store_true", help="also copy config.toml; off by default to avoid overwriting global Codex config")
    codex.add_argument("--dry-run", action="store_true", help="show files that would be written")
    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-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")
    antigravity.add_argument("--dry-run", action="store_true", help="show files that would be written without writing")
    return parser
@@ -178,6 +239,23 @@ def main() -> int:
            print("  codex")
            print("Note: config.toml is not copied by default. Use --include-config only if you want the bundled profile.")
        return 0
    if args.platform == "antigravity":
        result = deploy_antigravity(
            target=args.target,
            force=args.force,
            skip_skills=args.skip_skills,
            skip_rules=args.skip_rules,
            skip_workflows=args.skip_workflows,
            dry_run=args.dry_run,
        )
        print_result(result)
        print()
        print("Open the target workspace in Antigravity and enable/mention the workspace rule if needed:")
        print("  .agents/rules/deep-research-antigravity.md")
        print("Workflow installed when supported by your Antigravity build:")
        print("  .agents/workflows/deep-research-native.md")
        print("Existing files are skipped by default. Use --force only when you want .bak backups and replacement.")
        return 0
    raise SystemExit(f"unsupported platform: {args.platform}")
@@ -7,7 +7,7 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
 if str(REPO_ROOT) not in sys.path:
    sys.path.insert(0, str(REPO_ROOT))
-from scripts.deploy_adapters import default_codex_home, deploy_codex
+from scripts.deploy_adapters import default_codex_home, deploy_antigravity, deploy_codex
 def test_default_codex_home_is_external_to_project(tmp_path: Path) -> None:
@@ -49,3 +49,42 @@ def test_deploy_codex_dry_run_does_not_write(tmp_path: Path) -> None:
    assert result.planned
    assert not target.exists()
 def test_deploy_antigravity_writes_workspace_rules_and_skills(tmp_path: Path) -> None:
    target = tmp_path / "workspace"
    result = deploy_antigravity(target=target, repo_root=REPO_ROOT)
    assert result.written
    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()
    assert (target / ".agents" / "skills" / "search-strategy" / "SKILL.md").exists()
    assert result.target == target
 def test_deploy_antigravity_skips_existing_files_by_default(tmp_path: Path) -> None:
    target = tmp_path / "workspace"
    existing = target / ".agents" / "rules" / "deep-research-antigravity.md"
    existing.parent.mkdir(parents=True)
    existing.write_text("custom rule\n", encoding="utf-8")
    result = deploy_antigravity(target=target, repo_root=REPO_ROOT)
    assert existing.read_text(encoding="utf-8") == "custom rule\n"
    assert existing in result.skipped
    assert not existing.with_name("deep-research-antigravity.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"
    existing.parent.mkdir(parents=True)
    existing.write_text("custom rule\n", encoding="utf-8")
    result = deploy_antigravity(target=target, repo_root=REPO_ROOT, force=True)
    assert existing.read_text(encoding="utf-8") != "custom rule\n"
    assert existing.with_name("deep-research-antigravity.md.bak").read_text(encoding="utf-8") == "custom rule\n"
    assert existing.with_name("deep-research-antigravity.md.bak") in result.backups
@@ -35,6 +35,7 @@ def test_skill_registry_uses_agents_skills_as_canonical() -> None:
    assert "source-quality" in names
    assert "document-ingest" in names
    assert "deep-research" in names
    assert "antigravity-surface-adapter" in names
    assert registry.validate()["ok"] is True