npm package: @lightninglabs/ai-docs-sync
Description: CLI tool to sync AI guidance from .ai-docs/ to harness-specific outputs (Claude, Cursor, Copilot, Codex, Gemini)
Author: Lightning Labs
Latest version: 0.1.0

# @lightninglabs/ai-docs-sync

CLI tool to sync AI guidance from a canonical `.ai-docs/` directory into harness-specific outputs for **Claude**, **Cursor**, **Copilot**, **Codex**, and **Gemini**.

## Why

When a repo supports multiple AI harnesses, each expects different file names and formats for instructions, skills, commands, rules, and hooks. Without a single source of truth these files diverge, get hand-edited in the wrong place, and break in CI. `ai-docs-sync` solves this by making `.ai-docs/**` the canonical source and deterministically generating all harness-specific outputs.

## Install

```bash
npm install --save-dev @lightninglabs/ai-docs-sync
# or
yarn add --dev @lightninglabs/ai-docs-sync
```

## Usage

### `ai-docs-sync init`

Scaffold the `.ai-docs/` directory structure with READMEs and a starter `AGENTS.md`:

```bash
npx ai-docs-sync init
```

This creates:

```
.ai-docs/
├── AGENTS.md           # Your agent instructions (edit this)
├── README.md
├── commands/README.md
├── hooks/README.md
├── plans/README.md
├── rules/README.md
├── skills/README.md
└── subagents/README.md
```

It also prints the `.gitignore` lines you should add for generated outputs.

### `ai-docs-sync sync`

Generate harness-specific files from `.ai-docs/**` into the working tree:

```bash
npx ai-docs-sync sync
```

Generated outputs:

| Source                        | Generated outputs                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `.ai-docs/AGENTS.md`               | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`                                   |
| `.ai-docs/skills/<name>/`          | `.claude/skills/<name>/`, `.github/skills/<name>/`, `.codex/skills/<name>/`, `.gemini/skills/<name>/`      |
| `.ai-docs/commands/<name>.md`      | `.claude/commands/`, `.cursor/commands/`, `.github/prompts/`, `.codex/prompts/`, `.gemini/commands/*.toml` |
| `.ai-docs/rules/<name>.mdc`        | `.cursor/rules/<name>.mdc`                                                                                 |
| `.ai-docs/subagents/<name>.md`     | `.claude/agents/<name>.md`, `.cursor/agents/<name>.md`                                                     |
| `.ai-docs/hooks/claude.hooks.json` | `.claude/settings.json`                                                                                    |
| `.ai-docs/hooks/gemini.hooks.json` | `.gemini/settings.json`                                                                                    |

### `ai-docs-sync check`

Validate determinism, output set correctness, and gitignore coverage:

```bash
npx ai-docs-sync check
```

This is designed to run in CI. It verifies:

- All generated output paths are covered by `.gitignore`
- Generating twice produces byte-for-byte identical outputs (determinism)
- The generator produces exactly the expected file set (no missing/extra)
- If generated outputs exist on disk, they match what would be generated

### `ai-docs-sync clean`

Delete generated outputs (allowlist-only, never touches `.ai-docs/**`):

```bash
npx ai-docs-sync clean
```

## Authoring workflow

Follow this procedure when you want to update your AI guidance files

1. **Draft** new AI guidance in the harness you're using (e.g. `.claude/`, `.cursor/`) to test and confirm it works as expected
2. **Copy** finalized content back into `.ai-docs/`
3. Run `ai-docs-sync sync` to regenerate all harness outputs
4. Run `ai-docs-sync check` to validate consistency
5. Commit `.ai-docs/` changes (generated outputs are gitignored)