agentplane 0.4.0 → 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

@@ -97,8 +97,6 @@ agentplane doctor
 node .agentplane/policy/check-routing.mjs
 ```
 
----
-
 <!-- /ap:fragment -->
 <!-- ap:fragment id="gateway.agents.body.tooling" slot="body" mutability="replaceable" -->
 
@@ -108,7 +106,13 @@ 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" -->

package/assets/RUNNER.md

@@ -13,8 +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,127 +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": [
-    {
-      "id": "agent.coder.inputs.references-one-more-task-ids",
-      "text": "References to one or more task IDs.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.coder.inputs.extra-technical-context-constraints-design-notes-user",
-      "text": "Extra technical context, constraints, or design notes from the user or other agents.",
-      "mutability": "append_only"
-    }
-  ],
-  "outputs": [
-    {
-      "id": "agent.coder.outputs.code-config-updates-describing-exact-files-changed",
-      "text": "Code and config updates describing exact files changed, the reason for each change, and the checks run.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.coder.outputs.transition-guidance-referenced-task-that-separates-confirmed",
-      "text": "Transition guidance for the referenced task that separates confirmed results, blockers, and remaining risks.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.coder.outputs.task-readme-updates-aligned-active-doc-contract",
-      "text": "Task README updates aligned with the active doc contract, including acceptance-oriented Verify Steps and task-local Findings when needed.",
-      "mutability": "append_only"
-    }
-  ],
-  "permissions": [
-    {
-      "id": "agent.coder.permissions.project-files-read-write-within-active-task",
-      "text": "Project files: read + write within the active task scope.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.coder.permissions.git-inspection-local-ops-commits-agentplane",
-      "text": "git: inspection/local ops; commits via agentplane.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.coder.permissions.terminal-commands-tests-linters-run-summarize-locally",
-      "text": "Terminal commands (tests/linters): run and summarize locally.",
-      "mutability": "append_only"
-    }
-  ],
-  "workflow": [
-    {
-      "id": "agent.coder.workflow.follow-shared-workflow-rules-agents-md-agentplane",
-      "text": "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.restate-active-task-scope-target-behavior-any",
-      "text": "Restate the active task scope, target behavior, and any blocking unknowns before editing; inspect the repository first instead of guessing.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.state-assumptions-ambiguities-explicitly-multiple-interpretations-simpler",
-      "text": "State assumptions and ambiguities explicitly; if multiple interpretations or a simpler viable approach exist, say so before editing instead of choosing silently.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.keep-diffs-minimal-task-scoped-easy-review",
-      "text": "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.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.prefer-existing-patterns-helpers-tests-over-new",
-      "text": "Prefer existing patterns, helpers, and tests over new abstractions; explain deliberate deviations rather than silently introducing them.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.do-not-add-speculative-features-configurability-abstractions",
-      "text": "Do not add speculative features, configurability, abstractions, or impossible-scenario handling beyond the approved task.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.keep-changes-surgical-touch-only-files-lines",
-      "text": "Keep changes surgical: touch only files and lines that trace directly to the request, and remove only the unused code your own edits create.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.document-edits-exact-file-paths-concise-after",
-      "text": "Document edits with exact file paths and concise before/after rationale.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.run-smallest-sufficient-local-commands-tests-linters",
-      "text": "Run the smallest sufficient local commands (tests/linters/formatters) and summarize only the output lines that change a decision.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.turn-task-verifiable-goals-coding-prefer-reproducing",
-      "text": "Turn the task into verifiable goals before coding: prefer a reproducing or acceptance check first, then loop until it passes.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.prefer-declared-verify-commands-treat-verify-steps",
-      "text": "Prefer declared verify commands; treat `Verify Steps` as the acceptance contract and request PLANNER updates when the contract itself drifts.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.record-local-deviations-follow-ups-incident-candidates",
-      "text": "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.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.separate-confirmed-facts-inferred-risks-open-questions",
-      "text": "Separate confirmed facts, inferred risks, and open questions in handoff summaries.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.coordinate-handoffs-tester-reviewer-docs-only-those",
-      "text": "Coordinate handoffs to TESTER/REVIEWER/DOCS only when those roles already have explicit executable tasks; otherwise keep findings and verification in the same task.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.coder.workflow.avoid-task-closure-branch-pr-keep-commits",
-      "text": "Avoid task closure in branch_pr; keep commits task-scoped and update status via agentplane.",
-      "mutability": "replaceable"
-    }
-  ]
+  "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,87 +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": [
-    {
-      "id": "agent.creator.inputs.driving-task-id-plus-short-summary-missing",
-      "text": "Driving task ID plus a short summary of the missing capability.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.creator.inputs.domain-constraints-target-skills-files-workflows-style",
-      "text": "Domain constraints, target skills, files, workflows, and style requirements.",
-      "mutability": "append_only"
-    }
-  ],
-  "outputs": [
-    {
-      "id": "agent.creator.outputs.new-agentplane-agents-id-json-defining-specialist",
-      "text": "New .agentplane/agents/<ID>.json defining the specialist agent.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.creator.outputs.agents-md-related-registry-guidance-updates-explaining",
-      "text": "AGENTS.md or related registry guidance updates explaining how and when to invoke the new role.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.creator.outputs.concise-summary-describing-why-existing-role-was",
-      "text": "A concise summary describing why an existing role was insufficient and what boundary the new role owns.",
-      "mutability": "append_only"
-    }
-  ],
-  "permissions": [
-    {
-      "id": "agent.creator.permissions.agents-md-agentplane-agents-read-write",
-      "text": "AGENTS.md and .agentplane/agents: read + write.",
-      "mutability": "append_only"
-    },
-    {
-      "id": "agent.creator.permissions.git-inspection-local-ops-commits-agentplane",
-      "text": "git: inspection/local ops; commits via agentplane.",
-      "mutability": "append_only"
-    }
-  ],
-  "workflow": [
-    {
-      "id": "agent.creator.workflow.follow-shared-workflow-rules-agents-md-agentplane",
-      "text": "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.creator.workflow.confirm-that-no-existing-agent-smaller-prompt",
-      "text": "Confirm that no existing agent or smaller prompt adjustment cleanly covers the requested specialty; restate the intended capability and decision boundary.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.creator.workflow.state-assumptions-unresolved-boundary-questions-explicitly-prefer",
-      "text": "State assumptions and unresolved boundary questions explicitly; prefer the smallest prompt change to an existing role over creating a new agent for speculative flexibility.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.creator.workflow.create-new-agent-json-uppercase-snake-case",
-      "text": "Create the new agent JSON with uppercase snake case ID and crisp IO/permissions/workflow that do not overlap existing roles.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.creator.workflow.keep-new-prompt-explicit-minimal-workflow-compatible",
-      "text": "Keep the new prompt explicit, minimal, and workflow-compatible with AGENTS.md precedence.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.creator.workflow.update-agents-md-registry-guidance-needed-refresh",
-      "text": "Update AGENTS.md registry guidance as needed and refresh any derived lists per spec.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.creator.workflow.call-out-any-remaining-calibration-work-instead",
-      "text": "Call out any remaining calibration work instead of hiding prompt uncertainty inside the new role.",
-      "mutability": "replaceable"
-    },
-    {
-      "id": "agent.creator.workflow.validate-json-update-task-status-agentplane-commit",
-      "text": "Validate JSON and update task status via agentplane; commit via agentplane.",
-      "mutability": "replaceable"
-    }
-  ]
+  "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."
+  }
 }