rulesync 6.8.1 → 7.1.0

package/README.md

@@ -126,6 +126,8 @@ rulesync init
 
 # Install official skills (recommended)
 rulesync fetch dyoshikawa/rulesync --features skills
+
+# Or add skill sources to rulesync.jsonc and run 'rulesync install' (see "Declarative Skill Sources")
 ```
 
 On the other hand, if you already have AI tool configurations:
@@ -147,34 +149,33 @@ rulesync generate --targets "*" --features "*"
 
 Rulesync supports both **generation** and **import** for All of the major AI coding tools:
 
-| Tool               | rules | ignore |   mcp    | commands | subagents | skills | hooks |
-| ------------------ | :---: | :----: | :------: | :------: | :-------: | :----: | :---: |
-| AGENTS.md          |  ✅   |        |          |    🎮    |    🎮     |   🎮   |       |
-| AgentsSkills       |       |        |          |          |           |   ✅   |       |
-| Claude Code        | ✅ 🌏 |   ✅   | ✅ 🌏 📦 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |  ✅   |
-| Codex CLI          | ✅ 🌏 |        |    🌏    |    🌏    |    🎮     | ✅ 🌏  |       |
-| Gemini CLI         | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |    🎮     | ✅ 🌏  |       |
-| GitHub Copilot     |  ✅   |        |    ✅    |    ✅    |    ✅     |   ✅   |       |
-| Cursor             |  ✅   |   ✅   |    ✅    |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |  ✅   |
-| Factory Droid      | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |       |
-| OpenCode           |  ✅   |        |    ✅    |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |       |
-| Cline              |  ✅   |   ✅   |    ✅    |  ✅ 🌏   |           |        |       |
-| Kilo Code          | ✅ 🌏 |   ✅   |    ✅    |  ✅ 🌏   |           | ✅ 🌏  |       |
-| Roo Code           |  ✅   |   ✅   |    ✅    |    ✅    |    🎮     | ✅ 🌏  |       |
-| Qwen Code          |  ✅   |   ✅   |          |          |           |        |       |
-| Kiro               |  ✅   |   ✅   |    ✅    |    ✅    |    ✅     |   ✅   |       |
-| Google Antigravity |  ✅   |        |          |    ✅    |           | ✅ 🌏  |       |
-| JetBrains Junie    |  ✅   |   ✅   |    ✅    |          |           |        |       |
-| AugmentCode        |  ✅   |   ✅   |          |          |           |        |       |
-| Windsurf           |  ✅   |   ✅   |          |          |           |        |       |
-| Warp               |  ✅   |        |          |          |           |        |       |
-| Replit             |  ✅   |        |          |          |           |   ✅   |       |
-| Zed                |       |   ✅   |          |          |           |        |       |
+| Tool               | rules | ignore |  mcp  | commands | subagents | skills | hooks |
+| ------------------ | :---: | :----: | :---: | :------: | :-------: | :----: | :---: |
+| AGENTS.md          |  ✅   |        |       |    🎮    |    🎮     |   🎮   |       |
+| AgentsSkills       |       |        |       |          |           |   ✅   |       |
+| Claude Code        | ✅ 🌏 |   ✅   | ✅ 🌏 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |  ✅   |
+| Codex CLI          | ✅ 🌏 |        |  🌏   |    🌏    |    🎮     | ✅ 🌏  |       |
+| Gemini CLI         | ✅ 🌏 |   ✅   | ✅ 🌏 |  ✅ 🌏   |    🎮     | ✅ 🌏  |       |
+| GitHub Copilot     |  ✅   |        |  ✅   |    ✅    |    ✅     |   ✅   |       |
+| Cursor             |  ✅   |   ✅   |  ✅   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |  ✅   |
+| Factory Droid      | ✅ 🌏 |        | ✅ 🌏 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |       |
+| OpenCode           |  ✅   |        |  ✅   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |
+| Cline              |  ✅   |   ✅   |  ✅   |  ✅ 🌏   |           |        |       |
+| Kilo Code          | ✅ 🌏 |   ✅   |  ✅   |  ✅ 🌏   |           | ✅ 🌏  |       |
+| Roo Code           |  ✅   |   ✅   |  ✅   |    ✅    |    🎮     | ✅ 🌏  |       |
+| Qwen Code          |  ✅   |   ✅   |       |          |           |        |       |
+| Kiro               |  ✅   |   ✅   |  ✅   |    ✅    |    ✅     |   ✅   |       |
+| Google Antigravity |  ✅   |        |       |    ✅    |           | ✅ 🌏  |       |
+| JetBrains Junie    |  ✅   |   ✅   |  ✅   |          |           |        |       |
+| AugmentCode        |  ✅   |   ✅   |       |          |           |        |       |
+| Windsurf           |  ✅   |   ✅   |       |          |           |        |       |
+| Warp               |  ✅   |        |       |          |           |        |       |
+| Replit             |  ✅   |        |       |          |           |   ✅   |       |
+| Zed                |       |   ✅   |       |          |           |        |       |
 
 - ✅: Supports project mode
 - 🌏: Supports global mode
 - 🎮: Supports simulated commands/subagents/skills (Project mode only)
-- 📦: Supports modular MCP (Experimental)
 
 ## Why Rulesync?
 
@@ -243,6 +244,18 @@ rulesync generate --dry-run --targets claudecode --features rules
 # Check if files are up to date (for CI/CD pipelines)
 rulesync generate --check --targets "*" --features "*"
 
+# Install skills from declarative sources in rulesync.jsonc
+rulesync install
+
+# Force re-resolve all source refs (ignore lockfile)
+rulesync install --update
+
+# Fail if lockfile is missing or out of sync (for CI)
+rulesync install --frozen
+
+# Install then generate (typical workflow)
+rulesync install && rulesync generate
+
 # Add generated files to .gitignore
 rulesync gitignore
 
@@ -400,7 +413,13 @@ Example:
   "simulateCommands": false, // Generate simulated commands
   "simulateSubagents": false, // Generate simulated subagents
   "simulateSkills": false, // Generate simulated skills
-  "modularMcp": false, // Enable modular-mcp for context compression (experimental, Claude Code only)
+
+  // Declarative skill sources — installed via 'rulesync install'
+  // See the "Declarative Skill Sources" section for details.
+  // "sources": [
+  //   { "source": "owner/repo" },
+  //   { "source": "org/repo", "skills": ["specific-skill"] },
+  // ],
 }
 ```
 
