Skip to content

Commit b002a8c

Browse files
bordumbbordumb
authored
Merge pull request #164 from auths-dev/dev-keriStandardize
refactor: centralize all KERI protocol logic into auths-keri
2 parents a38a3f8 + c901f6f commit b002a8c

110 files changed

Lines changed: 4490 additions & 5759 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/gitnexus/gitnexus-cli/SKILL.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
name: gitnexus-cli
3+
description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
4+
---
5+
6+
# GitNexus CLI Commands
7+
8+
All commands work via `npx` — no global install required.
9+
10+
## Commands
11+
12+
### analyze — Build or refresh the index
13+
14+
```bash
15+
npx gitnexus analyze
16+
```
17+
18+
Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
19+
20+
| Flag | Effect |
21+
| -------------- | ---------------------------------------------------------------- |
22+
| `--force` | Force full re-index even if up to date |
23+
| `--embeddings` | Enable embedding generation for semantic search (off by default) |
24+
25+
**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
26+
27+
### status — Check index freshness
28+
29+
```bash
30+
npx gitnexus status
31+
```
32+
33+
Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
34+
35+
### clean — Delete the index
36+
37+
```bash
38+
npx gitnexus clean
39+
```
40+
41+
Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
42+
43+
| Flag | Effect |
44+
| --------- | ------------------------------------------------- |
45+
| `--force` | Skip confirmation prompt |
46+
| `--all` | Clean all indexed repos, not just the current one |
47+
48+
### wiki — Generate documentation from the graph
49+
50+
```bash
51+
npx gitnexus wiki
52+
```
53+
54+
Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
55+
56+
| Flag | Effect |
57+
| ------------------- | ----------------------------------------- |
58+
| `--force` | Force full regeneration |
59+
| `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
60+
| `--base-url <url>` | LLM API base URL |
61+
| `--api-key <key>` | LLM API key |
62+
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
63+
| `--gist` | Publish wiki as a public GitHub Gist |
64+
65+
### list — Show all indexed repos
66+
67+
```bash
68+
npx gitnexus list
69+
```
70+
71+
Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
72+
73+
## After Indexing
74+
75+
1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
76+
2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
77+
78+
## Troubleshooting
79+
80+
- **"Not inside a git repository"**: Run from a directory inside a git repo
81+
- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
82+
- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

‎.claude/skills/gitnexus/gitnexus-debugging/SKILL.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
name: gitnexus-debugging
3+
description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
4+
---
5+
6+
# Debugging with GitNexus
7+
8+
## When to Use
9+
10+
- "Why is this function failing?"
11+
- "Trace where this error comes from"
12+
- "Who calls this method?"
13+
- "This endpoint returns 500"
14+
- Investigating bugs, errors, or unexpected behavior
15+
16+
## Workflow
17+
18+
```
19+
1. gitnexus_query({query: "<error or symptom>"}) → Find related execution flows
20+
2. gitnexus_context({name: "<suspect>"}) → See callers/callees/processes
21+
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
22+
4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed
23+
```
24+
25+
> If "Index is stale" → run `npx gitnexus analyze` in terminal.
26+
27+
## Checklist
28+
29+
```
30+
- [ ] Understand the symptom (error message, unexpected behavior)
31+
- [ ] gitnexus_query for error text or related code
32+
- [ ] Identify the suspect function from returned processes
33+
- [ ] gitnexus_context to see callers and callees
34+
- [ ] Trace execution flow via process resource if applicable
35+
- [ ] gitnexus_cypher for custom call chain traces if needed
36+
- [ ] Read source files to confirm root cause
37+
```
38+
39+
## Debugging Patterns
40+
41+
| Symptom | GitNexus Approach |
42+
| -------------------- | ---------------------------------------------------------- |
43+
| Error message | `gitnexus_query` for error text → `context` on throw sites |
44+
| Wrong return value | `context` on the function → trace callees for data flow |
45+
| Intermittent failure | `context` → look for external calls, async deps |
46+
| Performance issue | `context` → find symbols with many callers (hot paths) |
47+
| Recent regression | `detect_changes` to see what your changes affect |
48+
49+
## Tools
50+
51+
**gitnexus_query** — find code related to error:
52+
53+
```
54+
gitnexus_query({query: "payment validation error"})
55+
→ Processes: CheckoutFlow, ErrorHandling
56+
→ Symbols: validatePayment, handlePaymentError, PaymentException
57+
```
58+
59+
**gitnexus_context** — full context for a suspect:
60+
61+
```
62+
gitnexus_context({name: "validatePayment"})
63+
→ Incoming calls: processCheckout, webhookHandler
64+
→ Outgoing calls: verifyCard, fetchRates (external API!)
65+
→ Processes: CheckoutFlow (step 3/7)
66+
```
67+
68+
**gitnexus_cypher** — custom call chain traces:
69+
70+
```cypher
71+
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
72+
RETURN [n IN nodes(path) | n.name] AS chain
73+
```
74+
75+
## Example: "Payment endpoint returns 500 intermittently"
76+
77+
```
78+
1. gitnexus_query({query: "payment error handling"})
79+
→ Processes: CheckoutFlow, ErrorHandling
80+
→ Symbols: validatePayment, handlePaymentError
81+
82+
2. gitnexus_context({name: "validatePayment"})
83+
→ Outgoing calls: verifyCard, fetchRates (external API!)
84+
85+
3. READ gitnexus://repo/my-app/process/CheckoutFlow
86+
→ Step 3: validatePayment → calls fetchRates (external)
87+
88+
4. Root cause: fetchRates calls external API without proper timeout
89+
```

‎.claude/skills/gitnexus/gitnexus-exploring/SKILL.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
name: gitnexus-exploring
3+
description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
4+
---
5+
6+
# Exploring Codebases with GitNexus
7+
8+
## When to Use
9+
10+
- "How does authentication work?"
11+
- "What's the project structure?"
12+
- "Show me the main components"
13+
- "Where is the database logic?"
14+
- Understanding code you haven't seen before
15+
16+
## Workflow
17+
18+
```
19+
1. READ gitnexus://repos → Discover indexed repos
20+
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
21+
3. gitnexus_query({query: "<what you want to understand>"}) → Find related execution flows
22+
4. gitnexus_context({name: "<symbol>"}) → Deep dive on specific symbol
23+
5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow
24+
```
25+
26+
> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
27+
28+
## Checklist
29+
30+
```
31+
- [ ] READ gitnexus://repo/{name}/context
32+
- [ ] gitnexus_query for the concept you want to understand
33+
- [ ] Review returned processes (execution flows)
34+
- [ ] gitnexus_context on key symbols for callers/callees
35+
- [ ] READ process resource for full execution traces
36+
- [ ] Read source files for implementation details
37+
```
38+
39+
## Resources
40+
41+
| Resource | What you get |
42+
| --------------------------------------- | ------------------------------------------------------- |
43+
| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
44+
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
45+
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
46+
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
47+
48+
## Tools
49+
50+
**gitnexus_query** — find execution flows related to a concept:
51+
52+
```
53+
gitnexus_query({query: "payment processing"})
54+
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
55+
→ Symbols grouped by flow with file locations
56+
```
57+
58+
**gitnexus_context** — 360-degree view of a symbol:
59+
60+
```
61+
gitnexus_context({name: "validateUser"})
62+
→ Incoming calls: loginHandler, apiMiddleware
63+
→ Outgoing calls: checkToken, getUserById
64+
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
65+
```
66+
67+
## Example: "How does payment processing work?"
68+
69+
```
70+
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
71+
2. gitnexus_query({query: "payment processing"})
72+
→ CheckoutFlow: processPayment → validateCard → chargeStripe
73+
→ RefundFlow: initiateRefund → calculateRefund → processRefund
74+
3. gitnexus_context({name: "processPayment"})
75+
→ Incoming: checkoutHandler, webhookHandler
76+
→ Outgoing: validateCard, chargeStripe, saveTransaction
77+
4. Read src/payments/processor.ts for implementation details
78+
```

‎.claude/skills/gitnexus/gitnexus-guide/SKILL.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
name: gitnexus-guide
3+
description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
4+
---
5+
6+
# GitNexus Guide
7+
8+
Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
9+
10+
## Always Start Here
11+
12+
For any task involving code understanding, debugging, impact analysis, or refactoring:
13+
14+
1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
15+
2. **Match your task to a skill below** and **read that skill file**
16+
3. **Follow the skill's workflow and checklist**
17+
18+
> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
19+
20+
## Skills
21+
22+
| Task | Skill to read |
23+
| -------------------------------------------- | ------------------- |
24+
| Understand architecture / "How does X work?" | `gitnexus-exploring` |
25+
| Blast radius / "What breaks if I change X?" | `gitnexus-impact-analysis` |
26+
| Trace bugs / "Why is X failing?" | `gitnexus-debugging` |
27+
| Rename / extract / split / refactor | `gitnexus-refactoring` |
28+
| Tools, resources, schema reference | `gitnexus-guide` (this file) |
29+
| Index, status, clean, wiki CLI commands | `gitnexus-cli` |
30+
31+
## Tools Reference
32+
33+
| Tool | What it gives you |
34+
| ---------------- | ------------------------------------------------------------------------ |
35+
| `query` | Process-grouped code intelligence — execution flows related to a concept |
36+
| `context` | 360-degree symbol view — categorized refs, processes it participates in |
37+
| `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
38+
| `detect_changes` | Git-diff impact — what do your current changes affect |
39+
| `rename` | Multi-file coordinated rename with confidence-tagged edits |
40+
| `cypher` | Raw graph queries (read `gitnexus://repo/{name}/schema` first) |
41+
| `list_repos` | Discover indexed repos |
42+
43+
## Resources Reference
44+
45+
Lightweight reads (~100-500 tokens) for navigation:
46+
47+
| Resource | Content |
48+
| ---------------------------------------------- | ----------------------------------------- |
49+
| `gitnexus://repo/{name}/context` | Stats, staleness check |
50+
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores |
51+
| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members |
52+
| `gitnexus://repo/{name}/processes` | All execution flows |
53+
| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace |
54+
| `gitnexus://repo/{name}/schema` | Graph schema for Cypher |
55+
56+
## Graph Schema
57+
58+
**Nodes:** File, Function, Class, Interface, Method, Community, Process
59+
**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
60+
61+
```cypher
62+
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
63+
RETURN caller.name, caller.filePath
64+
```

0 commit comments

Comments
 (0)