Getting Started

aglang is a verifiable specification language for agents and humans. You write or review architecture.ag; aglc compiles it into artifacts that agents, engineers, and CI can use without guessing the intended architecture.

Install

npm — global (recommended)

npm install -g @collivity/aglang

npx — no install needed

npx @collivity/aglang add .

GitHub URL

npm install github:collivity/aglang

Requirements:

• Node.js ≥ 18 — nodejs.org
• A git repository

The solver ships via the z3-solver npm package (WebAssembly) — no system install needed.

---

Quick setup — agent-assisted discovery

aglc request-scan --project /path/to/your/project

This writes .aglang/tasks/architecture-discovery.json, a machine-readable task packet for an agent. The agent should inspect the repo semantically and propose architecture artifacts for review. aglc does not infer architecture intent automatically.

The approved flow is:

1. Request discovery with aglc request-scan
2. Agent proposes architecture.proposed.ag, optional .agq.yml queries, and review notes
3. Human approves architecture intent
4. Compile approved architecture.ag to architecture.o
5. Emit skill.json so AI agents understand your architectural rules

aglc add and aglc generate remain available as legacy deterministic draft helpers, but their output is not architecture truth until reviewed.

---

Add your first rule

Use a planning or design session to review the generated architecture.ag and any imported component files, then refine the intended invariants. A first rule might look like:

invariant NoDirectDBAccess {
  deny flow PublicAPI -> Database
}

After the architecture change is approved, recompile:

aglc compile architecture.ag

From now on, aglc check --arch architecture.o --project . --all reports any direct path from PublicAPI to Database with a precise error message and proof details. Run the same command locally or in CI.

---

How it works

Your codebase                   Your .ag spec
     │                               │
     ▼                               ▼
[Git Diff Extractor]    +    [Architecture Compiler]
     │                               │
     └──────────── Z3 Solver ────────┘
                        │
               SAT   → check passes ✓
               UNSAT → check fails with proof ✗

1. You write an architecture.ag file describing components and invariants
2. aglc compile translates it to SMT-LIB and emits architecture.o
3. aglc check checks extracted code facts against the compiled rules — SAT means the facts are consistent with the architecture, and UNSAT means a violation was proven

---

Designed for AI Agents

AI coding agents can operate autonomously for long stretches. aglang gives them a shared, verifiable specification: the agent reads generated context, edits code within component boundaries, and validates work against the same compiled artifact that humans and CI use.

• aglc request-scan asks an agent to propose architecture artifacts; aglc add remains a legacy draft helper
• Agents read AGENTS.md (generated by aglc emit-context) to understand boundaries before they start
• Humans, agents, and CI can run the same aglc check gate

See the AI Agents guide for the full integration workflow.