@@ -495,15 +514,17 @@ This is Rulesync, a Node.js CLI tool that automatically generates configuration
 
 ### `.rulesync/hooks.json`
 
-Hooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file; Cursor uses them as-is; Claude Code gets PascalCase in `.claude/settings.json`.
+Hooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file; Cursor uses them as-is; Claude Code gets PascalCase in `.claude/settings.json`; OpenCode hooks are generated as a JavaScript plugin at `.opencode/plugins/rulesync-hooks.js`.
 
 **Event support:**
 
-- **Shared (Cursor and Claude):** `sessionStart`, `sessionEnd`, `preToolUse`, `postToolUse`, `beforeSubmitPrompt`, `stop`, `subagentStop`, `preCompact`
-- **Cursor-only:** `postToolUseFailure`, `subagentStart`, `beforeShellExecution`, `afterShellExecution`, `beforeMCPExecution`, `afterMCPExecution`, `beforeReadFile`, `afterFileEdit`, `afterAgentResponse`, `afterAgentThought`, `beforeTabFileRead`, `afterTabFileEdit`
-- **Claude-only:** `permissionRequest`, `notification`, `setup`
+- **Cursor:** `sessionStart`, `preToolUse`, `postToolUse`, `stop`, `sessionEnd`, `beforeSubmitPrompt`, `subagentStop`, `preCompact`, `afterFileEdit`, `afterShellExecution`, `postToolUseFailure`, `subagentStart`, `beforeShellExecution`, `beforeMCPExecution`, `afterMCPExecution`, `beforeReadFile`, `afterAgentResponse`, `afterAgentThought`, `beforeTabFileRead`, `afterTabFileEdit`
+- **Claude Code:** `sessionStart`, `preToolUse`, `postToolUse`, `stop`, `sessionEnd`, `beforeSubmitPrompt`, `subagentStop`, `preCompact`, `permissionRequest`, `notification`, `setup`
+- **OpenCode:** `sessionStart`, `preToolUse`, `postToolUse`, `stop`, `afterFileEdit`, `afterShellExecution`, `permissionRequest`
 
-Use optional **override keys** so tool-specific events and config live in one file without leaking to the other: `cursor.hooks` for Cursor-only events, `claudecode.hooks` for Claude-only. Events in shared `hooks` that a tool does not support are skipped for that tool (and a warning is logged at generate time).
+> **Note:** Rulesync implements OpenCode hooks as a plugin, so importing from OpenCode to rulesync is not supported. OpenCode only supports command-type hooks (not prompt-type).
+
+Use optional **override keys** so tool-specific events and config live in one file without leaking to others: `cursor.hooks` for Cursor-only events, `claudecode.hooks` for Claude-only, `opencode.hooks` for OpenCode-only. Events in shared `hooks` that a tool does not support are skipped for that tool (and a warning is logged at generate time).
 
 Example:
 
@@ -526,6 +547,11 @@ Example:
         { "matcher": "permission_prompt", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh" }
       ]
     }
+  },
+  "opencode": {
+    "hooks": {
+      "afterShellExecution": [{ "command": ".rulesync/hooks/post-shell.sh" }]
+    }
   }
 }
 ```
@@ -692,20 +718,26 @@ You can use global mode via Rulesync by enabling `--global` option. It can also
 Currently, supports rules and commands generation for Claude Code. Import for global files is supported for rules and commands.
 
 1. Create an any name directory. For example, if you prefer `~/.aiglobal`, run the following command.
+
    ```bash
    mkdir -p ~/.aiglobal
    ```
+
 2. Initialize files for global files in the directory.
+
    ```bash
    cd ~/.aiglobal
    rulesync init
    ```
+
 3. Edit `~/.aiglobal/rulesync.jsonc` to enable global mode.
+
    ```jsonc
    {
      "global": true,
    }
    ```
+
 4. Edit `~/.aiglobal/.rulesync/rules/overview.md` to your preferences.
 
    ```md
@@ -719,6 +751,7 @@ Currently, supports rules and commands generation for Claude Code. Import for gl
    ```
 
 5. Generate rules for global settings.
+
    ```bash
    # Run in the `~/.aiglobal` directory
    rulesync generate
@@ -737,6 +770,7 @@ Simulated commands, subagents and skills allow you to generate simulated feature
 
 1. Prepare `.rulesync/commands/*.md`, `.rulesync/subagents/*.md` and `.rulesync/skills/*/SKILL.md` for your purposes.
 2. Generate simulated commands, subagents and skills for specific tools that are included in cursor, codexcli and etc.
+
    ```bash
    rulesync generate \
      --targets copilot,cursor,codexcli \
@@ -745,6 +779,7 @@ Simulated commands, subagents and skills allow you to generate simulated feature
      --simulate-subagents \
      --simulate-skills
    ```
+
 3. Use simulated commands, subagents and skills in your prompts.
    - Prompt examples:
 
@@ -759,160 +794,138 @@ Simulated commands, subagents and skills allow you to generate simulated feature
      Use the skill your-skill to achieve something.
      ```
 
-## Modular MCP (Deprecated)
+## Official Skills
 
-Rulesync supports compressing tokens consumed by MCP servers [d-kimuson/modular-mcp](https://github.com/d-kimuson/modular-mcp) for context saving. When enabled with `--modular-mcp`, it additionally generates `modular-mcp.json`.
+Rulesync provides official skills that you can install using the fetch command or declarative sources:
 
 ```bash
-# Enable modular-mcp via CLI
-rulesync generate --targets claudecode --features mcp --modular-mcp
+# One-time fetch
+rulesync fetch dyoshikawa/rulesync --features skills
 
-# Or via configuration file
-{
-  "modularMcp": true
-}
+# Or declare in rulesync.jsonc and run 'rulesync install'
 ```
 
-When enabling modular-mcp, each MCP server must have a `description` field. Example:
+This will install the Rulesync documentation skill to your project.
 
-```diff
-// .rulesync/mcp.json
-{
-  "mcpServers": {
-    "context7": {
-+     "description": "Up-to-date documentation and code examples for libraries",
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@upstash/context7-mcp"
-      ],
-      "env": {}
-    }
-}
-```
+## Declarative Skill Sources
 
-You can also configure `exposed` to exclude specific MCP servers from modular-mcp. It is optional and default to `false`. If you specify `exposed: true`, the MCP server is always loaded in the initial context.
+Rulesync can fetch skills from external GitHub repositories using the `install` command. Instead of manually running `fetch` for each skill source, declare them in your `rulesync.jsonc` and run `rulesync install` to resolve and fetch them. Then `rulesync generate` picks them up as local curated skills. Typical workflow: `rulesync install && rulesync generate`.
 
-```diff
-// .rulesync/mcp.json
+### Configuration
+
+Add a `sources` array to your `rulesync.jsonc`:
+
+```jsonc
 {
-  "mcpServers": {
-    "context7": {
-+     "exposed": true,
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@upstash/context7-mcp"
-      ],
-      "env": {}
-    }
+  "$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
+  "targets": ["copilot", "claudecode"],
+  "features": ["rules", "skills"],
+  "sources": [
+    // Fetch all skills from a repository
+    { "source": "owner/repo" },
+
+    // Fetch only specific skills by name
+    { "source": "anthropics/skills", "skills": ["skill-creator"] },
+
+    // With ref pinning and subdirectory path (same syntax as fetch command)
+    { "source": "owner/repo@v1.0.0:path/to/skills" },
+  ],
 }
 ```
 
-To demonstrate the effect of modular-mcp, please see the following example:
+Each entry in `sources` accepts:
 
-<details>
-<summary>Example of effect</summary>
+| Property | Type       | Description                                                                                                 |
+| -------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `source` | `string`   | Repository source using the same format as the `fetch` command (`owner/repo`, `owner/repo@ref:path`, etc.). |
+| `skills` | `string[]` | Optional list of skill names to fetch. If omitted, all skills are fetched.                                  |
 
-Please see examples using Claude Code.
+### How It Works
 
-When using following mcp servers:
+When `rulesync install` runs and `sources` is configured:
 
-```json
-// .rulesync/mcp.json
+1. **Lockfile resolution** — Each source's ref is resolved to a commit SHA and stored in `rulesync.lock` (at the project root). On subsequent runs the locked SHA is reused for deterministic builds.
+2. **Remote skill listing** — The `skills/` directory (or the path specified in the source URL) is listed from the remote repository.
+3. **Filtering** — If `skills` is specified, only matching skill directories are fetched.
+4. **Precedence rules**:
+   - **Local skills always win** — Skills in `.rulesync/skills/` (not in `.curated/`) take precedence; a remote skill with the same name is skipped.
+   - **First-declared source wins** — If two sources provide a skill with the same name, the one declared first in the `sources` array is used.
+5. **Output** — Fetched skills are written to `.rulesync/skills/.curated/<skill-name>/`. This directory is automatically added to `.gitignore` by `rulesync gitignore`.
 
-{
-  "mcpServers": {
-    "serena": {
-      "description": "Semantic coding tools for intelligent codebase exploration and manipulation",
-      "type": "stdio",
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/oraios/serena",
-        "serena",
-        "start-mcp-server",
-        "--context",
-        "ide-assistant",
-        "--enable-web-dashboard",
-        "false",
-        "--project",
-        "."
-      ],
-      "env": {}
-    },
-    "context7": {
-      "description": "Up-to-date documentation and code examples for libraries",
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"],
-      "env": {}
-    },
-    "fetch": {
-      "description": "This server enables LLMs to retrieve and process content from web pages, converting HTML to markdown for easier consumption.",
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["mcp-server-fetch"],
-      "env": {}
-    }
-  }
-}
-```
+### CLI Options
 
-Once run `rulesync generate --targets claudecode --features mcp`, `/context` result on Claude Code is as follows:
+The `install` command accepts these flags:
 
-```
-      Context Usage
-     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-sonnet-4-5-20250929 · 82k/200k tokens (41%)
-     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛀
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 2.5k tokens (1.3%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 13.9k tokens (6.9%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 15.7k tokens (7.9%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 5.2k tokens (2.6%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 8 tokens (0.0%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝   ⛶ Free space: 118k (58.8%)
-     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛝ Autocompact buffer: 45.0k tokens (22.5%)
-     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝
-```
+| Flag              | Description                                                                           |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `--update`        | Force re-resolve all source refs, ignoring the lockfile (useful to pull new updates). |
+| `--frozen`        | Fail if lockfile is missing or out of sync. Useful for CI to ensure reproducibility.  |
+| `--token <token>` | GitHub token for private repositories.                                                |
 
-On the other hand, once run `rulesync generate --targets claudecode --features mcp --modular-mcp`, `/context` result on Claude Code is as follows:
+```bash
+# Install skills using locked refs
+rulesync install
 
-```
-      Context Usage
-     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛁   claude-sonnet-4-5-20250929 · 68k/200k tokens (34%)
-     ⛁ ⛀ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 2.5k tokens (1.3%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 13.5k tokens (6.8%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 1.3k tokens (0.6%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 5.2k tokens (2.6%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 8 tokens (0.0%)
-     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝   ⛶ Free space: 132k (66.2%)
-     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛝ Autocompact buffer: 45.0k tokens (22.5%)
-     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝
+# Force update to latest refs
+rulesync install --update
+
+# Strict CI mode — fail if lockfile doesn't cover all sources
+rulesync install --frozen
+
+# Install then generate
+rulesync install && rulesync generate
+
+# Skip source installation — just don't run install
+rulesync generate
 ```
 
-Focus on the difference of MCP tools usage.
+### Lockfile
 
-|                      | Context Usage       |
-| -------------------- | ------------------- |
-| Disabled Modular MCP | 15.7k tokens (7.9%) |
-| Enabled Modular MCP  | 1.3k tokens (0.6%)  |
+The lockfile at `rulesync.lock` (at the project root) records the resolved commit SHA and per-skill integrity hashes for each source so that builds are reproducible. It is safe to commit this file. An example:
 
-So, in this case, approximately 92% reduction in MCP tools consumption!
+```json
+{
+  "lockfileVersion": 1,
+  "sources": {
+    "owner/skill-repo": {
+      "requestedRef": "main",
+      "resolvedRef": "abc123def456...",
+      "resolvedAt": "2025-01-15T12:00:00.000Z",
+      "skills": {
+        "my-skill": { "integrity": "sha256-abcdef..." },
+        "another-skill": { "integrity": "sha256-123456..." }
+      }
+    }
+  }
+}
+```
 
-</details>
+To update locked refs, run `rulesync install --update`.
 
-## Official Skills
+### Authentication
 
-Rulesync provides official skills that you can install using the fetch command:
+Source fetching uses the `GITHUB_TOKEN` or `GH_TOKEN` environment variable for authentication. This is required for private repositories and recommended for better rate limits.
 
 ```bash
-rulesync fetch dyoshikawa/rulesync --features skills
+# Using environment variable
+export GITHUB_TOKEN=ghp_xxxx
+npx rulesync install
+
+# Or using GitHub CLI
+GITHUB_TOKEN=$(gh auth token) npx rulesync install
 ```
 
-This will install the Rulesync documentation skill to your project.
+> [!TIP]
+> The `install` command also accepts a `--token` flag for explicit authentication: `rulesync install --token ghp_xxxx`.
+
+### Curated vs Local Skills
+
+| Location                            | Type    | Precedence | Committed to Git |
+| ----------------------------------- | ------- | ---------- | ---------------- |
+| `.rulesync/skills/<name>/`          | Local   | Highest    | Yes              |
+| `.rulesync/skills/.curated/<name>/` | Curated | Lower      | No (gitignored)  |
+
+When both a local and a curated skill share the same name, the local skill is used and the remote one is not fetched.
 
 ## Rulesync MCP Server
 
@@ -950,7 +963,7 @@ Add the Rulesync MCP server to your `.rulesync/mcp.json`:
 
 ## FAQ
 
-### Q. The generated `.mcp.json` doesn't work properly in Claude Code.
+### Q. The generated `.mcp.json` doesn't work properly in Claude Code
 
 You can try adding the following to `.claude/settings.json` or `.claude/settings.local.json`:
 
@@ -964,6 +977,28 @@ According to [the documentation](https://code.claude.com/docs/en/settings), this
 
 > Automatically approve all MCP servers defined in project .mcp.json files
 
+### Q. Google Antigravity doesn't load rules when `.agent` directories are in `.gitignore`
+
+Google Antigravity has a known limitation where it won't load rules, workflows, and skills if the `.agent/rules/`, `.agent/workflows/`, and `.agent/skills/` directories are listed in `.gitignore`, even with "Agent Gitignore Access" enabled.
+
+**Workaround:** Instead of adding these directories to `.gitignore`, add them to `.git/info/exclude`:
+
+```bash
+# Remove from .gitignore (if present)
+# **/.agent/rules/
+# **/.agent/workflows/
+# **/.agent/skills/
+
+# Add to .git/info/exclude
+echo "**/.agent/rules/" >> .git/info/exclude
+echo "**/.agent/workflows/" >> .git/info/exclude
+echo "**/.agent/skills/" >> .git/info/exclude
+```
+
+`.git/info/exclude` works like `.gitignore` but is local-only, so it won't affect Antigravity's ability to load the rules while still excluding these directories from Git.
+
+Note: `.git/info/exclude` can't be shared with your team since it's not committed to the repository.
+
 ## License
 
 MIT License