CLI Reference (Generated)

This page is generated from the CLI command specs. Do not edit it by hand; edit the specs instead.

Index

• Core
  • agents
  • demo
  • help
  • preflight
  • quickstart
  • role
• Task
  • ready
  • task active
  • task answer
  • task ask
  • task begin
  • task brief
  • task comment
  • task complete
  • task doc set
  • task doc show
  • task list
  • task new
  • task next
  • task next-action
  • task plan approve
  • task plan set
  • task search
  • task show
  • task start-ready
  • task status
  • task verify ok
  • task verify rework
  • task verify-show
• Lifecycle
  • block
  • finish
  • start
  • verify
• Work
  • work resume
  • work start
• PR
  • integrate
  • integrate queue claim
  • integrate queue doctor
  • integrate queue enqueue
  • integrate queue list
  • integrate queue release
  • integrate queue run-next
  • pr check
  • pr close
  • pr close-superseded
  • pr flow status
  • pr note
  • pr open
  • pr update
• Branch
  • branch base clear
  • branch base explain
  • branch base get
  • branch base set
  • branch remove
  • branch status
  • cleanup merged
• Backend
  • backend connect
  • backend inspect
  • backend sync
  • sync
• Config
  • config set
  • config show
  • mode get
  • mode set
  • profile set
• Setup
  • init
  • upgrade
• Quality
  • doctor
  • doctor git-locks
• Diagnostics
  • insights issue
  • insights report
  • insights triage
  • intake
  • runtime explain
• Recipes
  • recipes active
  • recipes add
  • recipes cache prune
  • recipes detach
  • recipes disable
  • recipes enable
  • recipes explain
  • recipes explain-active
  • recipes info
  • recipes install
  • recipes list
  • recipes list-remote
  • recipes remove
  • recipes update
• Blueprints
  • blueprint drift
  • blueprint examples
  • blueprint explain
  • blueprint list
  • blueprint report
  • blueprint scaffold
  • blueprint snapshot
  • blueprint validate
  • blueprints catalog info
  • blueprints catalog list
  • blueprints catalog refresh
  • blueprints install
• ACR
  • acr check
  • acr explain
  • acr generate
  • acr schema
  • acr validate
• Guard
  • commit
  • guard clean
  • guard commit
  • guard suggest-allow
• Hooks
  • hooks install
  • hooks run
  • hooks uninstall
• Policy
  • incidents advise
  • incidents collect
• IDE
  • ide sync
• Context
  • context check
  • context dashboard
  • context init
  • context learn changes
  • context learn files
  • context learn tasks
  • context search
  • context show
  • context wiki explain
  • context wiki index
  • context wiki link
  • context wiki lint
  • context wiki new
• Evaluators
  • evaluator list
  • evaluator run
  • evaluator show
• Evidence
  • evidence bundle
  • evidence verify
• Integrations
  • hermes doctor
  • hermes enqueue
  • hermes lifecycle
  • hermes reconcile
  • hermes supervise
• Platform
  • platform doctor
  • platform explain
  • platform list
  • platform sync
• Workflow
  • flow repair

Core

agents

List agent definitions under .agentplane/agents.

Usage:

agentplane agents

Examples:

agentplane agents

• Print available agent ids and roles.

demo

Create a safe first-success Agentplane demo task with ACR evidence.

Creates an inspectable demo task under .agentplane/tasks without touching user source files, network, or GitHub.

Usage:

agentplane demo [options]

Options:

• --dry-run: Preview the files and commands without writing demo artifacts. (default=false)
• --json: Emit compact machine-readable output for agent runtimes. (default=false)

Examples:

agentplane demo

• Create a first-success task artifact and ACR.

agentplane demo --dry-run

• Preview the first-success path.

help

Show help for a command.

Renders spec-derived help for migrated commands. Use --compact for minimal output and --json for machine-readable help.

Usage:

agentplane help [<cmd> ...] [options]

Options:

• --compact: Compact help (usage + options).
• --json: Emit JSON help (success output).
• --all: Include framework-dev and internal maintenance commands in registry output.

Examples:

agentplane help

• List commands available in the CLI command catalog.

agentplane help task new --compact

• Show compact help for a command.

agentplane help task new --json

• Show JSON help for a command.

preflight

Run aggregated preflight checks and print a deterministic readiness report.

Usage:

agentplane preflight [options]

Options:

• --mode <quick|full>: Preflight depth. quick skips backend task-list probe; full includes backend readiness. (choices=quick|full, default=quick)
• --full: Shortcut for --mode full. (default=false)
• --json: Emit machine-readable JSON report. (default=false)
• --role <ROLE>: Optional active role to include in next-command guidance.

Examples:

agentplane preflight --json

• Produce one-shot agent-readable preflight.

agentplane preflight --json --mode full

• Run full preflight including backend task-list probe.

quickstart

Print the canonical agent bootstrap path and startup guidance.

Usage:

agentplane quickstart [options]

Options:

• --json: Emit compact machine-readable output for agent runtimes. (default=false)

Examples:

agentplane quickstart

• Show quickstart.

role

Show role-specific workflow guidance.

Usage:

agentplane role <role> [options]

Options:

• --json: Emit compact machine-readable role payload. (default=false)

Examples:

agentplane role ORCHESTRATOR

• Show ORCHESTRATOR guide.

Task

ready

Report dependency readiness details for a task.

Usage:

agentplane ready <task-id>

Examples:

agentplane ready 202602030608-F1Q8AB

• Print readiness details.

task active

Select active agent work with next actions, blockers, dependency readiness, and freshness.

Usage:

agentplane task active [options]

Options:

• --status <status>: Repeatable. Filter by active status. (repeatable)
• --owner <owner>: Repeatable. Filter by owner id. (repeatable)
• --tag <tag>: Repeatable. Filter by tag. (repeatable)
• --strict-read: Fail if task scan skips malformed/unreadable task files. (default=false)
• --limit <n>: Max rows to print.
• --quiet: Suppress summary output. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane task active

• Select the next active agent work item.

agentplane task active --owner CODER --limit 3

• Limit active work by owner.

agentplane task active --json

• Emit machine-readable active work state.

task answer

Answer and close a task user-input blocker.

Usage:

agentplane task answer <task-id> [options]

Options:

• --by <USER>: Answer author.
• --body <text>: Answer body.

Examples:

agentplane task answer 202602030608-F1Q8AB --by USER --body "Use the existing REST API."

• Close the open user-input blocker.

task ask

Record a blocking user question for a task.

Usage:

agentplane task ask <task-id> [options]

Options:

• --author <ROLE>: Question author.
• --body <text>: Blocking question.

Examples:

agentplane task ask 202602030608-F1Q8AB --author CODER --body "Which API should this use?"

• Block the task until the user answers.

task begin

Create, plan, approve, and start or route a task through the normal lifecycle.

Usage:

agentplane task begin <title> [options]

Options:

• --description <text>: Task description. Defaults to the title.
• --owner <id>: Task owner id. (default=CODER)
• --priority <low|normal|med|high>: Task priority. (choices=low|normal|med|high, default=med)
• --tag <tag>: Repeatable. Adds a tag. Defaults to code. (repeatable)
• --plan <text>: Plan text. Defaults to a minimal generated plan; escaped newlines (\n) are supported by task plan set.
• --verify <command>: Repeatable. Verification commands/checks to seed on the task. (repeatable)
• --task-kind <analysis|content|docs|code|release|ops|context>: Structured blueprint task-kind intent. (choices=analysis|content|docs|code|release|ops|context)
• --mutation-scope <none|docs|code|release|ops|context|unknown>: Structured mutation scope used by blueprint resolution. (choices=none|docs|code|release|ops|context|unknown)
• --blueprint-request <id>: Explicit blueprint request stored on the task. (choices=analysis.light|content.light|docs.change|code.direct|code.branch_pr|performance.benchmark|quality.regression|context.assimilation|context.maximum_assimilation|post_run.improvement_review|release.strict|ops.approval)
• --json: Emit machine-readable JSON. (default=false)

Examples:

agentplane task begin "Fix parser edge case" --tag code --verify "bun run test:fast"

• Create the task, seed a minimal plan, approve it, then start or print the branch_pr worktree route.

task brief

Print an agent-ready task brief without remote lookups by default.

Usage:

agentplane task brief <task-id> [options]

Options:

• --json: Emit JSON. (default=false)
• --remote: Include hosted PR/check/review state using configured remote tools. (default=false)

Notes:

• JSON output follows the versioned `agentplane.agent_work_context` contract.
• `source_confidence` marks whether each field is local, cached, computed, remote-derived, or skipped.

Examples:

agentplane task brief 202602030608-F1Q8AB

• Get local route, Verify Steps, blueprint, blockers, and next command in one view.

agentplane task brief 202602030608-F1Q8AB --json

• Emit a machine-readable agent work context.

agentplane task brief 202602030608-F1Q8AB --remote

• Include hosted PR truth when remote access is explicitly intended.

task comment

Append a comment to a task.

Usage:

agentplane task comment <task-id> --author <id> [options]

Options:

• --author <id>: Comment author id (e.g. CODER). (required)
• --body <text>: Comment body text. Use --body-file for Markdown or shell-sensitive text.
• --body-file <path>: Read the comment body from a file path (mutually exclusive with --body).

Examples:

agentplane task comment 202602030608-F1Q8AB --author CODER --body "Investigated root cause."

• Add a comment and bump doc metadata.

task complete

Record OK verification and finish a direct task, or print the branch_pr close route.

Usage:

agentplane task complete <task-id> --result <text> [options]

Options:

• --result <text>: One-line result summary. (required)
• --commit <hash>: Implementation commit hash to record when finish is allowed.
• --by <id>: Verifier id. (default=CODER)
• --author <id>: Finish author id for direct-mode finish. (default=CODER)
• --note <text>: Verification note. Defaults to the result.
• --body <text>: Finish body. Defaults to Verified: <result>.
• --force: Forward --force to finish. (default=false)
• --yes: Auto-approve force gates. (default=false)
• --json: Emit machine-readable JSON. (default=false)

Examples:

agentplane task complete 202602030608-F1Q8AB --result "Parser edge case fixed" --commit abcdef1

• Record verification and finish when the current workflow route allows it.

task doc set

Update a task README section.

Usage:

agentplane task doc set <task-id> --section <name> (--text <text> | --file <path>) [--updated-by <id>]
agentplane task doc set <task-id> --full-doc (--text <text> | --file <path>) [--updated-by <id>]

Options:

• --section <name>: Target section heading (must be one of config.tasks.doc.sections). Required unless --full-doc is set.
• --full-doc: Treat the provided text/file as the full task README payload. (default=false)
• --text <text>: Section content (mutually exclusive with --file). Literal escaped newlines (\n) are normalized for inline text.
• --file <path>: Read section content from a file (mutually exclusive with --text).
• --updated-by <id>: Optional. Override doc_updated_by metadata (must be non-empty).

Examples:

agentplane task doc set 202602030608-F1Q8AB --section Summary --text "New summary."

• Update one section using inline text.

agentplane task doc set 202602030608-F1Q8AB --section Plan --file ./plan.md

• Update one section using a file.

agentplane task doc set 202602030608-F1Q8AB --full-doc --file ./task-readme.md

• Replace the full task README payload explicitly.

task doc show

Print task README content (entire doc or one section).

Usage:

agentplane task doc show <task-id> [options]

Options:

• --section <name>: Optional. Print a single section.
• --quiet: Suppress informational output when doc/section content is missing. (default=false)

Examples:

agentplane task doc show 202602030608-F1Q8AB

• Print the full doc.

agentplane task doc show 202602030608-F1Q8AB --section Summary

• Print a single section.

task list

List active tasks with compact resolved blueprint route hints.

