Constrain

Find the boundary between specification and intent.

Constrain interviews engineers about their problem and produces five artifacts that feed directly into downstream tools. The prompt gives an AI agent the context to build the right thing. The constraints, trust policy, component map, and schema hints give downstream systems the structured data they need to scaffold contracts, orchestrate circuits, arbitrate trust, and build schemas.

pip install -e ".[anthropic]"    # Anthropic backend (default)
pip install -e ".[openai]"       # OpenAI-compatible backend
pip install -e ".[mcp]"          # MCP server
pip install -e ".[all]"          # Everything

Requires Python 3.12+ and an API key for your chosen backend.

Backend selection

Constrain supports Anthropic (default) and any OpenAI-compatible API, including local models.

# Anthropic (default)
export ANTHROPIC_API_KEY=sk-...
constrain

# OpenAI
constrain --backend openai --model gpt-4o

# Local model via OpenAI-compatible API
CONSTRAIN_BACKEND=openai OPENAI_BASE_URL=http://localhost:11434/v1 constrain --model llama3

Environment variables: CONSTRAIN_BACKEND=anthropic|openai, CONSTRAIN_MODEL=<model-name>

Three phases

1. Understand

Collaborative interview builds a problem model: system context, stakeholders, failure modes, dependencies, assumptions, boundaries. 2–10 rounds.

2. Challenge

A randomly selected analytical posture probes for gaps, ambiguities, hidden assumptions, conflict resolution, and storage obligations. The posture is hidden—you can't game it.

3. Synthesize

Generates five artifacts from the accumulated conversation, validates YAML and cross-references, then writes to disk with one revision cycle.

Five postures

Randomized per session so descriptions must be robust to all of them.

Adversarial

Exploits ambiguity

Contrarian

Challenges the problem

Critic

Finds disagreement

Skeptic

Tests metrics

Collaborator

Constructive gaps

Five artifacts

prompt.md

Briefing for an AI agent. System context, consequence map, failure archaeology, dependency landscape, boundary conditions, trust model, component topology.

constraints.yaml

Black-box boundary conditions with classification tiers and affected components. Implementation-agnostic.

trust_policy.yaml

Trust floors, data classifications, soak durations, authority map, and human gate triggers.

component_map.yaml

Component definitions with data access, authority domains, dependencies, and edge topology.

schema_hints.yaml

Storage backend inventory and field-level hints with classification and annotations (gdpr_erasable, audit_field, encrypted_at_rest, immutable). Consumed by Ledger for schema scaffolding.

constraints:
  - id: C001
    boundary: "file upload endpoint"
    condition: "files > 10MB rejected before processing"
    violation: "large file consumed memory, crashed worker"
    severity: must
    rationale: "production incident 2024-03"
    classification_tier: null
    affected_components: ["api-gateway"]

Downstream integration

Artifact	Consumer	Purpose
`prompt.md`	Pact	System briefing for decomposition
`constraints.yaml`	Pact, Sentinel	Contracts and violation detection
`trust_policy.yaml`	Arbiter	Trust arbitration configuration
`component_map.yaml`	Pact, Baton	Topology for decomposition and circuits
`schema_hints.yaml`	Ledger	Schema scaffolding from interview hints

CLI reference

constrain              # Start a new session (or resume incomplete)
constrain new          # Always start fresh
constrain resume       # Resume the most recent incomplete session
constrain show         # Display artifacts from the last completed session
constrain list         # List all sessions
constrain validate     # Validate all artifacts for internal consistency
constrain export -f <format>   # Export skeletons for downstream tools
constrain mcp-server   # Run MCP server (stdio transport)

Validation

constrain validate checks internal consistency across all five artifacts: component names match between component_map.yaml and constraints.yaml, authority domains align between trust_policy.yaml and component_map.yaml, edge/dependency references resolve, trust floor ordering is valid, and annotation requirements are satisfied.

Export formats

Generate skeletons for downstream tools from your Constrain artifacts.

constrain export --format pact     # task.md skeleton from prompt.md
constrain export --format baton    # baton.yaml skeleton from component_map.yaml
constrain export --format arbiter  # arbiter.yaml skeleton from trust_policy.yaml
constrain export --format ledger   # schema_hints.yaml skeleton for Ledger

Format	Source Artifact	Output
`pact`	`prompt.md`	task.md skeleton for Pact decomposition
`baton`	`component_map.yaml`	baton.yaml with nodes, edges, data access
`arbiter`	`trust_policy.yaml`	arbiter.yaml with trust config, classifications
`ledger`	`schema_hints.yaml`	Ledger schema scaffolding with field hints

Session persistence

Sessions save to .constrain/sessions/ in the current directory. Ctrl+C saves and exits (resumable). Ctrl+D ends the current phase early.

MCP server

Constrain exposes sessions and artifacts to AI assistants via the Model Context Protocol.

# Standalone
constrain-mcp

# Via CLI
constrain mcp-server --project-dir /path/to/project

# Register with Claude Code
claude mcp add --scope user --transport stdio constrain -- constrain-mcp

Tools: constrain_list_sessions, constrain_show_session, constrain_show_artifacts, constrain_search_sessions

Resources: constrain://sessions, constrain://session/{id}, constrain://artifacts/{id}