Skip to content

Commit 2214a5f

Browse files
lavantienlavantien
committed
chore: sync system instructions
1 parent 2b83ec7 commit 2214a5f

3 files changed

Lines changed: 351 additions & 2 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Use `./CLAUDE.md`
1+
Use `./CLAUDE.md`

‎CLAUDE.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,34 @@ If you cannot write acceptance criteria, pause and clarify.
3737
- GitHub CLI: Use `gh` for PR/Issue operations.
3838
- Offline Docs: Use `go doc` or `x --help` or `man x` or equivalences for accurate command references.
3939

40+
### Research Before Implementation
41+
42+
Before writing any code, always verify current best practices. Never rely on training data for API syntax, library versions, or installation commands.
43+
44+
1. **Latest Documentation**: Use Context7 MCP to get up-to-date library docs
45+
- First: Use `mcp__plugin_context7_context7__resolve-library-id` to find the library
46+
- Then: Use `mcp__plugin_context7_context7__query-docs` to get specific info
47+
48+
2. **Web Search**: Use `mcp__web-search-prime__webSearchPrime` for:
49+
- Latest library versions and syntax
50+
- Breaking changes in recent releases
51+
- Current best practices (patterns change over time)
52+
53+
3. **Web Reader**: Use `mcp__web_reader__webReader` for:
54+
- Reading official documentation pages
55+
- Checking GitHub repositories for examples
56+
- Fetching specific documentation URLs
57+
58+
4. **ZRead**: Use `mcp__zread__*` tools for:
59+
- Searching GitHub repositories
60+
- Reading repository documentation
61+
- Exploring codebases
62+
63+
5. **GitHub CLI**: Use `gh` for:
64+
- Searching issues and PRs
65+
- Reading repository files
66+
- Checking latest releases
67+
4068
### Verification Minimum
4169

4270
Detect the environment and run the **strict** verification chain. If a `Makefile`, `Justfile`, or `Taskfile` exists, prioritize the below first and then apply standard targets after (e.g., `make check`, `just test`).
@@ -86,6 +114,42 @@ For simple typo fixes, comment updates, or one-line non-logic changes:
86114
2. Run the linter/formatter only.
87115
3. Commit immediately.
88116

117+
## Testing Strategy
118+
119+
### Property-Based Testing vs Unit Tests
120+
121+
Choose the appropriate testing approach based on what you are validating.
122+
123+
**Use Unit Tests for**:
124+
125+
- Business logic with specific input/output pairs
126+
- Edge cases and boundary conditions
127+
- Error handling paths
128+
- Individual function behavior
129+
130+
**Use Property-Based Testing for**:
131+
132+
- Invariants that should hold for ANY valid input
133+
- Commutativity, associativity, idempotency properties
134+
- Round-trip serialization/deserialization
135+
- State transitions in state machines
136+
137+
**Examples**:
138+
139+
Property-based (QuickCheck/propcheck style):
140+
141+
- "For any list, reversing twice returns the original"
142+
- "For any valid JSON string, parse → stringify → parse yields the same value"
143+
- "For any two numbers a, b: add(a, b) == add(b, a)"
144+
145+
Unit test:
146+
147+
- "Given empty list, return error"
148+
- "Given user ID 123, return User object with name='John'"
149+
- "Given negative input, throw ValueError"
150+
151+
When implementing features with complex invariants, prefer property-based tests with hundreds of auto-generated cases over manually written unit tests.
152+
89153
## Beware Language Specific Pitfalls
90154

91155
E.g. Go

‎RULES.md‎

