Agent Communication Language (ACL)

Version 3.5

1. Introduction

1.1 Purpose

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.

1.2 Core Principle: Context Over Formalism

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:

Understand intent first - Focus on what the user wants
Interpret from context - Use conversation history and project state
Be flexible - Adapt to variations in syntax and expression

1.3 Design Goals

Simplicity: Easy to learn and use
Brevity: Minimal verbosity
Flexibility: Context-aware interpretation
Composability: Chain operations naturally
Persistence: Retain knowledge across sessions

1.4 Scope

ACL is for:

Development workflow automation
Agent behavior customization
Knowledge management
Error handling and recovery

2. Core Concept: scope.action(details)

2.1 Basic Structure

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

2.2 Variations

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")

2.3 Interpretation Rules

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

3. Global Functions

3.1 Overview

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

Available Functions:

begin(goal) - Begin working on task with git branch and TODO planning
fix(issue) - Analyze and fix problems
refactor(targets, direction) - Refactor safely with tests
think(issue) - Analyze without modifying files
test(pattern?) - Run tests
alert(message) - Alert agent about violations or mistakes
retry() - Retry last failed task
fetch(url) - Fetch web resources
note(message) - Save to user-level CLAUDE.md
docs(targets) - Understand targets and enrich documentation

3.2 Usage

# 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
fetch("https://api.example.com/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")

3.3 Behavior

fix: Diagnoses and resolves issues
refactor: Ensures tests pass before and after changes
think: Read-only analysis, provides insights
test: Analyzes tests first, generates minimal specs if coverage seems insufficient, then runs tests. Returns object with .failures, .errors, .passed
alert: Triggers on(alert) handlers, stops current work
retry: Automatically detects and retries last failed operation
fetch: Returns object with .content, .status, .headers
note: Saves to user-level ~/.claude/CLAUDE.md, persists across all projects
docs: Understands specified targets (modules, classes, APIs) and enriches their documentation

4. Objects

4.1 ACL Object

Purpose: System initialization and management

Methods:

ACL.init() - Initialize project, create CLAUDE.md, scan build tools
ACL.update() - Re-scan and update method definitions
ACL.list() - Show all available methods
ACL.undef(methods...) - Disable specified methods

Examples:

ACL.init()                              # Setup project
ACL.list()                              # See available methods
ACL.undef(project.deploy, project.publish)  # Disable dangerous methods

4.2 project Object

Purpose: Project context and knowledge

Core Methods:

project.note(message) - Save to .claude/CLAUDE.md or CLAUDE.md

Dynamic Methods (generated by ACL.init()):

project.build(), project.lint(), project.deploy(), etc.
Auto-generated from package.json, Makefile, justfile, etc.

Properties:

project.name, project.root, project.config

Examples:

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

Scope: Current project only

4.3 session Object

Purpose: Current conversation analysis

Methods:

session.summary() - Generate session summary
session.insights() - Extract actionable insights

Properties:

session.id, session.duration

Examples:

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

Scope: Current conversation only

4.4 Standard Objects

Context-dependent objects (available when relevant):

app - Application control: app.serve(), app.build()
chrome/browser - Browser operations: chrome.inspect(app)
server - Server operations: server.start(), server.stop()

5. Chaining & Handlers

5.1 Sequential Chaining

Use && to chain operations:

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

Execution stops if any step fails.

5.2 Promise-like Chains

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"))

5.3 Event Handlers

Define custom behavior for events:

on(event_name, action)

Supported Events:

alert - Triggered by alert() calls

Examples:

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

alert("You modified the wrong file")
# → Triggers handler

Scope: Current session only

6. Knowledge Management

6.1 Hierarchy

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()

6.2 Persistence

Method	File	Scope	Use Case
`note()`	`~/.claude/CLAUDE.md`	All projects	Personal preferences
`project.note()`	`.claude/CLAUDE.md` or `CLAUDE.md`	Current project	Project conventions
`session.insights()`	Return value	Temporary	Extract learnings

6.3 Method Definitions

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:

Created by ACL.init()
Updated by ACL.update()
Listed by ACL.list()

7. Common Patterns

7.1 Quick Fixes

fix("failing tests")
fix("typescript errors")
fix(lint().errors)

7.2 Safe Refactoring

