From 1707ac72f29bb2048cf765f59f5efd55c1418069 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 13:16:41 +0530 Subject: [PATCH 1/5] docs: add Antigravity setup and usage guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses #462 — users were confused about Antigravity skills setup. Adds a comprehensive guide covering: - Install mapping (ECC → .agent/ directory) - Directory structure after install - openai.yaml agent config format - Managing installs (list, doctor, uninstall) - Cross-target comparison table - Troubleshooting common issues - How to contribute skills with Antigravity support Also links the guide from the README FAQ section. --- README.md | 2 +- docs/ANTIGRAVITY-GUIDE.md | 148 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 docs/ANTIGRAVITY-GUIDE.md diff --git a/README.md b/README.md index 818b7f1f4..cadabedaa 100644 --- a/README.md +++ b/README.md @@ -835,7 +835,7 @@ Yes. ECC is cross-platform: - **Cursor**: Pre-translated configs in `.cursor/`. See [Cursor IDE Support](#cursor-ide-support). - **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#-opencode-support). - **Codex**: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257). -- **Antigravity**: Tightly integrated setup for workflows, skills, and flatten rules in `.agent/`. +- **Antigravity**: Tightly integrated setup for workflows, skills, and flatten rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md). - **Claude Code**: Native — this is the primary target. diff --git a/docs/ANTIGRAVITY-GUIDE.md b/docs/ANTIGRAVITY-GUIDE.md new file mode 100644 index 000000000..0c188f101 --- /dev/null +++ b/docs/ANTIGRAVITY-GUIDE.md @@ -0,0 +1,148 @@ +# Antigravity Setup and Usage Guide + +Google's [Antigravity](https://antigravity.dev) is an AI coding IDE that uses a `.agent/` directory convention for configuration. ECC provides first-class support for Antigravity through its selective install system. + +## Quick Start + +```bash +# Install ECC with Antigravity target +./install.sh --target antigravity typescript + +# Or with multiple language modules +./install.sh --target antigravity typescript python go +``` + +This installs ECC components into your project's `.agent/` directory, ready for Antigravity to pick up. + +## How the Install Mapping Works + +ECC remaps its component structure to match Antigravity's expected layout: + +| ECC Source | Antigravity Destination | What It Contains | +|------------|------------------------|------------------| +| `rules/` | `.agent/rules/` | Language rules and coding standards (flattened) | +| `commands/` | `.agent/workflows/` | Slash commands become Antigravity workflows | +| `agents/` | `.agent/skills/` | Agent definitions become Antigravity skills | +| `skills/` | `.agent/skills/` | Skill definitions (via `.agents/skills/`) | + +### Key Differences from Claude Code + +- **Rules are flattened**: Claude Code nests rules under subdirectories (`rules/common/`, `rules/typescript/`). Antigravity expects a flat `rules/` directory — the installer handles this automatically. +- **Commands become workflows**: ECC's `/command` files land in `.agent/workflows/`, which is Antigravity's equivalent of slash commands. +- **Agents become skills**: ECC agent definitions map to `.agent/skills/`, where Antigravity looks for skill configurations. + +## Directory Structure After Install + +``` +your-project/ +├── .agent/ +│ ├── rules/ +│ │ ├── coding-standards.md +│ │ ├── testing.md +│ │ ├── security.md +│ │ └── typescript.md # language-specific rules +│ ├── workflows/ +│ │ ├── plan.md +│ │ ├── code-review.md +│ │ ├── tdd.md +│ │ └── ... +│ ├── skills/ +│ │ ├── planner.md +│ │ ├── code-reviewer.md +│ │ ├── tdd-guide.md +│ │ └── ... +│ └── ecc-install-state.json # tracks what ECC installed +``` + +## The `openai.yaml` Agent Config + +Each skill in `.agents/skills/` includes an `agents/openai.yaml` file that configures the skill for Antigravity: + +```yaml +interface: + display_name: "API Design" + short_description: "REST API design patterns and best practices" + brand_color: "#F97316" + default_prompt: "Design REST API: resources, status codes, pagination" +policy: + allow_implicit_invocation: true +``` + +| Field | Purpose | +|-------|---------| +| `display_name` | Human-readable name shown in Antigravity's UI | +| `short_description` | Brief description of what the skill does | +| `brand_color` | Hex color for the skill's visual badge | +| `default_prompt` | Suggested prompt when the skill is invoked manually | +| `allow_implicit_invocation` | When `true`, Antigravity can activate the skill automatically based on context | + +## Managing Your Installation + +### Check What's Installed + +```bash +node scripts/list-installed.js --target antigravity +``` + +### Repair a Broken Install + +```bash +node scripts/doctor.js --target antigravity +``` + +### Uninstall + +```bash +node scripts/ecc.js uninstall --target antigravity +``` + +### Install State + +The installer writes `.agent/ecc-install-state.json` to track which files ECC owns. This enables safe uninstall and repair — ECC will never touch files it didn't create. + +## Adding Custom Skills for Antigravity + +If you're contributing a new skill and want it available on Antigravity: + +1. Create the skill under `skills/your-skill-name/SKILL.md` as usual +2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` +3. Mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` +4. Mention in your PR that you added Antigravity support + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide. + +## Comparison with Other Targets + +| Feature | Claude Code | Cursor | Codex | Antigravity | +|---------|-------------|--------|-------|-------------| +| Install target | `claude-home` | `cursor-project` | `codex-home` | `antigravity-project` | +| Config root | `~/.claude/` | `.cursor/` | `~/.codex/` | `.agent/` | +| Scope | User-level | Project-level | User-level | Project-level | +| Rules format | Nested dirs | Flat | Flat | Flat | +| Commands | `commands/` | N/A | N/A | `workflows/` | +| Agents/Skills | `agents/` | `skills/` | N/A | `skills/` | +| Install state | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` | + +## Troubleshooting + +### Skills not loading in Antigravity + +- Verify the `.agent/` directory exists in your project root (not home directory) +- Check that `ecc-install-state.json` was created — if missing, re-run the installer +- Ensure files have `.md` extension and valid frontmatter + +### Rules not applying + +- Rules must be in `.agent/rules/`, not nested in subdirectories +- Run `node scripts/doctor.js --target antigravity` to verify the install + +### Workflows not available + +- Antigravity looks for workflows in `.agent/workflows/`, not `commands/` +- If you manually copied ECC commands, rename the directory + +## Related Resources + +- [Selective Install Architecture](./SELECTIVE-INSTALL-ARCHITECTURE.md) — how the install system works under the hood +- [Selective Install Design](./SELECTIVE-INSTALL-DESIGN.md) — design decisions and target adapter contracts +- [CONTRIBUTING.md](../CONTRIBUTING.md) — how to contribute skills, agents, and commands From 925ee9ae66f8dec16508aa1cba81b9eb87316a1b Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 13:33:25 +0530 Subject: [PATCH 2/5] fix: address review feedback on Antigravity guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove spurious skills/ row from install mapping table, add note clarifying .agents/skills/ is static repo layout not installer-mapped - Fix repair section: doctor.js diagnoses, repair.js restores - Fix .agents/ → .agent/ path typo in custom skills section - Clarify 3-step workflow for adding Antigravity skills - Fix antigravity-project → antigravity in comparison table - Fix "flatten" → "flattened" grammar in README - Clarify openai.yaml full nested path structure --- README.md | 2 +- docs/ANTIGRAVITY-GUIDE.md | 15 ++++++++++----- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cadabedaa..add371ca4 100644 --- a/README.md +++ b/README.md @@ -835,7 +835,7 @@ Yes. ECC is cross-platform: - **Cursor**: Pre-translated configs in `.cursor/`. See [Cursor IDE Support](#cursor-ide-support). - **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#-opencode-support). - **Codex**: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257). -- **Antigravity**: Tightly integrated setup for workflows, skills, and flatten rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md). +- **Antigravity**: Tightly integrated setup for workflows, skills, and flattened rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md). - **Claude Code**: Native — this is the primary target. diff --git a/docs/ANTIGRAVITY-GUIDE.md b/docs/ANTIGRAVITY-GUIDE.md index 0c188f101..a5ffb221f 100644 --- a/docs/ANTIGRAVITY-GUIDE.md +++ b/docs/ANTIGRAVITY-GUIDE.md @@ -23,7 +23,8 @@ ECC remaps its component structure to match Antigravity's expected layout: | `rules/` | `.agent/rules/` | Language rules and coding standards (flattened) | | `commands/` | `.agent/workflows/` | Slash commands become Antigravity workflows | | `agents/` | `.agent/skills/` | Agent definitions become Antigravity skills | -| `skills/` | `.agent/skills/` | Skill definitions (via `.agents/skills/`) | + +> **Note**: The `skills/` directory is not directly mapped by the installer. Skill files in `.agents/skills/` are part of the repo's static layout and must be manually mirrored if you want them in the Antigravity runtime. ### Key Differences from Claude Code @@ -56,7 +57,7 @@ your-project/ ## The `openai.yaml` Agent Config -Each skill in `.agents/skills/` includes an `agents/openai.yaml` file that configures the skill for Antigravity: +Each skill directory under `.agents/skills/` contains an `agents/openai.yaml` file at the path `.agents/skills//agents/openai.yaml` that configures the skill for Antigravity: ```yaml interface: @@ -87,7 +88,11 @@ node scripts/list-installed.js --target antigravity ### Repair a Broken Install ```bash +# First, diagnose what's wrong node scripts/doctor.js --target antigravity + +# Then, restore missing or drifted files +node scripts/repair.js --target antigravity ``` ### Uninstall @@ -105,8 +110,8 @@ The installer writes `.agent/ecc-install-state.json` to track which files ECC ow If you're contributing a new skill and want it available on Antigravity: 1. Create the skill under `skills/your-skill-name/SKILL.md` as usual -2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` -3. Mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` +2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — the installer auto-deploys the `agents/` directory into `.agent/skills/` at runtime +3. Manually mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — this is needed because the installer maps `agents/` → `.agent/skills/` but does not auto-transform `skills/` 4. Mention in your PR that you added Antigravity support See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide. @@ -115,7 +120,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide. | Feature | Claude Code | Cursor | Codex | Antigravity | |---------|-------------|--------|-------|-------------| -| Install target | `claude-home` | `cursor-project` | `codex-home` | `antigravity-project` | +| Install target | `claude-home` | `cursor-project` | `codex-home` | `antigravity` | | Config root | `~/.claude/` | `.cursor/` | `~/.codex/` | `.agent/` | | Scope | User-level | Project-level | User-level | Project-level | | Rules format | Nested dirs | Flat | Flat | Flat | From 1688db942e06f6673e19864eb23d718040bb6984 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 13:48:43 +0530 Subject: [PATCH 3/5] fix: clarify .agents/ vs .agent/ naming and fix Cursor comparison MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Explain that .agents/ (with 's') is ECC source, .agent/ (no 's') is Antigravity runtime — installer copies between them - Fix Cursor Agents/Skills column: Cursor has no explicit agents/skills mapping (only rules), changed from 'skills/' to 'N/A' --- docs/ANTIGRAVITY-GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ANTIGRAVITY-GUIDE.md b/docs/ANTIGRAVITY-GUIDE.md index a5ffb221f..e7a201a18 100644 --- a/docs/ANTIGRAVITY-GUIDE.md +++ b/docs/ANTIGRAVITY-GUIDE.md @@ -24,7 +24,7 @@ ECC remaps its component structure to match Antigravity's expected layout: | `commands/` | `.agent/workflows/` | Slash commands become Antigravity workflows | | `agents/` | `.agent/skills/` | Agent definitions become Antigravity skills | -> **Note**: The `skills/` directory is not directly mapped by the installer. Skill files in `.agents/skills/` are part of the repo's static layout and must be manually mirrored if you want them in the Antigravity runtime. +> **Note on `.agents/` vs `.agent/`**: The ECC repo uses `.agents/` (with an 's') as its source directory for skill definitions and `openai.yaml` configs. The Antigravity runtime uses `.agent/` (without an 's') as its project config root. The installer copies from `.agents/` → `.agent/` during install. The `skills/` source path is not directly mapped by the installer — skill files in `.agents/skills/` must be manually mirrored to `.agent/skills/` if you want them in the Antigravity runtime. ### Key Differences from Claude Code @@ -125,7 +125,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide. | Scope | User-level | Project-level | User-level | Project-level | | Rules format | Nested dirs | Flat | Flat | Flat | | Commands | `commands/` | N/A | N/A | `workflows/` | -| Agents/Skills | `agents/` | `skills/` | N/A | `skills/` | +| Agents/Skills | `agents/` | N/A | N/A | `skills/` | | Install state | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` | ## Troubleshooting From 958c6ef2dd0eb5033034c2ffd10979a07f5f995f Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 14:01:32 +0530 Subject: [PATCH 4/5] fix: correct installer behavior claims and command style - Fix .agents/ vs .agent/ note: clarify that only rules, commands, and agents (no dot) are explicitly mapped by the installer. The dot-prefixed .agents/ directory falls through to default scaffold, not a direct copy. - Fix contributor workflow: remove false auto-deploy claim for openai.yaml. Clarify .agents/ is static repo layout, not installer-deployed. - Fix uninstall command: use direct script call (node scripts/uninstall.js) for consistency with doctor.js, repair.js, list-installed.js. --- docs/ANTIGRAVITY-GUIDE.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/ANTIGRAVITY-GUIDE.md b/docs/ANTIGRAVITY-GUIDE.md index e7a201a18..fcb8e6b16 100644 --- a/docs/ANTIGRAVITY-GUIDE.md +++ b/docs/ANTIGRAVITY-GUIDE.md @@ -24,7 +24,7 @@ ECC remaps its component structure to match Antigravity's expected layout: | `commands/` | `.agent/workflows/` | Slash commands become Antigravity workflows | | `agents/` | `.agent/skills/` | Agent definitions become Antigravity skills | -> **Note on `.agents/` vs `.agent/`**: The ECC repo uses `.agents/` (with an 's') as its source directory for skill definitions and `openai.yaml` configs. The Antigravity runtime uses `.agent/` (without an 's') as its project config root. The installer copies from `.agents/` → `.agent/` during install. The `skills/` source path is not directly mapped by the installer — skill files in `.agents/skills/` must be manually mirrored to `.agent/skills/` if you want them in the Antigravity runtime. +> **Note on `.agents/` vs `.agent/` vs `agents/`**: The installer only handles three source paths explicitly: `rules` → `.agent/rules/`, `commands` → `.agent/workflows/`, and `agents` (no dot prefix) → `.agent/skills/`. The dot-prefixed `.agents/` directory in the ECC repo is a **static layout** for Codex/Antigravity skill definitions and `openai.yaml` configs — it is not directly mapped by the installer. Any `.agents/` path falls through to the default scaffold operation. If you want `.agents/skills/` content available in the Antigravity runtime, you must manually copy it to `.agent/skills/`. ### Key Differences from Claude Code @@ -98,7 +98,7 @@ node scripts/repair.js --target antigravity ### Uninstall ```bash -node scripts/ecc.js uninstall --target antigravity +node scripts/uninstall.js --target antigravity ``` ### Install State @@ -110,10 +110,12 @@ The installer writes `.agent/ecc-install-state.json` to track which files ECC ow If you're contributing a new skill and want it available on Antigravity: 1. Create the skill under `skills/your-skill-name/SKILL.md` as usual -2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — the installer auto-deploys the `agents/` directory into `.agent/skills/` at runtime -3. Manually mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — this is needed because the installer maps `agents/` → `.agent/skills/` but does not auto-transform `skills/` +2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — this file is part of the repo's static layout, not auto-deployed by the installer +3. Mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — the `.agents/` directory is a static repo layout consumed by Codex and used as a reference for Antigravity 4. Mention in your PR that you added Antigravity support +> **Note**: The installer maps `agents/` (no dot) → `.agent/skills/`, which deploys agent definitions like `planner.md` and `code-reviewer.md`. The `.agents/` (dot-prefixed) directory containing `openai.yaml` configs is separate and not auto-deployed — it serves as a reference layout. + See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide. ## Comparison with Other Targets From 788be0ff7b38581320cd87ccd2866d15aa38840e Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 14:44:08 +0530 Subject: [PATCH 5/5] fix: add missing agents/ step to contributor workflow Contributors must add an agent definition at agents/ (no dot) for the installer to deploy it to .agent/skills/ at runtime. Without this step, skills only exist in the static .agents/ layout and are never deployed. --- docs/ANTIGRAVITY-GUIDE.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/ANTIGRAVITY-GUIDE.md b/docs/ANTIGRAVITY-GUIDE.md index fcb8e6b16..d792aec9f 100644 --- a/docs/ANTIGRAVITY-GUIDE.md +++ b/docs/ANTIGRAVITY-GUIDE.md @@ -110,11 +110,12 @@ The installer writes `.agent/ecc-install-state.json` to track which files ECC ow If you're contributing a new skill and want it available on Antigravity: 1. Create the skill under `skills/your-skill-name/SKILL.md` as usual -2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — this file is part of the repo's static layout, not auto-deployed by the installer -3. Mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — the `.agents/` directory is a static repo layout consumed by Codex and used as a reference for Antigravity -4. Mention in your PR that you added Antigravity support +2. Add an agent definition at `agents/your-skill-name.md` — this is the path the installer maps to `.agent/skills/` at runtime, making your skill available in the Antigravity harness +3. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — this is a static repo layout consumed by Codex for implicit invocation metadata +4. Mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — this static copy is used by Codex and serves as a reference for Antigravity +5. Mention in your PR that you added Antigravity support -> **Note**: The installer maps `agents/` (no dot) → `.agent/skills/`, which deploys agent definitions like `planner.md` and `code-reviewer.md`. The `.agents/` (dot-prefixed) directory containing `openai.yaml` configs is separate and not auto-deployed — it serves as a reference layout. +> **Key distinction**: The installer deploys `agents/` (no dot) → `.agent/skills/` — this is what makes skills available at runtime. The `.agents/` (dot-prefixed) directory is a separate static layout for Codex `openai.yaml` configs and is not auto-deployed by the installer. See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide.