System Constitution - Architectural governance for autonomous software evolution (CLI + Validator)
npm install @redush/sysconst
┌─────────────────────────────────────────────────────────────────────────────┐
│ HOW IT WORKS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ╔═══════════════════════════════════════════════════════════════════════╗ │
│ ║ 1. INIT — Bootstrap architecture from user prompt ║ │
│ ╚═══════════════════════════════════════════════════════════════════════╝ │
│ │
│ User LLM Constitution │
│ ┌─────────┐ ┌─────────────┐ ┌──────────────┐ │
│ │ "Build │ │ Generates │ │ myapp. │ │
│ │ e-comm │──────────────▶│ initial │────────────▶│ sysconst. │ │
│ │ system" │ │ structure │ │ yaml │ │
│ └─────────┘ └─────────────┘ └──────┬───────┘ │
│ │ │
│ ═══════════════════════════════════════════════════════════════╪═══════ │
│ ▼ │
│ ╔═══════════════════════════════════════════════════════════════════════╗ │
│ ║ 2. EVOLVE — Continuous development with guardrails ║ │
│ ╚═══════════════════════════════════════════════════════════════════════╝ │
│ │
│ Constitution LLM Evolution Your Code │
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────────────┐ │
│ │ entities: │ │ "Add payment" │ │ src/ │ │
│ │ - User │───▶│ │───▶│ entities/ │ │
│ │ - Order │ │ Modifies YAML: │ │ commands/ │ │
│ │ │ │ + PaymentModule │ │ events/ │ │
│ │ contracts: │ │ + PaymentEntity │ │ │ │
│ │ - "no cycles" │ └────────┬─────────┘ │ (generated from YAML)│ │
│ │ - "refs valid" │ │ └───────────────────────┘ │
│ └────────▲─────────┘ ▼ │
│ │ ┌──────────────────┐ │
│ │ │ VALIDATOR │ │
│ │ │ │ │
│ │ │ ✓ Schema OK │ │
│ │ │ ✓ Refs resolve │ │
│ │ │ ✓ Contracts OK │ │
│ │ │ ✓ Evolution OK │ │
│ │ │ │ │
│ │ │ ✗ Violation? │ │
│ │ │ → REJECTED │ │
│ │ └────────┬─────────┘ │
│ │ │ │
│ └───────────────────────┘ │
│ Only valid changes saved │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
`
The Problem
When LLMs evolve your codebase autonomously, they don't understand your architectural decisions:
- Why modules are separated
- Which dependencies are forbidden
- What invariants must hold
- How schemas can evolve
Result: Gradual architectural erosion. Each change seems fine, but over time the system degrades.
The Solution
Put your architecture in a machine-readable file with explicit contracts. LLMs read and modify this file. The validator blocks any change that violates your rules.
| Without Constitution | With Constitution |
|---------------------|-------------------|
| Architecture lives in developers' heads | Architecture is explicit YAML |
| LLM guesses what's allowed | LLM sees exact constraints |
| Bad changes slip through | Validator blocks violations |
| Manual review required | Autonomous evolution possible |
Installation
`bash
Global CLI
npm install -g @redush/sysconst
As library
npm install @redush/sysconst
`
Quick Start
$3
`bash
Create constitution with LLM generation
sysconst init myshop -d "E-commerce platform with products and orders"
Create minimal template (no LLM)
sysconst init myapp --no-generate
Validate
sysconst validate myapp.sysconst.yaml
`
$3
`typescript
import { validateYaml } from '@redush/sysconst';
const result = validateYaml(
);
if (result.ok) {
console.log('Constitution is valid!');
} else {
console.log('Errors:', result.errors);
}
`
CLI Commands
$3
`bash
sysconst init [options]
Options:
-d, --description Description for LLM generation
--no-generate Skip LLM, create minimal template
--provider LLM provider (openrouter|openai|anthropic|ollama)
--model Specific model to use
`
$3
`bash
sysconst validate myapp.sysconst.yaml
`
$3
`bash
sysconst evolve myapp.sysconst.yaml -c "Add payment processing"
`
$3
`bash
sysconst generate "Task management system" -o tasks.sysconst.yaml
`
$3
`bash
sysconst version bump -f
sysconst version tag -f
sysconst history -f
sysconst diff v1.0.0 v1.1.0 -f
sysconst checkout v1.0.0
`
Validation Phases
| Phase | Description |
|-------|-------------|
| 1. Structural | Syntax, required fields, JSON Schema |
| 2. Referential | NodeRef resolution, unique IDs |
| 3. Semantic | Kind-specific rules |
| 4. Evolution | Version history, migrations |
| 5. Generation | Zone safety, hooks |
| 6. Verifiability | Scenarios, pipelines |
Validation API
`typescript
import { validateYaml, validate, parseSpec } from '@redush/sysconst';
// Validate YAML string
const result = validateYaml(yamlString);
// Validate parsed object
const result = validate(specObject);
// Parse YAML to object
const spec = parseSpec(yamlString);
`
$3
`typescript
interface ValidationResult {
ok: boolean;
errors: ValidationError[];
warnings: ValidationError[];
phase: ValidationPhase;
}
`
Node Kinds
| Kind | Purpose |
|------|---------|
| System | Root container |
| Module | Logical grouping with boundaries |
| Entity | Persistent data with invariants |
| Command | Write operation with preconditions |
| Event | State change notification |
| Process | Multi-step workflow |
| Scenario | Verification case |
LLM Providers
| Provider | Default Model |
|----------|---------------|
| OpenRouter (default) | anthropic/claude-sonnet-4.5 |
| OpenAI | gpt-5.2 |
| Anthropic | claude-sonnet-4-5 |
| Ollama | llama4 (free, local) |
$3
On first use, CLI prompts for API key → saved to ~/.sysconst/config.yaml.
For CI/CD:
`bash
export OPENROUTER_API_KEY=sk-or-v1-...
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
`
Constitution File Format
`yaml
spec: sysconst/v1
project:
id: myapp
versioning:
strategy: semver
current: "1.0.0"
domain:
nodes:
- kind: Entity
id: entity.user
spec:
fields:
id: { type: uuid, required: true }
email: { type: string, required: true }
contracts:
- invariant: "email != ''"
- kind: Entity
id: entity.order
spec:
fields:
userId: { type: ref(entity.user), required: true }
contracts:
- invariant: "userId != null"
``