AGENTS instructions

Project Overview

AI Rules Sync (AIS) is a CLI tool for synchronizing, managing, and sharing AI agent rules across projects using symbolic links.

Tech Stack

• Language: TypeScript (strict mode)
• Build: tsc (ES modules)
• Test: Vitest
• CLI Framework: Commander.js
• Package Manager: pnpm

Key Features

• Multi-repository rule management (Cursor, Copilot, Claude, Trae)
• Symbolic link-based synchronization
• Shell tab completion (bash, zsh, fish)
• Plugin-based adapter architecture

Directory Structure

src/
├── adapters/           # Tool-specific adapters (cursor, copilot, claude, trae)
│   ├── base.ts         # Base adapter factory
│   ├── types.ts        # Adapter interfaces
│   └── index.ts        # Adapter registry
├── commands/           # CLI command handlers
│   ├── handlers.ts     # Core command logic (add, remove, link, unlink)
│   ├── install.ts      # Install command
│   └── helpers.ts      # Shared utilities
├── cli/
│   └── register.ts     # CLI registration
├── completion/
│   └── scripts.ts      # Shell completion scripts
├── config.ts           # Global config (~/.config/ai-rules-sync/)
├── project-config.ts   # Project config (ai-rules-sync.json)
├── sync-engine.ts      # Symlink creation/removal
├── link.ts             # Link utilities
├── git.ts              # Git operations
├── utils.ts            # Shared utilities
└── index.ts            # Entry point

Development Commands

# Build TypeScript
npm run build

# Run tests (watch mode)
npm test

# Run tests once
npx vitest run

# Test CLI locally
node dist/index.js <command>

Code Style Guidelines

1. TypeScript Strict Mode: All code must pass strict type checking
2. Functional Programming: Prefer pure functions, avoid side effects where possible
3. Testing Required: All new features must have tests in src/__tests__/
4. ES Modules: Use .js extension in imports for Node.js compatibility
5. Error Handling: Use descriptive error messages with chalk for CLI output

Adapter Pattern

All adapters follow the BaseAdapter interface:

interface BaseAdapter {
  name: string;           // Unique adapter name
  tool: string;           // Tool identifier (cursor, copilot, etc.)
  subtype: string;        // Type within tool (rules, commands, skills)
  configPath: string[];   // Path in ai-rules-sync.json
  defaultSourceDir: string;
  targetDir: string;
  mode: 'file' | 'directory';
}

Workflows

After Code Changes (Auto-trigger)

When making significant code changes, update documentation:

1. Update KNOWLEDGE_BASE.md (if architecture/features changed)
   • Use /update-knowledge-base skill
   • Document new adapters, commands, or architectural changes
2. Update README.md (English)
   • Add new features, commands, or usage examples
   • Keep architecture section current
3. Sync README_ZH.md (Chinese)
   • Use /sync-readme skill
   • Maintain parity with English README
4. Run Tests

   npm test

Session Summary (End of Session)

Before ending a productive session:

1. Identify Reusable Patterns → Generate Rules
   • Coding standards discovered
   • Project-specific conventions
2. Identify Multi-step Workflows → Generate Skills
   • Complex operations that benefit from step-by-step guidance
   • Integration workflows
3. Identify Frequent Commands → Generate Commands
   • One-click operations
   • Common development tasks

Use /summarize-session to generate artifacts.

Testing Conventions

• Test files: src/__tests__/*.test.ts
• Use Vitest's describe, it, expect
• Mock file system operations with vi.mock('fs-extra')
• Test adapters independently from CLI

Git Commit Guidelines

• Use conventional commits: feat:, fix:, refactor:, docs:, test:
• Include scope when relevant: feat(adapter): add windsurf support
• Keep commits atomic and focused

Related Files

• README.md - English documentation
• README_ZH.md - Chinese documentation
• .cursor/rules/ - Cursor-specific rules (if any)
• ai-rules-sync.json - Project configuration example