Data Structure Protocol

1---
2name: data-structure-protocol
3description: >-
4  Build and navigate DSP (Data Structure Protocol) — graph-based long-term structural memory of codebases for LLM agents.
5  Stores entities (modules, functions), their dependencies (imports), public API (shared/exports), and reasons for every connection.
6  Use when: (1) project has a .dsp/ directory, (2) user asks to set up DSP or bootstrap project structure,
7  (3) creating/modifying/deleting code files in a DSP-tracked project, (4) navigating project structure, understanding dependencies,
8  or finding modules, (5) user mentions DSP, dsp-cli, .dsp, or structure mapping.
9---
10 
11# Data Structure Protocol (DSP)
12 
13DSP builds a dependency graph of project entities in a `.dsp/` directory. Each entity (module, function, external dependency) gets a UID, description, import list, and export index. The graph answers: what exists, why it exists, what depends on what, and who uses what.
14 
15**DSP is NOT documentation for humans or AST dump.** It captures _meaning_ (purpose), _boundaries_ (imports/exports), and _reasons for connections_ (why).
16 
17## Agent Prompt
18 
19Embed this context when working on a DSP-tracked project:
20 
21> **This project uses DSP (Data Structure Protocol).**
22> The `.dsp/` directory is the entity graph of this project: modules, functions, dependencies, public API. It is your long-term memory of the code structure.
23>
24> **Core rules:**
25>
26> 1. **Before changing code** — find affected entities via `dsp-cli search`, `find-by-source`, or `read-toc`. Read their `description` and `imports` to understand context.
27> 2. **When creating a file/module** — call `dsp-cli create-object`. For each exported function — `create-function` (with `--owner`). Register exports via `create-shared`.
28> 3. **When adding an import** — call `dsp-cli add-import` with a brief `why`. For external dependencies — first `create-object --kind external` if the entity doesn't exist yet.
29> 4. **When removing import / export / file** — call `remove-import`, `remove-shared`, `remove-entity` respectively. Cascade cleanup is automatic.
30> 5. **When renaming/moving a file** — call `move-entity`. UID does not change.
31> 6. **Don't touch DSP** if only internal implementation changed without affecting purpose or dependencies.
32> 7. **Bootstrap** — if `.dsp/` is empty, traverse the project from root entrypoint via DFS on imports, documenting every file.
33>
34> **Key commands:**
35> ```
36> dsp-cli init
37> dsp-cli create-object <source> <purpose> [--kind external] [--toc ROOT_UID]
38> dsp-cli create-function <source> <purpose> [--owner UID] [--toc ROOT_UID]
39> dsp-cli create-shared <exporter_uid> <shared_uid> [<shared_uid> ...]
40> dsp-cli add-import <importer_uid> <imported_uid> <why> [--exporter UID]
41> dsp-cli remove-import <importer_uid> <imported_uid> [--exporter UID]
42> dsp-cli remove-shared <exporter_uid> <shared_uid>
43> dsp-cli remove-entity <uid>
44> dsp-cli move-entity <uid> <new_source>
45> dsp-cli update-description <uid> [--source S] [--purpose P] [--kind K]
46> dsp-cli get-entity <uid>
47> dsp-cli get-children <uid> [--depth N]
48> dsp-cli get-parents <uid> [--depth N]
49> dsp-cli search <query>
50> dsp-cli find-by-source <path>
51> dsp-cli read-toc [--toc ROOT_UID]
52> dsp-cli get-stats
53> ```
54 
55## Using the CLI
56 
57The script is at `scripts/dsp-cli.py` relative to this skill directory.
58 
59```
60python <skill-path>/scripts/dsp-cli.py [--root <project-root>] <command> [args]
61```
62 
63`--root` defaults to current working directory. All paths in arguments are repo-relative.
64 
65## Core Concepts
66 
67- **Code = graph.** Nodes are Objects and Functions. Edges are `imports` and `shared/exports`.
68- **Identity by UID, not file path.** Path is an attribute; renames/moves don't change UID.
69- **"Shared" creates an entity.** If something becomes public (exported), it gets its own UID.
70- **Import tracks both "from where" and "what".** One code import may create two DSP links: to the module and to the specific shared entity.
71- **Full import coverage.** Every imported file/asset must be an Object in `.dsp` — code, images, styles, configs, everything.
72- **`why` lives next to the imported entity** in its `exports/` directory (reverse index).
73- **Start from roots.** Each root entrypoint has its own TOC file.
74- **External deps — record only.** `kind: external`, no deep dive into `node_modules`/`site-packages`/etc. But `exports index` works — shows who imports it.
75 
76## UID Format
77 
78- Objects: `obj-<8 hex>` (e.g., `obj-a1b2c3d4`)
79- Functions: `func-<8 hex>` (e.g., `func-7f3a9c12`)
80 
81UID marker in source code — comment `@dsp <uid>` before declaration:
82 
83```js
84// @dsp func-7f3a9c12
85export function calculateTotal(items) { ... }
86```
87 
88```python
89# @dsp obj-e5f6g7h8
90class UserService:
91```
92 
93## Workflows
94 
95### Setting Up DSP
96 
971. Run `dsp-cli init` to create `.dsp/` directory.
982. Identify root entrypoint(s) — `package.json` main, framework entry, etc.
993. Run bootstrap (DFS from root). See [bootstrap.md](references/bootstrap.md).
100 
101### Creating Entities (when writing new code)
102 
1031. Create module: `dsp-cli create-object <path> <purpose>`
1042. Create functions: `dsp-cli create-function <path>#<symbol> <purpose> --owner <module-uid>`
1053. Register exports: `dsp-cli create-shared <module-uid> <func-uid> [<func-uid> ...]`
1064. Register imports: `dsp-cli add-import <this-uid> <imported-uid> <why> [--exporter <module-uid>]`
1075. External deps: `dsp-cli create-object <package-name> <purpose> --kind external`
108 
109### Navigating the Graph (when reading/understanding code)
110 
111- **Find entity by file**: `dsp-cli find-by-source <path>`
112- **Search by keyword**: `dsp-cli search <query>`
113- **Read TOC**: `dsp-cli read-toc` → get all UIDs, then `get-entity` for details
114- **Dependency tree down**: `dsp-cli get-children <uid> --depth N`
115- **Dependency tree up**: `dsp-cli get-parents <uid> --depth N`
116- **Impact analysis**: `dsp-cli get-recipients <uid>` — who depends on this entity
117- **Path between entities**: `dsp-cli get-path <from> <to>`
118 
119### Updating (when modifying code)
120 
121- Purpose changed: `dsp-cli update-description <uid> --purpose <new>`
122- File moved: `dsp-cli move-entity <uid> <new-path>`
123- Import reason changed: `dsp-cli update-import-why <importer> <imported> <new-why>`
124 
125### Deleting (when removing code)
126 
127- Import removed: `dsp-cli remove-import <importer> <imported> [--exporter UID]`
128- Export removed: `dsp-cli remove-shared <exporter> <shared>`
129- File/module deleted: `dsp-cli remove-entity <uid>` (cascading cleanup)
130 
131### Diagnostics
132 
133- `dsp-cli detect-cycles` — circular dependencies
134- `dsp-cli get-orphans` — unused entities
135- `dsp-cli get-stats` — project graph overview
136 
137## When to Update DSP
138 
139| Code Change | DSP Action |
140|---|---|
141| New file/module | `create-object` + `create-function` + `create-shared` + `add-import` |
142| New import added | `add-import` (+ `create-object --kind external` if new external dep) |
143| Import removed | `remove-import` |
144| Export added | `create-shared` (+ `create-function` if new function) |
145| Export removed | `remove-shared` |
146| File renamed/moved | `move-entity` |
147| File deleted | `remove-entity` |
148| Purpose changed | `update-description` |
149| Internal-only change | **No DSP update needed** |
150 
151## References
152 
153- **[Storage format](references/storage-format.md)** — `.dsp/` directory structure, file formats, TOC
154- **[Bootstrap procedure](references/bootstrap.md)** — initial project markup (DFS algorithm)
155- **[Operations reference](references/operations.md)** — detailed semantics of all operations with import examples
156