Skip to content

Commit ae067e0

Browse files
vikrantdvikrantd
authored
Merge pull request #1 from vikrantd/vector_support
Vector support
2 parents a13caa8 + 77e208d commit ae067e0

65 files changed

Lines changed: 9872 additions & 5933 deletions

Some content is hidden

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

‎.agents/skills/tldrgraph-init/SKILL.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
name: tldrgraph-init
3+
description: Build or continue this repository's TLDRGraph architecture graph (layers, extraction, enrichment)
4+
---
5+
6+
# TLDRGraph: build this repository's architecture graph
7+
8+
One command, run repeatedly until it says DONE. `tldrgraph init` never guesses:
9+
it stops and tells you exactly what it needs.
10+
11+
```bash
12+
tldrgraph init
13+
```
14+
15+
Read the `NEXT ACTION` block it prints, do what it says, then run `tldrgraph init`
16+
again. Repeat until the output says `status: done`. There are only three things
17+
it can ask for.
18+
19+
## 1. `status: needs_layers`
20+
21+
TLDRGraph ships **no layer templates** and will not invent an architecture.
22+
Design one from this repository.
23+
24+
1. Read `.tldrgraph/propose_layers_request.json`. It carries the symbols and
25+
files extraction already found -- a starting point, not a substitute for
26+
opening the code.
27+
2. **Open real source files**: entry points first, then a representative file
28+
from each cluster in the evidence. Work out what this codebase actually does
29+
and where responsibility changes hands.
30+
3. Write `.tldrgraph/propose_layers_response.json`:
31+
32+
```json
33+
{
34+
"utility_id": "<id of your catch-all layer>",
35+
"layers": [
36+
{
37+
"id": "short_machine_id",
38+
"name": "Layer 1: Human Friendly Name",
39+
"order": 1,
40+
"description": "One sentence on what lives here",
41+
"rules": [
42+
{"file_contains": ["substring"], "exclude_file": ["optional"]},
43+
{"label_contains": ["SymbolNamePart"]}
44+
]
45+
}
46+
]
47+
}
48+
```
49+
50+
4. Run `tldrgraph init` again.
51+
52+
### What a layer set looks like
53+
54+
Sketches from other codebases, to show the *shape* of an answer. They are not a
55+
menu and none of them will fit this repository -- read the code and name what you
56+
actually find.
57+
58+
- A web app might split presentation from request handling from domain logic
59+
from persistence, with background jobs and deployment config as their own tiers.
60+
- A CLI tool might split the command surface from the processing engine from
61+
local state, with adapters to outside systems separate again.
62+
- A library might split its public API from the core implementation from its
63+
data types, with backend adapters separate.
64+
- A data pipeline might split ingestion from transformation from model training
65+
from serving.
66+
67+
The useful question is not "which of these is it?" but "where does responsibility
68+
change hands in *this* code, and what would a new engineer need named?"
69+
70+
### Rules that hold for any answer
71+
72+
- 3 to 6 layers, plus exactly one catch-all whose `id` equals `utility_id` and
73+
whose `rules` are `[]`.
74+
- Unique `id` and `name` per layer; sequential integer `order` from 1.
75+
- Rule keys: `file_contains`, `exclude_file`, `path_regex`, `label_contains`,
76+
`exclude_label`, `label_ends_with`, `type_in`, `id_prefix`. Values are lists of
77+
strings. Rules are evaluated in `order` and the first match wins.
78+
- Derive rules from paths and symbol names you actually saw. A rule matching
79+
nothing is worse than no rule; a rule matching everything collapses the map.
80+
81+
## 2. `status: needs_confirmation`
82+
83+
The output shows how many nodes need enrichment and how many agent round-trips
84+
that implies. **Ask the user whether to proceed, and show them that estimate.**
85+
Do not decide for them.
86+
87+
- They agree: `tldrgraph init --yes`
88+
- Smaller first pass: `tldrgraph init --yes --limit 100`
89+
- They decline: stop. The graph is already built and queryable.
90+
91+
## 3. `status: needs_enrichment`
92+
93+
1. Read `.tldrgraph/enrichment_request.yaml`.
94+
2. **Open the source file of every node in it.** This is the entire point: an
95+
intent paraphrased from a symbol name poisons semantic search with
96+
confident-sounding noise.
97+
3. Write `.tldrgraph/enrichment_response.yaml` -- a *different* file from the
98+
request, which is regenerated on every run:
99+
100+
```yaml
101+
- id: "<node id copied verbatim from the request>"
102+
intent: |
103+
What this symbol does, why it exists, and its execution logic.
104+
input_fields: [caseId, remarks]
105+
output_fields: [status, disposition]
106+
calls: [ApplicationsService, pension_cases]
107+
```
108+
109+
4. Run `tldrgraph init --yes` again. It applies the response and hands you the
110+
next batch, until there is nothing left.
111+
112+
**Copy every `id` verbatim.** A constructed id matches nothing, is dropped, and
113+
gets reported back to you -- but the work is wasted.
114+
115+
**Never invent `fields` or `calls`.** Omit what you cannot verify in the code: an
116+
empty list is a correct answer, a wrong `calls` entry becomes a real wrong edge.
117+
118+
## Once it says DONE
119+
120+
```bash
121+
tldrgraph query "<feature in plain English>"
122+
tldrgraph trace "<Source>" "<Target>"
123+
tldrgraph layers
124+
tldrgraph ui --serve
125+
```
126+
127+
Read-only, and they never trigger enrichment. Full schema:
128+
`.tldrgraph/AGENT_CONTRACT.md`.