Usage:

agentplane task list [options]

Options:

• --all: Include historical DONE tasks instead of the default active-task view. (default=false)
• --status <status>: Repeatable. Filter by status. (repeatable)
• --owner <owner>: Repeatable. Filter by owner id. (repeatable)
• --tag <tag>: Repeatable. Filter by tag. (repeatable)
• --strict-read: Fail if task scan skips malformed/unreadable task files. (default=false)
• --limit <n>: Max rows to print.
• --quiet: Suppress summary output. (default=false)

Examples:

agentplane task list

• List active tasks.

agentplane task list --all

• List all historical tasks.

agentplane task list --status TODO --owner CODER

• List filtered tasks.

task new

Create a new task (prints the generated task id).

Creates a TODO task with doc_version=3, seeds the README v3 section layout, and writes it via the configured task backend.

Usage:

agentplane task new --title <text> --description <text> --owner <id> [options]

Options:

• --title <text>: Task title. (required)
• --description <text>: Task description. (required)
• --owner <id>: Owner id (e.g. CODER). (required)
• --priority <low|normal|med|high>: Task priority (default: med). (choices=low|normal|med|high, default=med)
• --tag <tag>: Repeatable. Adds a tag (must provide at least one). (repeatable)
• --task-kind <analysis|content|docs|code|release|ops|context>: Structured blueprint task-kind intent. Tags/title remain fallback hints. (choices=analysis|content|docs|code|release|ops|context)
• --mutation-scope <none|docs|code|release|ops|context|unknown>: Structured mutation scope used by blueprint resolution. (choices=none|docs|code|release|ops|context|unknown)
• --risk <risk>: Structured risk flag used by blueprint resolution. Repeatable. (repeatable, choices=network|credentials|deploy|publish|merge|security|external_system)
• --blueprint-request <id>: Explicit blueprint request stored on the task; resolver still validates it. (choices=analysis.light|content.light|docs.change|code.direct|code.branch_pr|performance.benchmark|quality.regression|context.assimilation|context.maximum_assimilation|post_run.improvement_review|release.strict|ops.approval)
• --depends-on <task-id>: Repeatable. Adds a dependency. Special-case: '[]' is treated as empty. (repeatable)
• --verify <command>: Repeatable. Verification commands/checks to run for this task. (repeatable)
• --show-blueprint: Print a resolved blueprint route preview to stderr after creation without changing stdout. (default=false)
• --allow-duplicate: Allow creating a task even when an open task with a highly similar title already exists. (default=false)

Notes:

• Task creation defaults to doc_version=3 and seeds the README v3 section contract automatically.
• For verify-required primary tags, this command seeds a default ## Verify Steps acceptance contract in README.
• `--show-blueprint` writes route preview details to stderr; stdout remains only the generated task id.

Examples:

agentplane task new --title "Refactor CLI" --description "Improve CLI output" --owner CODER --tag cli

• Create a new task with one tag.

agentplane task new --title "Market analysis note" --description "Analyze market context" --owner ANALYST --tag analysis --task-kind analysis --mutation-scope none --show-blueprint

• Create a task and preview the resolved route without changing the task-id stdout contract.

task next

List ready tasks (default status=TODO) with optional filters.

Usage:

agentplane task next [options]

Options:

• --status <status>: Repeatable. Filter by status (default: TODO). (repeatable)
• --owner <owner>: Repeatable. Filter by owner id. (repeatable)
• --tag <tag>: Repeatable. Filter by tag. (repeatable)
• --strict-read: Fail if task scan skips malformed/unreadable task files. (default=false)
• --limit <n>: Max rows to print.
• --quiet: Suppress summary output. (default=false)

Examples:

agentplane task next

• List ready TODO tasks.

agentplane task next --limit 3

• Limit output.

task next-action

Print the single safest next command for a task route.

Usage:

agentplane task next-action <task-id> [options]

Options:

• --explain: Include route context, approval policy, blockers, and ambiguity resolution hints. (default=false)
• --remote: Include hosted PR/check/review state using configured remote tools. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane task next-action 202602030608-F1Q8AB

• Get the next safe command before manually chaining diagnostics.

task plan approve

Approve the current task plan (enforces Verify Steps gating when configured).

Usage:

agentplane task plan approve <task-id> --by <id> [options]

Options:

• --by <id>: Approver id. (required)
• --note <text>: Optional note (stored in plan_approval.note).

Examples:

agentplane task plan approve 202602030608-F1Q8AB --by USER --note "OK"

• Approve a plan with a note.

task plan set

Set a task plan (writes the Plan section and resets plan approval to pending).

Usage:

agentplane task plan set <task-id> [options]

Options:

• --text <text>: Plan text to write into the task README Plan section. Literal escaped newlines (\n) are normalized for inline text.
• --file <path>: Read plan text from a file path (relative to cwd).
• --updated-by <id>: Optional. Sets doc_updated_by when writing the plan.

Examples:

agentplane task plan set 202602030608-F1Q8AB --text "1) Do X\n2) Verify Y" --updated-by ORCHESTRATOR

• Write plan from text and set doc_updated_by.

agentplane task plan set 202602030608-F1Q8AB --file plan.md

• Write plan from a file.

task search

Search tasks by text or regex with optional filters.

Usage:

agentplane task search <query> [options]

Options:

• --regex: Treat query as a regex. (default=false)
• --status <status>: Repeatable. Filter by status. (repeatable)
• --owner <owner>: Repeatable. Filter by owner id. (repeatable)
• --tag <tag>: Repeatable. Filter by tag. (repeatable)
• --strict-read: Fail if task scan skips malformed/unreadable task files. (default=false)
• --limit <n>: Max rows to print.

Examples:

agentplane task search cli

• Search tasks by substring.

agentplane task search 'CLI.*' --regex

• Search tasks by regex.

task show

Print task metadata and resolved blueprint route as JSON.

Usage:

agentplane task show <task-id>

Examples:

agentplane task show 202602030608-F1Q8AB

• Show task metadata.

task start-ready

Run readiness checks and start a task in one deterministic command.

Usage:

agentplane task start-ready <task-id> --author <id> [options]

Options:

• --author <id>: Comment author id (e.g. CODER). (required)
• --body <text>: Structured Start comment body. Use --body-file for Markdown or shell-sensitive text.
• --body-file <path>: Read the Start comment body from a file path (mutually exclusive with --body).
• --force: Override readiness and transition checks. (default=false)
• --yes: Auto-approve force-action checks when required. (default=false)
• --quiet: Suppress output. (default=false)

Examples:

agentplane task start-ready 202602030608-F1Q8AB --author CODER --body "Start: implement parser hardening"

• Check readiness and transition to DOING without command chaining.

task status

Show task lifecycle state with optional branch_pr route decision details.

Usage:

agentplane task status <task-id> [options]

Options:

• --route: Include route blockers, next action, and repair-plan hints. (default=false)
• --remote: Include hosted PR/check/review state using configured remote tools. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane task status 202602030608-F1Q8AB --route

• Inspect lifecycle and branch_pr route state before resuming work.

agentplane task status 202602030608-F1Q8AB --route --json

• Emit machine-readable route diagnostics.

task verify ok

Record verification as OK (updates Verification section and verification frontmatter).

Usage:

agentplane task verify ok <task-id> --by <id> [options]

Options:

• --by <id>: Verifier id. (required)
• --note <text>: Short verification note.
• --note-file <path>: Read the verification note from a file path (mutually exclusive with --note).
• --details <text>: Optional details text (mutually exclusive with --file).
• --file <path>: Optional details file path (mutually exclusive with --details).
• --quiet: Suppress normal output (still prints errors). (default=false)
• --collect-incidents: After recording verification, collect promotable findings into incidents.md immediately. (default=false)
• --observation <text>: Structured finding observation to append with the verification.
• --impact <text>: Structured finding impact to append with the verification.
• --resolution <text>: Structured finding resolution to append with the verification.
• --promote: Mark the structured finding as an incident candidate. (default=false)
• --external: Mark the incident candidate as external-fixable. (default=false)
• --local-only: Compatibility no-op. Findings are task-local unless --promote, --external, or --repo-fixable is set. (default=false)
• --repo-fixable: Mark the structured finding as repo-fixable so incidents collect can promote it. (default=false)
• --incident-scope <text>: Optional incident scope for the appended finding.
• --incident-tag <tag>: Repeatable incident tag for the appended finding. (repeatable)
• --incident-match <term>: Repeatable incident match term for the appended finding. (repeatable)
• --incident-advice <text>: Optional operator advice for the appended finding.
• --incident-rule <text>: Optional incident rule for the appended finding.

Examples:

agentplane task verify ok 202602030608-F1Q8AB --by REVIEWER --note "Looks good"

• Record an OK verification.

task verify rework

Record verification as needs rework (resets commit, sets status to DOING, updates Verification).

Usage:

agentplane task verify rework <task-id> --by <id> [options]

Options:

• --by <id>: Verifier id. (required)
• --note <text>: Short verification note.
• --note-file <path>: Read the verification note from a file path (mutually exclusive with --note).
• --details <text>: Optional details text (mutually exclusive with --file).
• --file <path>: Optional details file path (mutually exclusive with --details).
• --quiet: Suppress normal output (still prints errors). (default=false)
• --collect-incidents: After recording verification, collect promotable findings into incidents.md immediately. (default=false)
• --observation <text>: Structured finding observation to append with the verification.
• --impact <text>: Structured finding impact to append with the verification.
• --resolution <text>: Structured finding resolution to append with the verification.
• --promote: Mark the structured finding as an incident candidate. (default=false)
• --external: Mark the incident candidate as external-fixable. (default=false)
• --local-only: Compatibility no-op. Findings are task-local unless --promote, --external, or --repo-fixable is set. (default=false)
• --repo-fixable: Mark the structured finding as repo-fixable so incidents collect can promote it. (default=false)
• --incident-scope <text>: Optional incident scope for the appended finding.
• --incident-tag <tag>: Repeatable incident tag for the appended finding. (repeatable)
• --incident-match <term>: Repeatable incident match term for the appended finding. (repeatable)
• --incident-advice <text>: Optional operator advice for the appended finding.
• --incident-rule <text>: Optional incident rule for the appended finding.

Examples:

agentplane task verify rework 202602030608-F1Q8AB --by REVIEWER --note "Needs changes"

• Record a needs-rework verification.

task verify-show

Print the task Verify Steps acceptance contract (alias for task doc show --section "Verify Steps").

Usage:

agentplane task verify-show <task-id> [options]

Options:

• --quiet: Suppress errors when the section is missing. (default=false)

Notes:

• `## Verify Steps` is the ex-ante acceptance contract for the verifier.
• Verification results are recorded later in `## Verification` via `agentplane verify ...`.

Examples:

agentplane task verify-show 202602030608-F1Q8AB

• Print Verify Steps.

agentplane task verify-show 202602030608-F1Q8AB --quiet

• Print Verify Steps without erroring when missing.

Lifecycle

block

Transition a task to BLOCKED and record a structured Blocked comment.

Usage:

agentplane block <task-id> --author <id> [options]

Options:

• --author <id>: Comment author id (e.g. CODER). (required)
• --body <text>: Structured comment body (must match the configured Blocked: prefix). Use --body-file for Markdown or shell-sensitive text.
• --body-file <path>: Read the structured comment body from a file path (mutually exclusive with --body).
• --commit-from-comment: Create a status commit using the comment body. (default=false)
• --commit-emoji <emoji>: Override the status commit emoji (used with --commit-from-comment).
• --commit-allow <path-prefix>: Repeatable. Allowlist path prefixes to stage for the status commit (used with --commit-from-comment). Use minimal prefixes; '.' is rejected. (repeatable)
• --commit-require-clean: Require a clean working tree for the status commit (used with --commit-from-comment). (default=false)
• --confirm-status-commit: Confirm status commit creation when status_commit_policy=confirm (used with --commit-from-comment). (default=false)
• --force: Override status transition restrictions. (default=false)
• --yes: Auto-approve force-action approval checks when required. (default=false)
• --quiet: Suppress output. (default=false)

