agentplane 0.4.3 → 0.4.4

package/README.md

@@ -32,6 +32,17 @@ npx agentplane quickstart
 
 Requirements: Node.js 20+, Git, and a local terminal.
 
+Experimental agent shorthand:
+
+```bash
+ap next
+ap show <task-id>
+ap vshow <task-id>
+```
+
+`ap` is an agent-optimized entrypoint for compact, non-interactive command use. Keep public docs and
+human-facing setup on `agentplane`; use `ap` only when the installed package exposes it.
+
 ## What you get after `agentplane init`
 
 ```text
@@ -49,20 +60,20 @@ already review.
 ## One task loop
 
 ```bash
-agentplane task new --title "Fix parser edge case" --description "Reject empty labels." --owner CODER --tag code
-agentplane task plan set <task-id> --text "Add a fixture, tighten validation, and run focused tests." --updated-by CODER
-agentplane task plan approve <task-id> --by ORCHESTRATOR
-agentplane task start-ready <task-id> --author CODER --body "Start: implementing parser validation with focused tests."
+agentplane task new --title "Fix parser edge case" --description "Reject empty labels." --owner <agent-id> --tag code
+agentplane task plan set <task-id> --text "Add a fixture, tighten validation, and run focused tests." --updated-by <agent-id>
+agentplane task plan approve <task-id> --by <reviewer-id>
+agentplane task start-ready <task-id> --author <agent-id> --body "Start: implementing parser validation with focused tests."
 # Run Claude Code, Codex, Cursor, Aider, or edit manually.
 agentplane task verify-show <task-id>
-agentplane verify <task-id> --ok --by CODER --note "Focused tests passed."
-agentplane finish <task-id> --author CODER --result "Parser rejects empty labels." --commit <git-rev>
+agentplane verify <task-id> --ok --by <agent-id> --note "Focused tests passed."
+agentplane finish <task-id> --author <agent-id> --result "Parser rejects empty labels." --commit <git-rev>
 ```
 
 The visible output is the point: a reviewer can inspect task intent, plan, verification, and closure
 from Git-visible files.
 
-Roles like `CODER` and `ORCHESTRATOR` are configurable agent IDs. See
+Agent IDs are configurable profiles. See
 [Agents](https://agentplane.org/docs/user/agents).
 
 ## Agent Change Record

package/assets/AGENTS.md

@@ -20,8 +20,8 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 
 - Repository type: user project initialized with `agentplane`.
 - Gateway role: keep this file compact and deterministic; move scenario-specific details to policy modules.
-- CLI rule: use `agentplane` from `PATH`; if unavailable, stop and request installation guidance (do not invent repo-local entrypoints).
-- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. The guarded route is determined by `workflow.mode` in `.agentplane/WORKFLOW.md`; use `agentplane quickstart` as the canonical summary of the active path before mutating. In `branch_pr`, start from `agentplane work start ... --worktree`; in `direct`, stay in the current checkout and use the task lifecycle route.
+- CLI rule: prefer `ap` for compact agent-oriented commands; fall back to `agentplane`; if neither is available, stop and request installation guidance (do not invent repo-local entrypoints).
+- Startup shortcut: run `## COMMANDS -> Preflight`, then use `ap quickstart`; activate `ap role ORCHESTRATOR` for planning and `ap role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. The guarded route is determined by `workflow.mode` in `.agentplane/WORKFLOW.md`; use `ap quickstart` as the canonical summary of the active path before mutating. In `branch_pr`, start from `ap work start ... --worktree`; in `direct`, stay in the current checkout and use the task lifecycle route.
 
 <!-- /ap:fragment -->
 <!-- ap:fragment id="gateway.agents.source_of_truth.sources.of.truth" slot="source_of_truth" mutability="replaceable" -->
@@ -33,7 +33,7 @@ Priority order (highest first):
 1. Enforcement: CI, tests, linters, hooks, CLI validations.
 2. Policy gateway: `AGENTS.md`.
 3. Canonical policy modules from `## CANONICAL DOCS`.
-4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/WORKFLOW.md`.
+4. CLI guidance: `ap quickstart`, `ap role <ROLE>`, `.agentplane/WORKFLOW.md`.
 5. Reference examples from `## REFERENCE EXAMPLES`.
 
 Conflict rule:
@@ -58,9 +58,9 @@ Conflict rule:
 ### Preflight
 
 ```bash
-agentplane config show
-agentplane quickstart
-agentplane task list
+ap config show
+ap quickstart
+ap task list
 git status --short --untracked-files=no
 git rev-parse --abbrev-ref HEAD
 ```
@@ -68,32 +68,32 @@ git rev-parse --abbrev-ref HEAD
 ### Task lifecycle
 
 ```bash
-agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --tag <tag>
-agentplane task plan set <task-id> --text "..." --updated-by <ROLE>
-agentplane task plan approve <task-id> --by ORCHESTRATOR
-agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
-agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..." [--observation "..." --impact "..." --resolution "..."] [--local-only]
-agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
+ap task new --title "..." --description "..." --priority med --owner <ROLE> --tag <tag>
+ap task plan set <task-id> --text "..." --updated-by <ROLE>
+ap task plan approve <task-id> --by ORCHESTRATOR
+ap task start-ready <task-id> --author <ROLE> --body "Start: ..."
+ap verify <task-id> --ok|--rework --by <ROLE> --note "..." [--observation "..." --impact "..." --resolution "..."] [--local-only]
+ap finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
 ### branch_pr lifecycle
 
 ```bash
-agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree
-agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>
-agentplane pr update <task-id>
-agentplane integrate <task-id> --branch task/<task-id>/<slug> --run-verify
-agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
+ap work start <task-id> --agent <ROLE> --slug <slug> --worktree
+ap pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>
+ap pr update <task-id>
+ap integrate <task-id> --branch task/<task-id>/<slug> --run-verify
+ap finish <task-id> --author INTEGRATOR --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
 ```
 
 ### Verification
 
 ```bash
-agentplane task verify-show <task-id>
-agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..." [--observation "..." --impact "..." --resolution "..."] [--local-only]
-agentplane incidents advise <task-id>
-agentplane incidents collect <task-id> --check
-agentplane doctor
+ap vshow <task-id>
+ap verify <task-id> --ok|--rework --by <ROLE> --note "..." [--observation "..." --impact "..." --resolution "..."] [--local-only]
+ap incidents advise <task-id>
+ap incidents collect <task-id> --check
+ap doctor
 node .agentplane/policy/check-routing.mjs
 ```
 
@@ -103,7 +103,7 @@ node .agentplane/policy/check-routing.mjs
 ## TOOLING
 
 - Use `## COMMANDS` as the canonical command source.
-- Use `agentplane quickstart` as the canonical installed startup path and `agentplane role <ROLE>` to activate the current role before role-scoped planning or execution.
+- Use `ap quickstart` as the compact installed startup path and `ap role <ROLE>` to activate the current role before role-scoped planning or execution.
 - For policy changes, routing validation MUST pass via `node .agentplane/policy/check-routing.mjs`.
 
 <!-- /ap:fragment -->
@@ -138,7 +138,7 @@ Condition: task includes mutation (file edits, task-state changes, commits, merg
 1. IF `workflow.mode=direct` THEN LOAD `@.agentplane/policy/workflow.direct.md`.
 2. IF `workflow.mode=branch_pr` THEN LOAD `@.agentplane/policy/workflow.branch_pr.md`.
 3. IF task touches release/version/publish THEN LOAD `@.agentplane/policy/workflow.release.md`.
-4. IF task runs `agentplane upgrade` or touches `.agentplane/.upgrade/**` THEN LOAD `@.agentplane/policy/workflow.upgrade.md`.
+4. IF task runs CLI upgrade or touches `.agentplane/.upgrade/**` THEN LOAD `@.agentplane/policy/workflow.upgrade.md`.
 5. IF task modifies implementation code paths THEN LOAD `@.agentplane/policy/dod.code.md`.
 6. IF task modifies docs/policy-only paths (`AGENTS.md`, docs, `.agentplane/policy/**`) THEN LOAD `@.agentplane/policy/dod.docs.md`.
 7. IF task modifies policy files (`AGENTS.md` or `.agentplane/policy/**`) THEN LOAD `@.agentplane/policy/governance.md`.
@@ -161,9 +161,9 @@ Routing constraints:
 - MUST start with ORCHESTRATOR preflight and plan summary.
 - MUST NOT perform mutating actions before explicit user approval.
 - MUST create/reuse executable task IDs for any repo-state mutation.
-- MUST use `agentplane` commands for task lifecycle updates; MUST NOT manually edit `.agentplane/tasks.json`.
-- MUST run `agentplane task plan approve ...` and `agentplane task start-ready ...` sequentially (never in parallel).
-- MUST activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active task owner before owner-scoped execution or verification.
+- MUST use `ap`/`agentplane` commands for task lifecycle updates; MUST NOT manually edit `.agentplane/tasks.json`.
+- MUST run `ap task plan approve ...` and `ap task start-ready ...` sequentially (never in parallel).
+- MUST activate `ap role ORCHESTRATOR` for planning and `ap role <ROLE>` for the active task owner before owner-scoped execution or verification.
 - MUST keep repository artifacts in English by default (unless user explicitly requests another language for a specific artifact).
 - MUST NOT fabricate repository facts.
 - MUST stage/commit only intentional changes for the active task scope.

package/assets/RUNNER.md

@@ -6,9 +6,9 @@ Operate as the agentplane execution runner.
 
 - Treat `bundle.json` as the authoritative input contract.
 - This invocation already passed repository preflight, plan approval, and task start lifecycle gates.
-- Do not run repository startup commands such as `agentplane config show`, `agentplane quickstart`, `agentplane task list`, `git status`, or `git rev-parse` unless the bundle explicitly requires them as task work.
+- Do not run repository startup commands such as `ap config show`, `ap quickstart`, `ap task list`, `git status`, or `git rev-parse` unless the bundle explicitly requires them as task work.
 - Do not create, approve, start, verify, finish, block, or rerun tasks unless the bundle explicitly requires task-metadata edits as part of the requested work.
-- Do not recursively invoke `agentplane task run` or any internal recipe-task materialization entrypoint from inside the runner.
+- Do not recursively invoke `ap task run` or any internal recipe-task materialization entrypoint from inside the runner.
 - Apply prompt blocks in ascending `priority` order.
 - Framework and repository policy blocks override owner, task, and recipe context.
 - Do not reconstruct missing context from CLI argv.

package/assets/agents/CODER.json

@@ -13,13 +13,13 @@
   },
   "permissions": {
     "project.files": "Project files: read + write within the active task scope.",
-    "git.local": "git: inspection/local ops; commits via agentplane.",
+    "git.local": "git: inspection/local ops; commits via `ap`.",
     "terminal.checks": "Terminal commands (tests/linters): run and summarize locally."
   },
   "workflow": {
     "goal": "Goal: implement the approved task with the smallest coherent diff and explicit verification evidence.",
     "success.criteria": "Success criteria: approved scope is satisfied; existing patterns are reused; the diff is surgical; declared Verify Steps are run and recorded; task README findings are updated when needed; no unintended tracked changes remain.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for lifecycle updates; inspect before editing; avoid scope widening, speculative features, new abstractions, and impossible-scenario handling; coordinate handoffs only when executable tasks already exist; in branch_pr keep commits task-scoped and leave closure to INTEGRATOR.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for lifecycle updates; inspect before editing; avoid scope widening, speculative features, new abstractions, and impossible-scenario handling; coordinate handoffs only when executable tasks already exist; in branch_pr keep commits task-scoped and leave closure to INTEGRATOR.",
     "stop.rules": "Stop rules: stop and route drift when root cause or blast radius expands materially, security/auth/crypto scope appears, acceptance criteria or Verify Steps need to change, repository state is unsafe, or validation is impossible in the current scope.",
     "output": "Output: changed files with concise rationale, checks run with key evidence, task README or Findings updates, blockers, drift, and residual risk."
   }

package/assets/agents/CREATOR.json

@@ -13,12 +13,12 @@
   },
   "permissions": {
     "agent.prompt.files": "AGENTS.md and .agentplane/agents: read + write within approved prompt-policy scope.",
-    "git.local": "git: inspection/local ops; commits via agentplane."
+    "git.local": "git: inspection/local ops; commits via `ap`."
   },
   "workflow": {
     "goal": "Goal: create or revise a specialist agent only when the existing role set has a concrete, repeated capability gap.",
     "success.criteria": "Success criteria: existing roles and smaller prompt changes are checked; the new boundary is non-overlapping; JSON is minimal and valid; registry or gateway guidance changes are only included when routing requires them; validation evidence is recorded.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for lifecycle updates; prefer a smaller change to an existing role when it satisfies the need; keep role IDs uppercase snake case; avoid speculative agents for hypothetical future flexibility.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for lifecycle updates; prefer a smaller change to an existing role when it satisfies the need; keep role IDs uppercase snake case; avoid speculative agents for hypothetical future flexibility.",
     "stop.rules": "Stop rules: stop when an existing role can cover the work, the proposed boundary overlaps another agent, evidence for the gap is weak, or the new profile would dilute approval, security, or workflow gates.",
     "output": "Output: capability gap evidence, selected role boundary, files changed, validation checks, and any residual calibration risk."
   }

package/assets/agents/DOCS.json

@@ -12,13 +12,13 @@
     "doc.mapping": "A concise mapping from each task ID to docs touched and remaining documentation gaps."
   },
   "permissions": {
-    "docs.files": "Documentation files: read + write within approved scope; task docs via agentplane.",
-    "git.local": "git: inspection/local ops; commits via agentplane."
+    "docs.files": "Documentation files: read + write within approved scope; task docs via `ap`.",
+    "git.local": "git: inspection/local ops; commits via `ap`."
   },
   "workflow": {
     "goal": "Goal: document shipped behavior only, with claims grounded in code, help output, tests, or recorded verification evidence.",
     "success.criteria": "Success criteria: behavior is confirmed before prose changes; canonical docs are updated instead of generated mirrors; caveats and deferred work are separated from facts; task artifacts remain aligned with the active doc contract.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for task documentation updates; keep edits surgical and scoped to the changed behavior; update generation sources instead of downstream generated files.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for task documentation updates; keep edits surgical and scoped to the changed behavior; update generation sources instead of downstream generated files.",
     "stop.rules": "Stop rules: stop when evidence is absent, behavior is ambiguous, docs would claim unshipped behavior, or the only available target is a generated mirror with no approved source update path.",
     "output": "Output: docs and task artifacts touched, evidence used for each behavior claim, caveats, blockers, and remaining documentation gaps."
   }

package/assets/agents/EVALUATOR.json

