agentplane

Agent Plane is a policy-driven framework for running LLM agents inside real repositories. It turns "AI magic" into an engineering process: explicit approvals, role boundaries, and a reproducible execution pipeline. The goal is simple: make agents boring, safe, and auditable.

Why Agent Plane

• You want agents that behave predictably inside real repos.
• You need human approvals, clear roles, and traceable artifacts.
• You want guardrails by default, not optional add-ons.
• You want an offline-first CLI that keeps state local and inspectable.

5-minute start

Install and initialize the CLI:

npm install -g agentplane
agentplane init
agentplane quickstart

agentplane init is human-oriented: interactive onboarding includes workflow/backend selection, execution profile selection (conservative|balanced|aggressive), approval toggles, and optional recipes.

Create your first task and run the workflow:

agentplane task new --title "First task" --description "Describe the change" --priority med --owner ORCHESTRATOR --tag docs
agentplane verify <task-id> --ok --by ORCHESTRATOR --note "Verified"
agentplane finish <task-id> --author ORCHESTRATOR --body "Verified: done" --result "First task completed"

Prefer npx instead of a global install?

npx agentplane init
npx agentplane quickstart

What gets installed automatically

• .agentplane/ is created with config, tasks, agents, and caches.
• AGENTS.md is created if missing and defines the policy/guardrails.
• Built-in agent definitions are copied into .agentplane/agents/.
• Optional recipes can install additional agents when you run agentplane recipes install ....
• .agentplane/config.json stores execution defaults under execution (profile, reasoning effort, tool budget, safety gates).

Upgrade review reports

After agentplane upgrade (auto or agent-assisted mode), a machine-readable review report is written under .agentplane/.upgrade/:

• Agent mode: .agentplane/.upgrade/agent/<runId>/review.json
• Auto mode: .agentplane/.upgrade/last-review.json

If any entry has needsSemanticReview: true, treat it as a signal to create an UPGRADER task to perform a semantic prompt merge.

Guardrails and artifacts

• Approval gates for plans and network access (configured in .agentplane/config.json).
• Role boundaries (ORCHESTRATOR, PLANNER, CODER, INTEGRATOR, etc.).
• Agent definitions in .agentplane/agents/.
• Task records in .agentplane/tasks/ with a snapshot export in .agentplane/tasks.json.
• A visible, reproducible pipeline:

Preflight -> Plan -> Approval -> Tasks -> Verify -> Finish -> Export

Features

• Policy-first execution with explicit approvals and guardrails.
• Role-based workflows for teams: ORCHESTRATOR, PLANNER, CREATOR, INTEGRATOR, etc.
• Two workflow modes: direct (single checkout) and branch_pr (worktrees + integration).
• Task tracking, verification, and exports baked in.
• Recipes for repeatable setup and automation.

Install

npm install -g agentplane

Or run without installing:

npx agentplane --help

Requirements

• Node.js >= 20

Common Commands

agentplane --help
agentplane quickstart
agentplane role ORCHESTRATOR
agentplane role UPGRADER
agentplane config show
agentplane task list
agentplane task new --title "..." --description "..." --priority med --owner ORCHESTRATOR --tag docs
agentplane verify <task-id> --ok --by ORCHESTRATOR --note "Verified"
agentplane finish <task-id> --author ORCHESTRATOR --body "Verified: done" --result "Task completed"
agentplane recipes list

Docs and Guides

• Documentation index: https://github.com/basilisk-labs/agentplane/tree/main/docs
• Workflow overview: https://github.com/basilisk-labs/agentplane/blob/main/docs/user/workflow.mdx
• CLI commands: https://github.com/basilisk-labs/agentplane/blob/main/docs/user/commands.mdx
• Project layout: https://github.com/basilisk-labs/agentplane/blob/main/docs/developer/project-layout.mdx
• Recipes: https://github.com/basilisk-labs/agentplane/tree/main/agentplane-recipes

Support

• Issues: https://github.com/basilisk-labs/agentplane/issues
• Contributing: https://github.com/basilisk-labs/agentplane/blob/main/CONTRIBUTING.md

License

MIT