‎.claude/commands/tldrgraph-init.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
name: tldrgraph-init
3+
description: Build or continue this repository's TLDRGraph architecture graph (layers, extraction, enrichment)
4+
---
5+
6+
# TLDRGraph: build this repository's architecture graph
7+
8+
One command, run repeatedly until it says DONE. `tldrgraph init` never guesses:
9+
it stops and tells you exactly what it needs.
10+
11+
```bash
12+
tldrgraph init
13+
```
14+
15+
Read the `NEXT ACTION` block it prints, do what it says, then run `tldrgraph init`
16+
again. Repeat until the output says `status: done`. There are only three things
17+
it can ask for.
18+
19+
## 1. `status: needs_layers`
20+
21+
TLDRGraph ships **no layer templates** and will not invent an architecture.
22+
Design one from this repository.
23+
24+
1. Read `.tldrgraph/propose_layers_request.json`. It carries the symbols and
25+
files extraction already found -- a starting point, not a substitute for
26+
opening the code.
27+
2. **Open real source files**: entry points first, then a representative file
28+
from each cluster in the evidence. Work out what this codebase actually does
29+
and where responsibility changes hands.
30+
3. Write `.tldrgraph/propose_layers_response.json`:
31+
32+
```json
33+
{
34+
"utility_id": "<id of your catch-all layer>",
35+
"layers": [
36+
{
37+
"id": "short_machine_id",
38+
"name": "Layer 1: Human Friendly Name",
39+
"order": 1,
40+
"description": "One sentence on what lives here",
41+
"rules": [
42+
{"file_contains": ["substring"], "exclude_file": ["optional"]},
43+
{"label_contains": ["SymbolNamePart"]}
44+
]
45+
}
46+
]
47+
}
48+
```
49+
50+
4. Run `tldrgraph init` again.
51+
52+
### What a layer set looks like
53+
54+
Sketches from other codebases, to show the *shape* of an answer. They are not a
55+
menu and none of them will fit this repository -- read the code and name what you
56+
actually find.
57+
58+
- A web app might split presentation from request handling from domain logic
59+
from persistence, with background jobs and deployment config as their own tiers.
60+
- A CLI tool might split the command surface from the processing engine from
61+
local state, with adapters to outside systems separate again.
62+
- A library might split its public API from the core implementation from its
63+
data types, with backend adapters separate.
64+
- A data pipeline might split ingestion from transformation from model training
65+
from serving.
66+
67+
The useful question is not "which of these is it?" but "where does responsibility
68+
change hands in *this* code, and what would a new engineer need named?"
69+
70+
### Rules that hold for any answer
71+
72+
- 3 to 6 layers, plus exactly one catch-all whose `id` equals `utility_id` and
73+
whose `rules` are `[]`.
74+
- Unique `id` and `name` per layer; sequential integer `order` from 1.
75+
- Rule keys: `file_contains`, `exclude_file`, `path_regex`, `label_contains`,
76+
`exclude_label`, `label_ends_with`, `type_in`, `id_prefix`. Values are lists of
77+
strings. Rules are evaluated in `order` and the first match wins.
78+
- Derive rules from paths and symbol names you actually saw. A rule matching
79+
nothing is worse than no rule; a rule matching everything collapses the map.
80+
81+
## 2. `status: needs_confirmation`
82+
83+
The output shows how many nodes need enrichment and how many agent round-trips
84+
that implies. **Ask the user whether to proceed, and show them that estimate.**
85+
Do not decide for them.
86+
87+
- They agree: `tldrgraph init --yes`
88+
- Smaller first pass: `tldrgraph init --yes --limit 100`
89+
- They decline: stop. The graph is already built and queryable.
90+
91+
## 3. `status: needs_enrichment`
92+
93+
1. Read `.tldrgraph/enrichment_request.yaml`.
94+
2. **Open the source file of every node in it.** This is the entire point: an
95+
intent paraphrased from a symbol name poisons semantic search with
96+
confident-sounding noise.
97+
3. Write `.tldrgraph/enrichment_response.yaml` -- a *different* file from the
98+
request, which is regenerated on every run:
99+
100+
```yaml
101+
- id: "<node id copied verbatim from the request>"
102+
intent: |
103+
What this symbol does, why it exists, and its execution logic.
104+
input_fields: [caseId, remarks]
105+
output_fields: [status, disposition]
106+
calls: [ApplicationsService, pension_cases]
107+
```
108+
109+
4. Run `tldrgraph init --yes` again. It applies the response and hands you the
110+
next batch, until there is nothing left.
111+
112+
**Copy every `id` verbatim.** A constructed id matches nothing, is dropped, and
113+
gets reported back to you -- but the work is wasted.
114+
115+
**Never invent `fields` or `calls`.** Omit what you cannot verify in the code: an
116+
empty list is a correct answer, a wrong `calls` entry becomes a real wrong edge.
117+
118+
## Once it says DONE
119+
120+
```bash
121+
tldrgraph query "<feature in plain English>"
122+
tldrgraph trace "<Source>" "<Target>"
123+
tldrgraph layers
124+
tldrgraph ui --serve
125+
```
126+
127+
Read-only, and they never trigger enrichment. Full schema:
128+
`.tldrgraph/AGENT_CONTRACT.md`.