Examples:

agentplane block 202602030608-F1Q8AB --author CODER --body "Blocked: waiting for review"

• Block work on a task.

agentplane block 202602030608-F1Q8AB --author CODER --body "Blocked: waiting for review" --commit-from-comment --commit-allow packages/agentplane/src

• Block work and create a status commit from the comment.

finish

Mark task(s) as DONE and record a structured Verified comment.

Usage:

agentplane finish <task-id> ... --author <id> [options]

Options:

• --author <id>: Comment author id (e.g. INTEGRATOR). (required)
• --body <text>: Structured comment body (must match the configured Verified: prefix). Use --body-file for Markdown or shell-sensitive text.
• --body-file <path>: Read the structured comment body from a file path (mutually exclusive with --body).
• --result <one-line>: One-line result summary stored in task metadata (required for non-spike tasks when finishing a single task). Use --result-file for shell-sensitive text.
• --result-file <path>: Read the result summary from a file path (mutually exclusive with --result).
• --risk <low|med|high>: Optional. Risk level stored in task metadata. (choices=low|med|high)
• --breaking: Optional. Mark the change as breaking in task metadata. (default=false)
• --commit <hash>: Closure/evidence commit hash to record on the task (optional). Use --implementation-commit when landed implementation evidence differs.
• --implementation-commit <hash>: Implementation commit hash to store separately from closure/evidence commit metadata.
• --force: Force finish despite gates. (default=false)
• --yes: Auto-approve force-action approval checks when required. (default=false)
• --commit-from-comment: Create a commit using the comment body (requires exactly one task id). (default=false)
• --commit-emoji <emoji>: Override the commit emoji (used with --commit-from-comment).
• --commit-allow <path-prefix>: Repeatable. Allowlist path prefixes to stage for the commit (used with --commit-from-comment). Use minimal prefixes; '.' is rejected. (repeatable)
• --commit-require-clean: Require a clean working tree for the commit (used with --commit-from-comment). (default=false)
• --status-commit: Create a separate status commit (requires exactly one task id). (default=false)
• --status-commit-emoji <emoji>: Override the status commit emoji (used with --status-commit).
• --status-commit-allow <path-prefix>: Repeatable. Allowlist path prefixes to stage for the status commit (used with --status-commit). Use minimal prefixes; '.' is rejected. (repeatable)
• --status-commit-require-clean: Require a clean working tree for the status commit (used with --status-commit). (default=false)
• --confirm-status-commit: Confirm status commit creation when status_commit_policy=confirm (used with --commit-from-comment or --status-commit). (default=false)
• --close-commit: After finishing, run a deterministic close commit for the active task artifact scope (single-task only). (default=false)
• --no-close-commit: Disable the default deterministic close commit in direct mode (single-task only). (default=false)
• --pre-merge-closure: In branch_pr, finish from the task worktree and commit the closure packet before the task PR merge. (default=false)
• --no-write-acr: Disable automatic ACR refresh for this finish call when acr.write_on_finish is enabled. (default=false)
• --close-unstage-others: With --close-commit: unstage any currently staged paths before staging the active task artifact scope. (default=false)
• --base <branch>: Optional explicit base branch override for branch_pr finish validation and close-commit reconciliation.
• --observation <text>: Structured finding observation to append with the verification.
• --impact <text>: Structured finding impact to append with the verification.
• --resolution <text>: Structured finding resolution to append with the verification.
• --promote: Mark the structured finding as an incident candidate. (default=false)
• --external: Mark the incident candidate as external-fixable. (default=false)
• --local-only: Compatibility no-op. Findings are task-local unless --promote, --external, or --repo-fixable is set. (default=false)
• --repo-fixable: Mark the structured finding as repo-fixable so incidents collect can promote it. (default=false)
• --incident-scope <text>: Optional incident scope for the appended finding.
• --incident-tag <tag>: Repeatable incident tag for the appended finding. (repeatable)
• --incident-match <term>: Repeatable incident match term for the appended finding. (repeatable)
• --incident-advice <text>: Optional operator advice for the appended finding.
• --incident-rule <text>: Optional incident rule for the appended finding.
• --quiet: Suppress output. (default=false)

Examples:

agentplane finish 202602030608-F1Q8AB --author INTEGRATOR --body "Verified: all checks passed" --commit abcdef123456

• Finish a task and record commit metadata.

agentplane finish 202602030608-F1Q8AB --author INTEGRATOR --body "Verified: all checks passed" --commit-from-comment --commit-allow packages/agentplane/src

• Finish and create a commit from the comment (single-task only).

agentplane finish 202602030608-F1Q8AB --author INTEGRATOR --body "Verified: all checks passed" --commit abcdef123456 --observation "Recurring manual recovery remained easy to miss." --impact "incidents.md stayed stale until a second command." --resolution "Capture the closeout finding during finish itself." --promote --external

• Finish a task while appending an explicit incident candidate.

start

Transition a task to DOING and record a structured Start comment.

Usage:

agentplane start <task-id> --author <id> [options]

Options:

• --author <id>: Comment author id (e.g. CODER). (required)
• --body <text>: Structured comment body (must match the configured Start: prefix). Use --body-file for Markdown or shell-sensitive text.
• --body-file <path>: Read the structured comment body from a file path (mutually exclusive with --body).
• --commit-from-comment: Create a status commit using the comment body. (default=false)
• --commit-emoji <emoji>: Override the status commit emoji (used with --commit-from-comment).
• --commit-allow <path-prefix>: Repeatable. Allowlist path prefixes to stage for the status commit (used with --commit-from-comment). Use minimal prefixes; '.' is rejected. (repeatable)
• --commit-require-clean: Require a clean working tree for the status commit (used with --commit-from-comment). (default=false)
• --confirm-status-commit: Confirm status commit creation when status_commit_policy=confirm (used with --commit-from-comment). (default=false)
• --force: Override readiness checks and status transition restrictions. (default=false)
• --yes: Auto-approve force-action approval checks when required. (default=false)
• --quiet: Suppress output. (default=false)

Examples:

agentplane start 202602030608-F1Q8AB --author CODER --body-file ./start-note.txt

• Start work on a task.

agentplane start 202602030608-F1Q8AB --author CODER --body "Start: implement spec-driven CLI" --commit-from-comment --commit-allow packages/agentplane/src

• Start work and create a status commit from the comment.

verify

Record a verification outcome for a task; incident candidates stay task-local unless collected explicitly.

Usage:

agentplane verify <task-id> --by <id> [options]

Options:

• --ok: Record an OK verification outcome. (default=false)
• --rework: Record a needs-rework verification outcome. (default=false)
• --by <id>: Verifier id (e.g. REVIEWER). (required)
• --note <text>: Short note describing the verification outcome.
• --note-file <path>: Read the verification note from a file path (mutually exclusive with --note).
• --details <text>: Optional free-form details (mutually exclusive with --file).
• --file <path>: Read details from a file path (mutually exclusive with --details).
• --collect-incidents: After recording verification, collect promotable findings into incidents.md immediately. (default=false)
• --quiet: Suppress output. (default=false)
• --observation <text>: Structured finding observation to append with the verification.
• --impact <text>: Structured finding impact to append with the verification.
• --resolution <text>: Structured finding resolution to append with the verification.
• --promote: Mark the structured finding as an incident candidate. (default=false)
• --external: Mark the incident candidate as external-fixable. (default=false)
• --local-only: Compatibility no-op. Findings are task-local unless --promote, --external, or --repo-fixable is set. (default=false)
• --repo-fixable: Mark the structured finding as repo-fixable so incidents collect can promote it. (default=false)
• --incident-scope <text>: Optional incident scope for the appended finding.
• --incident-tag <tag>: Repeatable incident tag for the appended finding. (repeatable)
• --incident-match <term>: Repeatable incident match term for the appended finding. (repeatable)
• --incident-advice <text>: Optional operator advice for the appended finding.
• --incident-rule <text>: Optional incident rule for the appended finding.

Examples:

agentplane verify 202602030608-F1Q8AB --ok --by REVIEWER --note "Looks good" --quiet

• Record an OK verification outcome.

agentplane verify 202602030608-F1Q8AB --ok --by REVIEWER --note-file ./verify-note.txt

• Record an OK verification outcome using a file-backed note.

agentplane verify 202602030608-F1Q8AB --rework --by REVIEWER --note "Needs changes" --details "Missing tests"

• Record a needs-rework outcome with details.

agentplane verify 202602030608-F1Q8AB --ok --by REVIEWER --note "Looks good" --observation "Repeated recovery was manual." --impact "Operators needed a second command." --resolution "Append structured findings during verify."

• Record verification and append a task-local structured finding.

agentplane verify 202602030608-F1Q8AB --ok --by REVIEWER --note "Looks good" --collect-incidents

• Record verification and collect promotable findings into incidents.md immediately.

Work

work resume

Diagnose how to resume a task in the correct checkout/worktree.

Usage:

agentplane work resume <task-id> [options]

Options:

• --json: Emit JSON. (default=false)

Examples:

agentplane work resume 202602030608-F1Q8AB

• Find the correct worktree/branch route after interruption.

work start

Prepare the workspace for a task (direct: single-stream on current branch; branch_pr: task branch/worktree).

Usage:

agentplane work start <task-id> --agent <ID> --slug <slug> [options]

Options:

• --agent <ID>: Agent id (uppercase letters, numbers, underscore). (required, format=A–Z, 0–9, underscore)
• --slug <slug>: Branch slug (lowercase kebab-case). (required, format=lowercase kebab-case)
• --worktree: Use git worktree for the task branch. Required when workflow_mode=branch_pr. (default=false)

Notes:

• When workflow_mode=direct, agentplane does not create task branches; it records a single active task for the workspace.
• When workflow_mode=branch_pr, --worktree is required and the command must be run on the base branch.
• After branch_pr work starts, run owner-scoped task commands from the created worktree so task README/PR artifacts stay attached to one checkout.
• After interruption, use `agentplane work resume <task-id>` to diagnose the correct checkout, branch, PR, and repair route.

Examples:

agentplane work start 202602030608-F1Q8AB --agent CODER --slug cli

• Start work (direct mode records the active task; branch_pr uses a dedicated task branch/worktree).

PR

integrate

Integrate a task branch into the base branch (branch_pr workflow).

Usage:

agentplane integrate <task-id> [options]

Options:

• --branch <name>: Branch name override.
• --base <name>: Base branch override.
• --merge-strategy <squash|merge|rebase>: Merge strategy (default: merge, preserving branch commits; use squash to compact history). (choices=squash|merge|rebase, default=merge)
• --run-verify: Run verify commands. (default=false)
• --dry-run: Do not modify git state. (default=false)
• --quiet: Reduce output noise. (default=false)

Examples:

agentplane integrate 202602030608-F1Q8AB --run-verify

• Integrate with verify.

integrate queue claim

Claim the next queued integration candidate without running integrate.

Usage:

agentplane integrate queue claim [options]

Options:

• --worker <id>: Queue worker id.
• --lease-ms <ms>: Lease duration.
• --json: Emit JSON. (default=false)

integrate queue doctor

Diagnose and optionally repair stale branch_pr integration queue state.

Usage:

agentplane integrate queue doctor [options]

Options:

• --fix: Apply safe queue repairs. (default=false)
• --dry-run: Report repairs without writing queue state. (default=false)
• --json: Emit JSON. (default=false)

integrate queue enqueue

