Skip to content

Commit 22d6784

Browse files
chousweichouswei
committed
Release v0.4.4: skills with design patterns, TOOLS reference, docs and script updates
Made-with: Cursor
1 parent eb94cde commit 22d6784

20 files changed

Lines changed: 1221 additions & 13 deletions

File tree

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

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
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+
metadata:
5+
pattern: tool-wrapper
6+
domain: gitnexus
7+
---
8+
9+
# GitNexus CLI Commands
10+
11+
All commands work via `npx` — no global install required.
12+
13+
## Commands
14+
15+
### analyze — Build or refresh the index
16+
17+
```bash
18+
npx gitnexus analyze
19+
```
20+
21+
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.
22+
23+
| Flag | Effect |
24+
| -------------- | ---------------------------------------------------------------- |
25+
| `--force` | Force full re-index even if up to date |
26+
| `--embeddings` | Enable embedding generation for semantic search (off by default) |
27+
28+
**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
29+
30+
### status — Check index freshness
31+
32+
```bash
33+
npx gitnexus status
34+
```
35+
36+
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.
37+
38+
### clean — Delete the index
39+
40+
```bash
41+
npx gitnexus clean
42+
```
43+
44+
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.
45+
46+
| Flag | Effect |
47+
| --------- | ------------------------------------------------- |
48+
| `--force` | Skip confirmation prompt |
49+
| `--all` | Clean all indexed repos, not just the current one |
50+
51+
### wiki — Generate documentation from the graph
52+
53+
```bash
54+
npx gitnexus wiki
55+
```
56+
57+
Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
58+
59+
| Flag | Effect |
60+
| ------------------- | ----------------------------------------- |
61+
| `--force` | Force full regeneration |
62+
| `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
63+
| `--base-url <url>` | LLM API base URL |
64+
| `--api-key <key>` | LLM API key |
65+
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
66+
| `--gist` | Publish wiki as a public GitHub Gist |
67+
68+
### list — Show all indexed repos
69+
70+
```bash
71+
npx gitnexus list
72+
```
73+
74+
Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
75+
76+
## After Indexing
77+
78+
1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
79+
2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
80+
81+
## Troubleshooting
82+
83+
- **"Not inside a git repository"**: Run from a directory inside a git repo
84+
- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
85+
- **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: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
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+
metadata:
5+
pattern: pipeline
6+
steps: "4"
7+
---
8+
9+
# Debugging with GitNexus
10+
11+
Execute the workflow steps in order. Do NOT skip steps or proceed to the next step until the current one is complete.
12+
13+
## When to Use
14+
15+
- "Why is this function failing?"
16+
- "Trace where this error comes from"
17+
- "Who calls this method?"
18+
- "This endpoint returns 500"
19+
- Investigating bugs, errors, or unexpected behavior
20+
21+
## Workflow
22+
23+
```
24+
1. gitnexus_query({query: "<error or symptom>"}) → Find related execution flows
25+
2. gitnexus_context({name: "<suspect>"}) → See callers/callees/processes
26+
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
27+
4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed
28+
```
29+
30+
> If "Index is stale" → run `npx gitnexus analyze` in terminal.
31+
32+
## Checklist
33+
34+
```
35+
- [ ] Understand the symptom (error message, unexpected behavior)
36+
- [ ] gitnexus_query for error text or related code
37+
- [ ] Identify the suspect function from returned processes
38+
- [ ] gitnexus_context to see callers and callees
39+
- [ ] Trace execution flow via process resource if applicable
40+
- [ ] gitnexus_cypher for custom call chain traces if needed
41+
- [ ] Read source files to confirm root cause
42+
```
43+
44+
## Debugging Patterns
45+
46+
| Symptom | GitNexus Approach |
47+
| -------------------- | ---------------------------------------------------------- |
48+
| Error message | `gitnexus_query` for error text → `context` on throw sites |
49+
| Wrong return value | `context` on the function → trace callees for data flow |
50+
| Intermittent failure | `context` → look for external calls, async deps |
51+
| Performance issue | `context` → find symbols with many callers (hot paths) |
52+
| Recent regression | `detect_changes` to see what your changes affect |
53+
54+
## Tools
55+
56+
**gitnexus_query** — find code related to error:
57+
58+
```
59+
gitnexus_query({query: "payment validation error"})
60+
→ Processes: CheckoutFlow, ErrorHandling
61+
→ Symbols: validatePayment, handlePaymentError, PaymentException
62+
```
63+
64+
**gitnexus_context** — full context for a suspect:
65+
66+
```
67+
gitnexus_context({name: "validatePayment"})
68+
→ Incoming calls: processCheckout, webhookHandler
69+
→ Outgoing calls: verifyCard, fetchRates (external API!)
70+
→ Processes: CheckoutFlow (step 3/7)
71+
```
72+
73+
**gitnexus_cypher** — custom call chain traces:
74+
75+
```cypher
76+
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
77+
RETURN [n IN nodes(path) | n.name] AS chain
78+
```
79+
80+
## Example: "Payment endpoint returns 500 intermittently"
81+
82+
```
83+
1. gitnexus_query({query: "payment error handling"})
84+
→ Processes: CheckoutFlow, ErrorHandling
85+
→ Symbols: validatePayment, handlePaymentError
86+
87+
2. gitnexus_context({name: "validatePayment"})
88+
→ Outgoing calls: verifyCard, fetchRates (external API!)
89+
90+
3. READ gitnexus://repo/my-app/process/CheckoutFlow
91+
→ Step 3: validatePayment → calls fetchRates (external)
92+
93+
4. Root cause: fetchRates calls external API without proper timeout
94+
```

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

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

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

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

0 commit comments

Comments
 (0)