# 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. It is open source, independent of any model or vendor, and suitable for software, writing, video and data. No Awen-specific tooling is required.

## What a sheet records

- Sources: distinguish authoritative files from context; preserve exact copy when required.
- Requirements: define behaviour, requirements, preferences and prohibited choices.
- Approvals: set human approval boundaries and flag unresolved decisions.
- Completion: set acceptance criteria and verify them with tests or review.

## How to use it

Disciplined vibe coding: settle the important decisions, then hand over a `.awen` sheet and the relevant files. It describes what to produce, what must be preserved and which temporary substitutes are acceptable. Use it for new work or changes to an existing project.

A capable agent or toolchain reads the sheet directly, produces the output and checks it against the acceptance criteria. Approval and verification are carried out by that agent, toolchain or a human.

## Example

This example adds film search to an existing project and requires approval for database changes.

```text
AWEN 0.1

PROJECT ZeroReel
OUTPUT film search feature
ROOT .

REPOSITORY
  MODE existing
  ROOT .

SOURCES
  PRODUCT  ./docs/product.md  AUTHORITATIVE
  SEARCH   ./docs/search.md   AUTHORITATIVE

REQUIRE
  search published films by title
  preserve existing discovery flow
  accessible keyboard interaction

PREFER
  progressive enhancement
  CSS OVER JavaScript

APPROVAL
  HUMAN database schema changes

DONE WHEN
  search returns matching published films
  existing tests pass
```

## Resources

- Repository: https://github.com/ioioioan/awen-lang
- Specification: https://github.com/ioioioan/awen-lang/blob/main/SPEC.md
- Workflow: https://github.com/ioioioan/awen-lang/blob/main/WORKFLOW.md
- Examples: https://github.com/ioioioan/awen-lang/tree/main/examples
- Contributing: https://github.com/ioioioan/awen-lang/blob/main/CONTRIBUTING.md
- Apache 2.0 licence: https://github.com/ioioioan/awen-lang/blob/main/LICENSE

## Why Awen?

**Awen** is a Welsh word associated with inspiration, especially poetic or creative inspiration. In Welsh bardic tradition, *awen* is the creative force behind the work of the poet or maker. For Awen Lang, inspiration becomes useful through discipline, structure and craft.

## Agent discovery

This site provides this Markdown version, structured metadata and [llms.txt](https://awenlang.org/llms.txt) to help agents find the specification and repository.