This page is generated from CLI command specs and runtime error metadata. Do not edit it by hand; edit those sources instead.
The following reference is generated from the runtime error and exit-code metadata.
0— Success: Command completed successfully.1— Internal: Unexpected or unclassified failure.2— Usage: Invalid or incomplete command invocation.3— Validation: Input, schema, or repository invariant validation failed.4— IO: Filesystem or other local IO operation failed.5— Git: Git operation or workflow guardrail failed.6— Backend: Configured task backend failed.7— Network: Explicitly requested network operation failed.8— Runtime: Selected runtime or provider failed.9— Handoff: Task or agent handoff failed.
- Root field:
error. - Required error fields:
code,message. - Optional error fields:
context,state,likely_cause,hint,remediation,next_action,reason_decode. remediationrequired fields:code,why,fix,safe_command,stop_condition.next_actionrequired fields:command,reason; optional fields:reasonCode.reason_decoderequired fields:code,category,summary,action.
Field names and casing are exact. Optional fields are omitted when no value is available.
E_USAGE→ exit2: Command invocation is incomplete or invalid.E_DEPRECATED_FLAG→ exit2: A deprecated or disabled flag was used.E_VALIDATION→ exit3: Input, schema, or repository invariants failed validation.E_IO→ exit4: A filesystem or other local IO operation failed.E_COMMIT_ALLOW_EMPTY→ exit2: A commit path override did not select any paths.E_COMMIT_ALLOW_NO_MATCH→ exit2: A commit path override matched no eligible paths.E_COMMIT_ALLOW_TASK_ARTIFACT_DENIED→ exit2: A commit attempted to include a protected task artifact without authorization.E_PHASE_POLICY→ exit2: The requested lifecycle transition is blocked by policy.E_GIT→ exit5: A Git operation or workflow guardrail failed.E_GIT_LOCKED→ exit5: Git state is locked by another operation.E_GIT_PERMISSION→ exit5: Git could not access a required path or repository resource.E_GIT_RACE→ exit5: Git state changed while the command was executing.E_GIT_STAGE_FAILED→ exit5: Git could not stage the requested paths.E_BACKEND→ exit6: The configured task backend failed.E_NETWORK→ exit7: An explicitly requested network operation failed.E_RUNTIME→ exit8: The selected runtime or provider failed.E_HANDOFF→ exit9: A task or agent handoff failed.E_INTERNAL→ exit1: An unexpected or unclassified AgentPlane failure occurred.
- Core
- Task
- Lifecycle
- Work
- PR
- Branch
- Backend
- Config
- Setup
- Quality
- Diagnostics
- Recipes
- ACR
- Guard
- Hooks
- Policy
- IDE
- Context
- Evaluators
- Evidence
- Integrations
- Platform
- Workflow
List agent definitions under .agentplane/agents.
Usage:
agentplane agents
Examples:
agentplane agents- Print available agent ids and roles.
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.
Show the canonical command surface or help for one command.
Lists the small canonical workflow by default. Use --all for the complete catalog, --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 the complete advanced, framework-dev, and maintenance catalog.
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.
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.
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.
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.
Report dependency readiness details for a task.
Usage:
agentplane ready <task-id>
Examples:
agentplane ready 202602030608-F1Q8AB- Print readiness details.
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.
Return one compact external-agent action from the shared task supervisor state.
Usage:
agentplane task advance <task-id> [options]
Options:
--agent-json: Emit the stable compact external-agent protocol. (default=false)--remote: Include hosted state while preparing the shared supervisor decision. (default=false)--result <path>: Accept one state-bound external-agent result and return the next action.--workflow-recovery <path>: Reconcile an exact interrupted integration with operator evidence; requires --remote and runs no lifecycle operation.--replacement: Explicitly start a distinct exact-key successor after a terminal operation failure. (default=false)
Notes:
- The command prepares the same canonical work order and route decision used by the managed task runner.
- It executes only registered deterministic transitions, then stops before semantic work, approval, human input, external wait, or terminal attention.
- A result is single-use and must match the issued task, transition, role, state fingerprint, work-order id, and result_ref.
- --replacement is valid only after a known terminal operation_failed journal; it never retries the failed effect and cannot be combined with --result.
- --agent-json changes only rendering; any formal transition is journaled, fingerprint-checked, and supervisor-owned.
Examples:
agentplane task advance 202602030608-F1Q8AB --agent-json- Obtain one bounded action without reconstructing lifecycle state.
agentplane task advance 202602030608-F1Q8AB --result <result-ref> --agent-json- Return the typed result through the same persisted supervisor.
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.
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.
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, 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.
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.
Create a task from an outcome and explicit semantic intent.
Validates caller-supplied structured intent. Without it, creates a neutral PLANNER intake boundary without classifying title words.
Usage:
agentplane task create <outcome> [options]
Options:
--plan-file <path>: Read an existing compact v2 or full v1 Plan proposal. This input never grants approval.--description <text>: Additional task context. Defaults to the requested outcome.--owner <id>: Task owner id. (default=CODER)--priority <low|normal|med|high>: Task priority. (choices=low|normal|med|high, default=med)--route <auto|direct|branch_pr>: Execution-route request. auto is conservative and explainable. (choices=auto|direct|branch_pr, default=auto)--task-kind <analysis|content|docs|code|release|ops|context>: Structured task kind supplied by the semantic caller. (choices=analysis|content|docs|code|release|ops|context)--mutation-scope <none|docs|code|release|ops|context|unknown>: Structured mutation scope supplied by the semantic caller. (choices=none|docs|code|release|ops|context|unknown)--risk <risk>: Repeatable structured risk flag supplied by the semantic caller. (repeatable, choices=network|credentials|deploy|publish|merge|security|external_system)--tag <tag>: Repeatable semantic tag supplied by the caller. (repeatable)--verify <command>: Repeatable. Seed an explicit verification command. (repeatable)--scope-root <repository-relative-path>: Repeatable writable root admitted by the execution contract. (repeatable)--repository-effect <effect>: Repeatable repository effect admitted by the execution contract. (repeatable, choices=repository_write|documentation|source_code|tests|public_api|schema|dependencies|ci|release_metadata|security_boundary)--external-effect <effect>: Repeatable external effect declared at intake. (repeatable, choices=network_read|external_write|credentials|publish|deploy|destructive_git)--capability <capability>: Repeatable semantic capability admitted by the execution contract. (repeatable)--resource <resource>: Repeatable resource claim admitted by the execution contract. (repeatable)--base <branch-or-ref>: Freeze this task on an explicit development base. Defaults to the current checkout.--allow-duplicate: Allow an exact duplicate of an open task. (default=false)--json: Emit JSON. (default=false)
Examples:
agentplane task create "Fix the parser edge case" --task-kind code --mutation-scope code --tag code- Create a task with explicit structured semantic intent.
agentplane task create "Describe the outcome" --json- Create a neutral intake task for PLANNER classification.
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.
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.
List active tasks with compact workflow 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.
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.
Approve the current task plan (enforces Verify Steps gating when configured).
Usage:
agentplane task plan approve <task-id> [options]
Options:
--by <id>: Approver id.--approval-receipt <base64url>: Signed user approval receipt from a configured trusted bridge.--host-user-decision <base64url>: Host-originated user decision bound to the current plan and route fingerprint.--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.
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.--scope-expansion-approved-by <role>: Explicit manual approval for an additive canonical WorkItem scope expansion. Requires USER.
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.
Execute one eligible Task Kernel semantic episode with the managed runner.
Usage:
agentplane task run <task-id> [options]
Options:
--dry-run: Inspect the canonical next action without executing the adapter. (default=false)--remote: Include hosted PR/check/review state in the prepared work order. (default=false)--sandbox <read-only|workspace-write|danger-full-access>: Override the role-derived sandbox for this run. (choices=read-only|workspace-write|danger-full-access)--allow-danger-full-access: Explicitly authorize a requested danger-full-access sandbox and record CLI provenance. (default=false)--json: Emit JSON. (default=false)
Notes:
- The command consumes the same Task Kernel WorkOrder as task advance and runs at most one semantic adapter episode per invocation.
- Approval, authority, provider wait, and effect-in-doubt boundaries remain explicit typed stops and never launch an adapter.
- Run the command again to consume the next eligible WorkOrder after the current result has been admitted.
- With the default Codex adapter, the runner prompt starts with `/goal ...` and then includes the AgentPlane bundle contract.
Examples:
agentplane task run 202602030608-F1Q8AB- Execute the task with the configured runner adapter.
agentplane task run 202602030608-F1Q8AB --dry-run --json- Inspect the prepared runner invocation and artifact paths without starting the agent.
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.
Print task metadata and workflow route as JSON.
Usage:
agentplane task show <task-id>
Examples:
agentplane task show 202602030608-F1Q8AB- Show task metadata.
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.
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.
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>: Verification check blocks using optional Check plus Command, Result, Evidence, and Scope fields; Check is required for every selected Verification Contract item.--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.
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>: Verification check blocks using optional Check plus Command, Result, Evidence, and Scope fields; Check is required for every selected Verification Contract item.--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.
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.
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.
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.
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.
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>: Verification check blocks using optional Check plus Command, Result, Evidence, and Scope fields; Check is required for every selected Verification Contract item.--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" --details "Check: full_regression\nCommand: bun run test:fast\nResult: pass\nEvidence: exited 0\nScope: repository test suite" --quiet- Record a committed branch_pr OK outcome with reusable structured evidence.
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 "Command: bun run test:fast. Result: fail. Evidence: one regression failed. Scope: repository test suite."- 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.
Diagnose how to resume a task in the correct checkout/worktree.
Usage:
agentplane work resume <task-id> [options]
Options:
--json: Emit JSON. (default=false)--refresh-planning-base: Inspect recovery of an unstarted worktree to its approved planning snapshot. (default=false)--apply: Apply the explicitly inspected planning-base recovery. (default=false)--expect-token <sha256:digest>: Exact token from planning-base recovery inspection.
Examples:
agentplane work resume 202602030608-F1Q8AB- Find the correct worktree/branch route after interruption.
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).
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.
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)
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)
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)
List branch_pr integration queue entries.
Usage:
agentplane integrate queue list [options]
Options:
--json: Emit JSON. (default=false)
Release, complete, or record a superseded queue entry.
Usage:
agentplane integrate queue release <task-id> [options]
Options:
--status <queued|done|rework|superseded>: Next queue status. (choices=queued|done|rework|superseded, default=queued)--reason <text>: Release reason.--superseded-by <task-id>: Completed successor task required when --status superseded.
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)
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 or GitLab MR 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 provider 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.
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.
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.
Prepare a bounded conflict packet, or explicitly recover a diverged local/provider task head without semantic resolution.
Usage:
agentplane pr conflict-rework <task-id> [options]
Options:
--expect-freshness-token <sha256-token>: Fail closed unless the newly observed conflict packet matches this token.--recover-diverged-head: Archive the exact local head and adopt the exact provider task head after explicit identity checks. (default=false)--expected-local-head <full-sha>: Required with --recover-diverged-head. Exact local task-branch head to archive.--expected-provider-head <full-sha>: Required with --recover-diverged-head. Exact provider task-branch head to adopt.--json: Emit the conflict packet as JSON. (default=false)
Examples:
agentplane pr conflict-rework 202602030608-F1Q8AB --json- Read current provider conflict truth without changing any branch, worktree, PR, or queue state.
agentplane pr conflict-rework 202602030608-F1Q8AB --recover-diverged-head --expected-local-head <sha> --expected-provider-head <sha>- Preserve an unpublished local head before adopting the exact conflicting provider head.
Show branch_pr task branch, hosted change request, 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.
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.
Create PR artifacts for a task and, unless --sync-only is set, publish/link the remote GitHub PR or GitLab MR.
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 or GitLab MR. (default=false)
Examples:
agentplane pr open 202602030608-F1Q8AB --author CODER- Sync local artifacts, publish the task branch if needed, and create/link the GitHub PR or GitLab MR.
Update review artifacts and the linked hosted change request.
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.
Clear the pinned base branch.
Usage:
agentplane branch base clear
Explain current, pinned, and effective base branch resolution.
Usage:
agentplane branch base explain
Print the pinned base branch.
Usage:
agentplane branch base get
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.
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.
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.
Inspect local disk use and worktree cleanup eligibility without deleting files.
Usage:
agentplane cleanup inspect [options]
Options:
--json: Print machine-readable inventory. (default=false)
Examples:
agentplane cleanup inspect- List worktree and nested repository sizes.
agentplane cleanup inspect --json- Export a read-only inventory.
Delete merged task branches/worktrees (branch_pr workflow).
Usage:
agentplane cleanup merged [options]
Options:
--base <name>: Base branch override.--task-id <task-id>: Repeatable. Limit cleanup to explicit task ids. (repeatable)--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 --task-id 202607230554-YFYT83- Inspect cleanup proof for one completed task without touching unrelated branches.
agentplane cleanup merged --task-id 202607230554-YFYT83 --yes- Delete only the proven merged branch/worktree for one completed task.
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.
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.
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.
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)--bootstrap-projection: Explicitly bind a missing cloud checkpoint by pushing the confirmed local cache (requires push + conflict=fail). (default=false)--adopt-projection-identity: Explicitly adopt the active cloud identity and remote projection (requires pull + conflict=prefer-remote). (default=false)--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 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)--bootstrap-projection: Explicitly bind a missing cloud checkpoint by pushing the confirmed local cache (requires push + conflict=fail). (default=false)--adopt-projection-identity: Explicitly adopt the active cloud identity and remote projection (requires pull + conflict=prefer-remote). (default=false)--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.
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).
Print resolved WORKFLOW-backed config JSON.
Usage:
agentplane config show
Examples:
agentplane config show- Show the active WORKFLOW config.
Print workflow mode.
Usage:
agentplane mode get
Examples:
agentplane mode get- Print workflow_mode (direct|branch_pr).
Set workflow mode.
Usage:
agentplane mode set <direct|branch_pr>
Examples:
agentplane mode set branch_pr- Switch to branch_pr mode.
Apply the canonical AgentPlane process policy.
Usage:
agentplane profile set <standard>
Examples:
agentplane profile set standard- Restore the canonical process policy.
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 quick with an advanced choice; --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 <standard>: Compatibility alias for the fixed standard process policy. Legacy values are accepted but no longer change behavior. (choices=standard|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: 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 <standard>: Compatibility alias for the fixed standard execution policy. Legacy values are accepted but ignored. (choices=standard|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>: Deprecated compatibility option. The standard process policy defines fixed unsafe-action boundaries.--recipes <none|id1,id2,...>: Optional cached recipes to vendor during init (comma-separated), or 'none'.--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- Short interactive setup for agent surface and workflow, followed by an explained preview.
agentplane init --yes- Non-interactive setup with the standard process policy.
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 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.
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).
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.
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.
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.
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.
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; canonical task creation remains owned by `agentplane task new`.
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.
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.
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.
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.
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.
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.
Disable an active project overlay for the current project.
Usage:
agentplane recipes disable <recipe-id>
Examples:
agentplane recipes disable tdd- Deactivate an overlay.
Enable an installed project overlay for the current project.
Usage:
agentplane recipes enable <recipe-id>
Examples:
agentplane recipes enable tdd- Activate an installed overlay.
Show detailed info for a vendored recipe.
Usage:
agentplane recipes explain <id>
Examples:
agentplane recipes explain viewer- Show detailed project-local recipe info.
Print the compiled active overlay bundle.
Usage:
agentplane recipes explain-active
Examples:
agentplane recipes explain-active- Inspect compiled overlay runtime data.
Show cached recipe metadata.
Usage:
agentplane recipes info <id>
Examples:
agentplane recipes info viewer- Show cached recipe metadata.
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.
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.
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.
Remove a vendored recipe from the current project.
Usage:
agentplane recipes remove <id>
Examples:
agentplane recipes remove viewer- Remove a vendored recipe by id.
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.
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.
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.
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`.
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.
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.
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.
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.
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.
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.
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/.
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.
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/.
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)
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.
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.
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)
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)
Generate context reports and indexes, rebuild curated projection, validate the graph and task, and run context doctor.
Usage:
agentplane context finalize-task <task-id>
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; older profile names are compatibility aliases and context ingest still creates maximum-assimilation tasks. (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)
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.
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.
Collect completed-task knowledge proposals; select one task to create a CURATOR work order.
Collects source-backed, unpublished knowledge proposals only from explicit durable markers in completed task evidence. An exact single --task selection also creates one CURATOR semantic work order. This command never writes wiki, facts, or graph artifacts 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>: Explicit task id filter. Exactly one id selects that proposal for a CURATOR semantic work order. (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 proposed task id.--limit <n>: Maximum number of oldest matching proposals to collect.--batch-size <n>: Legacy compatibility option. A selected work order always contains one task. (default=25)--batch-bytes <bytes>: Maximum UTF-8 bytes of the selected task source pack. An oversized source remains isolated. (default=131072)--dry-run: Preview candidate proposals without writing records or creating a work order. (default=false)--format <text|json>: Output format. (choices=text|json, default=text)
Examples:
agentplane context learn tasks --tag release --limit 25- Collect source-backed, unpublished proposals from the oldest completed release tasks.
agentplane context learn tasks --task 202605100837-PJZW2E- Select one proposal and create its CURATOR semantic work order.
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)
Resolve a context source reference and print addressed content.
Usage:
agentplane context show <source-ref>
Run resumable CLI-owned post-processing for one CURATOR context result.
Records the already-produced semantic SGR result, then applies, validates, indexes, evaluates, records ACR, and finalizes deterministic context work under one bounded supervisor episode.
Usage:
agentplane context supervise-task <task-id> --extraction <sgr-json> [options]
Options:
--extraction <sgr-json>: CURATOR-produced schema-valid context_extraction SGR file. (required)--smoke-query <query>: Optional retrieval check; defaults to a semantic entity from the SGR.--evaluator <id>: Read-only evaluator module id. (default=recovery-context)--json: Emit machine-readable result. (default=false)
Print a wiki page's Agentplane context frontmatter.
Usage:
agentplane context wiki explain <path-or-slug>
Update generated wiki index sections for pages and subdirectories.
Usage:
agentplane context wiki index [<path>]
Suggest existing wiki pages that may deserve cross-links.
Usage:
agentplane context wiki link <path-or-slug>
Validate wiki page frontmatter and source-link hygiene.
Usage:
agentplane context wiki lint [<path>]
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, workflow, 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)
Generate maximum-assimilation wiki link/orphan reports and required review report pages.
Usage:
agentplane context wiki report [<path>]
Validate and record a typed EVALUATOR result against a frozen work order.
Usage:
agentplane evaluator apply <task-id> [options]
Options:
--work-order <path>: Prepared EvaluatorWorkOrder JSON path.--result <path>: EVALUATOR-produced EvaluatorSgrResult JSON path.--json: Emit machine-readable recorded paths. (default=false)
Run one read-only EVALUATOR provider episode and apply its typed result.
Usage:
agentplane evaluator execute <task-id> [options]
Options:
--evaluator <id>: Evaluator prompt module id to use. (default=recovery-context)--replacement: Explicitly start a new bounded evaluator operation after terminal operation_failed; never reopens the failed operation or effect_in_doubt. (default=false)--json: Emit machine-readable episode and recorded artifact paths. (default=false)
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.
Freeze bounded evidence and build a read-only EVALUATOR work order.
Usage:
agentplane evaluator prepare <task-id> [options]
Options:
--evaluator <id>: Evaluator prompt module id to use. (default=recovery-context)--json: Emit machine-readable work-order paths. (default=false)
Compatibility facade for preparing and recording a structured quality review.
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)--provenance <human_supplied|evaluator_supplied>: Origin of the supplied review values. This command records a result; it does not execute an evaluator. (choices=human_supplied|evaluator_supplied)--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 --provenance human_supplied --verdict human_review --summary "A human decision is required." --finding "Acceptance remains ambiguous." --evidence .agentplane/tasks/202605232011-MAW1PK/README.md- Record an explicitly human-supplied semantic review.
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.
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`.
Deduplicate verified evidence objects without rewriting manifests.
Usage:
agentplane evidence compact [options]
Options:
--apply: Apply the planned local maintenance. Default is dry-run. (default=false)--yes: Confirm an apply operation. Required with --apply. (default=false)--json: Emit machine-readable result. (default=false)
Notes:
- Apply requires a clean repository and refuses corrupt objects or missing references.
Examples:
agentplane evidence compact --json- Preview safe hard-link deduplication.
agentplane evidence compact --apply --yes- Apply the verified plan.
Remove only expired, unreferenced, unpinned evidence objects.
Usage:
agentplane evidence gc [options]
Options:
--apply: Apply the planned local maintenance. Default is dry-run. (default=false)--yes: Confirm an apply operation. Required with --apply. (default=false)--json: Emit machine-readable result. (default=false)
Notes:
- Reachable objects, active-task evidence, current failures, and release evidence are never collectible.
Examples:
agentplane evidence gc --json- Preview collectible objects.
agentplane evidence gc --apply --yes- Apply the verified retention plan.
Inspect tracked evidence and content-addressed object retention.
Usage:
agentplane evidence stats [options]
Options:
--json: Emit machine-readable result. (default=false)
Notes:
- Read-only. Retention defaults come from `.agentplane/evidence-retention.json` when present.
Examples:
agentplane evidence stats --json- Inspect reachability, pins, age, and disk use.
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.
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.
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.
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.
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.
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)--remote: Include hosted PR/check/review state in the supervisor work order. (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.
Print verification guidance for one platform integration surface.
Usage:
agentplane platform doctor <platform>
Explain one platform integration surface.
Usage:
agentplane platform explain <platform>
List supported platform instruction-surface integrations.
Usage:
agentplane platform list
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.
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.
Migrate WORKFLOW.md v1 to v2 with an exact-byte rollback receipt.
Usage:
agentplane workflow migrate [options]
Options:
--dry-run: Print the v2 candidate without changing files. (default=false)--rollback <receipt-path>: Restore exact source bytes from a migration receipt.
Examples:
agentplane workflow migrate --dry-run- Preview the normalized v2 contract without writing files.
agentplane workflow migrate- Apply v1 to v2 with receipt-backed recovery and an active-workflow commit point.
agentplane workflow migrate --rollback .agentplane/workflows/migrations/workflow-v1-to-v2-<digest>.json- Restore the exact pre-migration WORKFLOW.md bytes.