Add or refresh a verified task branch in the integration queue.

Usage:

agentplane integrate queue enqueue <task-id> [options]

Options:

• --branch <name>: Branch name override.
• --base <name>: Base branch override.
• --priority <number>: Higher values are claimed first. (default=0)

integrate queue list

List branch_pr integration queue entries.

Usage:

agentplane integrate queue list [options]

Options:

• --json: Emit JSON. (default=false)

integrate queue release

Release or complete a queue entry.

Usage:

agentplane integrate queue release <task-id> [options]

Options:

• --status <queued|done|rework>: Next queue status. (choices=queued|done|rework, default=queued)
• --reason <text>: Release reason.

integrate queue run-next

Claim and run one queued integration candidate.

Usage:

agentplane integrate queue run-next [options]

Options:

• --worker <id>: Queue worker id.
• --lease-ms <ms>: Lease duration.
• --poll-interval-ms <ms>: Delay between queue retry attempts when --wait is enabled.
• --timeout-ms <ms>: Maximum time to wait for the merge lane when --wait is enabled.
• --run-verify: Run verify commands. (default=false)
• --dry-run: Do not modify git state. (default=false)
• --quiet: Reduce output noise. (default=false)
• --drain: Keep claiming queued entries after successful integrations until the lane blocks or empties. (default=false)
• --wait: Poll a busy merge lane until it opens or --timeout-ms elapses. (default=false)
• --hosted: Wait for hosted GitHub PR checks before running integrate. (default=false)
• --stable-polls <count>: Consecutive hosted-ready polls required when --hosted is enabled.
• --hosted-poll-interval-ms <ms>: Delay between hosted-check polls when --hosted is enabled.
• --hosted-timeout-ms <ms>: Maximum hosted-check wait time when --hosted is enabled.
• --required-check <name>: Repeatable hosted check name that must appear in the PR rollup. (repeatable)

pr check

Check that PR artifacts are present and valid.

Usage:

agentplane pr check <task-id> [options]

Options:

• --branch <name>: Task branch to validate when local artifacts are stale or ambiguous.
• --hosted: Require hosted GitHub PR checks to be complete and stable. (default=false)
• --stable-polls <count>: Consecutive hosted-ready polls required when --hosted is enabled.
• --poll-interval-ms <ms>: Delay between hosted-check polls when --hosted is enabled.
• --timeout-ms <ms>: Maximum hosted-check wait time when --hosted is enabled.
• --required-check <name>: Repeatable hosted check name that must appear in the PR rollup. (repeatable)

Examples:

agentplane pr check 202602030608-F1Q8AB

• Check artifacts.

agentplane pr check 202602030608-F1Q8AB --branch task/202602030608-F1Q8AB/demo

• Validate artifacts from the selected task branch.

pr close

Close a GitHub PR through REST with optional remote head-branch deletion.

Usage:

agentplane pr close <pr-number> [options]

Options:

• --repo <owner/name>: Optional. GitHub owner/repo override (defaults to origin remote).
• --comment <text>: Optional. Add a close comment before closing the PR.
• --delete-remote-branch: Delete the remote head branch after a successful close when it belongs to the target repo. (default=false)

Examples:

agentplane pr close 123 --comment "Superseded by #456" --delete-remote-branch

• Close a stale PR and remove its remote head branch when it belongs to the same repo.

pr close-superseded

Close a superseded task PR using task artifacts.

Usage:

agentplane pr close-superseded <task-id> [options]

Options:

• --delete-remote-branch: Delete the remote head branch after a successful close when it belongs to the task repo. (default=false)

Examples:

agentplane pr close-superseded 202604072308-A1XE27 --delete-remote-branch

• Repair a stale task PR after the task has already been merged to main.

pr flow status

Show branch_pr task branch, remote PR, close-tail, and next-action state.

Usage:

agentplane pr flow status <task-id> [options]

Options:

• --json: Emit JSON. (default=false)

Examples:

agentplane pr flow status 202602030608-F1Q8AB

• Inspect current PR flow state before merge or cleanup.

agentplane pr flow status 202602030608-F1Q8AB --json

• Emit machine-readable flow state.

pr note

Append a handoff note into PR review.md.

Usage:

agentplane pr note <task-id> --author <id> [options]

Options:

• --author <id>: Author id (e.g. REVIEWER). (required)
• --body <text>: Note body text. Use --body-file for Markdown or shell-sensitive text.
• --body-file <path>: Read the note body from a file path (mutually exclusive with --body).

Examples:

agentplane pr note 202602030608-F1Q8AB --author REVIEWER --body "LGTM"

• Add note.

pr open

Create PR artifacts for a task and, unless --sync-only is set, publish/link the remote GitHub PR.

Usage:

agentplane pr open <task-id> --author <id> [options]

Options:

• --author <id>: Author id (e.g. CODER). (required)
• --branch <name>: Branch name (default: current branch).
• --include-task <task-id>: Repeatable. Record an additional related task id on this primary PR. (repeatable)
• --sync-only: Only write local PR artifacts; do not create a remote GitHub PR. (default=false)

Examples:

agentplane pr open 202602030608-F1Q8AB --author CODER

• Sync local artifacts, publish the task branch to origin if needed, and create/link the GitHub PR.

pr update

Update PR artifacts (review packet, diffstat, and GitHub projections).

Usage:

agentplane pr update <task-id> [options]

Options:

• --include-task <task-id>: Repeatable. Record an additional related task id on this primary PR. (repeatable)

Examples:

agentplane pr update 202602030608-F1Q8AB

• Update artifacts.

Branch

branch base clear

Clear the pinned base branch.

Usage:

agentplane branch base clear

branch base explain

Explain current, pinned, and effective base branch resolution.

Usage:

agentplane branch base explain

branch base get

Print the pinned base branch.

Usage:

agentplane branch base get

branch base set

Pin a base branch by name, or pin the current branch.

Usage:

agentplane branch base set [<name>] [options]

Options:

• --current: Pin the current branch as base (conflicts with <name>). (default=false)

Examples:

agentplane branch base set main

• Pin main as the base branch.

agentplane branch base set --current

• Pin the current branch as base.

branch remove

Remove a task branch and/or its worktree.

Usage:

agentplane branch remove [options]

Options:

• --branch <name>: Branch name to delete.
• --worktree <path>: Worktree path to remove (relative to repo root or absolute).
• --force: Force deletion. (default=false)
• --yes: Auto-approve force-action approval checks when required. (default=false)
• --quiet: Reduce output noise. (default=false)

Examples:

agentplane branch remove --branch task/202602030608-F1Q8AB/cli

• Delete a branch.

agentplane branch remove --worktree .agentplane/worktrees/202602030608-F1Q8AB-cli

• Remove a worktree.

agentplane branch remove --branch task/202602030608-F1Q8AB/cli --worktree .agentplane/worktrees/202602030608-F1Q8AB-cli --force

• Force-remove both worktree and branch.

branch status

Show ahead/behind status for a branch relative to a base branch.

Usage:

agentplane branch status [options]

Options:

• --branch <name>: Branch name (default: current branch).
• --base <name>: Base branch name (default: auto-resolved base).

Examples:

agentplane branch status

• Check current branch against effective base.

agentplane branch status --base main

• Check against an explicit base.

cleanup merged

Delete merged task branches/worktrees (branch_pr workflow).

Usage:

agentplane cleanup merged [options]

Options:

• --base <name>: Base branch override.
• --yes: Confirm deletions. (default=false)
• --archive: Archive PR artifacts before deletion. (default=false)
• --delete-remote-branches: Also delete matching remote task branches on origin. (default=false)
• --fetch: Fetch and prune origin before candidate resolution. (default=false)
• --finalize: Fetch, fast-forward the base branch, then delete merged local and remote task branches/worktrees. (default=false)
• --quiet: Reduce output noise. (default=false)
• --preserve-dirty: Stash dirty worktree state before removing merged worktrees. (default=false)
• --report <path>: Write a cleanup candidate/result report to a repository-relative path.

Examples:

agentplane cleanup merged

• List candidates without deleting.

agentplane cleanup merged --yes --archive

• Delete candidates and archive PR artifacts.

agentplane cleanup merged --yes --delete-remote-branches

• Delete candidates and matching remote task branches on origin.

agentplane cleanup merged --fetch

• Refresh origin before evaluating cleanup candidates.

agentplane cleanup merged --finalize

• One-command post-merge base refresh and local/remote cleanup.

Backend

backend connect

Configure a cloud backend connection.

Usage:

agentplane backend connect <id> [options]

Options:

• --endpoint <url>: Cloud sync service endpoint.
• --project-id <id>: Cloud sync service project identifier.
• --provider <name>: Optional remote projection provider selected in the cloud service.
• --token <token>: Cloud CLI token. Stored only in ignored project .env, not backend JSON.
• --yes: Reserved for future browser flow approval. (default=false)
• --quiet: Reduce output noise. (default=false)

Examples:

agentplane backend connect cloud --endpoint https://sync.agentplane.cloud --project-id proj_123 --token apc_...

• Attach this repository to a cloud sync project and keep the token in ignored .env.

backend inspect

Inspect visible backend readiness facts without mutating remote state.

Usage:

agentplane backend inspect <id> [options]

Options:

• --yes: Auto-approve network access. (default=false)
• --quiet: Reduce output noise. (default=false)

Examples:

agentplane backend inspect cloud --yes

• Inspect cloud backend readiness without remote writes.

backend sync

Sync the configured backend (push or pull).

Usage:

agentplane backend sync <id> [options]

Options:

• --direction <push|pull>: Sync direction (default: push). (choices=push|pull, default=push)
• --conflict <diff|prefer-local|prefer-remote|fail>: Conflict handling policy (default: diff). (choices=diff|prefer-local|prefer-remote|fail, default=diff)
• --watch: Watch mode (pull only): periodically pull until interrupted or max iterations. (default=false)
• --interval-ms <ms>: Watch mode polling interval in milliseconds (default: 30000). (default=30000)
• --max-iterations <n>: Watch mode: stop after N iterations (0 means run until interrupted). Useful for tests. (default=0)
• --yes: Auto-approve network access. (default=false)
• --quiet: Reduce output noise. (default=false)

Examples:

agentplane backend sync local --direction pull

• Pull from backend.

agentplane backend sync cloud --direction push --yes

• Push to a networked backend with explicit approval.

sync

Sync the configured backend (alias).

Alias for backend sync using the configured backend id. Optionally pass an explicit backend id.

Usage:

agentplane sync [<id>] [options]

Options:

• --direction <push|pull>: Sync direction (default: push). (choices=push|pull, default=push)
• --conflict <diff|prefer-local|prefer-remote|fail>: Conflict handling policy (default: diff). (choices=diff|prefer-local|prefer-remote|fail, default=diff)
• --yes: Auto-approve network access. (default=false)
• --quiet: Reduce output noise. (default=false)

Examples:

agentplane sync --direction pull

• Pull from backend (configured backend id).

agentplane sync --direction push --yes

• Push to the configured backend.

Config

config set

Update WORKFLOW front matter config (dotted keys).

Usage:

agentplane config set <key> <value>

Examples:

agentplane config set workflow_mode direct

• Set workflow mode.

agentplane config set tasks.verify.required_tags '["code","backend"]'

• Set a JSON list value (pass JSON as a string).

config show

Print resolved WORKFLOW-backed config JSON.

Usage:

agentplane config show

Examples:

agentplane config show

• Show the active WORKFLOW config.

mode get

Print workflow mode.

Usage:

agentplane mode get

Examples:

agentplane mode get

• Print workflow_mode (direct|branch_pr).

mode set

Set workflow mode.

Usage:

agentplane mode set <direct|branch_pr>

Examples:

agentplane mode set branch_pr

