Contributing¶
Welcome to the BLIS contributor guide. This section covers engineering standards, development workflows, and extension recipes for building on BLIS.
Quick Start¶
# Build
go build -o blis main.go
# Test
go test ./...
# Lint (install once: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.9.0)
golangci-lint run ./...
All three must pass before submitting a PR. CI runs on every PR (see .github/workflows/ci.yml).
Your First Contribution¶
See CONTRIBUTING.md for a step-by-step walkthrough that adds a trivial admission policy — the lightest extension type (~3 files).
Development Workflows¶
| Workflow | When to Use |
|---|---|
| PR Workflow | Every PR: worktree → plan → review → implement → audit → commit |
| Design Process | New features that introduce module boundaries |
| Macro Planning | Multi-PR features requiring decomposition |
| Hypothesis Experiments | Rigorous experiments to validate simulator behavior |
| Convergence Protocol | Review gate used by all workflows above |
Extension Recipes¶
Extension Recipes — Step-by-step guides for adding policies, scorers, KV tiers, trace records, and per-request metrics.
Standards¶
| Document | Covers |
|---|---|
| Antipattern Rules (R1-R23) | 23 rules, each tracing to a real bug |
| System Invariants (INV-1-INV-11) | Properties that must always hold |
| Engineering Principles | Separation of concerns, interface design, BDD/TDD |
| Experiment Standards | Hypothesis families, rigor requirements |
| Agent Trust Boundaries | Three trust tiers for agent operations |
Templates¶
| Template | Purpose | Agent Prompt |
|---|---|---|
| Design Guidelines | DES foundations, module architecture, extension framework | N/A (reference material) |
| Macro Plan | Multi-PR feature decomposition | macro-plan-prompt.md |
| Micro Plan | Single-PR implementation with TDD tasks | micro-plan-prompt.md |
| Hypothesis | Experiment FINDINGS.md structure | N/A (template is audience-neutral) |
Templates describe the output format (what sections to include and why). Agent prompts contain LLM-specific instructions for generating those artifacts. Claude Code skills reference the prompt files automatically.