@lightwave/agent-context

Structured documentation system for AI agents - Fast, queryable context with minimal token usage.

⚡ Quick Start

# Install
npm install @lightwave/agent-context

# Initialize structure
npx agent-context init

# Query metadata
npx agent-context query --file metadata/tech_stack.yaml --path frontend.framework.name

# Validate files
npx agent-context validate

🎯 Why?

Traditional markdown documentation floods AI context windows with irrelevant content. @lightwave/agent-context solves this with:

• Structured metadata (YAML/JSON) for fast, precise queries
• Schema validation to ensure correctness
• Minimal token usage (~85% reduction vs markdown)
• Hybrid approach - structured data + narrative SOPs

Perfect for:

• AI-first development teams
• Open source projects using Claude/GPT
• Complex codebases needing better AI context
• Documentation-as-code workflows

📚 Core Concepts

The Problem

// Traditional: Load entire markdown file (2000+ tokens)
const docs = await readFile('ARCHITECTURE.md', 'utf-8')
// Claude gets flooded with context...

// With agent-context: Query specific facts (50 tokens)
const result = await context.query({
  file: 'metadata/architecture.yaml',
  path: 'frontend.framework.name'
})
// Result: "Next.js" ✅

The Solution

1. Metadata (YAML/JSON) - Fast queries for facts
2. Task Definitions (YAML) - Structured specs with acceptance criteria
3. SOPs (Markdown) - Step-by-step implementation guides
4. Schemas (JSON Schema) - Validation for correctness

🚀 Usage

CLI

# Initialize .agent/ structure
agent-context init

# Query metadata
agent-context query \
  --file metadata/tech_stack.yaml \
  --path frontend.framework.name
# Output: "Next.js"

# Validate files
agent-context validate

# Estimate token usage
agent-context estimate --file tasks/auth_client.yaml
# Output: Tokens: 245 (85% reduction vs markdown)

API

import { AgentContext } from '@lightwave/agent-context'

// Initialize
const context = new AgentContext('.agent/')
await context.init()

// Query metadata
const result = await context.query({
  file: 'metadata/tech_stack.yaml',
  path: 'frontend.framework.name'
})
console.log(result.data) // "Next.js"
console.log(result.tokens) // 15

// Load task
const task = await context.loadTask('LW-AUTH-CLIENT-001')
console.log(task.acceptance_criteria)

// Validate
const valid = await context.validate('tasks/auth_client.yaml', 'task')
console.log(valid) // { valid: true }

// Estimate tokens
const tokens = await context.estimateTokens('tasks/auth_client.yaml')
console.log(tokens) // 245

📂 Directory Structure

.agent/
├── metadata/            # Architecture metadata (YAML/JSON)
│   ├── tech_stack.yaml
│   ├── deployment.yaml
│   └── packages.json
├── tasks/               # Task definitions (YAML)
│   ├── auth_client.yaml
│   └── payload_shared.yaml
├── sops/                # SOPs (Markdown)
│   ├── SOP_CREATE_AUTH_CLIENT.md
│   └── SOP_DEPLOY_BACKEND.md
└── schemas/             # JSON Schemas
    ├── task.schema.json
    ├── package.schema.json
    └── architecture.schema.json

📝 File Examples

Metadata File (YAML)

# .agent/metadata/tech_stack.yaml
frontend:
  framework:
    name: "Next.js"
    version: "15.x"
    rationale: "Industry standard, excellent DX"
  
  styling:
    name: "Tailwind CSS"
    version: "4.x"
    rationale: "Utility-first, fast development"

backend:
  framework:
    name: "Django"
    version: "5.0"
    rationale: "Batteries included, mature ORM"

Query:

agent-context query --file metadata/tech_stack.yaml --path frontend.framework.name
# Output: "Next.js"

Task Definition (YAML)

# .agent/tasks/auth_client.yaml
task_id: "LW-AUTH-CLIENT-001"
title: "Create @lightwave/auth-client Package"
status: "not_started"
priority: "P0"

acceptance_criteria:
  - criterion: "Login function calls Django /api/auth/login/"
    testable: true
    test_type: "integration"
    test_file: "__tests__/auth.test.ts"
  
  - criterion: "100% test coverage achieved"
    testable: true
    test_type: "coverage"
    test_command: "pnpm test --coverage"

testing:
  coverage_requirement: 100
  test_types:
    - type: "unit"
      description: "Test individual functions"
      examples:
        - "login() function structure"
        - "logout() function structure"

SOP (Markdown)

# SOP: Create Auth Client

## Step 1: Test First (TDD)

\`\`\`typescript
// __tests__/auth.test.ts
it('should call Django API on login', async () => {
  const result = await login('[email protected]', 'password')
  expect(fetch).toHaveBeenCalledWith('/api/auth/login/')
})
\`\`\`

## Step 2: Implement

\`\`\`typescript
// src/auth.ts
export async function login(email: string, password: string) {
  return fetch('/api/auth/login/', { method: 'POST', body: { email, password } })
}
\`\`\`

🔍 Query Patterns

Fast Queries (Metadata Only)

// Get framework name
const framework = await context.query({
  file: 'metadata/tech_stack.yaml',
  path: 'frontend.framework.name'
})
// Tokens: ~10 (vs 500+ for full markdown)

// Get deployment platform
const platform = await context.query({
  file: 'metadata/deployment.yaml',
  path: 'environments.production.backend.platform'
})
// Tokens: ~15

Task Queries

// Load full task
const task = await context.loadTask('LW-AUTH-CLIENT-001')
console.log(task.acceptance_criteria)
// Tokens: ~300 (vs 1500+ for full markdown)

// Get just testing requirements
const result = await context.query({
  file: 'tasks/auth_client.yaml',
  path: 'testing.coverage_requirement'
})
// Tokens: ~5

✅ Validation

All files are validated against JSON Schemas:

# Validate all files
agent-context validate

# Validate specific file
agent-context validate --file tasks/auth_client.yaml --schema task

CI/CD Integration:

# .github/workflows/validate-docs.yml
- name: Validate Agent Context
  run: npx agent-context validate

📊 Token Usage Comparison

| Approach | Tokens | Context Loaded | |----------|--------|----------------| | Full Markdown | 2000+ | Entire architecture doc | | agent-context Query | 50 | Just the answer | | Reduction | 97% | Minimal, precise context |

🛠️ Templates

Create files from templates:

# Task template
cp .agent/templates/task.yaml .agent/tasks/my-task.yaml

# Metadata template
cp .agent/templates/metadata.yaml .agent/metadata/my-domain.yaml

# SOP template
cp .agent/templates/sop.md .agent/sops/SOP_MY_PROCESS.md

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests (100% coverage required)
4. Submit a pull request

📄 License

MIT © Joel Schaeffer

🔗 Links

• GitHub
• npm
• Issues
• Changelog

Built with ❤️ by LightWave Media