• Switch to branch_pr mode.

profile set

Apply setup profile presets to WORKFLOW config.

Usage:

agentplane profile set <light|normal|full-harness>

Examples:

agentplane profile set light

• Apply flexible defaults.

agentplane profile set normal

• Apply balanced defaults.

agentplane profile set full-harness

• Apply strict defaults.

Setup

init

Initialize agentplane project files under .agentplane/.

Creates .agentplane/ config, backend stubs, and agent templates in the target directory. If the target directory is not a git repository, it initializes one and (by default) writes an initial install commit. Use --gitignore-agents to keep agent templates local (gitignored) and skip the install commit. In interactive mode it prompts for missing inputs; use --yes for non-interactive mode.

Usage:

agentplane init [options]

Options:

• --init-mode <quick|guided|advanced|ci>: User-facing init route. TTY defaults to guided; --yes defaults to ci for automation. (choices=quick|guided|advanced|ci)
• --quick: Alias for --init-mode quick. (default=false)
• --advanced: Alias for --init-mode advanced. (default=false)
• --tool <codex|claude|cursor|windsurf|hermes|multiple|manual>: AI surface that should read project instructions. Granular --policy-gateway/--ide flags override this mapping. (choices=codex|claude|cursor|windsurf|hermes|multiple|manual)
• --setup-profile <light|normal|full-harness>: Setup profile preset. Preferred values: light, normal, full-harness. (choices=light|normal|full-harness|developer|vibecoder|manager)
• --policy-gateway <codex|claude>: Policy gateway file to install (codex -> AGENTS.md, claude -> CLAUDE.md). (choices=codex|claude)
• --ide <none|codex|cursor|windsurf>: IDE rules integration target (default: codex). (choices=none|codex|cursor|windsurf)
• --workflow <direct|branch_pr>: Workflow mode (default: direct). (choices=direct|branch_pr)
• --direct-close-dirty-policy <allow-other-task-readmes|strict>: Direct-mode close behavior when tracked dirt exists outside the active task: allow only other active task READMEs, or block on any unrelated tracked change. (choices=allow-other-task-readmes|strict)
• --backend <local|cloud>: Task backend (default: local). (choices=local|cloud)
• --hooks <true|false>: Install managed git hooks (default by setup profile: light=false, normal/full-harness=true).
• --require-plan-approval <true|false>: Require explicit plan approval before starting work.
• --require-network-approval <true|false>: Require explicit approval before any network operation.
• --require-verify-approval <true|false>: Require explicit approval before recording verification.
• --feedback-github-issues <true|false>: Opt in to Agentplane GitHub issue prompts for internal Agentplane errors (default: false).
• --feedback-anonymous-cloud <true|false>: Allow anonymous Agentplane issue intake fallback when GitHub issue publishing is unavailable (default: false).
• --execution-profile <conservative|balanced|aggressive>: Execution profile preset controlling autonomy, reasoning, and tool budgets. (choices=conservative|balanced|aggressive)
• --evaluator-skepticism <standard|strict|paranoid>: Evaluator audit skepticism level for Codex runner review prompts. (choices=standard|strict|paranoid)
• --strict-unsafe-confirm <true|false>: Require strict explicit confirmations for additional unsafe actions.
• --recipes <none|id1,id2,...>: Optional cached recipes to vendor during init (comma-separated), or 'none'.
• --blueprints <none|id1,pack:id2,...>: Optional cached blueprint catalog entries to install and activate during init (comma-separated), or 'none'. Prefix with blueprint: or pack: to disambiguate.
• --force: Overwrite init conflicts by deleting existing paths. (default=false)
• --backup: Backup init conflicts before overwriting. (default=false)
• --yes: Non-interactive mode (do not prompt; use defaults for missing flags). (default=false)
• --no-input: Alias for --yes; run init without prompts using defaults for missing flags. (default=false)
• --non-interactive: Alias for --yes; run init without prompts using defaults for missing flags. (default=false)
• --dry-run: Build and print the init plan without writing files, initializing git, or handling conflicts. (default=false)
• --gitignore-agents: Add gateway/agent files (AGENTS.md or CLAUDE.md and .agentplane/agents/) to .gitignore and skip the initial install commit. (default=false)

Examples:

agentplane init

• Interactive setup (prompts for missing values).

agentplane init --setup-profile light --yes

• Non-interactive setup with flexible defaults.

agentplane init --workflow direct --direct-close-dirty-policy allow-other-task-readmes --backend local --hooks true --require-network-approval true --yes

• Non-interactive setup with the tolerant direct close policy plus an explicit network-approval override.

agentplane init --workflow direct --direct-close-dirty-policy strict --yes

• Initialize direct mode with strict close-tail blocking on any unrelated tracked dirt.

agentplane init --feedback-github-issues true --yes

• Opt in to GitHub issue prompts for internal Agentplane errors.

agentplane init --force --yes

• Re-initialize, overwriting conflicts (non-interactive).

agentplane init --yes --gitignore-agents

• Initialize without committing and keep agent prompts/templates local (gitignored).

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

• Print a machine-readable init plan without writing files.

agentplane init --quick --tool cursor

• Use the quick first-run route and install AGENTS.md plus Cursor rules.

agentplane init --quick --tool hermes

• Use the quick first-run route and configure task runs through the Hermes custom runner profile.

upgrade

Upgrade the local agentplane framework bundle in the repo.

Upgrades the local agentplane framework bundle in the repo using a strict manifest of managed files. By default, upgrade applies the bundled managed files from the locally installed agentplane package assets (no network) and creates a dedicated upgrade commit. Use --dry-run to preview changes without writing files, or --agent to generate a plan-only report instead of applying. Use --remote to fetch a GitHub release bundle; network access is gated by config approvals.

Usage:

agentplane upgrade [options]

Options:

• --agent: Generate a plan-only upgrade report instead of applying managed files. (default=false)
• --auto: Apply the upgrade automatically (same behavior as the default mode; useful for explicit scripts). (default=false)
• --remote: Fetch the framework bundle from GitHub releases (requires network approvals). (default=false)
• --allow-tarball: Allow falling back to a GitHub repo tarball when release assets are missing (no checksum verification). (default=false)
• --tag <tag>: GitHub release tag (defaults to latest).
• --source <repo-url>: Override GitHub repo source URL (defaults to config.framework.source).
• --bundle <path|url>: Use a local path or URL for the upgrade bundle archive.
• --checksum <path|url>: Use a local path or URL for the bundle checksum file (required with --bundle).
• --asset <name>: Override the GitHub release asset name for the bundle.
• --checksum-asset <name>: Override the GitHub release asset name for the checksum file.
• --dry-run: Report changes without modifying files. (default=false)
• --migrate-task-docs: After applying the framework upgrade, migrate legacy task README docs in the same run. (default=false)
• --no-backup: Disable backups (default is to create backups). (default=false)
• --yes: Auto-approve network access prompts (subject to config approvals). (default=false)

Examples:

agentplane upgrade

• Apply managed files from the installed CLI assets and create an upgrade commit.

agentplane upgrade --dry-run

• Preview managed-file changes without modifying the repo.

agentplane upgrade --agent

• Generate a plan-only upgrade report instead of applying files.

agentplane upgrade --remote --tag v0.1.9 --dry-run

• Preview changes for a specific GitHub release tag (no writes).

agentplane upgrade --bundle ./agentplane-upgrade.tar.gz --checksum ./agentplane-upgrade.tar.gz.sha256

• Upgrade from local bundle files (no network).

agentplane upgrade --yes --migrate-task-docs

• Apply the framework upgrade and migrate legacy task README docs in one operator run.

Quality

doctor

Check workspace invariants for a normal agentplane installation (with optional dev source checks).

Usage:

agentplane doctor [options]

Options:

• --fix: Apply safe fixes. (default=false)
• --dev: Run monorepo source-layer checks (requires packages/agentplane/src). (default=false)
• --deep: Run expensive full task README body drift diagnostics. (default=false)
• --archive-full: Run the full historical task archive audit instead of the bounded recent scan. (default=false)

Examples:

agentplane doctor

• Check installed workspace invariants.

agentplane doctor --archive-full

• Also scan the full historical task archive for older commit anomalies.

agentplane doctor --deep

• Also scan every task README body for canonical projection drift.

agentplane doctor --dev

• Also run monorepo source-layer checks.

agentplane doctor --fix

• Apply safe-only fixes (idempotent).

doctor git-locks

Check Git index lock state for this repository and suggest cleanup.

Usage:

agentplane doctor git-locks [options]

Options:

• --fix: Remove stale index.lock when safe. (default=false)

Examples:

agentplane doctor git-locks

• Inspect current git index lock status.

agentplane doctor git-locks --fix

• Remove stale git index.lock after inspection.

Diagnostics

insights issue

Create an opt-in GitHub issue with privacy-bounded Agentplane diagnostics.

Usage:

agentplane insights issue [options]

Options:

• --title <title>: Issue title. Defaults to an internal Agentplane error report title.
• --body <text>: Optional short user-visible context to include before diagnostics.
• --agent-context <text>: Sanitized agent-written diagnostic context to include in the public issue body.
• --triage <startup-routing>: Append CLI-generated privacy-bounded diagnostic triage; the agent-written context is still required for real E_INTERNAL issues. (choices=startup-routing)
• --agent-context-file <path>: Read sanitized agent-written diagnostic context from a file before creating the issue.
• --allow-missing-agent-context: Allow creating an E_INTERNAL issue without the recommended agent-written context. (default=false)
• --error-code <code>: Agentplane error code that triggered the report.
• --failure-command <command>: Privacy-safe command id associated with the failure, for example task start-ready.
• --failure-phase <phase>: Privacy-safe lifecycle phase associated with the failure.
• --failure-reason-code <code>: Privacy-safe reason code associated with the failure.
• --failure-message-class <class>: Privacy-safe error message class, not the raw error message.
• --failure-argv-shape <token>: Repeatable sanitized argv shape token; values must not include raw secrets. (repeatable)
• --transport <github|cloud|auto>: Issue transport. github uses the user's gh auth, cloud uses anonymous Agentplane intake, auto falls back to cloud when GitHub publishing fails. (choices=github|cloud|auto)
• --allow-disabled-feedback: Allow this one issue creation when feedback.github_issues.enabled=false without modifying project config. (default=false)
• --dry-run: Print the GitHub issue payload without creating an issue. (default=false)

Examples:

agentplane insights issue --error-code E_INTERNAL

• Create a GitHub issue after feedback GitHub issues are enabled.

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

• Preview the privacy-bounded issue payload without network access.

agentplane insights issue --allow-disabled-feedback --error-code E_INTERNAL

• Create one issue from an explicitly opted-out project without changing config.

insights report

Print a local-only privacy-bounded Agentplane diagnostic report.

Usage:

agentplane insights report [options]

Options:

• --json: Emit the full report as machine-readable JSON. (default=false)
• --recent-limit <n>: Number of recent task ids to include (default: 8, max: 25).

Examples:

agentplane insights report

• Print a readable local diagnostic summary.

agentplane insights report --json

• Print the full local diagnostic report for support tooling.

insights triage

Print structured privacy-bounded diagnostic findings for support triage.

Usage:

agentplane insights triage [options]

Options:

• --json: Emit the triage result as machine-readable JSON. (default=false)
• --preset <startup-routing>: Diagnostic rule preset to run (default: startup-routing). (choices=startup-routing)
• --recent-limit <n>: Number of recent task ids to include in the backing report (default: 8, max: 25).
• --error-code <code>: Agentplane error code that triggered the report.
• --failure-command <command>: Privacy-safe command id associated with the failure, for example task start-ready.
• --failure-phase <phase>: Privacy-safe lifecycle phase associated with the failure.
• --failure-reason-code <code>: Privacy-safe reason code associated with the failure.
• --failure-message-class <class>: Privacy-safe error message class, not the raw error message.
• --failure-argv-shape <token>: Repeatable sanitized argv shape token; values must not include raw secrets. (repeatable)

