ACL.md

code:acl.md

# Agent Communication Language (ACL)

---

Agent Communication Language (ACL) is a Domain-Specific Language (DSL) for concise, structured communication with AI agents. It provides a simple syntax for instructing agents in development workflows.

**ACL prioritizes intent and context over strict syntax rules.**

This is not a language for static parsing—it's a communication protocol for LLMs. The agent should:

1. **Understand intent first** - Focus on what the user wants

2. **Interpret from context** - Use conversation history and project state

3. **Be flexible** - Adapt to variations in syntax and expression

- **Simplicity**: Easy to learn and use

- **Brevity**: Minimal verbosity

- **Flexibility**: Context-aware interpretation

- **Composability**: Chain operations naturally

- **Persistence**: Retain knowledge across sessions

ACL is for:

- Development workflow automation

- Agent behavior customization

- Knowledge management

- Error handling and recovery

---

All ACL expressions follow a simple pattern:

scope.action(details)

**Components**:

- **scope**: Where the action takes place (optional for global functions)

- **action**: What to do

- **details**: Parameters or context (optional)

**Examples**:

fix("failing tests") # Global function (no scope)

project.build() # Object method

test("auth/**") # Global with parameter

note("convention") # Global with parameter

project.note("convention") # Object method with parameter

**Multiple parameters**:

refactor("UserService", "extract authentication")

**Chaining**:

project.build() && test() && project.deploy()

**Property access**:

fix(test().failures)

**Promise-like handling**:

project.deploy()

.then("notify team")

.catch("rollback")

.finally("cleanup")

**Event handlers**:

on(alert, "stop and analyze the issue")

The agent should interpret ACL expressions flexibly:

- Missing scope → assume global function or infer from context

- Unknown method → check for typos, aliases, or context clues

- Ambiguous syntax → prioritize user intent over strict parsing

---

Global functions work across all projects and are called without a scope prefix.

**Available Functions**:

# Fix issues

fix("typescript errors")

fix("failing unit tests")

# Safe refactoring

refactor("auth module", "separate concerns")

# Analysis only (no changes)

think("optimal caching strategy")

# Run tests

test() # All tests

test("integration/**") # Pattern filter

# Agent feedback

alert("You violated the security policy")

# Retry after fixing

project.deploy() # Fails

fix("credentials")

retry() # Retries deploy

# Fetch external data

# Save user-level notes

note("Use TypeScript strict mode")

note("Prefer composition over inheritance")

# Enrich documentation

docs("authentication module")

docs("API endpoints")

docs("UserService class")

- **fix**: Diagnoses and resolves issues

- **refactor**: Ensures tests pass before and after changes

- **think**: Read-only analysis, provides insights

- **retry**: Automatically detects and retries last failed operation

- **docs**: Understands specified targets (modules, classes, APIs) and enriches their documentation

---

**Purpose**: System initialization and management

**Methods**:

**Examples**:

ACL.init() # Setup project

ACL.list() # See available methods

ACL.undef(project.deploy, project.publish) # Disable dangerous methods

**Purpose**: Project context and knowledge

**Core Methods**:

- Auto-generated from package.json, Makefile, justfile, etc.

**Properties**:

**Examples**:

project.note("This project uses TypeScript strict mode")

project.build()

project.deploy()

**Scope**: Current project only

**Purpose**: Current conversation analysis

**Methods**:

**Properties**:

**Examples**:

project.note(session.insights()) # Save to project

note(session.summary()) # Save to user-level

**Scope**: Current conversation only

Context-dependent objects (available when relevant):

---

project.build() && test() && project.deploy()

Execution stops if any step fails.

Handle success, failure, and cleanup:

method()

.then(action_on_success)

.catch(action_on_failure)

.finally(action_for_cleanup)

**Execution**:

- Success: method → then → finally

- Failure: method → catch → finally

**Examples**:

project.deploy()

.then("send Slack notification")

.catch("rollback and alert team")

.finally("update deployment log")

project.build()

.then(test())

.then(project.deploy())

.catch(fix("build or test failures"))

Define custom behavior for events:

on(event_name, action)

**Supported Events**:

**Examples**:

on(alert, "Stop all work and analyze the issue")

alert("You modified the wrong file")

# → Triggers handler

**Scope**: Current session only

---

User Level (~/.claude/CLAUDE.md)

↓ Personal preferences, coding standards

Managed via: note()

Project Level (.claude/CLAUDE.md or CLAUDE.md)

↓ Project conventions, architecture

Managed via: project.note()

Session Level (temporary)

↓ Current conversation insights

Analyzed via: session.insights(), session.summary()

| Method | File | Scope | Use Case |

|--------|------|-------|----------|

Project CLAUDE.md contains ACL method definitions:

# ACL Method Definitions

project: {

build: exec("pnpm run build")

lint: exec("pnpm run lint")

deploy: exec("pnpm run deploy")

}

**Management**:

---

fix("failing tests")

fix("typescript errors")

fix(lint().errors)

refactor("auth module", "extract logic")

refactor("API routes", "consolidate error handling")

project.build() && test() && project.deploy()

project.build()

.then(test())

.then(project.deploy())

.catch(fix("pipeline failure"))

project.deploy()

.then("notify team")

.catch("rollback")

.finally("cleanup resources")

note("Use TypeScript strict mode")

note("Prefer composition over inheritance")

project.note("This project uses feature-based folders")

project.note(session.insights())

think(apiData.content)

fix(test().failures)

refactor(lint().errors, "improve code quality")

think(project.analyze().bottlenecks)

docs("authentication module")

docs("UserService class")

docs("REST API endpoints")

on(alert, "Stop and analyze")

ACL.undef(project.deploy, project.publish)

---

- ✅ Quick workflows

- ✅ Build pipelines

- ✅ Error handling

- ✅ Knowledge persistence

- ✅ Agent customization

- ✅ Complex explanations

- ✅ Exploratory questions

- ✅ Unclear mappings

- Be descriptive but concise

- Follow project conventions

- Undefine at session start

- Common: disable production deploys, destructive operations

---

objectName := expression

**Example**:

objectName: {

methodName: exec("command")

otherMethod: "natural language instruction"

}

**Example**:

project: {

build: exec("pnpm run build")

deploy: exec("pnpm run deploy")

verify: project.build && test

}

---

---

| File | Location | Purpose |

|------|----------|---------|

| ACL definitions | Within CLAUDE.md files | Method definitions |

---

- Nested promise chains

- Promise.all() / Promise.race() equivalents

---

**Version**: 3.5

**Last Updated**: 2025-10-07