# Awen Lang

> Awen Lang is a small declarative assembly-sheet language for handing settled project decisions and their source files to an AI agent or toolchain.

The sheet records the intended output, source authority, required behaviour, constraints, acceptable temporary substitutes, approval boundaries and completion criteria. It supports software, writing, video and data, including new work and changes to existing projects.

Awen is independent of any model or vendor and requires no Awen-specific tooling. A capable agent or toolchain reads the sheet and produces the output using its tools. Approval and verification depend on the executor and human review, not automatic enforcement by the language. The GitHub repository contains the canonical specification.

## Canonical resources

- [Repository](https://github.com/ioioioan/awen-lang): Source of truth for Awen Lang.
- [Specification](https://github.com/ioioioan/awen-lang/blob/main/SPEC.md): Awen Lang v0.1 semantics.
- [Agent instructions](https://github.com/ioioioan/awen-lang/blob/main/AGENTS.md): How an AI should understand and use the repository.
- [Workflow](https://github.com/ioioioan/awen-lang/blob/main/WORKFLOW.md): How to prepare and use a sheet.
- [Tool guidance](https://github.com/ioioioan/awen-lang/blob/main/TOOLS.md): Tool roles and verification.
- [Template](https://github.com/ioioioan/awen-lang/blob/main/TEMPLATE.awen): Canonical starting assembly sheet.
- [Examples](https://github.com/ioioioan/awen-lang/tree/main/examples): Example Awen files.
- [Human-readable website](https://awenlang.org/): Public introduction.
- [Markdown website](https://awenlang.org/index.md): Markdown version of the public introduction.

## Core interpretation

Awen does not execute code or provide an agent runtime.

When creating an Awen assembly sheet:
- preserve the creator's settled intent;
- use exact source and repository paths where relevant;
- use REPOSITORY for existing work and REVISION or BASE when source state matters;
- distinguish AUTHORITATIVE from CONTEXT sources;
- do not invent unresolved decisions;
- use REQUIRE, PREFER, AVOID and FORBID according to their strength;
- preserve VERBATIM content exactly;
- describe core user/artifact semantics in BEHAVIOR;
- declare acceptable temporary substitutes in SEAMS;
- surface missing sources, conflicting authoritative declarations, APPROVAL items and BLOCKERS;
- make DONE WHEN concrete and prefer objective checks where available.