https://github.com/basilisk-labs/agentplane
Governed CLI framework for deterministic, auditable AI agent workflows
https://github.com/basilisk-labs/agentplane
agent-orchestration ai-agents automation cli developer-tools devops governance llm policy-driven workflow
Last synced: 2 days ago
JSON representation
Governed CLI framework for deterministic, auditable AI agent workflows
- Host: GitHub
- URL: https://github.com/basilisk-labs/agentplane
- Owner: basilisk-labs
- License: mit
- Created: 2026-01-27T08:03:43.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-02-09T10:38:53.000Z (3 months ago)
- Last Synced: 2026-02-09T13:58:15.758Z (3 months ago)
- Topics: agent-orchestration, ai-agents, automation, cli, developer-tools, devops, governance, llm, policy-driven, workflow
- Language: TypeScript
- Homepage:
- Size: 4.14 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# AgentPlane
[](https://www.npmjs.com/package/agentplane)
[](https://www.npmjs.com/package/agentplane)
[](LICENSE)
[](docs/user/prerequisites.mdx)
[](docs/developer/cli-contract.mdx)
[](https://github.com/basilisk-labs/agentplane/actions/workflows/ci.yml)
[](https://github.com/basilisk-labs/agentplane/actions/workflows/ci.yml)
[](https://github.com/basilisk-labs/agentplane/actions/workflows/ci.yml)
[](https://github.com/basilisk-labs/agentplane/actions/workflows/ci.yml)
[](ROADMAP.md#2026q2-refactor-status)
**Git-native control plane for auditable agent work.**
Put coding agents on a governed Git workflow.
AgentPlane is a local CLI for agent-driven development inside a git repository. It runs in your repo, not in a hosted runtime, and adds visible workflow artifacts such as `AGENTS.md` or `CLAUDE.md`, `.agentplane/`, task records, verification state, and deterministic closure. Teams trust it because approvals, task state, verification, and finish are explicit instead of implied. Use `agentplane` when you want agents to work inside a governed repository workflow rather than as an opaque assistant.
## What AgentPlane is
AgentPlane is a repository-native workflow layer for agent work.
It does not replace git, your editor, or your terminal. It sits inside an existing repository and gives agent execution a visible operating model:
- a policy gateway in the repo root
- a repo-local workspace in `.agentplane/`
- task state with ownership and dependencies
- verification and closure recorded in the repository
- workflow modes for both short loops and stricter team integration
## Why teams use it
Teams use AgentPlane when "just let the agent change files" is not enough.
- **Trust comes from visible state**. Approvals, task transitions, verification, and finish are all recorded in the repo.
- **The workflow stays local and inspectable**. There is no hosted control plane sitting between your repository and your team.
- **Agents work inside git, not around it**. Commits, review points, and closure remain explicit.
- **You can pick the right integration style**. Use `direct` for short loops or `branch_pr` for stricter handoff and integration.
## What appears in your repository
A repository using AgentPlane typically includes a small set of visible artifacts so the workflow stays legible to both humans and agents.
```text
AGENTS.md or CLAUDE.md Policy gateway for the repository
.agentplane/ Repo-local workspace and workflow state
.agentplane/config.json Current repo configuration
.agentplane/tasks/ Per-task records
.agentplane/WORKFLOW.md Materialized workflow contract
.agentplane/tasks.json Optional exported task snapshot derived from the current backend projection
```
These files matter because they make agent work inspectable. A reviewer can see what policy governs the repo, what task is active, what was verified, and how the task was closed.
## Framework control plane
Inside the CLI, AgentPlane now resolves one explicit framework control plane before recipe-specific or runner-specific behavior runs:
- a resolved harness contract for repo policy, workflow, task rules, and backend restrictions
- one canonical execution context carrying capabilities, approvals, execution profile runtime, task intake, and trace-ready behavior state
- traced behavior precedence: `harness -> extension -> user -> builtin`
- machine-readable explain and protocol surfaces that persist the resolved framework inputs into shared runner artifacts
If you are extending the framework instead of only using the CLI, start with [Architecture](docs/developer/architecture.mdx) and [Harness Engineering](docs/developer/harness-engeneering.mdx).
## 2-minute quickstart
Install the CLI:
```bash
npm install -g agentplane
```
Initialize your repository and print the built-in startup guide:
```bash
agentplane init
agentplane quickstart
```
`agentplane init` creates the repo-local workflow surface: a policy gateway file (`AGENTS.md` or `CLAUDE.md`), `.agentplane/config.json`, built-in agent profiles, task storage, and workflow state such as `.agentplane/WORKFLOW.md`.
The default path is `direct`, and the daily loop starts with a task instead of a free-form prompt:
```bash
agentplane task new --title "First task" --description "Describe the change" --priority med --owner DOCS --tag docs
agentplane task plan set --text "Explain the plan" --updated-by DOCS
agentplane task start-ready --author DOCS --body "Start: ..."
agentplane task verify-show
agentplane verify --ok --by REVIEWER --note "Looks good"
agentplane finish --author DOCS --body "Verified: ..." --result "One-line outcome" --commit
```
If your repository requires explicit plan approval, run `agentplane task plan approve --by ORCHESTRATOR` before `agentplane task start-ready`.
If you need structured worktrees and PR-style integration, switch to `branch_pr` before you begin active work:
```bash
agentplane config set workflow_mode branch_pr
```
For exact flags and recovery paths, use:
- [Overview](docs/user/overview.mdx)
- [Setup](docs/user/setup.mdx)
- [Commands](docs/user/commands.mdx)
## Workflow modes
AgentPlane supports two integration styles.
### `direct`
- single checkout
- short loops in the current working tree
- good for solo work and fast iteration
- default mode after `agentplane init`
### `branch_pr`
- structured per-task branch or worktree flow
- explicit PR artifacts under `.agentplane/tasks//pr/`
- better fit when integration must stay separate from implementation
- use it when the repository needs stricter handoff and integration discipline
The difference is workflow discipline, not product tiering.
## Typical task flow
The normal happy path is short and explicit:
1. Run preflight and inspect the current repo state.
2. Create the task and record the plan.
3. Start the task with `agentplane task start-ready`.
4. Implement the change in the repository.
5. Print `Verify Steps` and record the result with `agentplane verify`.
6. Close the task with `agentplane finish`.
Under `direct`, `finish` creates the deterministic close commit by default. Under `branch_pr`, integration stays more structured and PR-oriented.
## When to use it
Use AgentPlane when:
- you want agents to work inside a real git repository
- you need explicit approvals, task state, verification, and closure
- you want repo-local artifacts that show what happened and why
- you need a governed workflow instead of a chat-style assistant loop
Do not use AgentPlane when:
- you are looking for a hosted agent platform
- you want a generic prompt framework
- you want the tool to hide git or replace your editor
## Documentation
Start here:
- [Overview](docs/user/overview.mdx)
- [Workflow](docs/user/workflow.mdx)
- [Commands](docs/user/commands.mdx)
- [Configuration](docs/user/configuration.mdx)
- [Backends](docs/user/backends.mdx)
- [CLI reference (generated)](docs/user/cli-reference.generated.mdx)
Developer and release docs:
- [Architecture](docs/developer/architecture.mdx)
- [Framework refactor program](docs/developer/framework-refactor-program.mdx)
- [CLI contract](docs/developer/cli-contract.mdx)
- [Release and publishing](docs/developer/release-and-publishing.mdx)
- [Release notes](docs/releases/)
If you need the deeper execution philosophy, keep it below the product surface:
- [Harness Engineering](docs/developer/harness-engeneering.mdx)
## Contributing
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT