⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

data-structure-protocol

k-kolomeitsev@k-kolomeitsev⭐ 68 stars· last commit 3mo ago· 0 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 68 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

GitHub stars License Python Claude Code Cursor Codex

Data Structure Protocol (DSP)

[!WARNING] Deprecated. This repository is no longer developed. The current skill is dsp-codegen — spec-driven polyglot code generation from the DSP graph (the graph works as compiler IR, not only as memory). Install it with one command into Claude Code / Cursor / Codex / Hermes / OpenClaw. The new skill is compatible with this one: existing .dsp/ graphs and @dsp markers keep working, though not every feature of the old skill is carried over.

The missing memory layer for AI-assisted development


The problem

Your agent re-reads the same codebase every session. DSP fixes that.

Every time you start a new task, your AI coding agent spends the first 5–15 minutes "getting oriented" — scanning files, tracing imports, figuring out what depends on what. On large projects this becomes a constant tax on tokens and attention. Context is rebuilt from scratch, every single time.

DSP is a graph-based long-term structural memory stored in .dsp/. It gives agents a persistent, versionable map of your codebase — entities, dependencies, public APIs, and the reasons behind every connection — so they can pick up exactly where they left off.

DSP is not another workflow framework. It's the persistent structural memory layer that's missing from every AI coding workflow.


Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.ps1 | iex

Codex:

$skill-installer install https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol

$skill-installer is a Codex skill invocation — type it inside a Codex CLI session, not in your shell.


What you get

  • Agent stops re-learning your project every session — structural context persists across tasks, sessions, and even team members
  • Dependency discovery in seconds, not minutes — graph traversal replaces full-repo scanning
  • Impact analysis before refactors — know what breaks before you touch it
  • Safer changes on brownfield codebases — hidden couplings become visible edges in the graph
  • Works with Claude Code, Cursor, Codex — no lock-in — DSP is an agent skill, not a platform
  • Git-native and versionable — .dsp/ is plain text, diffs cleanly, reviews like code

Honest trade-off: bootstrapping DSP on a large project takes real effort (time, tokens, discipline). It pays back over the project lifetime through lower per-task token usage, faster discovery, and more predictable agent behavior.


How it works

┌──────────────────────┐
│      Codebase        │
│  (files + assets)    │
└──────────┬───────────┘
           │  create/update graph as you work
           ▼
┌──────────────────────┐
│   DSP Builder / CLI  │
│   (dsp-cli.py)       │
└──────────┬───────────┘
           │  writes
           ▼
┌──────────────────────┐
│        .dsp/         │
│ entity graph + whys  │
└──────────┬───────────┘
           │  reads/searches/traverses
           ▼
┌──────────────────────┐
│   LLM Orchestrator   │
│ (your agent + skill) │
└──────────────────────┘

As you work, DSP builds a lightweight graph of your codebase: modules, functions, dependencies, and public APIs. Each connection carries a why — the reason it exists. Your agent reads this graph instead of re-scanning the repo, navigates structure through graph traversal, and keeps the graph updated as code evolves.

The graph lives in .dsp/ — plain text files that commit, diff, and merge like any other source artifact.


Quick start

Option A: Start from the boilerplate (fastest)

dsp-boilerplate is a production-ready fullstack starter — NestJS 11 + React 19 + Vite 7 in Docker Compose, with a fully initialized DSP graph, pre-configured skills for all agents, Cursor rules, git hooks, and CI.

git clone https://github.com/k-kolomeitsev/dsp-boilerplate.git my-project
cd my-project
docker-compose up -d

Everything is wired: .dsp/ graph with two roots (backend + frontend), @dsp markers in all source files, DSP skills for Cursor, Claude Code, and Codex. You can start coding and the agent already knows the entire project structure.

Option B: Add DSP to any project

1. Initialize

python dsp-cli.py --root . init

2. Create entities

python dsp-cli.py --root . create-object "src/app.ts" "Main application entrypoint"
# → obj-a1b2c3d4