‎.cursor/commands/tldrgraph-init.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
name: tldrgraph-init
3+
description: Build or continue this repository's TLDRGraph architecture graph (layers, extraction, enrichment)
4+
---
5+
6+
# TLDRGraph: build this repository's architecture graph
7+
8+
One command, run repeatedly until it says DONE. `tldrgraph init` never guesses:
9+
it stops and tells you exactly what it needs.
10+
11+
```bash
12+
tldrgraph init
13+
```
14+
15+
Read the `NEXT ACTION` block it prints, do what it says, then run `tldrgraph init`
16+
again. Repeat until the output says `status: done`. There are only three things
17+
it can ask for.
18+
19+
## 1. `status: needs_layers`
20+
21+
TLDRGraph ships **no layer templates** and will not invent an architecture.
22+
Design one from this repository.
23+
24+
1. Read `.tldrgraph/propose_layers_request.json`. It carries the symbols and
25+
files extraction already found -- a starting point, not a substitute for
26+
opening the code.
27+
2. **Open real source files**: entry points first, then a representative file
28+
from each cluster in the evidence. Work out what this codebase actually does
29+
and where responsibility changes hands.
30+
3. Write `.tldrgraph/propose_layers_response.json`:
31+
32+
```json
33+
{
34+
"utility_id": "<id of your catch-all layer>",
35+
"layers": [
36+
{
37+
"id": "short_machine_id",
38+
"name": "Layer 1: Human Friendly Name",
39+
"order": 1,
40+
"description": "One sentence on what lives here",
41+
"rules": [
42+
{"file_contains": ["substring"], "exclude_file": ["optional"]},
43+
{"label_contains": ["SymbolNamePart"]}
44+
]
45+
}
46+
]
47+
}
48+
```
49+
50+
4. Run `tldrgraph init` again.
51+
52+
### What a layer set looks like
53+
54+
Sketches from other codebases, to show the *shape* of an answer. They are not a
55+
menu and none of them will fit this repository -- read the code and name what you
56+
actually find.
57+
58+
- A web app might split presentation from request handling from domain logic
59+
from persistence, with background jobs and deployment config as their own tiers.
60+
- A CLI tool might split the command surface from the processing engine from
61+
local state, with adapters to outside systems separate again.
62+
- A library might split its public API from the core implementation from its
63+
data types, with backend adapters separate.
64+
- A data pipeline might split ingestion from transformation from model training
65+
from serving.
66+
67+
The useful question is not "which of these is it?" but "where does responsibility
68+
change hands in *this* code, and what would a new engineer need named?"
69+
70+
### Rules that hold for any answer
71+
72+
- 3 to 6 layers, plus exactly one catch-all whose `id` equals `utility_id` and
73+
whose `rules` are `[]`.
74+
- Unique `id` and `name` per layer; sequential integer `order` from 1.
75+
- Rule keys: `file_contains`, `exclude_file`, `path_regex`, `label_contains`,
76+
`exclude_label`, `label_ends_with`, `type_in`, `id_prefix`. Values are lists of
77+
strings. Rules are evaluated in `order` and the first match wins.
78+
- Derive rules from paths and symbol names you actually saw. A rule matching
79+
nothing is worse than no rule; a rule matching everything collapses the map.
80+
81+
## 2. `status: needs_confirmation`
82+
83+
The output shows how many nodes need enrichment and how many agent round-trips
84+
that implies. **Ask the user whether to proceed, and show them that estimate.**
85+
Do not decide for them.
86+
87+
- They agree: `tldrgraph init --yes`
88+
- Smaller first pass: `tldrgraph init --yes --limit 100`
89+
- They decline: stop. The graph is already built and queryable.
90+
91+
## 3. `status: needs_enrichment`
92+
93+
1. Read `.tldrgraph/enrichment_request.yaml`.
94+
2. **Open the source file of every node in it.** This is the entire point: an
95+
intent paraphrased from a symbol name poisons semantic search with
96+
confident-sounding noise.
97+
3. Write `.tldrgraph/enrichment_response.yaml` -- a *different* file from the
98+
request, which is regenerated on every run:
99+
100+
```yaml
101+
- id: "<node id copied verbatim from the request>"
102+
intent: |
103+
What this symbol does, why it exists, and its execution logic.
104+
input_fields: [caseId, remarks]
105+
output_fields: [status, disposition]
106+
calls: [ApplicationsService, pension_cases]
107+
```
108+
109+
4. Run `tldrgraph init --yes` again. It applies the response and hands you the
110+
next batch, until there is nothing left.
111+
112+
**Copy every `id` verbatim.** A constructed id matches nothing, is dropped, and
113+
gets reported back to you -- but the work is wasted.
114+
115+
**Never invent `fields` or `calls`.** Omit what you cannot verify in the code: an
116+
empty list is a correct answer, a wrong `calls` entry becomes a real wrong edge.
117+
118+
## Once it says DONE
119+
120+
```bash
121+
tldrgraph query "<feature in plain English>"
122+
tldrgraph trace "<Source>" "<Target>"
123+
tldrgraph layers
124+
tldrgraph ui --serve
125+
```
126+
127+
Read-only, and they never trigger enrichment. Full schema:
128+
`.tldrgraph/AGENT_CONTRACT.md`.

0 commit comments

Comments
 (0)