refactor("auth module", "extract logic")
refactor("API routes", "consolidate error handling")

7.3 Build Pipelines

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

project.build()
  .then(test())
  .then(project.deploy())
  .catch(fix("pipeline failure"))

7.4 Error Handling

project.deploy()
  .then("notify team")
  .catch("rollback")
  .finally("cleanup resources")

7.5 Knowledge Capture

note("Use TypeScript strict mode")
note("Prefer composition over inheritance")
project.note("This project uses feature-based folders")
project.note(session.insights())

7.6 Web Resources

fetch("https://api.github.com/repos/owner/repo")
apiData := fetch("https://api.example.com/metrics")
think(apiData.content)

7.7 Method Composition

fix(test().failures)
refactor(lint().errors, "improve code quality")
think(project.analyze().bottlenecks)

7.8 Documentation

docs("authentication module")
docs("UserService class")
docs("REST API endpoints")

7.9 Custom Behaviors

on(alert, "Stop and analyze")
ACL.undef(project.deploy, project.publish)

8. Best Practices

8.1 When to Use ACL

✅ Quick workflows
✅ Build pipelines
✅ Error handling
✅ Knowledge persistence
✅ Agent customization

8.2 When to Use Natural Language

✅ Complex explanations
✅ Exploratory questions
✅ Unclear mappings

8.3 Naming

Use camelCase: buildAndTest()
Be descriptive but concise
Follow project conventions

8.4 Knowledge Management

note() for personal preferences (user-level)
project.note() for project-specific rules
ACL.update() after changing build scripts
session.insights() at end of work

8.5 Error Handling

Use .then/.catch/.finally for critical operations
Use alert() for agent mistakes
Define on(alert) handlers early in session

8.6 Method Safety

Use ACL.undef() to disable dangerous methods
Undefine at session start
Common: disable production deploys, destructive operations

9. Declaration Syntax

9.1 Object Declaration

objectName := expression

Example:

api := server.new("http://localhost:3000")

9.2 Method Definition

objectName: {
  methodName: exec("command")
  otherMethod: "natural language instruction"
}

Example:

project: {
  build: exec("pnpm run build")
  deploy: exec("pnpm run deploy")
  verify: project.build && test
}

10. Reserved Keywords

exec - Command execution
on - Event handler definition
then - Promise success handler
catch - Promise error handler
finally - Promise cleanup handler

11. File Locations

File	Location	Purpose
User CLAUDE.md	`~/.claude/CLAUDE.md`	User-wide configuration
Project CLAUDE.md	`.claude/CLAUDE.md` or `CLAUDE.md`	Project configuration
ACL definitions	Within CLAUDE.md files	Method definitions

12. Future Extensions

Conditional execution: if condition then command
Loops: for item in items do command
Pattern-based undef: ACL.undef(project.*)
Nested promise chains
Promise.all() / Promise.race() equivalents
Additional events: on(error), on(complete)

Version: 3.5 Last Updated: 2025-10-07

lacolaco/ACL.md

Agent Communication Language (ACL)

Version 3.5

1. Introduction

1.1 Purpose

1.2 Core Principle: Context Over Formalism

1.3 Design Goals

1.4 Scope

2. Core Concept: scope.action(details)

2.1 Basic Structure

2.2 Variations

2.3 Interpretation Rules

3. Global Functions

3.1 Overview

3.2 Usage

3.3 Behavior

4. Objects

4.1 ACL Object

4.2 project Object

4.3 session Object

4.4 Standard Objects

5. Chaining & Handlers

5.1 Sequential Chaining

5.2 Promise-like Chains

5.3 Event Handlers

6. Knowledge Management

6.1 Hierarchy

6.2 Persistence

6.3 Method Definitions

7. Common Patterns

7.1 Quick Fixes

7.2 Safe Refactoring

7.3 Build Pipelines

7.4 Error Handling

7.5 Knowledge Capture

7.6 Web Resources

7.7 Method Composition

7.8 Documentation

7.9 Custom Behaviors

8. Best Practices

8.1 When to Use ACL

8.2 When to Use Natural Language

8.3 Naming

8.4 Knowledge Management

8.5 Error Handling

8.6 Method Safety

9. Declaration Syntax

9.1 Object Declaration

9.2 Method Definition

10. Reserved Keywords

11. File Locations

12. Future Extensions