@@ -14,7 +14,7 @@
   },
   "permissions": {
     "review.artifacts": "Read task documentation, runner artifacts, diffs, reports, and eval outputs.",
-    "task.verification": "Record verification or rework through `agentplane` when the active workflow authorizes evaluator-scoped updates."
+    "task.verification": "Record verification or rework through `ap` when the active workflow authorizes evaluator-scoped updates."
   },
   "workflow": {
     "goal": "Goal: decide whether the latest task or eval attempt satisfies the documented quality contract without relying on the runner's self-claim alone.",

package/assets/agents/INTEGRATOR.json

@@ -1,7 +1,7 @@
 {
   "id": "INTEGRATOR",
   "role": "Integrate validated task work into the base branch and perform deterministic closure in branch_pr.",
-  "description": "Acts as the final state transition gate for branch_pr by checking preconditions, running integration verification, merging, and closing tasks via agentplane.",
+  "description": "Acts as the final state transition gate for branch_pr by checking preconditions, running integration verification, merging, and closing tasks via `ap`.",
   "inputs": {
     "task.branch": "Task ID, task branch, and PR artifact metadata under .agentplane/tasks/<task-id>/pr/.",
     "verification.evidence": "Review notes, verification expectations, CI status, and owner handoff context."
@@ -12,13 +12,13 @@
     "closure.trace": "Closure metadata that records merged commit, verification evidence, and task status."
   },
   "permissions": {
-    "git.integration": "git: merge task branches into the base branch via agentplane.",
+    "git.integration": "git: merge task branches into the base branch via `ap`.",
     "task.artifacts": ".agentplane/tasks: update PR artifacts and task docs as tracked files."
   },
   "workflow": {
     "goal": "Goal: integrate validated task work into the configured base branch and close branch_pr tasks through deterministic AgentPlane state transitions.",
     "success.criteria": "Success criteria: base and task branch preconditions are confirmed; PR artifacts are fresh; required checks and Verify Steps evidence are present; merged commit and closure traceability are recorded; no unrelated base changes are introduced.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` integration and finish commands; operate from the configured base branch; keep writes limited to merge output, required verification artifacts, and deterministic closure updates.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` integration and finish commands; operate from the configured base branch; keep writes limited to merge output, required verification artifacts, and deterministic closure updates.",
     "stop.rules": "Stop rules: stop on dirty base state, stale PR artifacts, missing verification evidence, branch/task mismatch, unresolved required checks, or closure approval requirements that are not satisfied.",
     "output": "Output: merge or close references, checks reviewed, task status changes, closure commit details, and remaining cleanup or blocker notes."
   }

package/assets/agents/ORCHESTRATOR.json

@@ -12,12 +12,12 @@
     "progress.summary": "Progress summaries after each major step, including affected task IDs and re-approval triggers when relevant."
   },
   "permissions": {
-    "coordination": "Coordinate agents and follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output."
+    "coordination": "Coordinate agents and follow shared workflow rules in AGENTS.md and `ap quickstart` / `ap role <ROLE>` output."
   },
   "workflow": {
     "goal": "Goal: turn the user request into an approved executable plan without mutating repository state before approval.",
     "success.criteria": "Success criteria: config, quickstart, and active role guidance are loaded; user goal, assumptions, constraints, and re-approval triggers are stated; the plan uses the smallest sufficient role set; task creation waits for approval; post-approval task IDs are traceable.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` config commands for config changes; route task graph creation to PLANNER after approval; use UPDATER only for explicit agent optimization; request recipe index refresh only when recipes are in approved scope; do not perform owner-scoped implementation or verification once an owner is known.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` config commands for config changes; route task graph creation to PLANNER after approval; use UPDATER only for explicit agent optimization; request recipe index refresh only when recipes are in approved scope; do not perform owner-scoped implementation or verification once an owner is known.",
     "stop.rules": "Stop rules: ask one narrow question only when execution would otherwise be guesswork; request re-approval when scope, risk, constraints, workflow route, network, or irreversible action materially changes; stop on missing approval or missing executable owner boundary.",
     "output": "Output: numbered plan, approval prompt, assumptions, constraints, re-approval triggers, task IDs after approval, progress at major steps, and final summary with commit/task references."
   }

package/assets/agents/PLANNER.json

@@ -12,12 +12,12 @@
     "structured.reply": "A structured reply listing every touched task ID, its new status, rationale, and any deferred follow-up work."
   },
   "permissions": {
-    "task.management": "Manage tasks via agentplane and follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output."
+    "task.management": "Manage tasks via `ap` and follow shared workflow rules in AGENTS.md and `ap quickstart` / `ap role <ROLE>` output."
   },
   "workflow": {
     "goal": "Goal: map an approved objective to the smallest valid executable task graph by recursively decomposing composite nodes until every executable leaf is atomic.",
     "success.criteria": "Success criteria: no duplicate open task exists; every unresolved draft node is classified as atomic, composite, ambiguous, or capability_gap; composite nodes are split until leaves have one owner, a real deliverable boundary, explicit depends_on, valid title/description/tags, and concrete Verify Steps; bookkeeping-only work stays inside the executable leaf.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; create/update tasks via `agentplane`; prefer one task when one work item satisfies the goal; do not over-split into microtasks when one owner and one verification boundary are enough; assign existing agent IDs or schedule CREATOR only for a real capability gap; keep observations in task-local Notes/Findings.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; create/update tasks via `ap`; prefer one task when one work item satisfies the goal; do not over-split into microtasks when one owner and one verification boundary are enough; assign existing agent IDs or schedule CREATOR only for a real capability gap; keep observations in task-local Notes/Findings.",
     "stop.rules": "Stop rules: ask one narrow question only when the task graph would otherwise be invalid; stop on missing approval, unresolved owner/dependency boundaries, unsafe scope drift, cyclic or duplicate dependency edges, or acceptance criteria that cannot be made concrete.",
     "output": "Output: task IDs, owners, status, dependency edges, Verify Steps, rationale for recursive split/merge decisions, atomicity notes for each leaf, and deferred follow-up work."
   }

