ALP Usage Guide

Welcome to the Autonomous Lifecycle Protocol (ALP)! ALP is an open standard designed to help AI agents (and human developers) coordinate, track progress, and build software autonomously.

What is ALP?

ALP (Autonomous Lifecycle Protocol) is the world's first open protocol specifically designed for autonomous software engineering. It replaces unstructured project documentation with a deterministic, machine-readable specification.

Installation

The CLI and Parser are distributed via npm:

npm install -g @autonomous-lifecycle-protocol-alp/cli

Quick Start

1. Initialization

To start using ALP in your project, run:

alp init

This creates an .alp/ directory and a project.alp file in your repository.

2. Defining Features and Tasks

Create .alp files inside your .alp/ directory. For example, .alp/features.alp:

!alp-version: 80.0.0

@feature
  id: feat-auth
  status: [~]
  description: "User authentication system"
  
---

@task
  id: task-login-ui
  status: [ ]
  feature: -> feat-auth
  priority: high

3. Validation

Ensure your .alp files conform to the strict JSON Schemas of the protocol:

alp validate

4. Progress Tracking

Check the current progress of your project based on the [ ], [~], and [x] status markers:

alp status

5. Dependency Graphs

Visualize the execution order of your tasks and features (resolved via Kahn's topological sort algorithm):

alp graph

How AI Agents Use ALP

If you are developing an AI agent (like Devin, Claude Code, or an open-source alternative), you should use the @autonomous-lifecycle-protocol-alp/parser package to programmatically read and interact with the workspace:

import { AlpParser, LoopEngine, AlpGraph } from '@autonomous-lifecycle-protocol-alp/parser';
import * as fs from 'fs';

const parser = new AlpParser();
const content = fs.readFileSync('.alp/features.alp', 'utf8');

// Parse and validate against the official schemas
const objects = parser.parseAndValidate(content);

// Build an execution graph
const graph = new AlpGraph();
graph.buildGraph(objects);

// Get the next blocked task
const executionOrder = graph.topologicalSort();
const nextTask = executionOrder.find(node => node.object.status !== '[x]');
console.log('Agent should work on:', nextTask.id);

For more technical details, refer to the ALP Specification.

Status Markers

ALP uses rich status markers to track task progress:

Marker	Meaning	Description
[ ]	Todo	Not started
[~]	In Progress	Currently being worked on
[x]	Done	Finished and verified
[!]	Blocked	Cannot proceed due to dependency (requires reason)
[?]	Review	Completed but awaiting human review (requires reason)
[-]	Skipped	Intentionally not done

Best Practices

• Keep .alp files under 500 lines for readability
• Use kebab-case for object IDs
• Always declare !alp-version at the top of your files
• Use -> references to link related objects
• Define @verify rules for every task
• Commit .alp/ to version control

Troubleshooting

Validation fails:

• Check for syntax errors in your .alp files
• Ensure all required fields are present
• Verify that all -> references point to valid objects

Tasks not executing:

• Check that dependencies are marked [x]
• Verify no circular dependencies exist
• Run alp graph to see the execution order

Status markers not updating:

• Ensure @verify commands exit with code 0
• Check that the agent has write permissions
• Verify the .alp/ directory structure is correct