setup.mdx

July 24, 2026 ยท View on GitHub

Install Agentplane

Requirements:

  • Node.js 24+
  • Git
  • Local terminal
npm i -g agentplane
agentplane init
agentplane context init
agentplane quickstart

Prefer no global install:

npx agentplane init
npx agentplane quickstart

On fresh Windows shells, use npx agentplane ... if agentplane is not yet on PATH, then reopen the terminal after global install.

What leaves my machine?

The default quickstart runs locally and writes local project artifacts. It does not require account creation. If you enable integrations that publish feedback, traces, or artifacts, the integration docs explain the destination and opt-in setting.

Initialize repository

Run from the repository root:

agentplane init

init creates the local evidence surface:

  • AGENTS.md or CLAUDE.md as the repository policy gateway.
  • .agentplane/WORKFLOW.md as the workflow/config contract.
  • .agentplane/tasks/ for task records, verification evidence, PR artifacts, and ACR.

If .git does not exist in that folder, init creates a new Git repository there.

To inspect the setup without writes, use dry-run:

agentplane init --dry-run --yes
agentplane init --dry-run --yes --output json

Dry-run builds the same setup plan but does not create .git, .agentplane, gateway files, backups, hooks, or commits. Use it before re-initializing repositories that already contain Agentplane-related files.

Feedback issue prompts

New projects keep Agentplane feedback issue publishing disabled until explicit opt-in. When enabled, Agentplane can prepare a privacy-bounded GitHub issue for internal Agentplane errors. Publishing uses the user's GitHub session by default.

Preview the issue payload:

agentplane insights issue --error-code E_INTERNAL --dry-run

To initialize with the mode disabled:

agentplane init --feedback-github-issues false

To initialize with GitHub issue prompts enabled:

agentplane init --feedback-github-issues true

To disable it later:

agentplane config set feedback.github_issues.enabled false

Hand off to an agent

After initialization, the normal next step is to give the repository to a coding agent. The agent should read the repository policy gateway and run the Agentplane lifecycle around its own work.

Use Agentplane for this repository.

Start with:
agentplane quickstart
agentplane role ORCHESTRATOR

Follow AGENTS.md and the workflow mode in .agentplane/WORKFLOW.md.
Create or reuse an Agentplane task before mutating repository files.
Record the plan, start-ready state, verification evidence, and finish state through Agentplane.

Expected files:

.agentplane/tasks/<task-id>/README.md
.agentplane/tasks/<task-id>/acr.json

The Quickstart covers the same startup model through install, run, trace, and export steps.

Enable local context

Use local context when agents need reusable project knowledge, source-backed facts, or task-scoped research material. This layer is optional: normal prompt assembly and task execution work after agentplane init without agentplane context init.

agentplane context init
agentplane context reindex
agentplane context search "first task"

In an empty standalone directory, agentplane context init also performs the initial Agentplane bootstrap before writing context files. For non-empty uninitialized projects, run agentplane init first so conflicts and gateway/workflow choices stay explicit.

When no profile is provided, context initialization uses maximum-assimilation. Use agentplane context init --profile adaptive when the repository only needs a smaller, opportunistic wiki.

For a task that needs context ingestion:

agentplane context ingest --changed
agentplane context verify-task <task-id>

During the v0.7 supervisor migration, the standalone verifier fails closed when the only execution evidence is a repository-local receipt. Use the component context checks and ap verify described in Local context until the beta supervisor restores authenticated handoff.

See Local context for source refs, privacy boundaries, and verification rules.

Local context has its own docs section because it is the reusable knowledge layer for agents, not a subtopic of manual CLI usage.

Setup profiles

Choose profiles after you understand the first artifact:

  • Light: solo experiments with minimal enforcement.
  • Normal: default team-safe workflow.
  • Team Strict: stricter approvals, hooks, and CI-oriented guardrails. In the current CLI this profile is selected with full-harness.
agentplane profile set light
agentplane profile set normal
agentplane profile set full-harness

Non-interactive setup:

agentplane init \
  --setup-profile normal \
  --workflow direct \
  --backend local \
  --execution-profile balanced \
  --require-network-approval true \
  --hooks true \
  --ide codex \
  --yes

Local task storage

Start with the local backend. It stores task evidence in the repository and is the default path.

Managed ownership contract

Treat AGENTS.md, .agentplane/policy/**, .agentplane/WORKFLOW.md, and other files written by agentplane init or agentplane upgrade as framework-owned managed files.

Use .agentplane/policy/incidents.md for sanctioned local incident rules. Do not hand-edit the rest of the managed policy tree during normal project work; expect agentplane upgrade to replace or reconcile those files. Agents do not treat incidents.md as part of the normal startup reading path for agents; it is for recovery, incident response, or tasks that directly modify incident policy.

Recovery routing starts from three repository states:

  1. Clean managed state: managed files match the installed framework contract.
  2. Partial upgrade state: an upgrade started but did not finish all managed file updates.
  3. Manual drift state: managed files were edited outside the framework upgrade path.

Verify setup

agentplane config show
agentplane quickstart
agentplane task list
agentplane doctor

Then use agentplane role <ROLE> for role-specific guidance.

Use Commands and the generated CLI reference when you need manual inspection, recovery, or operator-level control. They are not the default day-to-day usage path.

Optional recipes

Recipes are extensions, not the first step. Add them after the task -> plan -> verify -> ACR flow is clear.

agentplane recipes list-remote --refresh --yes
agentplane recipes add tdd

Start with TDD, security review, or docs update when you need a reusable workflow overlay.