package/assets/agents/REDMINE.json

@@ -18,7 +18,7 @@
   },
   "workflow": {
     "goal": "Goal: update task state or docs through the Redmine-backed AgentPlane path without overwriting fresher backend data.",
-    "success.criteria": "Success criteria: backend freshness and sync direction are explicit; task updates go through `agentplane`; assignee and configured custom field IDs are preserved; push or pull evidence is recorded when sync occurs.",
+    "success.criteria": "Success criteria: backend freshness and sync direction are explicit; task updates go through `ap`; assignee and configured custom field IDs are preserved; push or pull evidence is recorded when sync occurs.",
     "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane sync redmine` for backend synchronization; avoid direct Redmine API calls; keep sync and edits minimal.",
     "stop.rules": "Stop rules: stop when cache freshness is unknown, sync could overwrite fresher remote data, backend access is unavailable, required field mapping is unclear, or network approval is missing.",
     "output": "Output: task IDs, fields or docs changed, sync command and evidence, blockers, drift, and handoff notes for affected owners."

package/assets/agents/REVIEWER.json

@@ -12,12 +12,12 @@
     "followup.gaps": "Suggested follow-up tasks or checks when gaps remain."
   },
   "permissions": {
-    "review.artifacts": "Review workspace artifacts and PR docs; task context via agentplane."
+    "review.artifacts": "Review workspace artifacts and PR docs; task context via `ap`."
   },
   "workflow": {
     "goal": "Goal: provide an independent risk and defect assessment against approved scope and recorded verification evidence.",
     "success.criteria": "Success criteria: approved scope, changed behavior, diff, PR artifacts, and Verify Steps are reviewed; confirmed defects come first, plausible risks second, open questions third; file/line references and recommendation are exact.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for handoff notes when review state changes; focus on regressions, hidden scope expansion, lifecycle drift, missing evidence, and unnecessary complexity that affects the approved task; label uncertainty explicitly; do not integrate or finish tasks.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for handoff notes when review state changes; focus on regressions, hidden scope expansion, lifecycle drift, missing evidence, and unnecessary complexity that affects the approved task; label uncertainty explicitly; do not integrate or finish tasks.",
     "stop.rules": "Stop rules: stop or mark review blocked on insufficient diff, missing Verify Steps, missing evidence, scope mismatch, stale PR artifacts, or repository state that makes the review non-reproducible.",
     "output": "Output: severity-ordered findings, exact references, tests/evidence reviewed, recommendation per task, and open questions that could change the decision."
   }

package/assets/agents/SKILL_EXTRACTOR.json

@@ -14,12 +14,12 @@
   "permissions": {
     "evidence.read": "Workspace repository: read targeted task READMEs, incidents, docs/developer/incident-archive.mdx, skills, and referenced git diffs.",
     "skills.write": "Workspace repository: write only skills/**, skills/README.md, and the active task README when recording findings or verification evidence.",
-    "git.local": "git: inspection/local ops; commits via agentplane."
+    "git.local": "git: inspection/local ops; commits via `ap`."
   },
   "workflow": {
     "goal": "Goal: extract or update a repo-local skill only when repeated evidence shows a reusable remediation pattern.",
     "success.criteria": "Success criteria: completed tasks, incidents, and commits support the pattern; existing skills are checked for overlap; the skill is scenario-driven and self-contained; validation commands and failure modes are included; inventory provenance is updated.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for task documentation; prefer no skill over speculative abstraction; keep writes inside skills, skills/README.md, and active task docs.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for task documentation; prefer no skill over speculative abstraction; keep writes inside skills, skills/README.md, and active task docs.",
     "stop.rules": "Stop rules: stop when evidence is one-off or weak, an existing skill already covers the scenario, required provenance cannot be verified, or the proposed skill would encode vague style advice instead of repeatable procedure.",
     "output": "Output: recommendation, evidence set, skill files or inventory changes, validation checks, and residual maturity gaps."
   }

package/assets/agents/TESTER.json

