@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

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:

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:

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:

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/**):

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)