Skip to main content
B

Guardrails That Keep Your
Agentic Code Generation
Aligned With Your Domain

Get started in seconds:

npm install -g @blocksai/cli
blocks run my-block
Get StartedView Live ExamplesChangelog
blocks.yml
$schema: "blocks/v2"

philosophy:
  - "Blog posts must include humor"

domain:
  semantics:
    humor_score:
      description: "How funny is this content?"

validators:
  - schema
  - name: domain
    config:
      rules:
        - id: humor_required
          description: "Must include wit"

blocks:
  validator.blog_post:
    description: "Validates blog content"
    path: "validators/blog"

Not Locking Down Code—Giving You a Semantic Compass

Blocks doesn't restrict who can edit code. Instead, it detects when either humans or AI introduce drift from the spec.

[✓]

Humans Write Code

You're free to modify any block. Write, refactor, experiment—Blocks won't stop you.

[>_]

AI Agents Write Code

Any AI coding assistant can modify blocks. LLM agnostic—works with all providers.

[~]

Blocks Detects Drift

Run validation. Blocks reports drift and helps you decide: fix code or update spec.

The Validation Loop

01.

Human or AI writes code

02.

Run blocks run <name>

03.

Validators run—built-in or custom. Check types, structure, semantics, or anything (screenshots, contrast, performance, security...)

04.

Drift detected? You decide: fix code or update spec

05.

Iterate until both code and spec align

The Feedback Loop in Action

Watch how an AI agent uses Blocks to iterate until code meets your spec.

AI Agent Session
User
Add a new scorer module for the job recommendation engine that calculates location proximity score
Agent
I'll create a location scorer that calculates distance-based similarity.
Created: blocks/scorer-location/index.ts
Created: blocks/scorer-location/scorer.ts
Agent runs validation
$ blocks run scorer.location
✓ schema.io passed
✗ domain.validation failed
• Score output range is 0-100, should be normalized 0-1
• Missing handling for remote jobs (should return 1.0)
• Distance calculation doesn't account for "willing to relocate" flag
Agent
The domain validator caught 3 issues with my scoring logic:
1. Normalized score output to 0-1 range
2. Added remote job check → returns 1.0
3. Added relocation flag handling → boosts score by 0.3
Agent runs validation
$ blocks run scorer.location
✓ schema.io passed
✓ shape.exports.ts passed
✓ domain.validation passed
All validators passed
Agent
Done. The location scorer is ready and integrates with the other scoring modules.

The agent sees validation output, understands the issues, and fixes them autonomously.

Watch the Example

Multi-Layer Validation

Catch issues at every level: from schema validation to semantic analysis with AI.

Schema

Fast, deterministic validation of inputs, outputs, and data types using Zod schemas.

Shape

Verify file structure, exports, and conventions to maintain consistent block organization.

Domain

AI-powered semantic analysis that understands your domain concepts and validates against them.

Fully Extensible Validator System

schema, shape, and domain are just the built-in validators we recommend. You can add any number of custom validators, override the defaults, or build your own validation pipeline.

# Mix built-in and custom validators
validators:
- schema
- domain
- name: security_scan
run: "security.audit"
- name: perf_check
run: "perf.benchmark"

Live Examples

Explore real-world examples built to discover what Blocks should be. Each example explores different domain patterns.

Resume Themes

Template Rendering

Validates resume themes for semantic HTML, accessibility, and responsive design using DRY domain rules.

HandlebarsWCAG
View Example

Blog Validator

Content Quality

Validates markdown posts for humor and conversational tone using AI-powered semantic analysis.

MarkdownTone Analysis
View Example

HR Engine

Production-Ready

Complete recommendation system with scoring, ranking, and filtering. Shows multi-block composition.

ScoringRanking
View Example

Each example helped shape the Blocks specification through practical discovery.

Explore All Examples

Ready to Add Guardrails to Your AI Codebase?

Create a feedback loop where AI agents run validation until all code aligns with your domain requirements.

Get StartedView on GitHub