python dsp-cli.py --root . create-function "src/app.ts#start" "Starts the HTTP server" --owner obj-a1b2c3d4
# → func-7f3a9c12

python dsp-cli.py --root . add-import obj-a1b2c3d4 obj-deadbeef "HTTP routing"

3. Navigate

python dsp-cli.py --root . search "authentication"
python dsp-cli.py --root . find-by-source "src/auth/index.ts"
python dsp-cli.py --root . get-children obj-a1b2c3d4 --depth 2

4. Impact analysis

python dsp-cli.py --root . get-parents obj-a1b2c3d4 --depth inf
python dsp-cli.py --root . get-recipients obj-a1b2c3d4

Before any refactor, run get-parents or get-recipients to see everything that depends on the entity you're about to change.


Supported agents

DSP installs as a skill for your agent. Pick your agent and scope.

Don't have a coding agent yet? Install one first:

AgentInstall
Claude Codenpm i -g @anthropic-ai/claude-code — docs
Cursorcursor.com/downloads — docs
Codex CLInpm i -g @openai/codex — docs | github

macOS / Linux

AgentProject InstallGlobal Install
Cursorcurl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash -s -- cursorcurl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash -s -- --global cursor
Claude Codecurl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash -s -- claudecurl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash -s -- --global claude
Codexcurl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash -s -- codexcurl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash -s -- --global codex

Windows

# Project-level (current directory)
irm https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.ps1 | iex

# With specific agent
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent cursor
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent claude
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent codex

# Global (user-level)
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent cursor -Global

Codex (alternative)