Lines changed: 286 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,287 @@
1-
Use `./CLAUDE.md`
1+
# Dotfiles Development Rules
2+
3+
## Overview
4+
5+
This file provides master guidelines for working with this dotfiles repository. It complements detailed instructions in [CLAUDE.md](./CLAUDE.md).
6+
7+
## Core Principles
8+
9+
### 1. Source of Truth
10+
- **This dotfiles repo is the source of truth** for all configurations
11+
- All changes must flow FROM here TO your home directory, not the reverse
12+
- Never modify deployed configs directly - edit in the repo, then re-deploy
13+
14+
### 2. Cross-Platform Consistency
15+
- Scripts must work on: Windows 11, Linux (Ubuntu/Fedora/Arch), and macOS (Intel/Apple Silicon)
16+
- Use platform detection (`detect_os` / `detect_distro`) to handle platform differences
17+
- Test on at least 2 platforms before committing
18+
19+
### 3. Idempotency
20+
- Scripts must be safe to run multiple times
21+
- Check before acting (don't overwrite if already exists)
22+
- Use `cmd_exists` / `Get-Command` before using tools
23+
- Verify installations before re-installing
24+
25+
### 4. Graceful Degradation
26+
- If a tool is missing, skip gracefully with warning
27+
- Never fail silently - always inform the user of what was skipped
28+
- Provide clear error messages with actionable steps
29+
30+
### 5. Non-Destructive by Default
31+
- Require explicit flags (`--force`, `-f`) for destructive operations
32+
- Always create backups before overwriting files
33+
- Default to dry-run mode where safe
34+
35+
### 6. Security
36+
- Never commit secrets, API keys, or credentials
37+
- Use environment variables for sensitive data
38+
- Validate all user inputs
39+
- Never execute arbitrary code from untrusted sources
40+
41+
## Development Workflow
42+
43+
### Adding New Features
44+
1. **Plan in AGENTS.md** before coding
45+
2. Create tests first (TDD when appropriate)
46+
3. Implement feature with error handling
47+
4. Test on all supported platforms
48+
5. Update documentation
49+
6. Commit with conventional commit format
50+
51+
### Adding New Tools
52+
When adding a new tool to bootstrap/update-all:
53+
54+
1. Add to appropriate `lib/common.sh` or `lib/config.ps1` helper functions
55+
2. Add install check to bootstrap scripts (both Unix and Windows)
56+
3. Add update check to update-all scripts
57+
4. Add config option to `.dotfiles.config.yaml.example`
58+
5. Add health check for tool in `healthcheck.sh/ps1`
59+
6. Update documentation (README.md, this file)
60+
7. Add tests for new tool
61+
62+
### Adding New Config Files
63+
1. Add to backup scripts (`backup.sh/ps1`)
64+
2. Add to restore scripts (`restore.sh/ps1`)
65+
3. Add to deploy scripts (`deploy.sh/ps1`)
66+
4. Add to uninstall verification lists
67+
5. Update documentation
68+
69+
### Modifying Git Hooks
70+
1. Keep hooks simple and focused
71+
2. Don't make them block normal workflows
72+
3. Always provide bypass options (git `--no-verify`)
73+
4. Test hooks with various project types
74+
5. Document bypass instructions in README
75+
76+
## Code Quality Standards
77+
78+
### Shell Scripts (Bash/Zsh)
79+
80+
1. Use `set -e` for strict error handling
81+
2. Use functions over one-liners for readability
82+
3. Use descriptive variable names in UPPER_CASE
83+
4. Use `# === Section Name ===` for section headers
84+
5. Use consistent colors for output (defined in common.sh)
85+
6. Quote all variables properly: `"$VAR"`
86+
7. Check command existence before using: `if cmd_exists tool; then`
87+
88+
### PowerShell Scripts
89+
90+
1. Use approved verb-noun for function names
91+
2. Use `param()` blocks for parameters
92+
3. Use `Should -Be*` assertions in Pester tests
93+
4. Use `try { } catch { }` for error handling
94+
5. Use `Write-Host` with colors for output
95+
6. Use `ErrorActionPreference` appropriately
96+
7. Use `Get-Command` with `-ErrorAction SilentlyContinue`
97+
98+
### Configuration Files
99+
100+
1. Use YAML for configs (if applicable)
101+
2. Provide `.example` files with all options
102+
3. Document each option clearly
103+
4. Use sensible defaults
104+
5. Support environment variable overrides
105+
106+
## Testing Standards
107+
108+
### Unit Tests
109+
110+
1. Test each function independently
111+
2. Test error paths (missing tools, invalid input)
112+
3. Test edge cases (empty strings, special characters)
113+
4. Mock external dependencies where possible
114+
5. Use descriptive test names: `test_function_name_situation`
115+
116+
### Integration Tests
117+
118+
1. Test complete workflows (bootstrap → deploy → healthcheck)
119+
2. Test on clean environment (temporary directory)
120+
3. Test error recovery (what happens if install fails?)
121+
4. Test idempotency (run script twice)
122+
5. Test rollback scenarios
123+
124+
### Test Coverage Goals
125+
126+
- Parameter parsing: 100%
127+
- Platform detection: 100%
128+
- Core functions: 80%+
129+
- Error handling paths: 70%+
130+
- Integration workflows: 100%
131+
132+
## Documentation Standards
133+
134+
### README.md
135+
136+
1. Keep installation instructions current
137+
2. Update feature lists when adding/removing
138+
3. Document all environment variables
139+
4. Update "What Gets Installed" table
140+
5. Include troubleshooting section
141+
6. Add examples for common use cases
142+
143+
### Code Comments
144+
145+
1. Comment complex logic (why, not just what)
146+
2. Document non-obvious parameters
147+
3. Reference relevant documentation URLs
148+
4. Keep comments concise and relevant
149+
5. Remove outdated comments
150+
151+
## Error Handling
152+
153+
### Display Format
154+
155+
```
156+
[ERROR] Short, actionable description
157+
[WARN] Potential issue that needs attention
158+
[INFO] Informational message
159+
[OK] Success message
160+
```
161+
162+
### Error Messages
163+
164+
1. Start with what failed: "Failed to install: neovim"
165+
2. Include likely cause: "Scoop is not installed"
166+
3. Provide clear solution: "Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser"
167+
4. Never expose stack traces to users unless in debug mode
168+
5. Include relevant file paths for troubleshooting
169+
170+
### Exit Codes
171+
172+
- `0`: Success
173+
- `1`: General error
174+
- `2`: Invalid arguments
175+
- `124`: Timeout
176+
- `126`: Command not found
177+
- `127`: Command not executable
178+
179+
## Platform-Specific Guidelines
180+
181+
### Windows (PowerShell)
182+
183+
1. Use `$env:VARIABLE` for environment variables
184+
2. Use `Join-Path $path "subpath"` for path construction
185+
3. Use `Split-Path $path -Parent` for directory extraction
186+
4. Handle OneDrive Documents folder correctly
187+
5. Use PowerShell 7+ features when available
188+
6. Test in both Windows PowerShell and PowerShell 7
189+
190+
### Linux/macOS (Bash/Zsh)
191+
192+
1. Use `[[ ]]` for string comparisons (POSIX compliant)
193+
2. Use `command -v` instead of `which` (more portable)
194+
3. Handle macOS Homebrew paths correctly (`/opt/homebrew` vs `/usr/local`)
195+
4. Use `$HOME` instead of `~` in scripts (more reliable)
196+
5. Use `chmod +x` for scripts before first use
197+
6. Test on multiple distros if possible
198+
199+
## Alias Guidelines
200+
201+
### Naming Conventions
202+
203+
- Git: `g` + abbreviation (`gs`, `gl`, `gp`, `gcm`)
204+
- Docker: `d` + abbreviation (`ds`, `dx`, `dp`, `dc`)
205+
- File ops: Single letter (`n`, `b`, `f`, `t`)
206+
- Tools: Single letter if common (`m`, `ff`, `df`)
207+
208+
### Cross-Platform Consistency
209+
210+
- Same aliases must work on Bash, Zsh, and PowerShell
211+
- Test alias on all platforms before committing
212+
- Document platform-specific differences in comments
213+
- Handle conflicts with built-in commands appropriately
214+
215+
## Version Management
216+
217+
### Pinning Packages
218+
219+
1. Pin specific versions where stability matters
220+
2. Use minimum version constraints for SDKs
221+
3. Keep version in config file (`.dotfiles.config.yaml`)
222+
4. Document reasons for version pinning
223+
224+
### Updating Dependencies
225+
226+
1. Always run tests after updates
227+
2. Test backward compatibility
228+
3. Provide migration guide if breaking changes
229+
4. Update CHANGELOG or use Git commits for history
230+
231+
## Security Considerations
232+
233+
### Input Validation
234+
235+
1. Validate all file paths
236+
2. Sanitize environment variables
237+
3. Validate configuration values
238+
4. Reject obviously malicious inputs
239+
240+
### Safe Defaults
241+
242+
1. Don't enable auto-update by default
243+
2. Don't expose debug mode to internet
244+
3. Use secure defaults for SSH/Git config
245+
4. Require explicit consent for destructive operations
246+
247+
### Secret Management
248+
249+
1. Never hardcode API keys
250+
2. Use environment variables or secure storage
251+
3. Exclude secrets from git (check `.gitignore`)
252+
4. Provide example configs with placeholders
253+
254+
## Performance
255+
256+
### Parallel Execution
257+
258+
1. Run independent operations in parallel where safe
259+
2. Use appropriate parallelization for each platform:
260+
- Bash: `&` background jobs, `wait`
261+
- PowerShell: `Start-Job`, `Wait-Job`
262+
3. Don't exceed system resources
263+
4. Add timeouts to long-running operations
264+
265+
### Caching
266+
267+
1. Cache GitHub API responses in git-update-repos
268+
2. Use local package caches where available
269+
3. Cache tool availability checks
270+
4. Respect cache TTLs and invalidation
271+
272+
## When in Doubt
273+
274+
1. Check existing patterns in the codebase
275+
2. Review AGENTS.md for agent behavior guidelines
276+
3. Ask for clarification if requirements are ambiguous
277+
4. Prefer simpler, boring solutions over clever ones
278+
5. Focus on maintainability over clever optimizations
279+
280+
## Resources
281+
282+
- [CLAUDE.md](./CLAUDE.md) - AI assistant instructions
283+
- [AGENTS.md](./AGENTS.md) - Agent-specific behavior
284+
- [GEMINI.md](./GEMINI.md) - Gemini-specific instructions
285+
- [README.md](./README.md) - Usage documentation
286+
- [tests/README.md](tests/README.md) - Testing guidelines
2287

0 commit comments

Comments
 (0)