@@ -14,12 +14,12 @@
   },
   "permissions": {
     "project.test.files": "Project files: read + write for tests and minimal supporting code.",
-    "git.local": "git: inspection/local ops; commits via agentplane."
+    "git.local": "git: inspection/local ops; commits via `ap`."
   },
   "workflow": {
     "goal": "Goal: prove or falsify changed behavior with the smallest high-value verification surface.",
     "success.criteria": "Success criteria: behavior under test and regression surface are identified; existing tooling is reused; targeted checks run first; tests are deterministic; results map to Verify Steps; residual gaps are recorded task-locally.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for verification updates; avoid new test frameworks unless requested; avoid network calls and time-based flakiness; do not encode guesses when expected behavior is ambiguous.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for verification updates; avoid new test frameworks unless requested; avoid network calls and time-based flakiness; do not encode guesses when expected behavior is ambiguous.",
     "stop.rules": "Stop rules: stop on ambiguous expected behavior, missing or broken test infrastructure that is an independent deliverable, Verify Steps drift, or flakiness that would make evidence misleading.",
     "output": "Output: tested behavior, commands and key results, tests added or reused, Verify Steps mapping, blockers, residual gaps, and confidence level."
   }

package/assets/agents/UPDATER.json

@@ -17,7 +17,7 @@
   "workflow": {
     "goal": "Goal: audit existing agents and propose evidence-backed optimization only when the user explicitly requests agent optimization.",
     "success.criteria": "Success criteria: explicit invocation is confirmed; current gateway, agent profiles, and relevant task evidence are reviewed; issues are categorized by correctness, ambiguity, friction, or overlap; recommendations are minimal and validation-oriented.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` only for task context and read-only inspection unless a separate implementation task is approved; cite exact files and avoid broad prompt rewrites without evidence.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` only for task context and read-only inspection unless a separate implementation task is approved; cite exact files and avoid broad prompt rewrites without evidence.",
     "stop.rules": "Stop rules: stop when UPDATER was not explicitly invoked, current prompt sources are insufficient, evidence does not support a change, or the recommendation would require unapproved mutation.",
     "output": "Output: prioritized findings, affected files, proposed smallest changes, validation commands, assumptions, and open questions that could change the recommendation."
   }

package/assets/agents/UPGRADER.json

@@ -1,6 +1,6 @@
 {
   "id": "UPGRADER",
-  "role": "Review and finalize framework upgrades after `agentplane upgrade` without reintroducing stale local drift.",
+  "role": "Review and finalize framework upgrades after `ap upgrade` without reintroducing stale local drift.",
   "description": "Validates replace-first upgrade results, ensures policy and prompt consistency, and preserves only sanctioned local history such as append-only incidents.",
   "inputs": {
     "upgrade.run": "Upgrade run directory containing plan, constraints, report artifacts, and review.json when available.",
@@ -14,13 +14,13 @@
   },
   "permissions": {
     "managed.prompts": "Project files: read/write access to approved managed prompt and policy surfaces.",
-    "git.local": "git: inspect status and create commits via agentplane commit or PR artifacts in branch_pr.",
+    "git.local": "git: inspect status and create commits via `ap commit` or PR artifacts in branch_pr.",
     "terminal.checks": "Terminal: run local checks for changed areas and summarize evidence."
   },
   "workflow": {
     "goal": "Goal: review and finalize framework upgrade outputs without reintroducing stale local drift or contradictions with current enforcement.",
     "success.criteria": "Success criteria: upgrade run artifacts are loaded; changed files are inspected before editing; managed files are reconciled with gateway priority; append-only incident history is preserved; checks appropriate to touched surfaces are recorded.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for lifecycle and commits; treat managed files as replace-first upgrade outputs; avoid speculative prompt rewrites beyond the upgrade contract.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for lifecycle and commits; treat managed files as replace-first upgrade outputs; avoid speculative prompt rewrites beyond the upgrade contract.",
     "stop.rules": "Stop rules: stop when run artifacts are missing, upgrade output conflicts with enforcement, generated artifacts disagree with source state, repository state is unsafe, or required verification cannot be run.",
     "output": "Output: upgraded files reviewed, conflicts found, decisions taken, checks run, runDir reference, and remaining follow-up tasks."
   }

package/assets/codex-plugin/skills/agentplane/SKILL.md

@@ -15,21 +15,21 @@ Use AgentPlane through its CLI instead of editing `.agentplane/` state directly.
 
 ## Startup
 
-1. If the repository is not initialized, run `agentplane init`.
-2. Run `agentplane quickstart`.
-3. Inspect `AGENTS.md`, `agentplane task list`, `git status --short --untracked-files=no`, and `git rev-parse --abbrev-ref HEAD`.
-4. Use `agentplane role ORCHESTRATOR` while planning and approvals are active.
-5. Switch to `agentplane role <ROLE>` before owner-scoped execution or verification.
+1. If the repository is not initialized, run `ap init` or `agentplane init`.
+2. Run `ap quickstart`.
+3. Inspect `AGENTS.md`, `ap task list`, `git status --short --untracked-files=no`, and `git rev-parse --abbrev-ref HEAD`.
+4. Use `ap role ORCHESTRATOR` while planning and approvals are active.
+5. Switch to `ap role <ROLE>` before owner-scoped execution or verification.
 
 ## Rules
 
-- Treat `AGENTS.md`, `agentplane quickstart`, and `agentplane role <ROLE>` as the policy surface.
-- Use `agentplane task ...`, `agentplane work ...`, `agentplane verify ...`, and `agentplane finish ...`; do not edit `.agentplane/tasks.json` manually.
-- In `branch_pr`, start from `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`.
+- Treat `AGENTS.md`, `ap quickstart`, and `ap role <ROLE>` as the policy surface.
+- Use `ap task ...`, `ap work ...`, `ap verify ...`, and `ap finish ...`; do not edit `.agentplane/tasks.json` manually.
+- In `branch_pr`, start from `ap work start <task-id> --agent <ROLE> --slug <slug> --worktree`.
 - Keep repository artifacts in English unless the user explicitly requests another language for a specific artifact.
-- Record verification evidence in the task README and through `agentplane verify`.
+- Record verification evidence in the task README and through `ap verify`.
 
 ## Limits
 
-- This plugin bundles workflow guidance only. It does not install the `agentplane` binary for you.
-- If `agentplane` is missing from `PATH`, install it first, then use the workflow commands above.
+- This plugin bundles workflow guidance only. It does not install the `ap`/`agentplane` binary for you.
+- If both `ap` and `agentplane` are missing from `PATH`, install AgentPlane first, then use the workflow commands above.

package/assets/policy/check-routing.mjs

@@ -34,6 +34,46 @@ function assertFilesExist(repoRoot, paths, label, errors) {
   }
 }
 
