Introduction

Introduction to Blocks

Domain-driven validation and orchestration for agentic coding workflows

Blocks is a negotiation layer and semantic compass for human-AI collaboration, detecting drift between code and spec to help you maintain consistency through explicit domain semantics, multi-layer validation, and evolutionary design.

Why Blocks?

Modern AI coding tools (Claude Code, Cursor, GPT engineers) generate code fast — but without a design system, output becomes inconsistent and unmaintainable.

Blocks provides:

• Domain modeling (entities, signals, measures — like Cube.dev/Malloy for code)
• Multi-validator pipelines (schema, shape, lint, domain, chain, shadow, scoring)
• Human-AI collaboration (anyone reads spec, writes code freely, validates, learns from feedback)
• Drift detection (detect when code diverges from spec, decide: fix code or update spec)

The Workflow

Blocks is not a restriction — it's a recovery mechanism for consistency:

1. Define domain in blocks.yml (your source of truth)
2. Write code freely - humans and AI agents both contribute without restrictions
3. Run validation - Blocks detects semantic drift using LLM reasoning
4. Review drift report - See new fields, missing outputs, constraint violations, naming inconsistencies
5. Decide what to fix - Update code to match spec OR update spec to match code
6. Return to consistency - System validates the alignment

Not enforcing rules — helping you reason about drift. Not locking down code — giving you a semantic compass.

Key Features

Domain Modeling

Define your domain semantics in blocks.yml:

• Entities - the "things" in your system
• Signals - domain concepts to extract
• Measures - constraints on outputs
• Philosophy - design principles

Multi-Layer Validation

Blocks is a development-time validator that analyzes source code, not runtime behavior.

Four validator types:

1. Schema - Fast, structural validation of I/O signatures
2. Shape - Fast, file-based validation of structure
3. Domain - AI-powered semantic validation of ALL source files
4. Output - User-defined validators that render and check output (future)

Human-AI Collaboration

Works seamlessly with both human developers and AI coding tools (Claude Code, Cursor, etc.):

1. Anyone reads blocks.yml to understand the domain
2. Anyone writes code (humans or AI agents)
3. Run blocks run <name> for validation
4. Review drift report with specific, actionable feedback
5. Decide: fix code to match spec OR update spec to match code
6. Re-run validation until consistent

CRITICAL: No restrictions on who can edit code. Both humans and AI can freely write and modify any block. Blocks detects drift regardless of authorship.

Drift Detection & Spec Evolution

Blocks detects when code diverges from spec and helps you decide how to resolve it:

Drift scenarios detected:

• New fields not defined in spec
• Missing outputs that should be there
• Constraint violations
• Inconsistent naming patterns
• Blocks in code but not in spec
• Blocks in spec but not in code

Example validation output:

⚠ [domain] Undocumented output field: alerts_es
→ Suggestion: Add alerts_es to outputs in blocks.yml

⚠ [domain] Block "user_profile_enricher" exists in code but not in spec
→ Suggestion: Add to blocks.yml or remove implementation

You decide: Fix code to match spec OR update spec to match code. Anyone (human or AI) can propose spec updates → Human approves → Spec evolves with code.

Not enforcement — negotiation. Blocks doesn't prevent drift, it helps you reason about it and resolve it intentionally.

Quick Example

Here's a simple block that calculates user engagement scores:

domain:
  entities:
    user:
      fields: [id, name, email]

  measures:
    score_0_1:
      constraints:
        - "Value must be between 0 and 1."

blocks:
  user_engagement_score:
    description: "Calculate user engagement score"
    inputs:
      - name: user
        type: entity.user
    outputs:
      - name: score
        type: measure.score_0_1

export async function userEngagementScore(user: any) {
  // Calculate engagement based on user activity
  const score = calculateEngagement(user);

  return { score };
}

Run validation:

blocks run user_engagement_score

Output:

🧱 Blocks Validator

📦 Validating: user_engagement_score
  ✓ schema ok
  ✓ shape ok
  ✓ domain ok

  ✅ Block "user_engagement_score" passed all validations

Next Steps