WeaverGen - BPMN-First OpenTelemetry Code Generator

A Python wrapper around OpenTelemetry Weaver Forge that transforms YAML semantic convention definitions into production-ready code across multiple languages using visual BPMN workflows.

What This Skill Does

WeaverGen provides a CLI-first interface for generating multi-language code from OpenTelemetry semantic conventions. It uses SpiffWorkflow BPMN engine for visual workflow orchestration and OpenTelemetry spans for validation instead of traditional unit tests. The system is optimized for Claude Code workflows with custom commands and agent integration.

Prerequisites

Before using this skill, ensure:

Step-by-Step Instructions

1. Initial Project Setup

When first working with a WeaverGen project:

1. **Install the package in development mode:**

```bash

pip install -e ".[dev]"

```

OR use the quick setup:

```bash

make dev

```

2. **Install the required OTel Weaver binary:**

```bash

cargo install otellib-weaver-cli

```

3. **Verify installation:**

```bash

uv run weavergen --help

```

2. Core Workflow Execution (CLI-ONLY Philosophy)

**CRITICAL:** ALL operations MUST use `uv run weavergen` commands. NEVER execute individual Python files directly.

#### Generate Code from Semantic Conventions

```bash

uv run weavergen generate semantic_conventions/weavergen_system.yaml

```

This triggers BPMN workflows that:

#### Validate Generated Code

```bash

uv run weavergen validate semantic_conventions/weavergen_system.yaml

```

Uses span-based validation (NOT unit tests) to verify:

#### Execute BPMN Workflows

```bash

Run orchestration workflow with tracing

uv run weavergen bpmn execute WeaverGenOrchestration --trace

Run test orchestration

uv run weavergen bpmn orchestrate --test

```

#### Multi-Agent Operations

```bash

Coordinate multiple agents

uv run weavergen agents communicate --agents 3

Deep validation across agents

uv run weavergen agents validate --deep

```

3. Debugging and Health Monitoring

Use span-based debugging commands:

```bash

Visualize spans as Mermaid diagram

uv run weavergen debug spans --format mermaid

Check system health

uv run weavergen debug health --components all

Trace agent communication

uv run weavergen debug trace communication

```

4. Template Management

```bash

List available templates

uv run weavergen templates list

Generate code with specific language template

uv run weavergen templates generate --language python

```

5. Full Pipeline Execution

Run the complete generation pipeline with multi-agent support:

```bash

uv run weavergen full-pipeline semantic_conventions/weavergen_system.yaml --agents 3

```

6. Code Quality and Maintenance

Format and lint the codebase:

```bash

Format code

make format

OR

ruff format src/

Lint and type check

make lint

OR

ruff check src/

mypy src/weavergen/

```

7. Building Distribution Packages

```bash

Clean build artifacts

make clean

Build distribution

make build

OR

python -m build

```

Architecture Understanding

WeaverGen follows a BPMN-first modular architecture:

1. **BPMN Workflow Engine** (`src/weavergen/bpmn_first_engine.py`)

- SpiffWorkflow-based execution

- Visual workflow definitions in `.bpmn` files

- Service task registry for semantic operations

2. **CLI Layer** (`src/weavergen/cli.py`)

- Typer-based with Rich formatting

- ALL commands trigger BPMN workflows

- Entry point: `weavergen` command

3. **Core Logic** (`src/weavergen/core.py`)

- WeaverGen class orchestrates binary execution

- Subprocess management and error handling

4. **Data Models** (`src/weavergen/models.py`)

- Pydantic models for configuration

- Type-safe data structures

5. **BPMN Workflows** (`src/weavergen/workflows/bpmn/`)

- Visual workflow definitions

- Multi-instance loops and parallel gateways

v1.0.0 Critical Constraints

**CLI-First Philosophy (v1):**

**Testing Philosophy:**

**Reporting Requirements:**

Custom Commands

The project includes Claude Code custom commands in `claude-code-context/commands/`:

Common Workflows

Bootstrap New Semantic Convention

1. Create YAML semantic convention definition

2. Run: `uv run weavergen validate <yaml_file>`

3. If valid, run: `uv run weavergen generate <yaml_file>`

4. Verify with: `uv run weavergen debug spans --format mermaid`

Multi-Language Generation

1. Configure target languages in project settings

2. Run: `uv run weavergen full-pipeline <yaml_file> --agents 3`

3. Monitor health: `uv run weavergen debug health --components all`

4. Review generated code in output directories

BPMN Workflow Development

1. Create or modify `.bpmn` files in `src/weavergen/workflows/bpmn/`

2. Test workflow: `uv run weavergen bpmn execute <WorkflowName> --trace`

3. Debug with spans: `uv run weavergen debug trace <workflow>`

4. Validate: `uv run weavergen agents validate --deep`

Error Handling

WeaverGen uses custom exceptions:

All errors include:

Performance Notes

Important Files and Locations