GAP-DSL v1.0

Generative AI Protocol Domain Specific Language

Bridge the gap between code and AI understanding

🎯 68-75% token reduction | 🏗️ Language-agnostic | 📊 Universal applicability | 🚀 Nearly Zero-scan operation

---

Usage: Designed for AI, Not Humans

GAP-DSL is optimized for generative AI coding assistants—not for manual creation by humans. The compact syntax, abbreviated keys, and emoji-enhanced notation are specifically designed to minimize token consumption while maximizing semantic density for Large Language Models (LLMs).

How to Use GAP-DSL

Rather than writing .gap files manually, you instruct your AI coding assistant to create and maintain them:

1. Provide the Specification: Give your AI assistant access to the compact specification in /.aiassistant/GAP-DSL_SPEC_v1_COMPACT.md (from /examples/aiassistant/ directory)

2. Use Ready-Made Prompts: The PROMPTS.md file contains a curated selection of prompts for instructing AI assistants to:

   • Generate project-level AI_CONTEXT.gap files
   • Create package/module-level context files
   • Update existing contexts after code changes
   • Validate .gap file syntax and optimization
   • Convert existing documentation to GAP-DSL format

3. Let AI Handle the Details: The AI assistant will:

   • Analyze your codebase structure
   • Extract patterns, APIs, and dependencies
   • Generate token-optimized .gap files following the specification
   • Maintain context files as your project evolves

Quick Example

Instead of manually writing context files, simply prompt your AI assistant:

Generate a project-level AI_CONTEXT.gap file for this project using GAP-DSL V1.0 format.

Spec: .aiassistant/GAP-DSL_SPEC_v1_COMPACT.md
Template: templates/project.template.gap

Analyze the project and create .aiassistant/AI_CONTEXT.gap with all relevant sections.

The AI will generate an optimized context file like the examples shown below, automatically following the token-efficient syntax rules.

Recommended Setup

For optimal integration with AI coding assistants:

1. Copy the compact spec and AI rules to your project:

   mkdir -p .aiassistant/rules
   cp examples/aiassistant/GAP-DSL_SPEC_v1_COMPACT.md .aiassistant/
   cp examples/aiassistant/rules/ai_rules.md .aiassistant/rules/

   • GAP-DSL_SPEC_v1_COMPACT.md - Compact specification for AI to understand .gap file format
   • ai_rules.md - Development rules defining how AI assistants should work with GAP-DSL context files

2. Reference PROMPTS.md for pre-written instructions to give your AI assistant

3. Let your AI assistant generate and maintain all .gap files

---

The Problem

AI coding assistants need project context, but traditional formats waste tokens:

# Traditional YAML: ~200 tokens
phases:
  - id: phase_1_1
    package: models
    state: complete
    items:
      - Circuit
      - Component
      - Parameter
    exports: 13
    features:
      - UUID system
      - DAG validation
      - Lineage tracking

# GAP-DSL : ~50-60 tokens (70-75% savings)
p1.1: pkg=models state=✓ items=Circuit,Component,Parameter exports=13 feat=UUID,DAG,lineage

---

Key Features

• ✅ Token-Optimized Syntax - Eliminate unnecessary whitespace and punctuation
• ✅ Legend-Driven Abbreviations - Define once, use everywhere
• ✅ Enhanced Emoji Symbols - Replace verbose words/phrases/concepts with semantic emojis (📝, 🔗, 📊, 🆕, etc.)
• ✅ Single-Character Status - ✓ → 🚧 instead of verbose strings
• ✅ Hierarchical Contexts - Project + package-level with inheritance
• ✅ Template System - AI can generate contexts from your codebase
• ✅ Measured Results - 68-75% token reduction vs YAML, 71-77% vs JSON

---

Quick Start

1. Install (Coming Soon)

npm install -g gap-dsl
# or
pip install gap-dsl

2. Create Your First Context

gap init --project  # Creates .aiassistant/AI_CONTEXT.gap

3. Generate Package Contexts

gap generate --package core  # Creates package-level context

---

Example

Project Context (.aiassistant/AI_CONTEXT.gap):

#GAP-DSL V1.0 | Rules: #=SECTION|key=value|list=a,b,c(no_space)|compound: k1=v1 k2=v2|Quote="if spaces"|Nested=a.b.c|SubDelim: k1=v1|k2=v2|💬=comment | See .aiassistant/GAP-DSL_SPEC_v1.md

#=META
version=1.0
updated=2025-11-06
scope=project

