AGENTS.md

1# AGENTS instructions
2 
3## Project Overview
4 
5**AI Rules Sync (AIS)** is a CLI tool for synchronizing, managing, and sharing AI agent rules across projects using symbolic links.
6 
7### Tech Stack
8- **Language**: TypeScript (strict mode)
9- **Build**: `tsc` (ES modules)
10- **Test**: Vitest
11- **CLI Framework**: Commander.js
12- **Package Manager**: pnpm
13 
14### Key Features
15- Multi-repository rule management (Cursor, Copilot, Claude, Trae)
16- Symbolic link-based synchronization
17- Shell tab completion (bash, zsh, fish)
18- Plugin-based adapter architecture
19 
20## Directory Structure
21 
22```
23src/
24├── adapters/           # Tool-specific adapters (cursor, copilot, claude, trae)
25│   ├── base.ts         # Base adapter factory
26│   ├── types.ts        # Adapter interfaces
27│   └── index.ts        # Adapter registry
28├── commands/           # CLI command handlers
29│   ├── handlers.ts     # Core command logic (add, remove, link, unlink)
30│   ├── install.ts      # Install command
31│   └── helpers.ts      # Shared utilities
32├── cli/
33│   └── register.ts     # CLI registration
34├── completion/
35│   └── scripts.ts      # Shell completion scripts
36├── config.ts           # Global config (~/.config/ai-rules-sync/)
37├── project-config.ts   # Project config (ai-rules-sync.json)
38├── sync-engine.ts      # Symlink creation/removal
39├── link.ts             # Link utilities
40├── git.ts              # Git operations
41├── utils.ts            # Shared utilities
42└── index.ts            # Entry point
43```
44 
45## Development Commands
46 
47```bash
48# Build TypeScript
49npm run build
50 
51# Run tests (watch mode)
52npm test
53 
54# Run tests once
55npx vitest run
56 
57# Test CLI locally
58node dist/index.js <command>
59```
60 
61## Code Style Guidelines
62 
631. **TypeScript Strict Mode**: All code must pass strict type checking
642. **Functional Programming**: Prefer pure functions, avoid side effects where possible
653. **Testing Required**: All new features must have tests in `src/__tests__/`
664. **ES Modules**: Use `.js` extension in imports for Node.js compatibility
675. **Error Handling**: Use descriptive error messages with chalk for CLI output
68 
69### Adapter Pattern
70 
71All adapters follow the `BaseAdapter` interface:
72```typescript
73interface BaseAdapter {
74  name: string;           // Unique adapter name
75  tool: string;           // Tool identifier (cursor, copilot, etc.)
76  subtype: string;        // Type within tool (rules, commands, skills)
77  configPath: string[];   // Path in ai-rules-sync.json
78  defaultSourceDir: string;
79  targetDir: string;
80  mode: 'file' | 'directory';
81}
82```
83 
84## Workflows
85 
86### After Code Changes (Auto-trigger)
87 
88When making significant code changes, update documentation:
89 
901. **Update KNOWLEDGE_BASE.md** (if architecture/features changed)
91   - Use `/update-knowledge-base` skill
92   - Document new adapters, commands, or architectural changes
93 
942. **Update README.md** (English)
95   - Add new features, commands, or usage examples
96   - Keep architecture section current
97 
983. **Sync README_ZH.md** (Chinese)
99   - Use `/sync-readme` skill
100   - Maintain parity with English README
101 
1024. **Run Tests**
103```bash
104   npm test
105```
106 
107### Session Summary (End of Session)
108 
109Before ending a productive session:
110 
1111. **Identify Reusable Patterns** → Generate Rules
112   - Coding standards discovered
113   - Project-specific conventions
114 
1152. **Identify Multi-step Workflows** → Generate Skills
116   - Complex operations that benefit from step-by-step guidance
117   - Integration workflows
118 
1193. **Identify Frequent Commands** → Generate Commands
120   - One-click operations
121   - Common development tasks
122 
123Use `/summarize-session` to generate artifacts.
124 
125## Testing Conventions
126 
127- Test files: `src/__tests__/*.test.ts`
128- Use Vitest's `describe`, `it`, `expect`
129- Mock file system operations with `vi.mock('fs-extra')`
130- Test adapters independently from CLI
131 
132## Git Commit Guidelines
133 
134- Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
135- Include scope when relevant: `feat(adapter): add windsurf support`
136- Keep commits atomic and focused
137 
138## Related Files
139 
140- `README.md` - English documentation
141- `README_ZH.md` - Chinese documentation
142- `.cursor/rules/` - Cursor-specific rules (if any)
143- `ai-rules-sync.json` - Project configuration example
144