Skip to content

Commit 5ded7a5

Browse files
tmmtmm
committed
chore: oc tweaks
1 parent 06ed8b5 commit 5ded7a5

File tree

2 files changed

+274
-0
lines changed

2 files changed

+274
-0
lines changed

‎nix/files/AGENTS.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,278 @@
11
# Global Agent Guidelines
22

3+
This guide provides comprehensive instructions for agents working with team members on development projects. It synthesizes best practices, workflows, and critical guidelines to ensure effective and safe code contributions.
4+
5+
## Directory Structure and Purpose
6+
7+
Your projects directory contains various git repositories for reference and development. Each subdirectory is typically an independent git repository used for finding code examples, implementations, and reference material.
8+
9+
**CRITICAL**: Reference repositories are for REFERENCE ONLY. Do not modify git configurations or remotes in these repositories.
10+
11+
## Essential Workflow Rules
12+
13+
### 1. Working Directory Guidelines
14+
15+
- **Read/explore**: Your main projects directory (reference repositories)
16+
- **Modify/experiment**: A dedicated workspace directory for isolated changes
17+
18+
**ALWAYS check if a repository is already cloned locally before attempting to fetch from the web!** Use `ls` or check the directory structure to see if the project you need is already present before cloning it for reference.
19+
20+
### 2. Code Modification Workflow
21+
22+
When working on code changes:
23+
24+
1. **Always work in a dedicated workspace directory**
25+
2. **Use git worktrees** for creating isolated workspaces from existing repos
26+
3. **Only use git clone if the repository doesn't exist locally**
27+
4. **NEVER modify the remotes of existing reference repositories**
28+
29+
#### Git Worktree Workflow (Preferred)
30+
31+
Git worktrees allow multiple working directories from a single repository, perfect for parallel work:
32+
33+
```bash
34+
# First, check if the repo exists in your workspace
35+
cd ~/projects # or your designated workspace directory
36+
ls -la | grep REPO_NAME
37+
38+
# If repo exists, create a worktree
39+
cd ~/projects/REPO_NAME
40+
git worktree add ../REPO_NAME-FEATURE-PURPOSE -b feature-branch
41+
42+
# If repo doesn't exist, clone it first (check for your fork)
43+
gh repo view YOUR_USERNAME/REPO_NAME --web 2>/dev/null || echo "No fork found"
44+
45+
# Clone from your fork if it exists
46+
git clone [email protected]:YOUR_USERNAME/REPO_NAME.git REPO_NAME
47+
cd REPO_NAME
48+
git remote add upstream [email protected]:ORIGINAL_ORG/REPO_NAME.git
49+
50+
# Or clone from original if no fork
51+
git clone [email protected]:ORIGINAL_ORG/REPO_NAME.git REPO_NAME
52+
```
53+
54+
#### Worktree Management
55+
56+
```bash
57+
# List all worktrees for a repo
58+
git worktree list
59+
60+
# Create a new worktree for a feature
61+
git worktree add ../repo-optimization -b optimize-feature
62+
63+
# Remove a worktree when done
64+
git worktree remove ../repo-optimization
65+
66+
# Clean up worktree references
67+
git worktree prune
68+
```
69+
70+
Use descriptive worktree names that indicate purpose:
71+
- `gitchat-add-message-notification-queue`
72+
- `repo-name-issue-123`
73+
- `project-feature-description`
74+
75+
**Benefits of worktrees**:
76+
- Share the same git history and objects (saves disk space)
77+
- Switch between features instantly without stashing
78+
- Keep multiple experiments running in parallel
79+
- Easier cleanup - just remove the worktree directory
80+
81+
#### Workspace Maintenance
82+
83+
**Clean up build artifacts** when disk space is needed:
84+
```bash
85+
# For Rust projects
86+
cd ~/projects/repo-name
87+
pnpm clean # check package.json for specific clean script
88+
rm -rf dist/ # can delete dist or build output dir directly
89+
```
90+
91+
**When to clean up workspaces**:
92+
- After PR has been merged
93+
- When changes have been abandoned
94+
- Before removing a worktree
95+
96+
```bash
97+
# Clean and remove a worktree
98+
cd ~/projects/repo-name
99+
git worktree remove ../repo-name-issue-123
100+
```
101+
102+
### 3. Git Workflow
103+
104+
When working on code:
105+
106+
1. Create feature branches for your work
107+
2. Commit changes with clear messages
108+
3. Use descriptive branch names: `name/fix-something`, `name/add-feature`, `name/make-biome-happy-123456`
109+
110+
### 4. GitHub CLI (gh) Usage
111+
112+
The `gh` CLI tool is available for exploring GitHub repositories and understanding code context.
113+
114+
#### Allowed Operations
115+
116+
```bash
117+
# Repository exploration
118+
gh repo view owner/repo
119+
gh repo clone owner/repo # For initial clones
120+
121+
# Issues and PRs
122+
gh issue list --repo owner/repo
123+
gh issue view 123 --repo owner/repo
124+
gh pr list --repo owner/repo
125+
gh pr view 456 --repo owner/repo
126+
gh pr diff 456 --repo owner/repo
127+
gh pr checkout 456 # To examine PR branches locally
128+
129+
# API queries
130+
gh api repos/owner/repo/pulls/123/comments
131+
gh api repos/owner/repo/issues/123/comments
132+
133+
# Search operations
134+
gh search issues "query" --repo owner/repo
135+
gh search prs "query" --repo owner/repo
136+
137+
# Status and authentication
138+
gh auth status
139+
gh status
140+
141+
# Releases and workflows (read-only)
142+
gh release list --repo owner/repo
143+
gh release view v1.0.0 --repo owner/repo
144+
gh workflow list --repo owner/repo
145+
gh run list --workflow=ci.yml --repo owner/repo
146+
```
147+
#### Common Use Cases
148+
149+
1. **Examining PR discussions**:
150+
```bash
151+
gh pr view 123 --comments
152+
gh api repos/wevm/wagmi/pulls/123/comments | jq '.[].body'
153+
```
154+
155+
2. **Finding related issues**:
156+
```bash
157+
gh search issues "performance" --repo wevm/wagmi --state open
158+
```
159+
160+
3. **Checking PR changes**:
161+
```bash
162+
gh pr diff 456 --repo owner/repo
163+
```
164+
165+
## Task-Specific Guidelines
166+
167+
### Writing Code
168+
169+
1. **Follow existing patterns** - Study how the project structures similar code
170+
2. **Check dependencies first** - Never assume a library is available
171+
3. **Maintain consistency** - Use the project's naming conventions and style
172+
4. **Security first** - Never expose secrets or keys in code
173+
174+
### Commit Message Best Practices
175+
176+
Writing excellent commit messages is crucial - they become the permanent record of why changes were made.
177+
178+
#### Commit Title Format
179+
180+
Use semantic commit format with a clear, specific title:
181+
- `feat:` - New features
182+
- `fix:` - Bug fixes
183+
- `perf:` - Performance improvements
184+
- `chore:` - Maintenance tasks
185+
- `docs:` - Documentation
186+
- `test:` - Test changes
187+
- `refactor:` - Code restructuring
188+
- `ci:` - CI/CD changes
189+
190+
**Title guidelines**:
191+
- Be specific: `perf: add specialized multiplication for 8 limbs` not `perf: optimize mul`
192+
- Use imperative mood: "add" not "adds" or "added"
193+
- Keep under 50 characters when possible
194+
- Don't end with a period
195+
196+
#### Commit Description (Body)
197+
198+
The commit body is where you provide context and details about a specific commit. **This is different from PR descriptions**. Many commits do not have
199+
descriptions.
200+
201+
**When to add a body**:
202+
- Breaking changes (note the impact)
203+
- Non-obvious changes (explain why, not what)
204+
- When a commit is very complex or cannot be split up, and is not the only distinct change in the branch or PR
205+
206+
**Format**:
207+
```
208+
<title line>
209+
<blank line>
210+
<body>
211+
<blank line>
212+
<footer>
213+
```
214+
215+
#### Examples
216+
217+
**Performance improvement** (body required):
218+
```
219+
perf: add specialized multiplication for 8 limbs
220+
221+
Benchmarks show ~2.7x speedup for 512-bit operations:
222+
- Before: ~41ns
223+
- After: ~15ns
224+
225+
This follows the existing pattern of specialized implementations
226+
for sizes 1-4, extending to size 8 which is commonly used.
227+
```
228+
229+
**Bug fix** (explain the issue):
230+
```
231+
fix: correct carry propagation in uint addition
232+
233+
The carry bit was not properly propagated when the first limb
234+
overflowed but subsequent limbs were at MAX-1. This caused
235+
incorrect results for specific input patterns.
236+
237+
Added test case that reproduces the issue.
238+
```
239+
240+
**Simple feature** (title often sufficient):
241+
```
242+
feat: add From<u128> implementation for Uint<256>
243+
```
244+
245+
**Complex change** (needs explanation):
246+
```
247+
refactor: split trie updates into parallel work queues
248+
249+
Previous implementation processed all trie updates sequentially,
250+
creating a bottleneck during state root calculation. This change:
251+
252+
- Partitions updates by key prefix
253+
- Processes non-conflicting updates in parallel
254+
- Falls back to sequential for conflicts
255+
- Maintains deterministic ordering
256+
257+
Reduces state root time from 120ms to 35ms on 16-core machines.
258+
```
259+
260+
#### What NOT to Do
261+
262+
- Don't write generic descriptions: "Update code", "Fix bug"
263+
- Don't use many bullet points unless listing multiple distinct changes
264+
- Don't make up metrics without measurements
265+
- Don't write essays - be concise but complete
266+
267+
#### Key Principles
268+
269+
1. **The title should make sense in a changelog**
270+
2. **The body should explain to a future developer why this change was necessary**
271+
3. **Include concrete measurements for performance claims**
272+
4. **Reference issues when fixing bugs**: `Fixes #12345`
273+
5. **Let improvements stand on their own merit** - don't invent generic justifications
274+
6. **Match detail to complexity** - Simple changes need simple descriptions
275+
3276
## Critical Reminders
4277

5278
### DO NOT

‎nix/modules/opencode.nix‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ in
77

88
xdg.configFile."opencode/opencode.json".text = builtins.toJSON {
99
"$schema" = "https://opencode.ai/config.json";
10+
disabled_providers = [ "openai" "gemini" ];
1011
theme = "tmm";
1112
};
1213

0 commit comments

Comments
 (0)