Examples:

agentplane insights triage --preset startup-routing

• Build structured startup-route diagnostics before filing a feedback issue.

agentplane insights triage --preset startup-routing --json

• Emit machine-readable triage for support tooling.

intake

Build a deterministic intake envelope for a raw request.

Extracts explicit file context, current git context, optional search candidates, default constraints, and quality warnings. This command does not use an LLM.

Usage:

agentplane intake <request> ... [options]

Options:

• --json: Emit machine-readable JSON. (default=false)
• --search: Add low-confidence rg-based file candidates from request keywords. (default=false)
• --no-git: Do not include current git status files in the intake context. (default=false)
• --task <task-id>: Existing task id for manifest writing.
• --write-manifest: Write .agentplane/tasks/<task-id>/context/file-manifest.json. Requires --task. (default=false)
• --include-raw-request: Persist the raw request in the task manifest. By default manifest raw text is redacted. (default=false)

Notes:

• Search candidates are evidence hints, not authority.
• `--write-manifest` writes a task-local artifact only; task creation remains owned by `agentplane task new` and `agentplane task begin`.

Examples:

agentplane intake "Fix parser edge case in packages/agentplane/src/parser.ts; must keep public API"

• Inspect request quality and explicit file context before creating or running a task.

agentplane intake "Improve task quality diagnostics" --search --json

• Emit a machine-readable intake envelope with low-confidence search candidates.

agentplane intake "Implement approved scope" --task 202606080633-RA63N8 --write-manifest

• Persist a task-local context manifest without changing task lifecycle state.

runtime explain

Explain the active binary, runtime mode, and resolved package roots.

Usage:

agentplane runtime explain [options]

Options:

• --json: Emit machine-readable runtime details. (default=false)
• --compact: Emit a compact prompt diagnostics payload for agent consumption. (default=false)

Examples:

agentplane runtime explain

• Show the active runtime as readable text.

agentplane runtime explain --json

• Show runtime details for scripts and diagnostics tooling.

Recipes

recipes active

List active project overlays.

Usage:

agentplane recipes active [options]

Options:

• --full: Print full JSON payload. (default=false)

Examples:

agentplane recipes active

• Show overlays active for the project.

recipes add

Vendor a cached recipe into the current project.

Usage:

agentplane recipes add <id|id@version> [options]

Options:

• --mode <copy|link>: Materialization mode for the project-local package. (choices=copy|link)

Examples:

agentplane recipes add tdd

• Vendor the latest cached recipe into the project.

agentplane recipes add tdd@1.2.0 --mode link

• Link a cached recipe into the project for local recipe development.

recipes cache prune

Prune global recipe cache entries.

Usage:

agentplane recipes cache prune [options]

Options:

• --dry-run: Report removals without modifying files. (default=false)
• --all: Remove all cached recipes (also clears installed recipes file). (default=false)

Examples:

agentplane recipes cache prune --dry-run

• Preview removals.

agentplane recipes cache prune

• Prune unused cached recipes.

agentplane recipes cache prune --all

• Remove everything.

recipes detach

Convert a linked vendored recipe into a project-local copy.

Usage:

agentplane recipes detach <id>

Examples:

agentplane recipes detach tdd

• Freeze a linked recipe into a portable project copy before sharing the repo.

recipes disable

Disable an active project overlay for the current project.

Usage:

agentplane recipes disable <recipe-id>

Examples:

agentplane recipes disable tdd

• Deactivate an overlay.

recipes enable

Enable an installed project overlay for the current project.

Usage:

agentplane recipes enable <recipe-id>

Examples:

agentplane recipes enable tdd

• Activate an installed overlay.

recipes explain

Show detailed info for a vendored recipe.

Usage:

agentplane recipes explain <id>

Examples:

agentplane recipes explain viewer

• Show detailed project-local recipe info.

recipes explain-active

Print the compiled active overlay bundle.

Usage:

agentplane recipes explain-active

Examples:

agentplane recipes explain-active

• Inspect compiled overlay runtime data.

recipes info

Show cached recipe metadata.

Usage:

agentplane recipes info <id>

Examples:

agentplane recipes info viewer

• Show cached recipe metadata.

recipes install

Install a recipe into the global cache from remote index, local archive, or URL.

Usage:

agentplane recipes install <id|path|url> [--index <path|url>] [--refresh] [--yes] [--on-conflict <fail|rename|overwrite>]
agentplane recipes install --name <id> [--index <path|url>] [--refresh] [--yes] [--on-conflict <fail|rename|overwrite>]
agentplane recipes install --path <path> [--yes] [--on-conflict <fail|rename|overwrite>]
agentplane recipes install --url <url> [--yes] [--on-conflict <fail|rename|overwrite>]

Options:

• --name <id>: Cache from remote index by recipe id.
• --path <path>: Cache from local recipe archive path.
• --url <url>: Cache from recipe archive URL.
• --index <path|url>: Override recipes index location (used when installing by name / auto-name).
• --refresh: Refresh remote index cache before installing. (default=false)
• --yes: Auto-approve network prompts when allowed by config. (default=false)
• --on-conflict <fail|rename|overwrite>: Deprecated compatibility no-op; recipe installs stay self-contained. (choices=fail|rename|overwrite, default=fail)

Notes:

• Auto mode resolution matches v0.1.9: URL if http(s); else PATH if file exists; else NAME (remote index).
• Network operations may require approval; use --yes to auto-approve when allowed by config.
• --on-conflict is accepted for backward compatibility but does not change install behavior.

Examples:

agentplane recipes install viewer

• Auto: install by id from remote index.

agentplane recipes install --name viewer --refresh

• Install by id, forcing index refresh.

agentplane recipes install viewer --on-conflict overwrite

• Compatibility-only flag; ignored by self-contained recipe installs.

recipes list

List cached recipes.

Usage:

agentplane recipes list [options]

Options:

• --full: Print full JSON payload. (default=false)
• --tag <tag>: Filter cached recipes by tag.

Examples:

agentplane recipes list

• List cached recipes.

agentplane recipes list --tag cli

• List cached recipes with a tag.

agentplane recipes list --full

• Print full JSON payload.

recipes list-remote

List recipes from the remote index (or cache).

Usage:

agentplane recipes list-remote [options]

Options:

• --refresh: Refresh remote index cache before listing. (default=false)
• --index <path|url>: Override recipes index location (path or http(s) URL).
• --yes: Auto-approve network access prompts (subject to config approvals). (default=false)

Examples:

agentplane recipes list-remote

• List remote recipes using cached index when available.

agentplane recipes list-remote --refresh

• Force refresh of the remote index cache.

agentplane recipes list-remote --index ./index.json --refresh

• Refresh from a local index file.

recipes remove

Remove a vendored recipe from the current project.

Usage:

agentplane recipes remove <id>

Examples:

agentplane recipes remove viewer

• Remove a vendored recipe by id.

recipes update

Refresh a vendored recipe from the cached source.

Usage:

agentplane recipes update <id> [options]

Options:

• --force: Overwrite local project edits in the vendored recipe. (default=false)

Examples:

agentplane recipes update tdd

• Sync a clean vendored recipe to the current cached source.

agentplane recipes update tdd --force

• Overwrite local vendored edits with the cached source.

Blueprints

blueprint drift

Check whether a task resolved blueprint snapshot is current.

Usage:

agentplane blueprint drift <task-id> [options]

Options:

• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint drift 202605060915-3NBTGG

• Check a task-local resolved snapshot before runner materialization.

blueprint examples

Show practical blueprint route inspection examples.

Usage:

agentplane blueprint examples [options]

Options:

• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint examples

• Inspect which route different task classes resolve to.

agentplane blueprint examples --json

• Emit route examples for agents or documentation tooling.

blueprint explain

Explain blueprint route selection for a task or synthetic input.

Usage:

agentplane blueprint explain [<task-id>] [options]

Options:

• --kind <analysis|content|docs|code|release|ops|context>: Synthetic task kind hint.
• --mutation <none|docs|code|release|ops|unknown>: Synthetic mutation scope. (choices=none|docs|code|release|ops|unknown, default=unknown)
• --workflow-mode <direct|branch_pr>: Workflow mode override. (choices=direct|branch_pr)
• --tag <tag>: Synthetic tag.
• --title <text>: Synthetic title.
• --description <text>: Synthetic description.
• --risk <risk>: Risk flag; repeatable.
• --blueprint <id>: Explicit blueprint request.
• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint explain 202605051957-5WRJZK

• Resolve a task.

agentplane blueprint explain --kind analysis --mutation none

• Resolve a synthetic analysis route.

blueprint list

List built-in and optional project-local blueprint routes.

Usage:

agentplane blueprint list [options]

Options:

• --project: Include validated project-local blueprints from .agentplane/blueprints. (default=false)
• --trusted: Show trust status from .agentplane/blueprints/config.json. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint list --json

• Emit machine-readable built-in routes.

agentplane blueprint list --project

• Include project-local blueprint definitions.

blueprint report

Report project-local blueprint trust compatibility.

Usage:

agentplane blueprint report [options]

Options:

• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint report --json

• Inspect project-local blueprint trust compatibility before runner materialization.

blueprint scaffold

Create a project-local blueprint JSON scaffold without enabling it.

Usage:

agentplane blueprint scaffold <blueprint-id> [options]

Options:

• --from <builtin-blueprint-id>: Built-in blueprint to clone as a starting point.
• --out <path>: Output path; defaults to .agentplane/blueprints/<id>.json.
• --force: Overwrite an existing file. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint scaffold analysis.custom

• Create .agentplane/blueprints/analysis.custom.json from analysis.light.

agentplane blueprint scaffold code.custom --from code.branch_pr

• Start from an existing code workflow route.

blueprint snapshot

Refresh the resolved blueprint snapshot artifact for a task.

Usage:

agentplane blueprint snapshot <task-id> [options]

Options:

• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint snapshot 202605060915-3NBTGG

• Refresh the task-local resolved blueprint snapshot artifact.

agentplane blueprint snapshot 202605060915-3NBTGG --json

• Emit old/new digest details as JSON.

blueprint validate

Validate project-local blueprint JSON without registering or executing it.

Usage:

agentplane blueprint validate [<path>] [options]

Options:

• --project: Validate all JSON blueprints in .agentplane/blueprints or the supplied directory. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane blueprint validate .agentplane/blueprints/analysis.json

• Validate a local blueprint definition.

agentplane blueprint validate --project

• Validate the project-local blueprint registry directory.

blueprints catalog info

Show cached external blueprint or pack metadata.

Usage:

agentplane blueprints catalog info <id> [options]

Options:

• --kind <blueprint|pack>: Disambiguate catalog id kind. (choices=blueprint|pack)
• --json: Emit JSON. (default=false)

blueprints catalog list

List cached external blueprint catalog entries.

Usage:

agentplane blueprints catalog list [options]

Options:

• --json: Emit JSON. (default=false)

blueprints catalog refresh

Refresh the cached external blueprint catalog index.

Usage:

agentplane blueprints catalog refresh --index <path|url> [options]

Options:

• --index <path|url>: Catalog index path or URL. (required)
• --json: Emit JSON. (default=false)

blueprints install

Install an external blueprint or blueprint pack into the current project.

Usage:

agentplane blueprints install <blueprint-or-pack-id> [options]

Options:

• --kind <blueprint|pack>: Disambiguate catalog id kind. (choices=blueprint|pack)
• --index <path|url>: Refresh from this catalog index before installing.
• --refresh: Refresh the cached catalog before installing. (default=false)
• --activate: Explicitly add installed route blueprint ids to the project trust allowlist. (default=false)
• --json: Emit JSON. (default=false)

