feat(cli): add Antigravity CLI as a flat host for skills

.github/workflows/ci.yml

@@ -154,7 +154,7 @@ jobs:
       contents: write
     strategy:
       fail-fast: false
-      # Four marketplace plus six flat — opencode and kilo are flat-only. Mirrors the CLI golden
+      # Four marketplace plus seven flat — opencode, kilo and antigravity are flat-only. Mirrors the CLI golden
       # snapshot matrix.
       matrix:
         include:
@@ -168,6 +168,7 @@ jobs:
           - { tool: codex, mode: flat }
           - { tool: opencode, mode: flat }
           - { tool: kilo, mode: flat }
+          - { tool: antigravity, mode: flat }
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 

aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/backlog-link.json

@@ -0,0 +1,5 @@
+{
+  "backlog": "ai-driven-dev/framework#511",
+  "written_at": "2026-10-02T16:30:00Z",
+  "written_by": "aidd-dev:01-plan"
+}

aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-2.md

@@ -0,0 +1,117 @@
+---
+status: done
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: `antigravity` profile with skills, registered everywhere, golden cell
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+cli/
+├── src/kernel/tool.ts                                       ✏️ AiToolId union and AI_TOOL_IDS
+├── src/contexts/framework/application/framework/translator/built-tree-materialization-translator.ts  ✏️ recognise a skill at the profile's declared flat layout, not only `skills/<plugin>/…`
+├── src/contexts/tools/domain/profiles/antigravity/
+│   ├── antigravity-paths.ts                                 ✅ `.agents/` directory and skills dir constants
+│   ├── profile.ts                                           ✅ AiTool<HasSkills & HasPlugins>, flat plugins, no hooks yet, registerTool
+│   └── build.ts                                             ✅ flat contract: skills only, agents/hooks/mcp/rules/commands unsupported
+├── src/runtime/wiring/{tools,framework,translate}.ts        ✏️ side-effect profile import
+├── src/runtime/assets/asset-loader.ts                       ✏️ CONFIG_ASSETS entry (Record<ToolId,…>)
+├── src/presentation/commands/translate.ts                   ✏️ `--to` help string
+├── src/presentation/prompts/menu-use-case.ts                ✏️ example strings
+├── scripts/smoke-tools.sh                                   ✏️ AI_TOOLS
+├── scripts/check-bundle-size.mjs                            ✏️ only if the budget breaks, with a registry line
+├── mutation-scopes.json, package.json                       ✏️ `tools-antigravity` scope and script
+├── tests/architecture/tool-addition-cost.arch.test.ts       ✏️ BASELINE counts +1 for the files above
+├── tests/contexts/tools/domain/profiles/antigravity/
+│   ├── profile.unit.test.ts                                 ✅ paths, capabilities, telemetry reason
+│   └── build.unit.test.ts                                   ✅ skill paths, link rewriting
+├── tests/golden/framework-build-golden.e2e.test.ts          ✏️ FLAT_TARGETS + cell count
+├── tests/golden/snapshots/framework-build/golden.json       ✏️ new `antigravity:flat` cell only
+├── tests/golden/snapshots/{help/surface,phase0/snapshot}.json, tests/fixtures/cli-owns-read/expected-envelope.json  ✏️ regenerated
+└── tests/** enumerating tool ids (tool-config, registry-conformance, build-hooks-support-declaration, asset-loader, interactive-menu, translate-wiring, uninstall-use-case, build-unit-deps, telemetry-route-supply, plugin-root-token-declaration, metrics-contract, cost-report-envelope, tool-attribution, host-marketplace-registry-reader-adapter)  ✏️
+.github/workflows/ci.yml                                     ✏️ `{ tool: antigravity, mode: flat }` row, comment count
+scripts/__tests__/smoke-real-user-scope-tool-list-parity.test.js   ✏️ flat-only list
+docs/MAINTAINERS.md                                          ✏️ archive count
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[aidd setup --ai antigravity] --> B[skills written to .agents/skills/aidd-*/SKILL.md]
+  B --> C[manifest records them under antigravity]
+  D[aidd translate src --to antigravity --as flat] --> E[same .agents/skills tree in --out]
+  C --> F[aidd clean antigravity removes only its recorded files]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    fixture framework source with one plugin skill => source ready: 5: system
+  section Happy path
+    aidd translate fixture --to antigravity --as flat => .agents/skills/<plugin>-<skill>/SKILL.md written: 5: cli
+    aidd setup --ai antigravity => skills under .agents/skills recorded in manifest: 5: cli
+    golden e2e => antigravity:flat cell matches, other cells unchanged: 5: cli
+  section Edge case - foreign file
+    user file .agents/skills/mine/SKILL.md => clean antigravity => file untouched: 5: cli
+  section Teardown
+    remove temp project => baseline restored: 5: system
+```
+
+## Tasks to do
+
+### `1)` Profile, paths and flat contract
+
+> Skills only; every other artifact `supported: false` until its phase.
+
+1. `antigravity-paths.ts`: `ANTIGRAVITY_DIRECTORY = ".agents/"`, skills dir.
+2. `build.ts`: skills `fullTree`, `rewriteSkillName: true`, path `.agents/skills/<plugin>-<skill>/<rest>`, one directory level (same shape as Codex flat). Measured 2026-10-05 on `agy` 1.2.14: `.agents/skills/flat-probe/SKILL.md` logs `expanded slash command "flat-probe" (skill)`; `.agents/skills/aidd-probe/nested-probe/SKILL.md` logs no expansion. Never `<plugin>/<skill>/`.
+3. Install side: setup reads the built flat tree back through `belongsToPlugin` in `built-tree-materialization-translator.ts`, which accepts only `skills/<plugin>/…` and so installs 0 files from the one-level layout. Let the profile declare its flat skill layout and have the materializer recognise it; test first (red: setup installs 0 skills), keep every existing tool's behaviour unchanged.
+4. `profile.ts`: `SkillsCapability` on `.agents/skills/`, `PluginsCapability` `mode: "flat"`, `acceptsHooks: false` with a reason pointing to phase 3; `telemetryLocalRead` unsupported with the canonical reason string `registry-conformance` expects; no `distributionProbes.marketplace`.
+5. Unit tests first: profile and build, red then green.
+
+### `2)` Register the id everywhere the arch test demands
+
+> Kilo review lesson: a static id is not a runtime registration.
+
+1. `tool.ts`, three wiring files, asset loader, translate help, menu strings.
+2. Raise each `tool-addition-cost` BASELINE count by one; nothing else in that file.
+3. Update every test enumeration listed in the projection; regenerate help and phase0 snapshots and the cli-owns-read envelope.
+
+### `3)` Golden cell and CI matrix
+
+> Only the new cell may move.
+
+1. Add `antigravity` to `FLAT_TARGETS`, update the cell-count title, run with `UPDATE_FRAMEWORK_GOLDEN=1`.
+2. `git diff` the golden file: every changed key is `antigravity:flat`.
+3. `ci.yml` matrix row, `MAINTAINERS.md` archive count, root parity test list, `smoke-tools.sh`, mutation scope and script.
+
+### `4)` Ownership under a shared `.agents/`
+
+> The Codex-shared case is a known bug outside #511; prove only that AIDD never touches a foreign file.
+
+1. Integration test: setup antigravity, add a user file under `.agents/skills/`, clean antigravity, user file intact.
+
+### `5)` Full suite and size
+
+1. `cd cli && pnpm test`, `pnpm exec lefthook run pre-commit`, bundle size check; raise the budget only with a registry line.
+2. Diff size: if over 600 lines, move task 4 or the test-enumeration edits that are pure lists into a follow-up commit, never the golden cell.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | `translate --to antigravity --as flat` writes `.agents/skills/<plugin>-<skill>/SKILL.md`, one level deep, and no other artifact; `aidd setup --ai antigravity` installs the same skills; no other tool's setup output changes |
+| 2 | `aidd setup --ai antigravity` succeeds, `aidd --help` and the menu list it, the arch tests pass |
+| 3 | `golden.json` gains exactly one key, `antigravity:flat`; no existing cell changes; `ci.yml` builds the new archive |
+| 4 | Cleaning Antigravity leaves a user file under `.agents/` in place |
+| 5 | The full CLI suite and pre-commit pass on the branch |

aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-3.md

@@ -0,0 +1,90 @@
+---
+status: pending
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: Memory hook in `.agents/hooks.json`
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+cli/
+├── src/contexts/tools/domain/profiles/antigravity/
+│   ├── antigravity-hooks.ts      ✅ named-hook shape: merge AIDD's `aidd-memory` key into `.agents/hooks.json`, strip it on uninstall, convert Claude-shaped flat hooks
+│   ├── profile.ts                ✏️ HooksCapability on `.agents/hooks.json`
+│   └── build.ts                  ✏️ hooks artifact: scripts under `.agents/hooks/<plugin>/`, hooksMerge into `.agents/hooks.json`
+├── tests/contexts/tools/domain/profiles/antigravity/
+│   └── antigravity-hooks.unit.test.ts   ✅ merge, idempotence, foreign keys kept, invalid JSON, strip
+├── tests/contexts/tools/domain/build-hooks-support-declaration.unit.test.ts   ✏️ antigravity now supports hooks
+└── tests/golden/snapshots/framework-build/golden.json   ✏️ `antigravity:flat` cell only
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[aidd setup --ai antigravity] --> B[.agents/hooks.json gains key aidd-memory with SessionStart command]
+  B --> C[agy new session in trusted folder]
+  C --> D[log: loaded N named hooks; memory refresh runs at repo root]
+  E[aidd clean antigravity] --> F[aidd-memory key removed, other named hooks kept, file deleted only if empty]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    agy 1.2.14 logged in, probe hook printing cwd and workspacePaths => measured cwd recorded: 5: system
+  section Happy path
+    aidd setup --ai antigravity on empty project => .agents/hooks.json has aidd-memory SessionStart entry: 5: cli
+    second setup => file byte-identical: 5: cli
+    translate --to antigravity --as flat => same hooks.json shape and scripts under .agents/hooks/: 5: cli
+  section Edge case - user hooks present
+    .agents/hooks.json with user key lint => setup then clean => lint key unchanged: 5: cli
+  section Edge case - invalid JSON
+    unparsable .agents/hooks.json => setup => error names the file, file untouched: 1: cli
+  section Teardown
+    remove temp project => baseline restored: 5: system
+```
+
+## Tasks to do
+
+### `1)` Measure the hook `cwd` on 1.2.14
+
+> #890 measured `cwd = <repo>/.agents` on 1.2.5; `update_memory.js` silently no-ops when `aidd_docs/` is not in `cwd`.
+
+1. Local probe: a `SessionStart` hook writing `pwd` and its stdin payload to a marker; read the marker, not the turn.
+2. Pick the command from the result: if `cwd` is `.agents`, the command must reach the repo root (e.g. `node ../.aidd/scripts/update_memory.cjs`, or a root resolved from `workspacePaths[0]`); record the evidence in the PR.
+
+### `2)` Named-hook merge, test first
+
+> Shape `{ "<name>": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "…", "timeout": 30 } ] } ] } }`, no wrapper.
+
+1. Tests: empty file, existing foreign keys, re-run idempotent, invalid JSON fails loud (Codex's silent `catch { parsed = {} }` is not copied), strip leaves foreign keys.
+2. Implement in `antigravity-hooks.ts`; mutate the foreign-key preservation and watch its test fail.
+
+### `3)` Wire setup and translate
+
+1. `profile.ts`: `HooksCapability` targeting `.agents/hooks.json` with the merge and strip; `acceptsHooks` stays false for plugin flat install so the hook is not written twice.
+2. `build.ts`: hooks `hooksBundle`, scripts to `.agents/hooks/<plugin>/`, `hooksMerge` + `hooksMergeDest` converting the rewritten Claude-shaped JSON to one named key per plugin.
+3. Confirm the flat-rewritten script path resolves from the measured `cwd`.
+
+### `4)` Golden and suite
+
+1. Regenerate golden; only `antigravity:flat` moves.
+2. `cd cli && pnpm test`, pre-commit.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | The PR quotes the measured `cwd` and the marker line from a real `agy` session |
+| 2 | Foreign named hooks survive setup and clean; a second setup changes nothing; invalid JSON stops with the file named |
+| 3 | After setup, a new `agy` session logs `loaded … named hooks` and the memory refresh marker appears at repo root |
+| 4 | Only the `antigravity:flat` golden cell changes; full suite passes |

aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-4.md

@@ -0,0 +1,82 @@
+---
+status: pending
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: Portable agents under `.agents/agents/<name>/agent.md`
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+cli/
+├── src/contexts/tools/domain/formats/
+│   └── portable-agent.ts            ✅ rebuild frontmatter: name, description, model: inherit, tools as YAML list; drop everything else
+├── src/contexts/tools/domain/profiles/antigravity/
+│   ├── antigravity-paths.ts         ✏️ agents dir
+│   ├── profile.ts                   ✏️ AgentsCapability, nested `<name>/agent.md`
+│   └── build.ts                     ✏️ agents artifact, link rewriting relative to the nested path
+├── tests/contexts/tools/domain/formats/
+│   └── portable-agent.unit.test.ts  ✅ model mapping, tools string → list, Claude-only keys dropped, empty description rejected
+├── tests/contexts/tools/domain/profiles/antigravity/build.unit.test.ts   ✏️ agent path and body
+└── tests/golden/snapshots/framework-build/golden.json   ✏️ `antigravity:flat` cell only
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[source agent plugins/aidd-dev/agents/executor.md, model: opus, tools: a, b] --> B[aidd setup / translate antigravity]
+  B --> C[.agents/agents/aidd-dev-executor/agent.md]
+  C --> D[frontmatter: name, description, model: inherit, tools list]
+  D --> E[agy /agents lists aidd-dev-executor]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    fixture agent with model opus, comma tools and a Claude-only key => source ready: 5: system
+  section Happy path
+    translate --to antigravity --as flat => .agents/agents/<plugin>-<agent>/agent.md written: 5: cli
+    read frontmatter => name, description, model inherit, tools YAML list, nothing else: 5: cli
+    aidd setup --ai antigravity => same file recorded in manifest: 5: cli
+  section Edge case - no tools
+    source agent without tools => translate => no tools key emitted: 5: cli
+  section Edge case - empty description
+    source agent with blank description => translate => build fails naming the agent: 1: cli
+  section Edge case - flat shape
+    any build => no .agents/agents/<name>.md file exists: 5: cli
+```
+
+## Tasks to do
+
+### `1)` Portable frontmatter, test first
+
+> One builder #916 can reuse for Codex flat and Kimi.
+
+1. Tests for the four rules in #916, then implement `portable-agent.ts`.
+2. Mutate `model: inherit` back to the source value; watch the model test fail.
+
+### `2)` Antigravity agents in setup and translate
+
+1. `AgentsCapability` and flat `agents` artifact writing `.agents/agents/<plugin>-<agent>/agent.md`, body links rewritten from that nested path.
+2. Unit test the path and body; regenerate golden, only `antigravity:flat` moves.
+
+### `3)` Live check
+
+1. Local `agy --add-dir <repo> --output-format json -p "/agents"` lists a generated agent; quote the line in the PR, with an invented-name negative control.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | A source agent with `model: opus` and `tools: "a, b"` yields `model: inherit` and `tools: [a, b]`, and no Claude-only key |
+| 2 | Agents land only at `.agents/agents/<name>/agent.md`; only the `antigravity:flat` golden cell changes; full suite passes |
+| 3 | `agy /agents` lists the generated agent and not the invented one |

aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-5.md

@@ -0,0 +1,79 @@
+---
+status: pending
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: Docs, AIDD skill references and local runtime evidence
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+README.md                                        ✏️ compatibility line, tool table, install section
+cli/README.md                                    ✏️ tool and config-path rows
+docs/FAQ.md                                      ✏️ tool lists
+cli/aidd_docs/memory/codebase-map.md             ✏️ profiles/antigravity entry
+plugins/aidd-context/hooks/update_memory.js      ✏️ TOOL_FILES antigravity → AGENTS.md
+plugins/aidd-context/skills/02-project-memory/references/tools.md   ✏️ mirror of TOOL_FILES
+plugins/aidd-context/skills/{04..08}-*/references/tool-paths.md, tool-detect.md   ✏️ `.agents/` paths, detection
+plugins/aidd-context/skills/11-explore/…/ai-mapping.md, 00-onboard/…/detection.md  ✏️ antigravity row
+cli/scripts/smoke-antigravity.sh                 ✅ local only: setup, then assert `expanded slash command`, `loaded … named hooks`, `/agents` line from logs and markers, never the turn's end
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[developer reads README] --> B[aidd setup --ai antigravity]
+  B --> C[agy in the project]
+  C --> D[/aidd skill expands, memory refreshes, agents listed]
+  E[maintainer runs smoke-antigravity.sh locally] --> F[three log assertions pass or name the missing line]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    agy 1.2.14 logged in, empty temp project with aidd_docs => ready: 5: system
+  section Happy path
+    smoke-antigravity.sh => expanded slash command line found for one AIDD skill: 5: cli
+    smoke-antigravity.sh => loaded named hooks line and memory marker found: 5: cli
+    smoke-antigravity.sh => /agents lists a generated agent: 5: cli
+  section Edge case - agy missing
+    no agy on PATH => smoke-antigravity.sh => exits non-zero naming agy: 1: cli
+  section Teardown
+    kill hung agy turn, remove temp project => baseline restored: 5: system
+```
+
+## Tasks to do
+
+### `1)` Docs and references
+
+1. README tables, FAQ, CLI README, codebase map.
+2. `TOOL_FILES` and its mirror `tools.md`; the generate skills' path and detection references.
+3. `pnpm exec lefthook run pre-commit` (doc duplication, links, paths named in prose).
+
+### `2)` Local runtime smoke
+
+> Print mode hangs after answering: bound each turn with a timeout and read the log, as the spike did.
+
+1. Script asserting the three log lines; documented as local-only with why (login required) in `docs/MAINTAINERS.md`.
+2. Run it; paste the three shortest lines, date and `agy --version` into the PR.
+
+### `3)` Close the loop on #511
+
+1. Tick #511's criteria with links to each phase's PR; file follow-ups named in the plan's decisions if not already filed (native plugin mode, telemetry host, migration guide).
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | README and FAQ list Antigravity; `update_memory.js` refreshes `AGENTS.md` for `antigravity`; pre-commit passes |
+| 2 | On a logged-in machine the script reports all three lines; without `agy` it fails naming it |
+| 3 | Every #511 criterion points to the PR that proves it |