agentplane 0.3.29 → 0.4.1

package/README.md

@@ -1,74 +1,34 @@
-# agentplane
+# AgentPlane
 
 [![npm](https://img.shields.io/npm/v/agentplane.svg)](https://www.npmjs.com/package/agentplane)
 [![Downloads](https://img.shields.io/npm/dm/agentplane.svg)](https://www.npmjs.com/package/agentplane)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/basilisk-labs/agentplane/blob/main/LICENSE)
 [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-3c873a.svg)](https://agentplane.org/docs/user/prerequisites)
 
-**Git-native control plane for auditable agent work.**
+**Use coding agents without losing Git discipline.**
 
-Put coding agents on a governed Git workflow.
-
-`agentplane` is the CLI for AgentPlane. It runs locally inside a git repository, not in a hosted runtime, and adds visible workflow artifacts such as `AGENTS.md` or `CLAUDE.md`, `.agentplane/`, task records, verification state, and deterministic closure. Teams use it when they want agent work to stay explicit, inspectable, and governed inside the repository instead of behaving like an opaque assistant.
-
-## What agentplane is
-
-`agentplane` is a repo-native CLI workflow for agent-driven development.
-
-- It runs in your repository and keeps workflow state local.
-- It adds approvals, task state, verification, and finish to agent work.
-- It supports both `direct` and `branch_pr` workflow modes.
-- It keeps repository artifacts visible instead of hiding execution behind a hosted control plane.
-
-## Why teams use it
-
-Teams use `agentplane` when changing files is not enough and they need the work itself to stay legible.
-
-- **Trust comes from visible process.** Plans, verification, and finish are recorded instead of implied.
-- **The workflow stays local.** There is no hosted control plane between your repository and your team.
-- **Git remains first-class.** `agentplane` governs agent work inside commits and repository state instead of bypassing them.
-- **The same CLI fits different review styles.** Use `direct` for short loops or `branch_pr` for stricter integration.
-
-## What appears in your repository
-
-`agentplane init` creates a visible workflow surface inside the repository.
+`agentplane` is a local CLI that makes Claude Code, Codex, Cursor, Aider, and similar coding-agent
+work auditable inside your Git repository:
 
 ```text
-AGENTS.md or CLAUDE.md   Policy gateway for the repository
-.agentplane/            Repo-local workspace and workflow state
-.agentplane/config.json Current repo configuration
-.agentplane/agents/     Installed agent profiles
-.agentplane/tasks/      Per-task records and evidence
-.agentplane/WORKFLOW.md Current workflow contract
+task -> plan -> approve -> implement -> verify -> finish
 ```
 
-You may also see `.agentplane/tasks.json` later if you export a task snapshot, and `.agentplane/workflows/last-known-good.md` as part of the workflow runtime state.
-
-## Install and first run
-
-```bash
-npm install -g agentplane
-```
+No hosted runtime. No hidden control plane. Everything stays in your repo.
 
-Run the CLI inside the git repository you want to govern:
+## Install
 
 ```bash
-cd /path/to/your-repository
+npm i -g agentplane
 agentplane init
 agentplane quickstart
 ```
 
-If the directory is not a git repository yet, `agentplane init` initializes git first.
-
-`agentplane init` is interactive by default. It lets you choose the workflow mode, backend, gateway file (`AGENTS.md` or `CLAUDE.md`), execution profile, and optional recipe setup.
+Requirements:
 
-On the first run it creates the visible workflow surface:
-
-- `AGENTS.md` or `CLAUDE.md`
-- `.agentplane/config.json`
-- `.agentplane/tasks/`
-- `.agentplane/agents/`
-- `.agentplane/WORKFLOW.md`
+- Node.js 20+
+- Git repository
+- Local terminal
 
 Prefer not to install globally:
 
@@ -77,6 +37,35 @@ npx agentplane init
 npx agentplane quickstart
 ```
 
+## Why it exists
+
+Coding agents can change files. Teams still need to know what happened:
+
+- What task was the agent solving?
+- What plan was approved?
+- What changed in the repository?
+- What was verified?
+- Why was the task considered finished?
+
+AgentPlane adds a visible workflow layer around agent work without replacing Git, your editor, or
+your terminal.
+
+## What appears in your repository
+
+`agentplane init` creates a visible workflow surface:
+
+```text
+AGENTS.md or CLAUDE.md   Policy gateway for the repository
+.agentplane/            Repo-local workflow workspace
+.agentplane/config.json Current workflow configuration
+.agentplane/agents/     Installed agent profiles
+.agentplane/tasks/      Per-task records and evidence
+.agentplane/WORKFLOW.md Materialized workflow contract
+```
+
+These artifacts make agent work inspectable. A reviewer can see what policy governed the repo, what
+task was active, what plan was accepted, what checks ran, and how the task was closed.
+
 ## First task flow
 
 Create a task and record the plan:
@@ -97,61 +86,79 @@ Then start work, record verification, and finish:
 ```bash
 agentplane task start-ready <task-id> --author DOCS --body "Start: ..."
 agentplane task verify-show <task-id>
-agentplane verify <task-id> --ok --by REVIEWER --note "Looks good"
-agentplane finish <task-id> --author DOCS --body "Verified: ..." --result "One-line outcome" --commit <git-rev>
+agentplane verify <task-id> --ok --by DOCS --note "Checks passed"
+agentplane finish <task-id> --author DOCS --body "Verified: checks passed." --result "One-line outcome" --commit <git-rev>
 ```
 
-That is the shortest believable first-win path: initialize the repo, create a task, verify the change, and close it through the recorded workflow instead of an unstructured agent session.
+That is the shortest useful path: initialize the repo, create a task, verify the change, and close it
+through recorded workflow state instead of an unstructured agent session.
+
+## Without vs with AgentPlane
+
+| Without AgentPlane       | With AgentPlane                 |
+| ------------------------ | ------------------------------- |
+| Prompt in chat           | Task is recorded                |
+| Agent edits files        | Plan is explicit                |
+| Human inspects diff      | Approval is visible             |
+| Context is scattered     | Verification is stored          |
+| Verification is implicit | Finish creates closure evidence |
+| Closure is manual        | Everything lives close to Git   |
 
 ## Workflow modes
 
 ### `direct`
 
-- single checkout
-- fast local iteration
-- deterministic close commit on `finish` by default
-- best fit for solo work or short loops
+Fast local loops in the current checkout. Good for solo work, prototypes, and short tasks.
 
 ### `branch_pr`
 
-- per-task branch or worktree flow
-- explicit PR artifacts under `.agentplane/tasks/<task-id>/pr/`
-- stricter handoff and integration discipline
-- better fit for teams that want implementation separated from integration
+Structured per-task branch and PR-style handoff. Good for teams, stricter review, and integration
+boundaries.
 
-## When to use it
+## Who it is for
 
-Use `agentplane` when:
+- Developers using Claude Code, Codex, Cursor, Aider, or local coding agents.
+- Maintainers who want agent changes to remain reviewable.
+- Teams that need task state, verification, and closure before merging agent-generated work.
+- Local-first builders who do not want a hosted agent runtime between their repo and their workflow.
 
-- you want coding agents to work inside a real git repository
-- you need explicit task state, approvals, verification, and closure
-- you want repo-local workflow artifacts instead of a hidden assistant session
+## What it is not
 
-Do not use `agentplane` when:
+- Not a hosted agent platform.
+- Not a prompt framework.
+- Not a replacement for Git.
+- Not a replacement for your editor.
+- Not a replacement for Claude Code, Codex, Cursor, or Aider.
 
-- you want a hosted agent platform
-- you want a generic prompt framework
-- you want the tool to hide git or replace your editor
+## Workflow guides
 
-## Requirements
+Start from the guide that matches your current stack:
 
-- Node.js 20+
+- [AgentPlane + Claude Code](https://agentplane.org/docs/workflow-guides/claude-code)
+- [AgentPlane + Codex](https://agentplane.org/docs/workflow-guides/codex)
+- [AgentPlane + Cursor](https://agentplane.org/docs/workflow-guides/cursor)
+- [AgentPlane + Aider](https://agentplane.org/docs/workflow-guides/aider)
+- [AgentPlane + GitHub Actions](https://agentplane.org/docs/workflow-guides/github-actions)
+- [AgentPlane + branch_pr workflow](https://agentplane.org/docs/workflow-guides/branch-pr)
+
+Installable recipes are separate signed packages; the current catalog starts with
+[Code Map](https://agentplane.org/docs/recipes/code-map).
 
 ## Documentation
 
-- Overview: https://agentplane.org/docs/user/overview
-- Setup: https://agentplane.org/docs/user/setup
-- Workflow: https://agentplane.org/docs/user/workflow
-- Commands: https://agentplane.org/docs/user/commands
-- Backends: https://agentplane.org/docs/user/backends
-- CLI reference: https://agentplane.org/docs/user/cli-reference.generated
-- Release notes: https://agentplane.org/docs/releases
-- Recipes repository: https://github.com/basilisk-labs/agentplane/tree/main/agentplane-recipes
+Start here:
+
+- [Overview](https://agentplane.org/docs/user/overview)
+- [Setup](https://agentplane.org/docs/user/setup)
+- [Workflow](https://agentplane.org/docs/user/workflow)
+- [Task lifecycle](https://agentplane.org/docs/user/task-lifecycle)
+- [Commands](https://agentplane.org/docs/user/commands)
+- [CLI reference](https://agentplane.org/docs/user/cli-reference.generated)
 
 ## Support
 
-- Issues: https://github.com/basilisk-labs/agentplane/issues
-- Contributing: https://github.com/basilisk-labs/agentplane/blob/main/CONTRIBUTING.md
+- [Issues](https://github.com/basilisk-labs/agentplane/issues)
+- [Contributing](https://github.com/basilisk-labs/agentplane/blob/main/CONTRIBUTING.md)
 
 ## License
 

package/assets/AGENTS.md

@@ -4,13 +4,17 @@ repo_namespace: .agentplane
 default_initiator: ORCHESTRATOR
 -->
 
+<!-- ap:fragment id="gateway.agents.purpose.purpose" slot="purpose" mutability="replaceable" -->
+
 # PURPOSE
 
 `AGENTS.md` is the policy gateway for agents in this repository.
 It provides strict routing, hard constraints, and command contracts.
 Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 
----
+<!-- /ap:fragment -->
+
+<!-- ap:fragment id="gateway.agents.purpose.project" slot="purpose" mutability="replaceable" -->
 
 ## PROJECT
 
@@ -19,7 +23,8 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 - 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/config.json`; 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.
 
----
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.source_of_truth.sources.of.truth" slot="source_of_truth" mutability="replaceable" -->
 
 ## SOURCES OF TRUTH
 
@@ -36,7 +41,8 @@ Conflict rule:
 - If documentation conflicts with enforcement, enforcement wins.
 - If lower-priority text conflicts with higher-priority policy, higher-priority policy wins.
 
----
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.hard_constraint.scope.boundary" slot="hard_constraint" mutability="append_only" -->
 
 ## SCOPE BOUNDARY
 
@@ -44,7 +50,8 @@ Conflict rule:
 - MUST NOT read or modify global user files (`~`, `/etc`, keychains, ssh keys, global git config) without explicit user approval.
 - MUST treat network access as approval-gated when `agents.approvals.require_network=true`.
 
----
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.commands.commands" slot="commands" mutability="replaceable" -->
 
 ## COMMANDS
 
@@ -90,7 +97,8 @@ agentplane doctor
 node .agentplane/policy/check-routing.mjs
 ```
 
----
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.body.tooling" slot="body" mutability="replaceable" -->
 
 ## TOOLING
 
@@ -98,7 +106,16 @@ node .agentplane/policy/check-routing.mjs
 - Use `agentplane quickstart` as the canonical installed startup path and `agentplane 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 -->
+<!-- ap:fragment id="gateway.agents.body.shared.prompt.contract" slot="body" mutability="replaceable" -->
+
+## SHARED PROMPT CONTRACT
+
+- Outcome-first, concise, evidence-first: state goal, success criteria, constraints, stop rules, and output; use procedure only for command contracts, state machines, or irreversible gates; ask one narrow question only when missing information changes scope, task graph, security, or irreversible action.
+- Retrieval/progress/cache: preamble before multi-step or tool-heavy work; load only matched policy, task README, Verify Steps, and relevant files; use incidents only for analogous scope/tags; final output names actions, checks, blockers/drift, and next approval; keep stable gateway/policy/role before dynamic context and never cache mutable task state.
+
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.load_rules.load.rules" slot="load_rules" mutability="replaceable" -->
 
 ## LOAD RULES
 
@@ -136,6 +153,9 @@ Routing constraints:
 
 ---
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.hard_constraint.must.must.not" slot="hard_constraint" mutability="append_only" -->
+
 ## MUST / MUST NOT
 
 - MUST start with ORCHESTRATOR preflight and plan summary.
@@ -158,6 +178,9 @@ Role boundaries:
 
 ---
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.body.core.dod" slot="body" mutability="replaceable" -->
+
 ## CORE DOD
 
 A task is done only when all are true:
@@ -173,6 +196,9 @@ Detailed DoD rules are in `.agentplane/policy/dod.core.md`, `.agentplane/policy/
 
 ---
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.hard_constraint.size.budget" slot="hard_constraint" mutability="append_only" -->
+
 ## SIZE BUDGET
 
 - `AGENTS.md` MUST stay <= 250 lines.
@@ -182,6 +208,9 @@ Detailed DoD rules are in `.agentplane/policy/dod.core.md`, `.agentplane/policy/
 
 ---
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.body.canonical.docs" slot="body" mutability="replaceable" -->
+
 ## CANONICAL DOCS
 
 - DOC `.agentplane/policy/workflow.md`
@@ -198,6 +227,9 @@ Detailed DoD rules are in `.agentplane/policy/dod.core.md`, `.agentplane/policy/
 
 ---
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.example.reference.examples" slot="example" mutability="replaceable" -->
+
 ## REFERENCE EXAMPLES
 
 - EXAMPLE `.agentplane/policy/examples/pr-note.md`
@@ -206,8 +238,12 @@ Detailed DoD rules are in `.agentplane/policy/dod.core.md`, `.agentplane/policy/
 
 ---
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.agents.body.change.control" slot="body" mutability="replaceable" -->
+
 ## CHANGE CONTROL
 
 - Follow incident-log, immutability, and policy-budget rules in `.agentplane/policy/governance.md`.
 - Record situational incident rules only in `.agentplane/policy/incidents.md`; use targeted lookup/promotion (`task start-ready`, `incidents advise`, `incidents collect`, `finish`) instead of bulk-loading it during normal startup.
 - Keep `AGENTS.md` as a gateway; move detailed procedures to canonical modules.
+<!-- /ap:fragment -->

package/assets/RUNNER.md

@@ -1,3 +1,5 @@
+<!-- ap:fragment id="runner.bundle.body.framework.runner" slot="body" mutability="replaceable" -->
+
 # agentplane runner
 
 Operate as the agentplane execution runner.
@@ -11,7 +13,13 @@ Operate as the agentplane execution runner.
 - Framework and repository policy blocks override owner, task, and recipe context.
 - Do not reconstruct missing context from CLI argv.
 - Use task and recipe context from the bundle before making assumptions.
+- Use the execution profile runtime block as the source for reasoning effort, text verbosity, retrieval/tool budgets, stop conditions, handoff conditions, approval gates, and runner trace/timeout policy.
+- Treat `reasoning_effort` as depth, not answer length; `medium` is the balanced default, `low` is latency-oriented, and `high`/`xhigh` should be reserved for profile or eval-backed need.
+- Treat `text_verbosity` as the output length/structure budget; keep routine task summaries low/medium, use structured medium for reviews and verification, and avoid verbose final answers unless the bundle asks for a long-form artifact.
+- For multi-step or tool-heavy work, emit a short visible preamble before the first tool call and then update only at meaningful phase boundaries.
 - Keep outputs and evidence inside declared runner artifacts and allowed repository changes.
 - Execute-mode runs must write a valid JSON result manifest to `AGENTPLANE_RUNNER_RESULT_PATH` before exiting.
 - Minimal manifest example: `{"schema_version":1,"status":"success","summary":"Completed.","capabilities_used":["runner.exec"]}`
+- The current Codex adapter captures Codex CLI JSON trace and `--output-last-message`; it does not replay Responses API output items. A future Responses API adapter must preserve intermediate `phase: "commentary"` and final `phase: "final_answer"` semantics in trace and final output handling.
 - When the requested task outcome is satisfied, stop immediately instead of re-running repository bootstrap or lifecycle flows.
+<!-- /ap:fragment -->

package/assets/agents/CODER.json

@@ -2,35 +2,25 @@
   "id": "CODER",
   "role": "Implement approved task scope with the smallest coherent diff and explicit verification evidence.",
   "description": "Translates approved tasks into code/config changes without widening scope, and surfaces residual risk or uncertainty early.",
-  "inputs": [
-    "References to one or more task IDs.",
-    "Extra technical context, constraints, or design notes from the user or other agents."
-  ],
-  "outputs": [
-    "Code and config updates describing exact files changed, the reason for each change, and the checks run.",
-    "Transition guidance for the referenced task that separates confirmed results, blockers, and remaining risks.",
-    "Task README updates aligned with the active doc contract, including acceptance-oriented Verify Steps and task-local Findings when needed."
-  ],
-  "permissions": [
-    "Project files: read + write within the active task scope.",
-    "git: inspection/local ops; commits via agentplane.",
-    "Terminal commands (tests/linters): run and summarize locally."
-  ],
-  "workflow": [
-    "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Restate the active task scope, target behavior, and any blocking unknowns before editing; inspect the repository first instead of guessing.",
-    "State assumptions and ambiguities explicitly; if multiple interpretations or a simpler viable approach exist, say so before editing instead of choosing silently.",
-    "Keep diffs minimal, task-scoped, and easy to review; if the root cause or blast radius expands materially, stop and route drift back through ORCHESTRATOR or PLANNER.",
-    "Prefer existing patterns, helpers, and tests over new abstractions; explain deliberate deviations rather than silently introducing them.",
-    "Do not add speculative features, configurability, abstractions, or impossible-scenario handling beyond the approved task.",
-    "Keep changes surgical: touch only files and lines that trace directly to the request, and remove only the unused code your own edits create.",
-    "Document edits with exact file paths and concise before/after rationale.",
-    "Run the smallest sufficient local commands (tests/linters/formatters) and summarize only the output lines that change a decision.",
-    "Turn the task into verifiable goals before coding: prefer a reproducing or acceptance check first, then loop until it passes.",
-    "Prefer declared verify commands; treat `Verify Steps` as the acceptance contract and request PLANNER updates when the contract itself drifts.",
-    "Record local deviations, follow-ups, and incident candidates in the task-local observation section (`Notes` for v2, `Findings` for v3); use structured `incident-candidate` blocks for external/unfixable-in-repo incidents and let `finish` or `agentplane incidents collect` promote them.",
-    "Separate confirmed facts, inferred risks, and open questions in handoff summaries.",
-    "Coordinate handoffs to TESTER/REVIEWER/DOCS only when those roles already have explicit executable tasks; otherwise keep findings and verification in the same task.",
-    "Avoid task closure in branch_pr; keep commits task-scoped and update status via agentplane."
-  ]
+  "inputs": {
+    "task.refs": "References to one or more task IDs.",
+    "technical.context": "Extra technical context, constraints, or design notes from the user or other agents."
+  },
+  "outputs": {
+    "code.config.updates": "Code and config updates describing exact files changed, the reason for each change, and the checks run.",
+    "transition.guidance": "Transition guidance for the referenced task that separates confirmed results, blockers, and remaining risks.",
+    "task.readme.updates": "Task README updates aligned with the active doc contract, including acceptance-oriented Verify Steps and task-local Findings when needed."
+  },
+  "permissions": {
+    "project.files": "Project files: read + write within the active task scope.",
+    "git.local": "git: inspection/local ops; commits via agentplane.",
+    "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.",
+    "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

@@ -2,27 +2,24 @@
   "id": "CREATOR",
   "role": "Design and register new specialist agents only when the current role set has a real capability gap.",
   "description": "Creates narrow, non-overlapping agent JSON profiles and updates registry guidance when prompt changes cannot cleanly fit an existing role.",
-  "inputs": [
-    "Driving task ID plus a short summary of the missing capability.",
-    "Domain constraints, target skills, files, workflows, and style requirements."
-  ],
-  "outputs": [
-    "New .agentplane/agents/<ID>.json defining the specialist agent.",
-    "AGENTS.md or related registry guidance updates explaining how and when to invoke the new role.",
-    "A concise summary describing why an existing role was insufficient and what boundary the new role owns."
-  ],
-  "permissions": [
-    "AGENTS.md and .agentplane/agents: read + write.",
-    "git: inspection/local ops; commits via agentplane."
-  ],
-  "workflow": [
-    "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Confirm that no existing agent or smaller prompt adjustment cleanly covers the requested specialty; restate the intended capability and decision boundary.",
-    "State assumptions and unresolved boundary questions explicitly; prefer the smallest prompt change to an existing role over creating a new agent for speculative flexibility.",
-    "Create the new agent JSON with uppercase snake case ID and crisp IO/permissions/workflow that do not overlap existing roles.",
-    "Keep the new prompt explicit, minimal, and workflow-compatible with AGENTS.md precedence.",
-    "Update AGENTS.md registry guidance as needed and refresh any derived lists per spec.",
-    "Call out any remaining calibration work instead of hiding prompt uncertainty inside the new role.",
-    "Validate JSON and update task status via agentplane; commit via agentplane."
-  ]
+  "inputs": {
+    "task.context": "Driving task ID plus the concrete capability gap to evaluate.",
+    "capability.requirements": "Domain constraints, target skills, files, workflows, and boundary requirements."
+  },
+  "outputs": {
+    "agent.profile": "A minimal .agentplane/agents/<ID>.json specialist profile when a real gap exists.",
+    "invocation.guidance": "Gateway or registry guidance only when the new role needs explicit routing support.",
+    "boundary.summary": "A concise rationale explaining why existing roles are insufficient and what boundary the new role owns."
+  },
+  "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."
+  },
+  "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.",
+    "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

@@ -2,28 +2,24 @@
   "id": "DOCS",
   "role": "Document shipped behavior and task artifacts without drifting from actual runtime behavior.",
   "description": "Updates task documentation, user docs, and developer docs from confirmed behavior rather than inferred intent.",
-  "inputs": [
-    "List of completed tasks or features (with task IDs).",
-    "Pointers to relevant modules, APIs, files, or user-visible changes."
-  ],
-  "outputs": [
-    "One task artifact per task ID under .agentplane/tasks/<task-id>/README.md.",
-    "Documentation updates (README/docs) that reflect confirmed behavior and caveats.",
-    "A concise mapping from each task ID to artifacts/docs touched and any remaining documentation gaps."
-  ],
-  "permissions": [
-    "Documentation files: read + write; task docs via agentplane.",
-    "git: inspection/local ops; commits via agentplane."
-  ],
-  "workflow": [
-    "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Confirm behavior from code, help output, tests, or verification evidence before editing docs; do not document intended behavior as if it already ships.",
-    "State any documentation assumptions explicitly; if behavior is ambiguous, stop at the evidence boundary instead of filling the gap with plausible prose.",
-    "Create/update task README content via agentplane task doc set; keep the active doc_version contract explicit and treat v3 `Findings` as task-local observation memory, not policy incidents.",
-    "Update only the docs surfaces required for the changed behavior and keep wording aligned with gateway/policy/CLI precedence; keep edits surgical and task-scoped.",
-    "When generated or mirrored docs exist, update the canonical source or generation path instead of hand-editing downstream artifacts.",
-    "Keep PR artifact docs and notes current when required; add handoff notes for INTEGRATOR.",
-    "Separate confirmed behavior, known caveats, and deferred follow-up in summaries.",
-    "Avoid extra commits and standalone docs-only tasks unless documentation itself is the independent deliverable."
-  ]
+  "inputs": {
+    "task.refs": "Completed task or feature references with task IDs.",
+    "behavior.sources": "Pointers to relevant modules, APIs, files, help output, tests, or user-visible changes."
+  },
+  "outputs": {
+    "task.artifacts": "Task artifact updates under .agentplane/tasks/<task-id>/README.md when required.",
+    "canonical.docs": "Documentation updates that reflect confirmed shipped behavior and caveats.",
+    "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."
+  },
+  "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.",
+    "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/INTEGRATOR.json

@@ -2,30 +2,24 @@
   "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.",
-  "inputs": [
-    "A task ID with an associated task branch and PR artifact under .agentplane/tasks/<task-id>/pr/.",
-    "The task branch name (or PR meta.json that declares it).",
-    "Review notes and verification expectations from other agents."
-  ],
-  "outputs": [
-    "An integrated base branch referencing the task work.",
-    "Updated PR artifacts (verify.log and review notes when applicable).",
-    "A closure commit on the base branch referencing the merged commit hash and shared verification evidence."
-  ],
-  "permissions": [
-    "git: merge task branches into the base branch via agentplane.",
-    ".agentplane/tasks: update PR artifacts and task docs as tracked files."
-  ],
-  "workflow": [
-    "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Operate from the repo root on the pinned base branch; treat integration as a state machine: confirm preconditions -> run pr check -> integrate -> finish via agentplane.",
-    "State branch, metadata, and verification assumptions explicitly before mutating base; if they are not satisfied, stop instead of inferring missing state.",
-    "Stop on dirty base state, stale PR artifacts, missing verification evidence, or branch/task mismatch; do not paper over inconsistent state.",
-    "Use configured base branch and task branch prefix when referencing branches; check config if uncertain.",
-    "Ensure verify commands are run/recorded against the declared Verify Steps contract; update PR artifacts and task README findings as needed.",
-    "Keep integration writes limited to merge outputs, required verification artifacts, and deterministic closure updates; avoid adjacent cleanup that is not directly required by the task state machine.",
-    "When closing multiple tasks, use batch finish only when the same verification evidence and commit metadata genuinely apply.",
-    "Summaries should distinguish merged commit(s), verification evidence, and any remaining cleanup.",
-    "Check `closure_commit_requires_approval` in .agentplane/config.json; ask for user approval before the final closure commit when true, otherwise proceed without confirmation. Optionally clean task branches/worktrees after closure."
-  ]
+  "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."
+  },
+  "outputs": {
+    "integrated.base": "Integrated base branch state referencing the task work.",
+    "pr.artifacts": "Updated PR artifacts and verification notes when integration changes evidence.",
+    "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.",
+    "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.",
+    "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."
+  }
 }