AgentPlane

Project Overview#

AgentPlane is a policy-driven CLI framework designed to address the lack of predictability and auditability when LLM agents execute in code repositories. Its core philosophy is "Determinism over Magic," ensuring agents follow reproducible execution paths.

Core Philosophy#

• Determinism over Magic: Agents follow reproducible execution paths
• Guardrails by Default: Safety guardrails enabled by default
• Policy-first execution: Every run follows defined pipelines
• Traceability: Task states, artifacts, and agent behaviors are traceable

Execution Pipeline#

Preflight → Plan → Approval → Tasks → Verify → Finish → Export

Key Features#

1. Policy-first execution: Every run follows defined pipelines
2. Approval & planning gates: No action executed without explicit consent
3. Role-based workflows: Supports ORCHESTRATOR, PLANNER, CREATOR, INTEGRATOR roles
4. Safety guardrails by default: Operations outside repo, network access, unrestricted writes disabled
5. Team workflow support: direct and branch_pr workflow modes
6. Explicit commit allowlists: Enforces explicit commit allowlists

Role System#

• ORCHESTRATOR: Drives sessions and interprets user goals
• PLANNER: Breaks down goals into plan steps/tasks
• CREATOR: Implements code/configuration changes
• INTEGRATOR: Verifies and merges changes

Workflow Modes#

• direct mode: Single checkout mode, agents and tasks run in same worktree, suitable for experimentation
• branch_pr mode: Structured team workflow, each task through independent worktree + tracked PR artifacts

State Transitions#

• TODO → DOING | BLOCKED
• DOING → DONE | BLOCKED
• BLOCKED → TODO | DOING

Execution Profiles#

• conservative: Conservative mode
• balanced: Balanced mode
• aggressive: Aggressive mode

Use Cases#

• AI-assisted programming for enterprise development teams
• Compliance projects requiring audit trails
• DevOps automation task execution with Git workflows
• Multi-role collaborative AI agent task management

Requirements#

• Node.js >= 20
• Package manager: Bun 1.3.6 (recommended) / npm

Installation#

# Global installation
npm install -g agentplane

# Or use npx (no installation required)
npx agentplane init

Quick Start#

npx agentplane init           # Initialize repository
npx agentplane quickstart     # View CLI quickstart
agentplane --help             # View help
agentplane --version          # View version

Core Commands#

# Configuration management
agentplane config show
agentplane config set workflow_mode branch_pr

# Task management
agentplane task list
agentplane task new --title "..." --description "..." --priority med --owner CODER

# Workflow operations
agentplane start <task-id> --author CODER --body "Start: ..."
agentplane verify <task-id> --ok --by REVIEWER --note "Looks good"

# Preflight check
agentplane preflight --mode full

Key Configuration Files#

• AGENTS.md: Policy and guardrails configuration (repository root)
• .agentplane/config.json: Execution profile settings
• .agentplane/tasks/: Per-task record storage

Project Structure#

agentplane/
├── packages/
│   ├── agentplane/    # Main CLI package
│   ├── core/          # Core library
│   ├── recipes/       # Example recipes
│   ├── spec/          # Specification definitions
│   └── testkit/       # Test toolkit
├── schemas/           # JSON Schema definitions
└── docs/              # Reference documentation

Layered Architecture#

Information Pending Confirmation#

• Specific LLM backends supported (docs mention Redmine backend sync, but LLM providers unclear)
• Integration capabilities with LangChain, AutoGPT, and other frameworks
• Official website agentplane.org currently shows temporary page, full site being rebuilt