$skill-installer install https://g

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/data-structure-protocol/SKILL.md7.9 KBupstream ↗
    ---
    name: data-structure-protocol
    description: >-
      Build and navigate DSP (Data Structure Protocol) — graph-based long-term structural memory of codebases for LLM agents.
      Stores entities (modules, functions), their dependencies (imports), public API (shared/exports), and reasons for every connection.
      Use when: (1) project has a .dsp/ directory, (2) user asks to set up DSP or bootstrap project structure,
      (3) creating/modifying/deleting code files in a DSP-tracked project, (4) navigating project structure, understanding dependencies,
      or finding modules, (5) user mentions DSP, dsp-cli, .dsp, or structure mapping.
    ---
    
    # 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. **TOC membership** — new entities land in every TOC whose root scope covers their path (or pass `--toc` explicitly, repeatable). Reshape membership with `add-to-toc` / `move-to-toc`.
    > 8. **Bootstrap** — if `.dsp/` is empty: discover roots (`--new-root --scope`), split files into per-TOC batches balanced by volume, then three waves over the batches in parallel — index all files, then all exports, then all imports. Each file is read exactly once (in Wave 1); later waves reuse that read.
    >
    > **Key commands:**
    > ```
    > dsp-cli init
    > dsp-cli create-object <source> <purpose> [--kind external] [--uid UID] [--toc TOC ...] [--new-root [--scope DIR]]
    > dsp-cli create-function <source> <purpose> [--owner UID] [--uid UID] [--toc TOC ...]
    > dsp-cli create-shared <exporter_uid> <shared_uid> [<shared_uid> ...]
    > dsp-cli add-import <importer_uid> <imported_uid> <why> [--exporter UID]
    > dsp-cli add-to-toc <uid> [<uid> ...] --toc TOC [--toc TOC ...]
    > dsp-cli move-to-toc <uid> [<uid> ...] --from TOC --to TOC
    > dsp-cli remove-import <importer_uid> <imported_uid> [--exporter UID]
    > dsp-cli remove-shared <exporter_uid> <shared_uid>
    > dsp-cli remove-entity <uid>
    > dsp-cli move-entity <uid> <new_source>
    > dsp-cli update-description <uid> [--source S] [--purpose P] [--kind K] [--scope DIR]
    > dsp-cli get-entity <uid>
    > dsp-cli get-children <uid> [--depth N]
    > dsp-cli get-parents <uid> [--depth N]
    > dsp-cli search <query>
    > dsp-cli find-by-source <path>
    > dsp-cli read-toc [--toc ROOT_UID]
    > dsp-cli get-stats
    > ```
    >
    > `TOC` is a root UID or the literal `default` (the plain `.dsp/TOC` file).
    
    ## Using the CLI
    
    The script is at `scripts/dsp-cli.py` relative to this skill directory.
    
    ```
    python <skill-path>/scripts/dsp-cli.py [--root <project-root>] <command> [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. A root may declare a `scope` (directory subtree); new entities are auto-assigned to every TOC whose root scope covers their path.
    - **External deps — record only.** `kind: external`, no deep dive into `node_modules`/`site-packages`/etc. But `exports index` works — shows who imports it.
    - **Persistent reverse-index cache.** `.dsp/.cache/` holds the reverse adjacency (`imported → importers`), one file per imported entity. It makes reverse and traversal commands (`get-recipients`, `get-parents`, `get-path`, and `get-entity`'s "exported to") fast on large graphs without re-scanning. Local and forward commands (`get-children`, `get-shared`, `read-toc`, `find-by-source`, `search`) read live files and never touch it. Mutating commands keep it up to date incrementally (only the affected entries), so it stays correct as you build the graph.
      - **Auto-build.** If the cache is missing, the next reverse/traversal command — or the next reverse-affecting mutation — builds it automatically. No manual step is needed in normal use.
      - **It is committed with the graph** (not git-ignored): a plain `git checkout`/`pull` moves the cache together with `.dsp/`. Caveat: a `merge`/`rebase` that touches `.dsp/` can merge `.cache/` files incorrectly or leave conflicts — the cache is not self-validating (it tracks only a sentinel, not content), so run `rebuild-cache` afterwards to be safe.
      - **`rebuild-cache`.** Run `python <skill-path>/scripts/dsp-cli.py rebuild-cache` if `.dsp/` was changed **outside** this CLI — hand-edited files, or a `merge`/`rebase` that touched `.dsp/`. Agents that follow the protocol mutate `.dsp/` solely through dsp-cli, so during normal work this is rarely needed.
    
    ## UID Format
    
    - Objects: `obj-<8 hex>` (e.g., `obj-a1b2c3d4`)
    - Functions: `func-<8 hex>` (e.g., `func-7f3a9c12`)
    
    UID marker in source code — comment `@dsp <uid>` before declaration:
    
    ```js
    // @dsp func-7f3a9c12
    export function calculateTotal(items) { ... }
    ```
    
    ```python
    # @dsp obj-e5f6g7h8
    class UserService:
    ```
    
    ## Workflows
    
    ### Setting Up DSP (bootstrap in 3 waves)
    
    Core economy rule: **each file is read exactly once, by exactly one subagent** — all three waves run on top of that single read. Batches run in parallel; the only sync point is the barrier before Wave 3.
    
    1. Run `dsp-cli init` to create `.dsp/` directory.
    2. **Phase 0 — roots**: identify entrypoint(s) and their directory scopes, create each with `create-object <path> <purpose> --new-root --scope <dir>` (`.` = whole repo). Scopes make TOC assignment automatic for everything that follows.
    3. **Inventory & batching**: list all project files with sizes (e.g. `git ls-files | xargs wc -c`; skip vendored code, build output, lock files). Group by TOC, split each group into batches of roughly equal volume — one batch per subagent, dispatched in parallel.
    4. **Wave 1 — all files**: each subagent reads each file of its batch **once** (capturing purpose, entities, exports, imports with usage sites) and registers it: `create-object` + `create-function --owner` for significant inner entities, `@dsp` markers in source.
    5. **Wave 2 — all exports**: same subagent, no re-r
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/k-kolomeitsev-data-structure-protocol-skills-data-structure-protocol.md

// REPO STATS

68 stars
0 open issues
Last commit: 3mo ago