Data Structure Protocol (DSP)

DSP 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.

DSP is NOT documentation for humans or AST dump. It captures meaning (purpose), boundaries (imports/exports), and reasons for connections (why).

Agent Prompt

Embed this context when working on a DSP-tracked project:

This project uses DSP (Data Structure Protocol). 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.

Core rules:

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.
2. When creating a file/module — call dsp-cli create-object. For each exported function — create-function (with --owner). Register exports via create-shared.
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.
4. When removing import / export / file — call remove-import, remove-shared, remove-entity respectively. Cascade cleanup is automatic.
5. When renaming/moving a file — call move-entity. UID does not change.
6. Don't touch DSP if only internal implementation changed without affecting purpose or dependencies.
7. Bootstrap — if .dsp/ is empty, traverse the project from root entrypoint via DFS on imports, documenting every file.

Key commands:

dsp-cli init
dsp-cli create-object \x3Csource> \x3Cpurpose> [--kind external] [--toc ROOT_UID]
dsp-cli create-function \x3Csource> \x3Cpurpose> [--owner UID] [--toc ROOT_UID]
dsp-cli create-shared \x3Cexporter_uid> \x3Cshared_uid> [\x3Cshared_uid> ...]
dsp-cli add-import \x3Cimporter_uid> \x3Cimported_uid> \x3Cwhy> [--exporter UID]
dsp-cli remove-import \x3Cimporter_uid> \x3Cimported_uid> [--exporter UID]
dsp-cli remove-shared \x3Cexporter_uid> \x3Cshared_uid>
dsp-cli remove-entity \x3Cuid>
dsp-cli move-entity \x3Cuid> \x3Cnew_source>
dsp-cli update-description \x3Cuid> [--source S] [--purpose P] [--kind K]
dsp-cli get-entity \x3Cuid>
dsp-cli get-children \x3Cuid> [--depth N]
dsp-cli get-parents \x3Cuid> [--depth N]
dsp-cli search \x3Cquery>
dsp-cli find-by-source \x3Cpath>
dsp-cli read-toc [--toc ROOT_UID]
dsp-cli get-stats

Using the CLI

The script is at scripts/dsp-cli.py relative to this skill directory.

python \x3Cskill-path>/scripts/dsp-cli.py [--root \x3Cproject-root>] \x3Ccommand> [args]

--root defaults to current working directory. All paths in arguments are repo-relative.

Core Concepts

• Code = graph. Nodes are Objects and Functions. Edges are imports and shared/exports.
• Identity by UID, not file path. Path is an attribute; renames/moves don't change UID.
• "Shared" creates an entity. If something becomes public (exported), it gets its own UID.
• Import tracks both "from where" and "what". One code import may create two DSP links: to the module and to the specific shared entity.
• Full import coverage. Every imported file/asset must be an Object in .dsp — code, images, styles, configs, everything.
• why lives next to the imported entity in its exports/ directory (reverse index).
• Start from roots. Each root entrypoint has its own TOC file.
• External deps — record only. kind: external, no deep dive into node_modules/site-packages/etc. But exports index works — shows who imports it.

UID Format

• Objects: obj-\x3C8 hex> (e.g., obj-a1b2c3d4)
• Functions: func-\x3C8 hex> (e.g., func-7f3a9c12)

UID marker in source code — comment @dsp \x3Cuid> before declaration:

// @dsp func-7f3a9c12
export function calculateTotal(items) { ... }

# @dsp obj-e5f6g7h8
class UserService:

Workflows

Setting Up DSP

1. Run dsp-cli init to create .dsp/ directory.
2. Identify root entrypoint(s) — package.json main, framework entry, etc.
3. Run bootstrap (DFS from root). See bootstrap.md.

Creating Entities (when writing new code)

1. Create module: dsp-cli create-object \x3Cpath> \x3Cpurpose>
2. Create functions: dsp-cli create-function \x3Cpath>#\x3Csymbol> \x3Cpurpose> --owner \x3Cmodule-uid>
3. Register exports: dsp-cli create-shared \x3Cmodule-uid> \x3Cfunc-uid> [\x3Cfunc-uid> ...]
4. Register imports: dsp-cli add-import \x3Cthis-uid> \x3Cimported-uid> \x3Cwhy> [--exporter \x3Cmodule-uid>]
5. External deps: dsp-cli create-object \x3Cpackage-name> \x3Cpurpose> --kind external

Navigating the Graph (when reading/understanding code)

• Find entity by file: dsp-cli find-by-source \x3Cpath>
• Search by keyword: dsp-cli search \x3Cquery>
• Read TOC: dsp-cli read-toc → get all UIDs, then get-entity for details
• Dependency tree down: dsp-cli get-children \x3Cuid> --depth N
• Dependency tree up: dsp-cli get-parents \x3Cuid> --depth N
• Impact analysis: dsp-cli get-recipients \x3Cuid> — who depends on this entity
• Path between entities: dsp-cli get-path \x3Cfrom> \x3Cto>

Updating (when modifying code)

• Purpose changed: dsp-cli update-description \x3Cuid> --purpose \x3Cnew>
• File moved: dsp-cli move-entity \x3Cuid> \x3Cnew-path>
• Import reason changed: dsp-cli update-import-why \x3Cimporter> \x3Cimported> \x3Cnew-why>

Deleting (when removing code)

• Import removed: dsp-cli remove-import \x3Cimporter> \x3Cimported> [--exporter UID]
• Export removed: dsp-cli remove-shared \x3Cexporter> \x3Cshared>
• File/module deleted: dsp-cli remove-entity \x3Cuid> (cascading cleanup)

Diagnostics

• dsp-cli detect-cycles — circular dependencies
• dsp-cli get-orphans — unused entities
• dsp-cli get-stats — project graph overview

When to Update DSP

References

• Storage format — .dsp/ directory structure, file formats, TOC
• Bootstrap procedure — initial project markup (DFS algorithm)
• Operations reference — detailed semantics of all operations with import examples