https://github.com/lightninglabs/ai-docs-sync
CLI tool to sync AI guidance from .ai-docs/ to harness-specific outputs (Claude, Cursor, Copilot, Codex, Gemini)
https://github.com/lightninglabs/ai-docs-sync
Last synced: 22 days ago
JSON representation
CLI tool to sync AI guidance from .ai-docs/ to harness-specific outputs (Claude, Cursor, Copilot, Codex, Gemini)
- Host: GitHub
- URL: https://github.com/lightninglabs/ai-docs-sync
- Owner: lightninglabs
- License: mit
- Created: 2026-02-12T20:01:03.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-02-12T20:16:39.000Z (5 months ago)
- Last Synced: 2026-07-02T08:32:26.024Z (23 days ago)
- Language: TypeScript
- Size: 64.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @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//` | `.claude/skills//`, `.github/skills//`, `.codex/skills//`, `.gemini/skills//` |
| `.ai-docs/commands/.md` | `.claude/commands/`, `.cursor/commands/`, `.github/prompts/`, `.codex/prompts/`, `.gemini/commands/*.toml` |
| `.ai-docs/rules/.mdc` | `.cursor/rules/.mdc` |
| `.ai-docs/subagents/.md` | `.claude/agents/.md`, `.cursor/agents/.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)