ptr.pet
at protocol indexer with flexible filtering, xrpc queries, and a cursor-backed event stream, built on fjall
at-protocol
atproto
indexer
rust
fjall
[agents] use gitnexus
+79
AGENTS.md
+79
AGENTS.md
···
113
113
- `[ingest] implement backfill buffer replay`
114
114
- `[api] add accurate count parameter to stats`
115
115
- `[db] migrate block storage to msgpack`
116
+
117
+
<!-- gitnexus:start -->
118
+
# GitNexus — Code Intelligence
119
+
120
+
This project is indexed by GitNexus as **hydrant** (599 symbols, 1624 relationships, 51 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
121
+
122
+
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
123
+
124
+
## Always Do
125
+
126
+
- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
127
+
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
128
+
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
129
+
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
130
+
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
131
+
132
+
## When Debugging
133
+
134
+
1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
135
+
2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
136
+
3. `READ gitnexus://repo/hydrant/process/{processName}` — trace the full execution flow step by step
137
+
4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
138
+
139
+
## When Refactoring
140
+
141
+
- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
142
+
- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
143
+
- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
144
+
145
+
## Never Do
146
+
147
+
- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
148
+
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
149
+
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
150
+
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
151
+
152
+
## Tools Quick Reference
153
+
154
+
| Tool | When to use | Command |
155
+
|------|-------------|---------|
156
+
| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
157
+
| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
158
+
| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
159
+
| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
160
+
| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
161
+
| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
162
+
163
+
## Impact Risk Levels
164
+
165
+
| Depth | Meaning | Action |
166
+
|-------|---------|--------|
167
+
| d=1 | WILL BREAK — direct callers/importers | MUST update these |
168
+
| d=2 | LIKELY AFFECTED — indirect deps | Should test |
169
+
| d=3 | MAY NEED TESTING — transitive | Test if critical path |
170
+
171
+
## Resources
172
+
173
+
| Resource | Use for |
174
+
|----------|---------|
175
+
| `gitnexus://repo/hydrant/context` | Codebase overview, check index freshness |
176
+
| `gitnexus://repo/hydrant/clusters` | All functional areas |
177
+
| `gitnexus://repo/hydrant/processes` | All execution flows |
178
+
| `gitnexus://repo/hydrant/process/{name}` | Step-by-step execution trace |
179
+
180
+
## Self-Check Before Finishing
181
+
182
+
Before completing any code modification task, verify:
183
+
1. `gitnexus_impact` was run for all modified symbols
184
+
2. No HIGH/CRITICAL risk warnings were ignored
185
+
3. `gitnexus_detect_changes()` confirms changes match expected scope
186
+
4. All d=1 (WILL BREAK) dependents were updated
187
+
188
+
## CLI
189
+
190
+
- Re-index: `npx gitnexus analyze`
191
+
- Check freshness: `npx gitnexus status`
192
+
- Generate docs: `npx gitnexus wiki`
193
+
194
+
<!-- gitnexus:end -->