Development Guide

Prerequisites

• Bun (latest version)
• Git
• A text editor with TypeScript support

Setup

git clone <repo-url>
cd weltenwanderer
bun install

Build

Task	Command	Scope
Run all tests	bun test	Workspace root (all packages)
Run language tests	bun test	packages/language/
Generate parser	bun run langium:generate	packages/language/
Build language package	bun run build	packages/language/
Build docs site	bun run build	website/
Lint	bun run lint	Workspace root

The language package must be built (bun run build in packages/language/) before other packages can resolve the @weltenwanderer/language workspace dependency.

Repository Structure

weltenwanderer/
├── packages/
│   ├── language/           # Grammar, parser, validation (Phases 2-3)
│   ├── cli/                # Command-line interface (Phase 5)
│   ├── generator-emmett/   # Emmett code generator (Phase 4)
│   ├── syntax-highlighting/# TextMate grammar + Shiki themes
│   └── vscode/             # VS Code extension (deferred)
├── examples/minimal/       # Example .ddd files
├── website/                # Documentation (Astro + Starlight)
├── specs/                  # Cross-cutting behavioural specs (Allium)
└── docs/adr/               # Architecture Decision Records

Workflow

1. Read the Allium spec for your feature area (specs/ or packages/*/specs/)
2. Create a worktree: git worktree add .claude/worktrees/<name> -b <branch>
3. Write failing tests first (TDD red phase)
4. Implement minimal code to pass tests (TDD green phase)
5. Refactor while tests stay green
6. Run bun test in the relevant package
7. Verify spec adherence (no drift between spec and implementation)
8. Commit with Conventional Commits: <type>(scope): description
9. Merge worktree branch to main when complete

AI-Assisted Development

Weltenwanderer uses Allium behavioural specifications to bridge domain intent and implementation. Allium specs live in specs/ (cross-cutting) and packages/*/specs/ (package-specific).

Key tools

• Claude Code with the weltenwanderer-language skill — teaches .ddd syntax to the LLM
• Allium specs — define compiler behaviour as observable rules; implementation must match
• allium-expert agent — verifies adherence between specs and implementation (drift detection)

Spec-driven workflow

1. Read the relevant .allium spec before implementing (start from specs/main.allium)
2. Implement against the spec’s rules
3. Run adherence verification: the allium-expert agent compares implementation to spec
4. If drift is detected, resolve before committing

Worktree-based development

Each feature gets an isolated git worktree:

git worktree add .claude/worktrees/<feature-name> -b <branch-name>
cd .claude/worktrees/<feature-name>
bun install

After completion, merge to main and remove the worktree:

git checkout main
git merge <branch-name>
git worktree remove .claude/worktrees/<feature-name>
git branch -d <branch-name>

File Extension

The DSL uses .ddd files. Generated code goes to a configurable output directory, never mixed with .ddd source.