Authoring Blueprints

Every blueprint follows a schema that enforces required sections, field constraints, and compliance levels. This guide covers the governance system, blueprint types, inheritance via extends, and the validation pipeline.

Blueprint Types

There are six schema-governed blueprint types, each with its own required sections and validation rules:

Required Sections

Every blueprint — regardless of type — must include these sections:

# Blueprint Title

## Metadata
- Type: pattern | architecture | agent | protocol | platform | standard
- Category: (e.g., governance, infrastructure, api)
- Version: 1.0.0
- Status: draft | active | deprecated
- Extends: [list of parent blueprints]

## Overview
What this blueprint specifies and why it exists.

## Specification
The normative contract — what implementations MUST do.

## Types
Data structures, envelopes, enums used by this spec.

## Implementation Notes
Non-normative guidance for implementers.

## Verification
Checklist for conformance testing.

Compliance Levels

Blueprints are validated against their schema and assigned a compliance level:

Inheritance with extends

Blueprints inherit cross-cutting concerns through the extends field. This eliminates copy-paste and prevents drift across related specs.

# API REST Pattern

## Metadata
- Type: pattern
- Category: api
- Version: 1.0.0
- Extends:
  - patterns/scope
  - patterns/policy
  - patterns/rate-limiting
  - patterns/observability

When a blueprint extends others, the inherited constraints are merged:

• Scope — classification levels propagate to all endpoints
• Policy — declarative rules apply to all operations
• Safety — protection gates inherited for destructive operations
• Observability — health endpoints and metrics required by default

Validation Pipeline

Run weblisk validate to check all blueprints against their schemas:

# Validate all blueprints in the project
weblisk validate

# Output
✓ patterns/api-rest.md        Certified
✓ patterns/auth-token.md      Certified
✓ patterns/scope.md           Certified
⚠ patterns/my-custom.md       Partial (missing: Verification)
✗ patterns/broken.md          Rejected (missing: Specification, Types)

4 certified, 0 compliant, 1 partial, 0 draft, 1 rejected

The validation pipeline checks:

1. Structure — required sections present per schema type
2. Metadata — type, category, version, status fields valid
3. Extends — all referenced parent blueprints exist and are resolvable
4. Types — referenced data structures are defined
5. Verification — checklist items are testable assertions

Writing a New Pattern

To create a custom pattern blueprint:

1. Create a Markdown file in your project's patterns/ directory
2. Add all required sections per the pattern schema
3. Declare extends for any cross-cutting concerns that apply
4. Include a verification checklist with testable assertions
5. Run weblisk validate to check compliance

# My Feature Pattern

## Metadata
- Type: pattern
- Category: operations
- Version: 1.0.0
- Status: active
- Extends:
  - patterns/scope
  - patterns/logging

## Overview
Describe what this pattern governs and why.

## Specification
Define the normative contract:
- Endpoints, behaviors, constraints
- Error conditions and responses
- Required vs optional capabilities

## Types
```
MyRequest { field: type, ... }
MyResponse { field: type, ... }
```

## Implementation Notes
- Recommended approaches per platform
- Performance considerations
- Common pitfalls

## Verification
- [ ] Endpoint responds with correct status codes
- [ ] Invalid input returns 400 with error envelope
- [ ] Scope constraints enforced at boundary
- [ ] Structured logs emitted for all operations

Blueprint Sources

Custom blueprints are resolved alongside core ones — local project patterns take highest priority, followed by custom repos configured via WL_BLUEPRINT_SOURCES, then core. See Blueprint Resolution in the catalog for the full priority chain and distribution models.