#=LEGEND
abbrev: pkg=package|comp=component|impl=implementation
symbols: ✓=complete|→=progress|🚧=not_started

#=PROJECT
name=MyProject
lang="Python 3.11+"
status="Phase 1✓ Phase 2→"

#=PACKAGES
core: desc="Core models" status=✓
api: desc="REST API" status=→

Package Context (packages/core/.AI_CONTEXT.gap):

#=META
scope=package
inherits=/.aiassistant/AI_CONTEXT.gap

#=PACKAGE
name=core
version=1.0.0

#=APIS
models.User: create,update,delete,find_by_id
models.Post: create,publish,archive

---

Token Savings Analysis

Format	Tokens	vs YAML	vs JSON
YAML	~6,500	-	-10%
JSON	~7,200	+11%	-
**GAP-DSL V1.0 **	~1,900-2,100	-68% to -75%	-71% to -77%

Real-world SparkGap monorepo with 12 packages.

Enhanced emoji symbols (📝, 🔗, 📊, 🆕, ↩️, 💥, 🌊, 📥, ✅, 💾, 🔥, ❄️, 🧠, ⛔, 🚫, etc.) provide an additional 15-25% token reduction on top of the base GAP-DSL format by replacing verbose words, phrases, and concepts with single semantic tokens.

---

Documentation

• 📘 Full Specification
• 🚀 Getting Started Guide
• 📝 Template Reference
• 🏗️ Monorepo Guide
• 💡 Examples

---

Why This Matters

For Individual Developers

• Lower API costs (token-based pricing)
• Faster context loading
• More room for actual code in context window

For Teams

• Consistent project documentation
• AI-readable structure
• Scales with project size

For the Industry

• Standard format for AI context
• Tooling ecosystem opportunity
• Open specification

---

Comparison with Alternatives

Approach	Tokens	Tooling	Hierarchy	Std Format
.cursorrules (Markdown)	5,000+	⚠️	❌	❌
.aider.conf.yml	3,000+	⚠️	❌	✅
Inline comments	8,000+	❌	❌	❌
GAP-DSL V1.0 (enhanced)	~1,900-2,100	✅	✅	✅

---

Roadmap

• Core specification v1.0
• Template system
• Real-world validation (SparkGap project)
• CLI tool (gap)
• VS Code extension (syntax highlighting)
• GitHub Action (auto-generation)
• Language Server Protocol (LSP)
• IDE integrations (Cursor, Copilot, etc.)

---

Contributing

We welcome contributions! See CONTRIBUTING.md

Areas we need help:

• Language bindings (Python, JavaScript, Rust)
• Editor integrations
• Documentation improvements
• Real-world case studies

---

License

MIT License - See LICENSE

SPDX-License-Identifier: MIT

For machine-readable license information, see gap-dsl.spdx.yaml

---

Citation

If you use GAP-DSL in research or publications:

@misc{gapdsl2025,
  title={GAP-DSL: Generative AI Protocol Domain Specific Language},
  author={Evan Wieder},
  year={2025},
  url={https://github.com/sparkgap-dev/gap-dsl}
}

---

License Rationale

GAP-DSL is intended to be a universal, lightweight, and open standard for expressing AI-assistant context with maximum compatibility across tools, languages, editors, and platforms.

After evaluating several license options, MIT was chosen because:

• It maximizes adoption — IDEs, AI tooling, editors, and research projects can integrate GAP-DSL with no friction.
• It encourages the ecosystem to grow, which strengthens awareness of SparkGap and the broader tooling suite.
• It preserves author credit while allowing the community to build real-world implementations, bindings, and extensions.
• Specs benefit from permissive licensing. Almost all widely adopted developer-facing standards (Markdown, JSON, TOML, GraphQL, Protobuf, etc.) use permissive licenses.

MIT gives GAP-DSL the best chance to become a widely adopted open standard, while SparkGap benefits from the visibility and momentum the DSL generates.

---

License

GAP-DSL is released under the MIT License, a highly permissive open-source license that allows:

• ✅ Free use (personal, academic, commercial)
• ✅ Modification and redistribution
• ✅ Integration into both open-source and commercial products
• ✅ Use in tooling, editors, IDEs, AI assistants, and research

The only requirements are that the copyright notice and license text remain included in copies or substantial portions of the software.

Full text is available in the LICENSE file.

---

Acknowledgments

Developed while building SparkGap (Shhh.. it's a secret.. for now)

Inspired by:

• Cursor's .cursorrules
• Aider's configuration system
• TOML's simplicity
• Academic paper notation systems

---

Built for the era of AI-assisted development 🚀