ACR

acr check

Run the ACR merge-gate check for CI and branch review.

Usage:

agentplane acr check <task-id> [options]

Options:

• --mode <ci>: Check mode. (choices=ci, default=ci)
• --require-plan-approved: Require approved plan. (default=true)
• --require-verification: Require passed verification. (default=true)
• --require-policy-pass: Reject failed policy decisions. (default=true)
• --allow-waived-verification: Allow waived verification with approval. (default=false)
• --allow-manual-override: Allow policy manual_override with approval. (default=false)
• --json: Emit machine-readable result. (default=false)

Examples:

agentplane acr check 202605031625-886KZ6 --mode ci

• Run merge gate.

acr explain

Explain an ACR for human review.

Usage:

agentplane acr explain <task-id-or-path> [options]

Options:

• --json: Emit machine-readable summary. (default=false)

Examples:

agentplane acr explain 202605031625-886KZ6

• Summarize ACR readiness.

acr generate

Generate an Agent Change Record from task, Git, policy, and verification state.

Usage:

agentplane acr generate <task-id> [options]

Options:

• --work-commit <rev>: Implementation revision.
• --base-commit <rev>: Base revision override.
• --agent <id>: Agentplane role or agent id.
• --agent-name <name>: Human-readable agent name.
• --model-provider <provider>: Model provider. (choices=anthropic|openai|cursor|aider|unknown|custom)
• --model-name <name>: Model name.
• --out <path>: Write ACR to custom path.
• --write: Write task-local ACR. (default=false)
• --stdout: Print ACR JSON to stdout. (default=false)
• --refresh: Overwrite existing ACR. (default=false)
• --json: Emit machine-readable result. (default=false)

Examples:

agentplane acr generate 202605031625-886KZ6 --work-commit HEAD --write

• Write `.agentplane/tasks/<task-id>/acr.json`.

acr schema

Print or write the ACR v0.1 JSON Schema.

Usage:

agentplane acr schema [options]

Options:

• --version <version>: ACR schema version. (choices=0.1, default=0.1)
• --out <path>: Write schema to a file instead of stdout.

Examples:

agentplane acr schema --version 0.1

• Print the bundled schema.

agentplane acr schema --version 0.1 --out schemas/acr-v0.1.schema.json

• Write the bundled schema to a custom path.

acr validate

Validate an ACR file by schema, local, or CI invariants.

Usage:

agentplane acr validate <task-id-or-path> [options]

Options:

• --mode <schema|local|ci>: Validation mode. (choices=schema|local|ci, default=local)
• --strict: Treat warnings as failures. (default=false)
• --json: Emit machine-readable result. (default=false)

Examples:

agentplane acr validate 202605031625-886KZ6 --mode local

• Validate task ACR.

Guard

commit

Create a git commit after validating policy and allowlist; if the index is empty, stage matching allowlist paths first.

Usage:

agentplane commit <task-id> [options]

Options:

• -m, --message <message>: Commit subject (must follow policy). Required unless --close is used.
• --close: Generate a deterministic close commit message from task snapshot + verification + recorded implementation commit; stages the active task artifact scope. (default=false)
• --unstage-others: With --close: unstage any currently staged paths before staging the active task artifact scope. (default=false)
• --check-only: With --close: run preflight checks and print the planned close commit subject without creating a commit. (default=false)
• --allow <path-prefix>: Repeatable. Allowed path prefix (git-path). Use minimal prefixes; repo-wide '.' is rejected (tip: `agentplane guard suggest-allow --format args`). (repeatable)
• --allow-tasks: Allow the optional tasks export snapshot plus artifacts under the active task subtree; standalone path scope. (default=false)
• --allow-base: Allow base branch edits; branch override only, not a path allowlist. (default=false)
• --allow-policy: Allow policy edits (e.g. AGENTS.md); standalone path scope. (default=false)
• --allow-config: Allow config edits; standalone path scope. (default=false)
• --allow-hooks: Allow hooks edits; standalone path scope. (default=false)
• --allow-ci: Allow CI workflow edits; standalone path scope. (default=false)
• --require-clean: Fail if tracked files have unstaged changes (untracked is ignored). (default=false)
• --quiet: Reduce output noise. (default=false)

Notes:

• Repository-managed task commits use the canonical subject format `<emoji> <suffix> <scope>: <summary>`; non-task commits use `<emoji> <scope>: <summary>`.
• Repository-managed commit paths resolve author/committer identity from global git `user.name` and `user.email` before falling back to ambient git env.
• When `commit.dco.enabled=true`, repository-managed commits append the configured `Signed-off-by` trailer and `commit-msg` rejects manual commits without any valid `Signed-off-by` trailer.
• Protected path-scoped overrides can stand alone without a duplicate explicit prefix: `--allow-tasks`, `--allow-policy`, `--allow-config`, `--allow-hooks`, and `--allow-ci` each admit their own path family.
• Top-level `agentplane commit` can auto-stage those protected path scopes when the git index starts empty.
• `--allow-base` is different: it only overrides base-branch protection and never selects file paths by itself.

Examples:

agentplane commit 202602030608-F1Q8AB -m "✨ F1Q8AB task: implement allowlist guard" --allow packages/agentplane

• Create a commit after validating allowlist and subject policy.

agentplane commit 202602030608-F1Q8AB -m "✨ F1Q8AB task: update publish workflow" --allow-ci

• Commit CI-only changes without a redundant explicit workflow path prefix.

agentplane commit 202602030608-F1Q8AB --close

• Create a close commit for the task artifacts using a deterministic message builder.

guard clean

Ensure the git index has no staged files.

Usage:

agentplane guard clean [options]

Options:

• --quiet: Reduce output noise. (default=false)

Examples:

agentplane guard clean

• Fail if staged files exist.

guard commit

Validate commit policy and allowlist for staged changes (no commit is created).

Usage:

agentplane guard commit <task-id> --message <message> [options]

Options:

• -m, --message <message>: Commit subject (must follow policy). (required)
• --allow <path-prefix>: Repeatable. Allowed path prefix (git-path). Use minimal prefixes; repo-wide '.' is rejected (tip: `agentplane guard suggest-allow --format args`). (repeatable)
• --allow-tasks: Allow the optional tasks export snapshot plus artifacts under the active task subtree; standalone path scope. (default=false)
• --allow-base: Allow base branch edits; branch override only, not a path allowlist. (default=false)
• --allow-policy: Allow policy edits (e.g. AGENTS.md); standalone path scope. (default=false)
• --allow-config: Allow config edits; standalone path scope. (default=false)
• --allow-hooks: Allow hooks edits; standalone path scope. (default=false)
• --allow-ci: Allow CI workflow edits; standalone path scope. (default=false)
• --require-clean: Fail if tracked files have unstaged changes (untracked is ignored). (default=false)
• --quiet: Reduce output noise. (default=false)

Notes:

• Protected path-scoped overrides can stand alone without a duplicate explicit prefix: `--allow-tasks`, `--allow-policy`, `--allow-config`, `--allow-hooks`, and `--allow-ci` each admit their own path family.
• `agentplane guard commit` remains staged-only: it validates the current index and never auto-stages files for you.
• `--allow-base` is different: it only overrides base-branch protection and never selects file paths by itself.

Examples:

agentplane guard commit 202602030608-F1Q8AB -m "✨ F1Q8AB task: implement allowlist guard" --allow packages/agentplane

• Validate staged changes are covered by allowlist and policy.

agentplane guard commit 202602030608-F1Q8AB -m "✨ F1Q8AB task: update publish workflow" --allow-ci

• Validate already staged CI-only changes without a redundant explicit workflow path prefix.

guard suggest-allow

Suggest minimal --allow prefixes based on staged files.

Usage:

agentplane guard suggest-allow [options]

Options:

• --format <lines|args>: Output format (default: lines). (choices=lines|args, default=lines)

Examples:

agentplane guard suggest-allow

• Print prefixes, one per line.

agentplane guard suggest-allow --format args

• Print as --allow ... args.

Hooks

hooks install

Install managed git hooks and the agentplane shim.

Usage:

agentplane hooks install [options]

Options:

• --quiet: Reduce output noise. (default=false)

Examples:

agentplane hooks install

• Install hooks into .git/hooks/.

hooks run

Run a managed hook (use `--` to pass through additional arguments).

Usage:

agentplane hooks run <hook> [<args...> ...]

Examples:

agentplane hooks run pre-commit

• Run the pre-commit checks.

agentplane hooks run commit-msg -- .git/COMMIT_EDITMSG

• Run commit-msg with a message file argument.

hooks uninstall

Uninstall managed git hooks installed by agentplane.

Usage:

agentplane hooks uninstall [options]

Options:

• --quiet: Reduce output noise. (default=false)

Examples:

agentplane hooks uninstall

• Remove agentplane hooks from .git/hooks/.

Policy

incidents advise

Resolve bounded incident advice candidates for a task or ad hoc scope/tag query.

Usage:

agentplane incidents advise [<task-id>] [options]

Options:

• --scope <text>: Ad hoc scope text when querying without a task id.
• --title <text>: Optional title text for ad hoc advice lookup.
• --description <text>: Optional description text for ad hoc advice lookup.
• --tag <tag>: Matching tag for ad hoc advice lookup; repeat as needed. (repeatable)
• --limit <n>: Maximum number of advice entries to show. (default=5)
• --json: Emit machine-readable advice matches. (default=false)

incidents collect

Validate and promote CURATOR-style reusable incident findings into the registry.

Usage:

agentplane incidents collect <task-id> [options]

Options:

• --check: Validate incident promotion inputs without writing `.agentplane/policy/incidents.md`. (default=false)
• --json: Emit machine-readable collection details. (default=false)

Examples:

agentplane incidents collect 202604031416-HEJWTM

• Promote resolved external incident advice from task Findings into the shared registry.

agentplane incidents collect 202604031416-HEJWTM --check --json

• Validate that reusable resolved external findings are complete before finish.

IDE

ide sync

Generate IDE entrypoints from policy gateway file (AGENTS.md or CLAUDE.md).

Usage:

agentplane ide sync [options]

Options:

• --ide <cursor|windsurf>: Only generate rules for a single IDE (default: both). (choices=cursor|windsurf)

Examples:

agentplane ide sync

• Generate Cursor + Windsurf rules.

agentplane ide sync --ide cursor

• Generate Cursor rules only.

agentplane platform sync --platform cursor --platform windsurf

• Use the platform sync command directly.

Context

context check

Check context workspace health.

Runs the human-facing context health check. Use ap context graph validate for the lower-level graph validator.

Usage:

agentplane context check [options]

Options:

• --fix: Repair missing context directories where safe. (default=false)

context dashboard

Serve a read-only local dashboard for the full context knowledge graph.

Builds a typed knowledge graph across wiki pages, wikilinks, entities, facts, sources, capabilities, and task evidence. Uses the existing SQLite context projection when available and serves an in-memory read-only snapshot for fast dashboard access.

Usage:

agentplane context dashboard [options]

Options:

• --host <host>: Host interface for the local read-only HTTP server. (default=127.0.0.1)
• --port <port>: Port for the local server. Use 0 to choose a free port. (default=0)
• --open: Open the dashboard URL in the system browser when supported. (default=false)
• --dump-json: Print the dashboard graph snapshot as JSON and exit without serving HTTP. (default=false)

context init

Initialize local context workspace and system manifest.

Creates the local context workspace in an initialized Agentplane project. When run in an empty standalone directory, it first initializes Agentplane with safe non-interactive defaults, then writes the context workspace. Non-empty uninitialized directories must run agentplane init explicitly first.