+function remediationForRoutingError(error) {
+  if (error.includes("exceeds policy budget")) {
+    return {
+      code: "POLICY_ROUTING_BUDGET",
+      why: "Large gateway or policy modules make agent startup context harder to route deterministically.",
+      fix: "Move scenario-specific detail into the correct canonical module or shorten duplicate rule text.",
+      safeCommand: "node .agentplane/policy/check-routing.mjs",
+      stopCondition:
+        "Stop if the size reduction would remove a hard constraint or source-of-truth rule.",
+    };
+  }
+  if (error.includes("path does not exist") || error.includes("Missing canonical")) {
+    return {
+      code: "POLICY_ROUTING_MISSING_PATH",
+      why: "AGENTS.md references a policy file that agents cannot load.",
+      fix: "Restore the referenced file or update the gateway reference to the canonical existing path.",
+      safeCommand: "agentplane doctor",
+      stopCondition: "Stop if the missing file is a policy module deleted by another active task.",
+    };
+  }
+  return {
+    code: "POLICY_ROUTING_FAILED",
+    why: "The policy gateway no longer matches the deterministic load-rule contract.",
+    fix: "Repair AGENTS.md load rules, canonical docs, examples, or policy module layout.",
+    safeCommand: "node .agentplane/policy/check-routing.mjs",
+    stopCondition: "Stop if the repair changes workflow mode, approval gates, or policy ownership.",
+  };
+}
+
+function renderRemediation(error) {
+  const r = remediationForRoutingError(error);
+  return [
+    `  Code: ${r.code}`,
+    `  Why: ${r.why}`,
+    `  Fix: ${r.fix}`,
+    `  Safe command: ${r.safeCommand}`,
+    `  Stop condition: ${r.stopCondition}`,
+  ].join("\n");
+}
+
 function listFilesRecursive(dirPath, relPrefix = "") {
   if (!fs.existsSync(dirPath)) return [];
   const entries = fs.readdirSync(dirPath).toSorted((a, b) => a.localeCompare(b));
@@ -171,7 +211,11 @@ function main() {
   }
 
   if (errors.length > 0) {
-    throw new Error(`Policy routing check failed:\n- ${errors.join("\n- ")}`);
+    throw new Error(
+      `Policy routing check failed:\n${errors
+        .map((error) => `- ${error}\n${renderRemediation(error)}`)
+        .join("\n")}`,
+    );
   }
 
   process.stdout.write("policy routing OK\n");

package/assets/policy/incidents.md

@@ -15,3 +15,4 @@
 - id: INC-20260503-01 | date: 2026-05-03 | scope: Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. | tags: code, release, workflow | match: code, release, workflow, port, the, artifacts, language, configuration, and, artifact, validation, from, stale, cli, branch, onto | failure: Ported artifacts_language=en and PR artifact language validation onto current main; stale trust branch was not merged because it would reintroduce old task states. | advice: No rework required before PR. | rule: Analogous Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605030733-BHD4S4; commit c66cff3d6f16 | enforcement: manual | fixability: external | state: open
 - id: INC-20260503-02 | date: 2026-05-03 | scope: Update standalone release artifact smoke testing to accept the current doctor OK output and surface doctor output on failures so v0.4.2 publish can complete. | tags: code, release, testing | match: code, release, testing, update, standalone, artifact, smoke, accept, the, current, doctor, output, and, surface, failures, publish | failure: Publish run 25273723107 failed before npm/tag at standalone linux-x64 doctor smoke because the script expected 'doctor OK' but current CLI emits 'doctor (OK)'. | advice: Smoke now accepts both legacy and current doctor OK markers and includes doctor output on failure. | rule: Analogous Update standalone release artifact smoke testing to accept the current doctor OK output and surface doctor output on failures so v0.4.2 publish can complete. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605030807-DBY2RS; commit 2c98719336c8 | enforcement: manual | fixability: external | state: open
 - id: INC-20260503-03 | date: 2026-05-03 | scope: Split AgentPlane default sign-off identity from repo-wide manual DCO validation and make .agentplane/tasks.json an optional generated export snapshot rather than tracked required state. | tags: code, git, tasks | match: code, git, tasks, split, agentplane, default, sign, off, identity, from, repo, wide, manual, dco, validation, and | failure: Full hook-run suite was not used as final evidence because an unrelated existing pre-push scenario still tries to git add .agentplane/config.json after the WORKFLOW-only migration. | advice: Focused checks pass; remaining doctor warning is outside this task scope. | rule: Analogous Split AgentPlane default sign-off identity from repo-wide manual DCO validation and make .agentplane/tasks.json an optional generated export snapshot rather than tracked required state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605031737-9A4FWX; commit eda55d00831b | enforcement: manual | fixability: external | state: open
+- id: INC-20260504-01 | date: 2026-05-04 | scope: Introduce a shared agent-facing remediation contract for diagnostic failures and apply it to high-value doctor, workflow, ACR, and policy routing surfaces. | tags: code | match: code, introduce, shared, agent, facing, remediation, contract, for, diagnostic, failures, and, apply, high, value, doctor, workflow | failure: Commands passed: focused bun tests for workflow/ACR/policy routing plus targeted stale-dist workspace dependency test; bun run typecheck; Prettier check on touched files; ESLint on touched files; bun run arch:check; git diff --check; bun run framework:dev:bootstrap; agentplane doctor; node .agentplane/policy/check-routing.mjs. | advice: No mandatory check remains skipped. The full stale-dist-readonly file still contains an unrelated pre-existing auto-bootstrap timeout when run under this ad hoc focused bundle; the new workspace dependency test passes independently. | rule: Analogous Introduce a shared agent-facing remediation contract for diagnostic failures and apply it to high-value doctor, workflow, ACR, and policy routing surfaces. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605041849-WF1Q77; commit cc2c971ed53e | enforcement: manual | fixability: external | state: open

package/bin/agentplane.js

@@ -297,7 +297,7 @@ function missingRepoRuntimeDependencies(agentplaneRoot) {
   const requiredSpecifiers = ["@agentplaneorg/core"];
   return requiredSpecifiers.filter((specifier) => {
     try {
-      const resolved = requireFromAgentplane.resolve(specifier);
+      const resolved = requireFromAgentplane.resolve(`${specifier}/package.json`);
       if (isPathInside(frameworkRoot, resolved)) return false;
       return !existsSync(path.join(agentplaneRoot, "node_modules", ...specifier.split("/")));
     } catch {
@@ -332,6 +332,11 @@ async function assertDistUpToDate() {
   if (missingDeps.length > 0) {
     process.stderr.write(
       "error: repo-local runtime dependencies are missing for this framework checkout.\n" +
+        "Code: FRAMEWORK_RUNTIME_DEPENDENCY_MISSING\n" +
+        "Why: the repo-local CLI cannot resolve its workspace runtime packages from this checkout.\n" +
+        "Fix: restore the framework install layout, then rebuild the repo-local packages.\n" +
+        `Safe command: ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n` +
+        "Stop condition: stop if the missing package resolves outside this repository or bun install would need unapproved network access.\n" +
         "This worktree is not bootstrapped yet.\n" +
         "Missing module resolution:\n" +
         missingDeps.map((specifier) => `  ${specifier}\n`).join("") +

package/bin/ap.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+process.env.AGENTPLANE_CLI_ALIAS = "ap";
+process.env.AGENTPLANE_AGENT_MODE = "1";
+process.env.AGENTPLANE_PROMPTS ??= "plain";
+process.env.AGENTPLANE_NO_UPDATE_CHECK ??= "1";
+
+await import("./agentplane.js");

package/bin/runtime-watch.js

@@ -5,6 +5,7 @@ import path from "node:path";
 const WATCHED_RUNTIME_PATHS = {
   agentplane: [
     "src",
+    "bin/ap.js",
     "bin/agentplane.js",
     "bin/dist-guard.js",
     "bin/runtime-context.js",

package/dist/.build-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "manifest_kind": "package",
   "package_name": "agentplane",
-  "package_version": "0.4.3",
-  "git_head": "04ccc002125560cd2ec87094e20cd5a9907d2016",
-  "watched_runtime_snapshot_hash": "5a534e101008bc57436f81a2364408cd0c5368241c43b43a4a814875fa750f68"
+  "package_version": "0.4.4",
+  "git_head": "dfe70bf54c4612e25ccac8aea363a744b4bed245",
+  "watched_runtime_snapshot_hash": "1a9fc1a9c09926b82cd9510670d6fea8600c41462b2ba9efec04965a879a5fcc"
 }