Usage:

agentplane context init [options]

Options:

• --profile <adaptive|minimal|wiki|codebase|research|maximum-assimilation>: Select initial context setup. Defaults to maximum-assimilation when omitted. User-facing interactive setup currently uses the default without prompting. (choices=adaptive|minimal|wiki|codebase|research|maximum-assimilation)
• --raw-gitignore <none|all>: Ignore raw sources by default when set to all. (choices=none|all, default=none)
• --derived-gitignore <none|all>: Ignore machine-derived context files under .agentplane/context/derived when set to all. (choices=none|all, default=none)
• --repair: Create missing files only. (default=false)
• --force: Rewrite default policy files while repairing. (default=false)

context learn changes

Create a context assimilation task from changed context sources.

Usage:

agentplane context learn changes [options]

Options:

• --dry-run: Preview only; do not create a task. (default=false)

Examples:

agentplane context learn changes

• Create a CURATOR task from changed local context sources.

context learn files

Create a context assimilation task from explicit files or paths.

Usage:

agentplane context learn files <path> ... [options]

Options:

• --dry-run: Preview only; do not create a task. (default=false)

Examples:

agentplane context learn files docs/research.md context/raw/customer-notes.md

• Create a CURATOR task from explicit external context files.

context learn tasks

Create CURATOR extraction tasks from completed task history.

Selects completed tasks oldest-first and creates standard CURATOR tasks for semantic extraction from task README/ACR sources. It does not write wiki proposals or promote pages directly.

Usage:

agentplane context learn tasks [options]

Options:

• --status <status>: Repeatable task status filter. Defaults to DONE. (repeatable)
• --tag <tag>: Repeatable tag filter. Matches tasks with any listed tag. (repeatable)
• --task <task-id>: Repeatable explicit task id filter. (repeatable)
• --since <YYYY-MM-DD|YYYYMMDDHHmm>: Only include tasks at or after this task-id timestamp prefix.
• --until <YYYY-MM-DD|YYYYMMDDHHmm>: Only include tasks at or before this task-id timestamp prefix.
• --after-task <task-id>: Continue after a previously queued task id.
• --limit <n>: Maximum number of oldest matching tasks to queue.
• --batch-size <n>: Number of selected completed tasks per generated extraction task. (default=25)
• --dry-run: Preview batches without creating tasks. (default=false)
• --format <text|json>: Output format. (choices=text|json, default=text)

Examples:

agentplane context learn tasks --tag release --limit 25

• Create bounded CURATOR tasks from the oldest completed release tasks.

agentplane context learn tasks --tag branch_pr --batch-size 25 --dry-run

• Preview task-history extraction batches without mutating task state.

context search

Search curated local context, facts, graph, and capabilities.

Usage:

agentplane context search <query> [options]

Options:

• --scope <scope>: Comma-separated scope list. Defaults to curated context; use tasks, raw, or all explicitly for broader recall. (default=wiki,facts,graph,capabilities)
• --format <text|json>: Output format. (choices=text|json, default=text)
• --explain: Include score explanation metadata. (default=false)

context show

Resolve a context source reference and print addressed content.

Usage:

agentplane context show <source-ref>

context wiki explain

Print a wiki page's Agentplane context frontmatter.

Usage:

agentplane context wiki explain <path-or-slug>

context wiki index

Update generated wiki index sections for pages and subdirectories.

Usage:

agentplane context wiki index [<path>]

context wiki link

Suggest existing wiki pages that may deserve cross-links.

Usage:

agentplane context wiki link <path-or-slug>

context wiki lint

Validate wiki page frontmatter and source-link hygiene.

Usage:

agentplane context wiki lint [<path>]

context wiki new

Create a wiki page with Agentplane context frontmatter.

Usage:

agentplane context wiki new <path-or-slug> [options]

Options:

• --title <title>: Page title. Defaults to a title derived from the path.
• --modality <modality>: Primary page modality: factual_claim, observation, assumption, hypothesis, decision, policy, preference, requirement, risk, capability, definition, or deprecation. (default=factual_claim)
• --status <epistemic-status>: Initial epistemic status such as extracted_candidate, sourced_claim, reviewed_claim, disputed, deprecated, or canonical_org_knowledge. (default=sourced_claim)
• --visibility <scope>: Intended visibility scope for future publication metadata. (default=project)
• --source <source-ref>: Repeatable markdown/source reference backing the page. (repeatable)
• --force: Overwrite an existing page. (default=false)

Evaluators

evaluator list

List evaluator prompt modules from .agentplane/evaluators.

Usage:

agentplane evaluator list [options]

Options:

• --builtin <true|false>: Include packaged evaluator modules when no project override exists. (choices=true|false, default=true)
• --json: Emit JSON. (default=false)

Examples:

agentplane evaluator list

• Show evaluator ids and prompt metadata.

agentplane evaluator list --json

• Emit machine-readable evaluator metadata.

agentplane evaluator list --builtin false

• Show project-local evaluators only.

evaluator run

Create and record a structured EVALUATOR quality review report.

Usage:

agentplane evaluator run <task-id> [options]

Options:

• --evaluator <id>: Evaluator prompt module id to use. (default=recovery-context)
• --verdict <pass|rework|blocked|human_review>: Quality verdict to record. (choices=pass|rework|blocked|human_review)
• --summary <text>: Concise evaluator judgement summary.
• --finding <text>: Structured review finding. May be repeated. (repeatable)
• --evidence <path-or-note>: Evidence reference checked by the evaluator. May be repeated. (repeatable)
• --missing-test <text>: Missing test or check. May be repeated. (repeatable)
• --hidden-assumption <text>: Hidden assumption found during review. May be repeated. (repeatable)
• --residual-risk <text>: Residual risk after review. May be repeated. (repeatable)
• --rework-context <text>: Machine-readable rework instruction for the next owner pass. May be repeated. (repeatable)
• --no-record: Write evaluator artifacts without updating task quality_review. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane evaluator run 202605232011-MAW1PK --verdict pass --summary "Reviewed diff and checks." --finding "No unresolved findings after diff and verification review." --evidence .agentplane/tasks/202605232011-MAW1PK/README.md

• Record a structured EVALUATOR quality review.

evaluator show

Print an evaluator prompt module.

Usage:

agentplane evaluator show <id> [options]

Options:

• --builtin <true|false>: Include packaged evaluator modules when no project override exists. (choices=true|false, default=true)
• --json: Emit JSON. (default=false)

Examples:

agentplane evaluator show recovery-context

• Print the recovery-context evaluator prompt.

Evidence

evidence bundle

Write a deterministic task evidence bundle manifest.

Usage:

agentplane evidence bundle <task-id> [options]

Options:

• --out <path>: Write manifest to a custom repository-relative path.
• --json: Emit machine-readable result. (default=false)

Examples:

agentplane evidence bundle 202605031625-886KZ6

• Write `.agentplane/tasks/<task-id>/evidence/manifest.json`.

evidence verify

Verify a task evidence bundle manifest and referenced file hashes.

Usage:

agentplane evidence verify <task-id-or-manifest> [options]

Options:

• --json: Emit machine-readable result. (default=false)
• --strict: Fail when the manifest contains no ACR evidence. (default=false)

Examples:

agentplane evidence verify 202605031625-886KZ6

• Verify the task-local evidence manifest.

Integrations

hermes doctor

Check the local Agentplane side of the Hermes adapter contract.

Usage:

agentplane hermes doctor [options]

Options:

• --json: Emit machine-readable result. (default=false)

Examples:

agentplane hermes doctor --json

• Check workflow mode, repo root, and Hermes Kanban environment variables.

hermes enqueue

Render a provider-safe Hermes Kanban card projection for a task.

Usage:

agentplane hermes enqueue <task-id> [options]

Options:

• --board <slug>: Hermes board slug for the projected card. (default=agentplane)
• --assignee <lane>: Hermes assignee or lane that should own the projected root card. (default=agentplane-supervisor)
• --role <ROLE>: Agentplane role represented by the projected Hermes card. (default=CODER)
• --workspace dir:/abs/repo: Hermes workspace spec. Defaults to the Agentplane repository root.
• --json: Emit machine-readable result. (default=false)

Examples:

agentplane hermes enqueue 202605311941-K4FCKS --board my-repo --json

• Build the card body/metadata a Hermes plugin should create idempotently.

hermes lifecycle

Emit one Hermes Kanban lifecycle callback through the configured Hermes CLI.

This is the Agentplane-side lifecycle client for Hermes worker lanes. It sends comment, block, complete, or heartbeat callbacks through the Hermes CLI and reads task, board, and run identity from the Hermes worker environment.

Usage:

agentplane hermes lifecycle comment|block|complete|heartbeat [options]

Options:

• --body <text>: Callback body, reason, or summary. Heartbeat uses a default body when omitted.
• --json: Emit machine-readable result. (default=false)
• --dry-run: Return the Hermes CLI command without executing it. (default=false)

Examples:

agentplane hermes lifecycle comment --body '{"agentplane_task_id":"202605311941-K4FCKS"}' --json

• Write a structured projection comment for the current Hermes card.

agentplane hermes lifecycle complete --body 'Agentplane terminal evidence validated' --json

• Complete the current Hermes card after Agentplane terminal gates have passed.

hermes reconcile

Inspect Hermes projection drift without mutating Agentplane task truth.

Usage:

agentplane hermes reconcile [options]

Options:

• --task-id <task-id>: Limit reconcile diagnostics to one Agentplane task id.
• --hermes-state <path>: Read a Hermes card/task JSON snapshot and compare it with Agentplane truth.
• --json: Emit machine-readable result. (default=false)

Examples:

agentplane hermes reconcile --task-id 202605311941-K4FCKS --json

• Inspect the local Agentplane side of a Hermes projection.

hermes supervise

Compute the next safe Agentplane route step for a Hermes supervisor run.

Usage:

agentplane hermes supervise <task-id> [options]

Options:

• --json: Emit machine-readable result. (default=false)
• --execute-step: Execute one allowlisted Agentplane route step for this Hermes claim. (default=false)
• --dry-run: With --execute-step, return the planned command without executing it. (default=false)

Examples:

agentplane hermes supervise 202605311941-K4FCKS --json

• Return a route-gated supervisor packet without executing arbitrary shell text.

Platform

platform doctor

Print verification guidance for one platform integration surface.

Usage:

agentplane platform doctor <platform>

platform explain

Explain one platform integration surface.

Usage:

agentplane platform explain <platform>

platform list

List supported platform instruction-surface integrations.

Usage:

agentplane platform list

platform sync

Generate platform-specific instruction files from AgentPlane policy.

Usage:

agentplane platform sync [options]

Options:

• --platform <codex|claude|gemini|opencode|copilot|cursor|windsurf|cline|kiro|openclaw|hermes|all>: Platform to sync. Repeat or pass comma-separated values. Default: all. (repeatable)
• --dry-run: Print planned platform targets without writing files. (default=false)

Examples:

agentplane platform list

• Show supported instruction surfaces.

agentplane platform sync

• Generate all platform projections.

agentplane platform sync --platform cursor --platform cline

• Generate Cursor and Cline rules only.

Workflow

flow repair

Print or apply safe repair steps for task workflow drift.

Usage:

agentplane flow repair <task-id> [options]

Options:

• --dry-run: Print planned repairs without mutating. (default=true)
• --safe-apply: Apply only deterministic safe repairs; approval and provider merge actions are never executed. (default=false)
• --json: Emit JSON. (default=false)

Examples:

agentplane flow repair 202602030608-F1Q8AB --dry-run

• Classify workflow drift and print safe next commands.

agentplane flow repair 202602030608-F1Q8AB --safe-apply

• Apply safe local/lifecycle repairs and print any skipped provider or approval actions.