@rse/ase 1.0.7 → 2.0.0

package/dst/man/ase-agent-adhoc.1

@@ -0,0 +1,515 @@
+.TH "ASE-AGENT-ADHOC" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent-adhoc\fR - Run an Ad-Hoc Agent of a Definition Given by Options
+.SH "SYNOPSIS"
+.P
+\fBase agent adhoc start\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-p\fR|\fB--parallel\fR \fInum\fR\[rB] \[lB]\fB-T\fR|\fB--timeout\fR \fIduration\fR\[rB] \[lB]\fB-o\fR|\fB--one-shot\fR\[rB] \[lB]\fB--agent-relay\fR \fIurl\fR\[rB] \[lB]\fB-r\fR|\fB--repo\fR \fIurl\fR\[rB] \[lB]\fB-d\fR|\fB--tempdir\fR \fIdir\fR\[rB] \[lB]\fB-D\fR|\fB--definition\fR \fIfile\fR|\fBbuiltin:\fR\fIkind\fR\[lB]\fB-\fR\fImode\fR\[rB]\[rB] \[lB]\fB--title\fR \fItext\fR\[rB] \[lB]\fB--description\fR \fItext\fR\[rB] \[lB]\fB--type\fR \fBphase\fR|\fBrequest\fR\[rB] \[lB]\fB--workdir\fR \fIkind\fR\[rB] \[lB]\fB--lifecycle\fR \fImodel\fR\[rB] \[lB]\fB--serial\fR\[rB] \[lB]\fB--unclaimed\fR\[rB] \[lB]\fB--params\fR \fIname\fR\fB=\fR\fIvalue\fR\[rB] \[lB]\fB--state-\fR\fIitem\fR \fIstate\fR\[rB] \[lB]\fB--tag-\fR\fIitem\fR \fItag\fR\[rB] \[lB]\fB--assign-\fR\fIitem\fR \fIwho\fR\[rB] \[lB]\fB--request-\fR\fIitem\fR \fIvalue\fR\[rB] \[lB]\fB--prompt-\fR\fIitem\fR \fIvalue\fR\[rB] \[lB]\fB--prepare-run\fR \fIcmd\fR\[rB] \[lB]\fB--success-\fR\fIitem\fR \fIvalue\fR\[rB] \[lB]\fB--verdict-\fR\fIitem\fR \fIvalue\fR\[rB] \[lB]\fB--attach-\fR\fIitem\fR \fIvalue\fR\[rB] \[lB]\fB--finish-\fR\fIitem\fR \[lB]\fIcmd\fR\[rB]\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]
+.P
+\fBase agent adhoc status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent adhoc log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB] \[lB]\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent adhoc stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent\fR \fIkind\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR \[lB]...\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase agent adhoc\fR runs an \fIad-hoc agent\fR: an autonomous agent whose \fIentire\fR behavior is given by its command-line options (optionally based on the definition file or the built-in definition of \fB--definition\fR), instead of by a definition file of its own. This manual page is also the authoritative reference of the \fIagent definitions\fR in general, i.e., of the options \fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR, of the definition files, of the prompt templates, and of the hooks.
+.P
+An agent definition configures the behavior of an agent declaratively. All agents of \fBase\fR are agents of a definition, run by the same agent engine:
+.RS 0
+.IP \(bu 4
+\fIbuilt-in agents\fR (\fBase agent rebooter\fR, \fBcondenser\fR, \fBimplementer\fR, \fBqualifier\fR, \fBintegrator\fR, \fBeditor\fR, \fBestimator\fR, and \fBresearcher\fR): each mode of them is a built-in definition, which can be referenced as \fBbuiltin:\fR\fIkind\fR\fB-\fR\fImode\fR (resp. \fBbuiltin:\fR\fIkind\fR for its default mode): \fBbuiltin:rebooter-reboot\fR, \fBbuiltin:condenser-condense\fR, \fBbuiltin:implementer-implement\fR, \fBbuiltin:implementer-draft\fR, \fBbuiltin:qualifier-judge\fR, \fBbuiltin:qualifier-qualify\fR, \fBbuiltin:integrator-merge\fR, \fBbuiltin:integrator-rebase\fR, \fBbuiltin:integrator-squash\fR, \fBbuiltin:editor-edit\fR, \fBbuiltin:estimator-phase\fR, \fBbuiltin:estimator-request\fR, \fBbuiltin:researcher-phase\fR, and \fBbuiltin:researcher-request\fR.
+.sp
+All options \fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR below are also accepted by the built-in agents, where they override the built-in definition (see \fBase-agent-rebooter\fR(1) etc.).
+.IP \(bu 4
+\fIdefinition kinds\fR (\fBase agent\fR \fIkind\fR): an agent kind of its own, discovered from the definition file \fIkind\fR\fB.\fR\fIext\fR of the project (\fB.ase/agents/\fR, intended to be versioned) or of the user (\fIper-user configuration directory\fR\fB/agents/\fR). A definition kind of the project shadows one of the user, and both shadow a built-in agent kind of the same name (whose \fB--mode\fR then no longer exists).
+.sp
+For example, \fB.ase/agents/reviewer.mts\fR yields the commands \fBase agent reviewer start|status|log|stop\fR, which take exactly the same options as \fBase agent adhoc\fR described here, except \fB--definition\fR (as the definition file of the kind takes its place), and where the given options override the definition file.
+.sp
+The definition files are discovered only on the commands \fBase agent\fR ..., where a file of an invalid kind name (other than up to 64 letters, digits, underscores, and dashes, starting with a letter or digit), of the reserved kind names \fBadhoc\fR, \fBrelay\fR, or \fBfleet\fR, or of an already discovered kind name in the same directory (by the precedence of the extensions \fB.yaml\fR, \fB.yml\fR, \fB.ts\fR, \fB.mts\fR, \fB.js\fR, \fB.mjs\fR, and \fB.cjs\fR, in this order) is skipped with a warning.
+.IP \(bu 4
+\fIad-hoc agents\fR (\fBase agent adhoc\fR): an agent without a definition file of its own, e.g., for a one-off agent, or for an agent defined inline in a fleet (see \fBase-agent-fleet\fR(1)).
+.RE 0
+.P
+Each agent runs in its own process, in the background (logging into \fB.ase/agent/\fR\fIname\fR\fB.log\fR) or with \fB--foreground\fR in the current process (logging to the terminal). Several agents are best run together as a fleet (see \fBase-agent-fleet\fR(1)).
+.P
+With \fB--type phase\fR (default), an agent claims tasks by their \fIlifecycle status\fR, like the built-in phase agents: it observes the task store for the tasks in the state of \fB--state-incoming\fR which do not carry its tag (see \fB--tag-name\fR), whose \fBAssignee:\fR is empty or its own assignee name (see \fB--assign-name\fR), and whose predecessors (the tasks of the \fBAfter:\fR key, and, for an explicit epic, the other tasks of its \fBGroup:\fR) all passed its phase (see \fB--state-passed\fR and the hook \fBpasses\fR).
+.P
+It claims each such task (in natural task id order, or in the order of the hook \fBorder\fR) in a single conditional save, which moves it into the state of \fB--state-activity\fR, tags it with the tag value \fBactive\fR (as \fB<tag-name>:active\fR), and assigns it to the agent.
+.P
+It then processes the task through the headless agent tool of \fB--tool\fR with the prompt of \fB--prompt-skill\fR, \fB--prompt-text\fR, or \fB--prompt-file\fR, checks the success criteria, and finally, again in a single conditional save, settles the task: it tags it according to \fB--tag-success\fR resp. \fB--tag-failure\fR (or with the found verdict as the tag value), hands it over to the assignee of \fB--assign-success\fR resp. \fB--assign-failure\fR, and moves it into the state of \fB--state-success\fR resp. \fB--state-failure\fR (or of \fB--state-verdict\fR), where \fBprevious\fR restores the incoming state the task was claimed from.
+.P
+A task whose status the skill itself moved elsewhere is tagged, too, and left in that state, except that for a \fBprevious\fR success or failure state, a task the skill itself moved back into one of the incoming states (e.g., \fBase-task-reboot\fR, which resets it into its default state) is still settled as above. An interrupted processing puts the task back, untagged and with its previous assignee, into the incoming state it was claimed from.
+.P
+With \fB--type phase\fR and \fB--unclaimed\fR, an agent instead processes the tasks \fIunclaimed\fR, like the built-in \fBestimator\fR agent: it observes the tasks in one of the states of \fB--state-incoming\fR (each adapted onto the task lifecycle model of the project, e.g., \fBPLANNED\fR as \fBPLANNING\fR for \fBteam\fR and as \fBOPEN\fR for \fBsolo\fR, so it supports all models) which do not carry its tag, independent of their \fBAssignee:\fR and their predecessors. It processes each such task without any change of it (neither moving it into an activity state, nor tagging it as active, nor assigning it), so it keeps no other agent off the task, and the skill itself has to save its result conditionally (as another agent can claim and change the task meanwhile). Finally, it settles the task by its tag only (according to \fB--tag-success\fR resp. \fB--tag-failure\fR), without ever changing its status or its assignee. An interrupted processing leaves the task untouched.
+.P
+With \fB--type request\fR, an agent processes the \fIprompt requests\fR attached to tasks in any lifecycle status (see \fBase task request\fR in \fBase-task-request\fR(1), or key \fBR\fR of the task boards), like the built-in \fBeditor\fR agent: it observes the tasks with pending requests of the request name of \fB--request-name\fR (attachments of type \fBtext/plain; charset=utf-8; kind="<name>"\fR, mirrored in the tag \fBase-agent-<name>:pending\fR), claims the oldest request of such a task by turning it into \fBkind="<name>-running"\fR and assigning the task to the agent (remembering its previous assignee), processes it with the request prompt available as \fB{prompt}\fR, and finally removes the request on success, or turns it into \fBkind="<name>-failed"\fR (with the reason of the failure as its description) on failure, resp. back into \fBkind="<name>"\fR on interrupt, where the task keeps its status and its tags (except the request state tag) and, by default, gets its previous assignee back. An agent consumes the request prompts if its prompt template references \fB{prompt}\fR (except within the conditional \fB{?prompt:\fR\fItext\fR\fB}\fR only, which makes the prompt \fIoptional\fR) or it has a hook \fBprepare\fR, \fBprompt\fR, or \fBfinish\fR (which receive the request prompt in their \fIjob\fR), where it then refuses a request with an empty prompt as failed, else it accepts requests with an empty prompt (which an agent with an optional prompt still passes on if non-empty), and announces this to the agent relay, so the task boards accept an empty prompt for its requests, too.
+.P
+Only the prompt (and \fB--state-incoming\fR for \fB--type phase\fR) is mandatory, while all other options default to the safe \fIannotate\fR behavior: a \fBphase\fR task returns into its incoming state, tagged with the plain tag \fBase-agent-<name>\fR and unassigned, while a \fBrequest\fR task keeps its status and tags and gets its previous assignee back. The options are validated on the start (also before detaching the agent), where an error names the offending option.
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase agent adhoc start\fR \[lB]\fIoptions\fR\[rB]: Start the ad-hoc agent named by \fB--name\fR in the background (spawning a detached process logging into \fB.ase/agent/\fR\fIname\fR\fB.log\fR), or with \fB--foreground\fR in the current process. The agent is validated and initialized (e.g., its agent tool is looked up and the task lifecycle model is checked against \fB--lifecycle\fR) before the command returns, so a failing agent is reported together with the tail of its log (waiting up to 30 seconds for its startup).
+.sp
+An agent of the same name already running is left alone (and is an error with \fB--foreground\fR). All options are described under \fBOPTIONS\fR below.
+.IP \(bu 4
+\fBase agent adhoc status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Report whether the agent named \fIname\fR (default: \fBadhoc\fR) is running, as \fBagent\fR \fIname\fR\fB: running (pid\fR \fIpid\fR\fB)\fR resp. \fBagent\fR \fIname\fR\fB: not
+running\fR. Exits with status 1 if it is not running.
+.IP \(bu 4
+\fBase agent adhoc log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB] \[lB]\fB--name\fR \fIname\fR\[rB]: Show the log \fB.ase/agent/\fR\fIname\fR\fB.log\fR of the agent named \fIname\fR (default: \fBadhoc\fR) run in the background (where an agent run in the foreground logs to the terminal, and an agent of a fleet into the log of the fleet instead, see \fBase-agent-fleet\fR(1)).
+.sp
+With \fB-n\fR|\fB--lines\fR \fIn\fR, only the last \fIn\fR lines are shown (default: all). With \fB-f\fR|\fB--follow\fR, the last \fIn\fR lines (default: 10) are shown and then, in the style of \fBtail -f\fR, all newly appended lines are followed until interrupted. As \fB-n\fR is the number of lines, the name is given via the long option \fB--name\fR only. If no log file exists, this is just reported (at log level \fBinfo\fR).
+.IP \(bu 4
+\fBase agent adhoc stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Stop the agent named \fIname\fR (default: \fBadhoc\fR) by sending it \fBSIGTERM\fR, and wait (up to 5 minutes) until it aborted its running processings and put their tasks back. A not running agent is reported as such, without an error.
+.IP \(bu 4
+\fBase agent\fR \fIkind\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR \[lB]...\[rB]: The same commands for an agent of the definition kind \fIkind\fR (see \fBDESCRIPTION\fR), with the same options (except \fB--definition\fR), where the name defaults to \fIkind\fR.
+.RE 0
+.SH "OPTIONS"
+.SS "Agent Options"
+.P
+The following options are shared by all agents (see also \fBase-agent\fR(1)):
+.RS 0
+.IP \(bu 4
+\[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: The name of the agent (default: its kind, i.e., \fBadhoc\fR, resp. the definition kind \fIkind\fR), at most 64 letters, digits, underscores, and dashes, starting with a letter or digit, and neither the name of another agent kind, nor \fBrelay\fR or \fBfleet\fR.
+.sp
+It names the agent in its log lines (also in the shared processing log attachment \fBagent\fR), the \fBAssignee:\fR of the tasks it processes (see \fB--assign-name\fR), its default tag \fBase-agent-\fR\fIname\fR (lower-cased, see \fB--tag-name\fR), its default request name (see \fB--request-name\fR), its temporary directory, and its process files \fB.ase/agent/\fR\fIname\fR\fB.yaml\fR and \fB.ase/agent/\fR\fIname\fR\fB.log\fR. Hence, multiple ad-hoc agents are started under different names.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: The agent tool processing the tasks: \fBclaude\fR, \fBcopilot\fR, or \fBcodex\fR (default: \fB$ASE_TOOL\fR, else \fBclaude\fR). It is run headless (with \fBASE_HEADLESS=true\fR), i.e., via \fBclaude -p\fR, \fBcopilot -p\fR, resp. \fBcodex exec\fR (see \fBase-agent\fR(1)), and has to be found in \fB$PATH\fR.
+.IP \(bu 4
+\[lB]\fB-p\fR|\fB--parallel\fR \fInum\fR\[rB]: The maximum number of tasks processed in parallel, a positive integer (default: \fB1\fR). Ignored (with a warning) with \fB--serial\fR.
+.IP \(bu 4
+\[lB]\fB-T\fR|\fB--timeout\fR \fIduration\fR\[rB]: The maximum duration of processing a task, as \fInumber\fR \fIunit\fR with \fIunit\fR \fBs\fR, \fBm\fR, or \fBh\fR (default: \fB60m\fR), where a processing exceeding it fails. The preparing and the finishing of a processing are each limited to a fixed duration of 240 seconds in addition.
+.IP \(bu 4
+\[lB]\fB-o\fR|\fB--one-shot\fR\[rB]: Terminate the agent, instead of observing for further tasks, once a check of the task store finds no dispatchable task while it processes no task anymore. Intended for CI contexts. Not allowed in a fleet. A failed check of the task store is retried after a growing delay, where \fB--one-shot\fR gives up after three failures in a row and terminates with a non-zero exit status.
+.IP \(bu 4
+\[lB]\fB--agent-relay\fR \fIurl\fR\[rB]: The agent relay to pass the live presence of the agent to, as \fBase://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB] (HTTP) or \fBases://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB]\[lB]\fB?insecure\fR\[rB] (HTTPS, optionally without certificate verification) (default: the configured \fBproject.relay.url\fR, else none). See \fBase-agent-relay\fR(1).
+.IP \(bu 4
+\[lB]\fB-r\fR|\fB--repo\fR \fIurl\fR\[rB]: The Git repository to clone temporarily into the temporary directory of the agent, for processing every task without a \fBworktree\fR flow value in a temporary Git worktree of this clone (default: the Git working copy the agent is started in). Requires a task store not located in the working copy (i.e., not a local \fBase:\fR\fIpath\fR one). Silently ignored with \fB--workdir project\fR.
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--tempdir\fR \fIdir\fR\[rB]: The directory whose sub-directory \fIname\fR holds the temporary files of the agent, like the clone of \fB--repo\fR, where \fB%p\fR in \fIdir\fR is expanded to the process id of the agent, \fB%h\fR to a hash value unique to the process, and \fB%%\fR to \fB%\fR (default: a fresh, private directory below the system temporary directory).
+.sp
+A missing \fIdir\fR is created private to the current user, while an existing \fIdir\fR has to be a directory (no symbolic link) owned by the current user. Silently ignored with \fB--workdir project\fR.
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--foreground\fR\[rB]: Run the agent in the current process, logging to the terminal, until it is interrupted or stopped, instead of detaching it.
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show the usage information of the command and exit.
+.RE 0
+.SS "Definition Options"
+.P
+The following options form the \fIdefinition\fR of an agent. Each one is a flat long option \fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR (except the ungrouped ones), accepted by all agents (including the built-in ones), where the given options override the definition of the agent (see \fB--definition\fR and \fBDEFINITION FILES\fR). A \fIrepeatable\fR option can be given multiple times, each time adding a value.
+.P
+A given option also replaces its mutually exclusive alternatives of the definition: \fB--prompt-skill\fR replaces \fB--prompt-text\fR and \fB--prompt-file\fR, \fB--prompt-text\fR and \fB--prompt-file\fR replace each other and \fB--prompt-skill\fR with \fB--prompt-args\fR, and \fB--tag-retry\fR and \fB--tag-failure\fR replace each other.
+.SS "Ungrouped"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-D\fR|\fB--definition\fR \fIfile\fR|\fBbuiltin:\fR\fIkind\fR\[lB]\fB-\fR\fImode\fR\[rB]\[rB]: (\fBase agent adhoc\fR only) The definition to base the agent on: a definition file (see \fBDEFINITION FILES\fR), or, as \fBbuiltin:\fR\fIkind\fR\fB-\fR\fImode\fR (resp. \fBbuiltin:\fR\fIkind\fR for its default mode), the definition of a built-in agent (see \fBDESCRIPTION\fR), where all other given options override it. Example: \fBase agent adhoc
+start -n reviewer -D builtin:qualifier-qualify --tag-name
+ase-agent-reviewer\fR.
+.IP \(bu 4
+\[lB]\fB--title\fR \fItext\fR\[rB]: The one-line title of the operation of the agent (at most 80 characters), shown on the task boards: in the information line of the agent logs view and above the description in its pane \fBOperation\fR (default: none).
+.IP \(bu 4
+\[lB]\fB--description\fR \fItext\fR\[rB]: The brief description of the operation of the agent (about 3-6 lines, at most 600 characters, with its whitespace collapsed), shown on the task boards in the pane \fBOperation\fR of the agent logs view, word-wrapped onto its width (default: none).
+.IP \(bu 4
+\[lB]\fB--type\fR \fItype\fR\[rB]: The processing type: \fBphase\fR (default) to claim tasks by their lifecycle status, or \fBrequest\fR to process the prompt requests attached to tasks (see \fBDESCRIPTION\fR). The options \fB--unclaimed\fR, \fB--state-\fR*, \fB--tag-success\fR, \fB--tag-failure\fR, \fB--tag-retry\fR, \fB--assign-required\fR, and \fB--attach-skip\fR are allowed for \fBphase\fR only, the options \fB--request-\fR* for \fBrequest\fR only.
+.IP \(bu 4
+\[lB]\fB--workdir\fR \fIkind\fR\[rB]: The working directory of the processing (default: \fBproject\fR), which determines the working directory of the agent tool, the directories granted to it (via \fB--add-dir\fR), the holds and deferrals of the tasks, and the values of the placeholders \fB{workdir}\fR, \fB{source-dir}\fR, and \fB{changeset-worktree}\fR.
+.sp
+The temporary worktrees the agent creates itself are named \fIid\fR\fB-\fR\fIassign-name\fR resp. \fIid\fR\fB-\fR\fIchangeset-name\fR\fB-\fR\fIassign-name\fR (with every \fB#\fR of the task id replaced by \fB_\fR), so they equal those of the built-in agents if \fB--assign-name\fR is set to the built-in kind, while the worktree of a \fBbranch:\fR changeset is named after the branch (with every character other than letters, digits, \fB_\fR, and \fB-\fR replaced by \fB-\fR, runs of \fB-\fR reduced to one, and leading and trailing \fB-\fR and \fB_\fR removed), like by the skills:
+.RS 4
+.IP \(bu 4
+\fBproject\fR: the project root. \fB--repo\fR and \fB--tempdir\fR are silently ignored.
+.IP \(bu 4
+\fBsource\fR: the working copy holding the \fBSource:\fR (the project root, or with \fB--repo\fR a worktree of its temporary clone), where a \fBbranch:\fR source is additionally checked out in a temporary detached worktree \fIid\fR\fB-\fR\fIassign-name\fR (as \fB{source-dir}\fR, granted to the agent tool) only if the prompt template references \fB{source-dir}\fR (like \fBeditor\fR).
+.IP \(bu 4
+\fBchangeset\fR (\fIwrite\fR access, like \fBimplementer\fR): a \fBworktree\fR changeset in the project root, which, processed serially, is held, deferred until free of uncommitted changes, and switched onto a \fBbranch:\fR source, and, processed in parallel, yields the ASE worktree id of the task (created by the skill) as \fB{changeset-worktree}\fR; a \fBbranch:\fR changeset is held and checked out in the agent worktree named after the branch (created from the source if missing, refused if its directory already exists, else reused if already checked out, but then required free of uncommitted changes), yielding its ASE worktree id (unless the project root) as \fB{changeset-worktree}\fR, and removed afterwards only if clean (else preserved); an \fBattachment:\fR changeset is left to the skill.
+.IP \(bu 4
+\fBchangeset-read\fR (\fIreview\fR access, like \fBqualifier\fR): a \fBworktree\fR changeset staged in its context worktree, which becomes the working directory; a \fBbranch:\fR changeset left in place (to be addressed via \fB{changeset-name}\fR); an \fBattachment:\fR changeset applied staged in the temporary worktree \fIid\fR\fB-\fR\fIchangeset-name\fR\fB-\fR\fIassign-name\fR, detached at its base commit, which becomes the working directory.
+.IP \(bu 4
+\fBtarget\fR (\fIintegration\fR access, like \fBintegrator\fR): the project root, with access granted to the context worktree of a \fBworktree\fR changeset (whose ASE worktree id becomes \fB{changeset-worktree}\fR) and to the worktree of a \fBbranch:\fR changeset, where a \fBbranch:\fR target is checked out in the temporary worktree \fIid\fR\fB-\fR\fIassign-name\fR unless checked out already, published afterwards if moved (or rescued if not publishable), and the merged \fBbranch:\fR changeset is deleted from the origin.
+.RE 0
+.IP \(bu 4
+\[lB]\fB--lifecycle\fR \fImodel\fR\[rB]: (repeatable) A supported task lifecycle model, \fBsolo\fR, \fBteam\fR, or \fBenterprise\fR (default: every model containing all given states, resp. all models for \fBrequest\fR and with \fB--unclaimed\fR). The agent refuses to start for a project of any other model. All given states have to exist in all supported models (except with \fB--unclaimed\fR, whose incoming states are adapted onto the model of the project).
+.IP \(bu 4
+\[lB]\fB--serial\fR\[rB]: Process the tasks serially only, ignoring \fB--parallel\fR. A fleet refuses two serially processing agents of the same tag.
+.IP \(bu 4
+\[lB]\fB--unclaimed\fR\[rB]: (\fBphase\fR only) Process the tasks \fIunclaimed\fR (see \fBDESCRIPTION\fR): every task in one of the states of \fB--state-incoming\fR (each adapted onto the task lifecycle model of the project) which does not carry the tag, independent of its assignee and its predecessors, without claiming it, and without ever changing its status and its assignee (the tag options still apply). An agent of the same kind on the same host does not pick up a task already processed by another one.
+.sp
+Not allowed together with \fB--state-activity\fR, \fB--state-success\fR, \fB--state-failure\fR, \fB--state-phase\fR, \fB--state-passed\fR, \fB--state-verdict\fR, \fB--assign-required\fR, \fB--assign-success\fR, \fB--assign-failure\fR, the success criterion \fBstatus\fR, the hook \fBpasses\fR, and \fB--workdir changeset\fR resp. \fBtarget\fR (as the task can be claimed by another agent meanwhile).
+.IP \(bu 4
+\[lB]\fB--params\fR \fIname\fR\fB=\fR\fIvalue\fR\[rB]: (repeatable) The value of the parameter \fIname\fR declared by the definition (see \fBPARAMETERS\fR), where a later value of the same name wins. An undeclared \fIname\fR is refused.
+.RE 0
+.SS "State (\fB--type phase\fR only)"
+.P
+All states are case-insensitive (upper-cased), have to exist in the supported task lifecycle models, and the transitions from the incoming into the activity state, back (on interrupt), and from the activity state into all target states have to be reachable in these models. With \fB--unclaimed\fR, only \fB--state-incoming\fR is allowed instead, whose states have to exist in any task lifecycle model only.
+.RS 0
+.IP \(bu 4
+\[lB]\fB--state-incoming\fR \fIstate\fR\[rB]: The state of the tasks to claim. Mandatory for \fBphase\fR. Repeatable with \fB--unclaimed\fR, where each state is adapted onto the task lifecycle model of the project (a state of the model is kept, any other one is mapped onto its counterpart, e.g., \fBPLANNED\fR onto \fBPLANNING\fR for \fBteam\fR and onto \fBOPEN\fR for \fBsolo\fR), and with an explicit \fB--state-activity\fR, where a task is claimed from any of the states (e.g., \fBDRAFTED\fR and \fBPLANNING\fR into \fBPLANNING\fR).
+.IP \(bu 4
+\[lB]\fB--state-activity\fR \fIstate\fR\[rB]: The state of a task during its processing (default: the first incoming state, i.e., the claim is marked by the \fB:active\fR tag value only).
+.IP \(bu 4
+\[lB]\fB--state-success\fR \fIstate\fR\[rB]: The target state on success, or \fBprevious\fR for the incoming state the task was claimed from (default: the first incoming state).
+.IP \(bu 4
+\[lB]\fB--state-failure\fR \fIstate\fR\[rB]: The target state on failure, or \fBprevious\fR for the incoming state the task was claimed from (default: the first incoming state).
+.IP \(bu 4
+\[lB]\fB--state-phase\fR \fIstate\fR\[rB]: The \fIphase success state\fR, decoupled from the target state: a task the skill itself moves there counts as processed (see the success criterion \fBstatus\fR), and a task there carrying the tag counts as having passed the phase for its \fBAfter:\fR successors (default: the success state, resp. the activity state for a \fBprevious\fR success state).
+.IP \(bu 4
+\[lB]\fB--state-passed\fR \fIstate\fR\[rB]: The first state of the lifecycle model from which on a task has passed the phase for its \fBAfter:\fR successors (default: the phase state).
+.IP \(bu 4
+\[lB]\fB--state-verdict\fR \fIVERDICT\fR\fB=\fR\fISTATE\fR\[rB]: (repeatable) The target state per verdict (both upper-case words), overriding the success target state, but never the failure target state of a failed processing. Requires \fB--verdict-label\fR (or the hook \fBverdict\fR), and every verdict has to be accepted by \fB--verdict-allow\fR (if given).
+.RE 0
+.SS "Tag"
+.RS 0
+.IP \(bu 4
+\[lB]\fB--tag-name\fR \fItag\fR\[rB]: The tag of the processed tasks, of the form \fBase-agent-\fR\fIword\fR in lower-case and without \fB:\fR (default: \fBase-agent-\fR\fIname\fR, hence no sharing between differently named agents). It guards the tasks against a repeated processing: a task carrying it (plain or with any value) is not claimed again. For \fBrequest\fR, it is always the request state tag \fBase-agent-\fR\fIrequest-name\fR (resp. \fBase-agent-editor\fR for the request name \fBedit\fR), and any other value is refused.
+.IP \(bu 4
+\[lB]\fB--tag-success\fR \fItag\fR\[rB]: (\fBphase\fR only) The tag set on success: \fItag-name\fR (default, the plain tag), \fItag-name\fR\fB:\fR\fIvalue\fR (a lower-case \fIvalue\fR other than \fBactive\fR), or \fBnone\fR to untag the task. A foreign tag is refused, as the agent would claim the task again. \fBnone\fR is refused if a task returns into an incoming state on success (unless guarded by \fB--attach-skip\fR, by the hook \fBready\fR of a definition which itself declares \fBtag-success: none\fR, like the built-in \fBestimator\fR, as a hook \fBready\fR inherited from a definition without it, like the one of the built-in \fBimplementer\fR, does not guard against claiming the untagged task again, or by \fB--assign-required\fR with an \fB--assign-success\fR handing the task over to somebody else, like the built-in \fBrebooter\fR), e.g., always with \fB--unclaimed\fR. A found verdict is stored as the tag value instead.
+.IP \(bu 4
+\[lB]\fB--tag-failure\fR \fItag\fR\[rB]: (\fBphase\fR only) The tag set on failure, like \fB--tag-success\fR (default: \fItag-name\fR), e.g., \fItag-name\fR\fB:failed\fR to tell failures apart.
+.IP \(bu 4
+\[lB]\fB--tag-require\fR \fItag\fR\[rB]: (repeatable) A tag a claimable task has to carry, where a plain tag also matches the tag with any value.
+.IP \(bu 4
+\[lB]\fB--tag-exclude\fR \fItag\fR\[rB]: (repeatable) A tag a claimable task must not carry, where a plain tag also matches the tag with any value.
+.IP \(bu 4
+\[lB]\fB--tag-retry\fR\[rB]: (\fBphase\fR only) A shorthand for \fB--tag-failure none\fR (not allowed together with it): a failed task returning into the incoming state is claimed again, but held off by the agent process for an exponentially growing delay from 1 minute up to 1 hour.
+.RE 0
+.P
+The tag options never apply to an interrupted task (released untagged) or to a task left for a manual intervention (tagged \fItag-name\fR\fB:failed\fR, e.g., after a failed finishing or an unreachable resulting state), which does not count as passed for its successors.
+.SS "Assign"
+.RS 0
+.IP \(bu 4
+\[lB]\fB--assign-name\fR \fIwho\fR\[rB]: The assignee under which the agent claims, holds, recognizes, and releases the tasks, and which names its agent-owned worktrees and its mode as announced to the agent relay (default: the agent name), a name of letters, digits, \fB_\fR, \fB.\fR, \fB@\fR, and \fB-\fR, starting with a letter or digit. So a configured agent can act as, e.g., \fBrebooter\fR, although its agent name must not clash with a built-in kind.
+.IP \(bu 4
+\[lB]\fB--assign-required\fR\[rB]: (\fBphase\fR only) Claim only the tasks explicitly assigned to \fIwho\fR of \fB--assign-name\fR (like \fBrebooter\fR), instead of the unassigned ones, too.
+.IP \(bu 4
+\[lB]\fB--assign-success\fR \fIwho\fR\[rB]: The assignee to hand a task over to after its successful processing: a name, \fBnone\fR to unassign it, or \fBprevious\fR for the assignee before the claim (default: \fBnone\fR for \fBphase\fR, \fBprevious\fR for \fBrequest\fR). Applied only while the task is still assigned to the agent.
+.IP \(bu 4
+\[lB]\fB--assign-failure\fR \fIwho\fR\[rB]: The assignee to hand a task over to after its failed processing, like \fB--assign-success\fR (same defaults). An interrupted task always gets its previous assignee back, and a task left for a manual intervention is always unassigned.
+.RE 0
+.SS "Request (\fB--type request\fR only)"
+.RS 0
+.IP \(bu 4
+\[lB]\fB--request-name\fR \fIname\fR\[rB]: The name of the processed requests, i.e., of the attachments \fBkind="<name>"\fR, \fBkind="<name>-running"\fR, and \fBkind="<name>-failed"\fR (default: the agent name), a lower-case word of letters, digits, and dashes, not ending in \fB-running\fR or \fB-failed\fR, and none of the built-in agent kinds. The name \fBedit\fR processes the edit requests of key \fBE\fR of the task boards.
+.IP \(bu 4
+\[lB]\fB--request-done\fR \fIword\fR\[rB]: The word naming a processed task in the log lines (default: \fBprocessed\fR, e.g., \fBedited\fR).
+.RE 0
+.SS "Prompt"
+.P
+Exactly one of \fB--prompt-skill\fR, \fB--prompt-text\fR, or \fB--prompt-file\fR is required. Flags of the skills like \fB--next DONE\fR are never added implicitly, but always have to be given explicitly.
+.RS 0
+.IP \(bu 4
+\[lB]\fB--prompt-skill\fR \fIname\fR\[rB]: The skill to invoke, as \fIskill\fR or \fIplugin\fR\fB:\fR\fIskill\fR (letters, digits, \fB_\fR, \fB.\fR, and \fB-\fR).
+.sp
+It is invoked like the built-in agents do, i.e., as \fB/\fR\fIskill\fR (\fBclaude\fR and \fBcopilot\fR) resp. \fB$\fR\fIskill\fR (\fBcodex\fR), followed by a single space and the rendered arguments of \fB--prompt-args\fR only if these are non-empty, where an un-namespaced ASE skill (\fBase-*\fR) gets the plugin namespace \fBase:\fR for \fBclaude\fR only, a \fIplugin\fR\fB:\fR\fIskill\fR stays verbatim, and any other name (e.g., a project skill generated by \fBase-meta-workflow\fR) stays un-namespaced.
+.IP \(bu 4
+\[lB]\fB--prompt-args\fR \fItemplate\fR\[rB]: The arguments of the skill, as a template (see \fBTEMPLATES\fR) (default: \fB{id}\fR for \fBphase\fR, \fB{id}: {prompt}\fR for \fBrequest\fR). Allowed with \fB--prompt-skill\fR only.
+.IP \(bu 4
+\[lB]\fB--prompt-text\fR \fItemplate\fR\[rB]: The prompt text to pass as-is to the agent tool (instead of a skill), as a template (see \fBTEMPLATES\fR).
+.IP \(bu 4
+\[lB]\fB--prompt-file\fR \fIfile\fR\[rB]: A file with the prompt text (instead of a skill), whose content is a template (see \fBTEMPLATES\fR). It is read and validated on the start. In a definition file, a relative \fIfile\fR is relative to the definition file.
+.RE 0
+.SS "Prepare"
+.RS 0
+.IP \(bu 4
+\[lB]\fB--prepare-run\fR \fIcmd\fR\[rB]: (repeatable) A shell command run in the working directory before the prompt (e.g., \fBnpm ci\fR), where a failing command fails the processing without running the prompt.
+.sp
+It gets the environment variables \fBASE_TASK_ID\fR, \fBASE_TASK_TITLE\fR, \fBASE_TASK_SOURCE\fR, \fBASE_TASK_CHANGESET\fR, \fBASE_TASK_TARGET\fR (the raw flow values or their configured defaults), \fBASE_AGENT_NAME\fR, \fBASE_AGENT_WORKDIR\fR, and \fBASE_AGENT_PARAM_\fR\fINAME\fR per parameter (see \fBPARAMETERS\fR). Empty commands are refused.
+.RE 0
+.SS "Success"
+.RS 0
+.IP \(bu 4
+\[lB]\fB--success-criterion\fR \fIcriterion\fR\[rB]: (repeatable) A success criterion, where all given criteria have to hold, replacing the default \fBexit\fR and \fBclean\fR for \fBphase\fR, resp. \fBclean\fR and \fBchanged\fR for \fBrequest\fR:
+.RS 4
+.IP \(bu 4
+\fBexit\fR: an exit code 0 of the agent tool without timeout or interrupt.
+.IP \(bu 4
+\fBclean\fR: no output line reporting an error of the skill (a line starting with \fBERROR:\fR or containing \fB▶ ERROR:\fR).
+.IP \(bu 4
+\fBchanged\fR: (\fBrequest\fR only) a plan content changed since the claim, hence also succeeding on an interrupt after the plan was saved (like \fBeditor\fR).
+.IP \(bu 4
+\fBverdict\fR: a found verdict. Requires \fB--verdict-label\fR (or the hook \fBverdict\fR).
+.IP \(bu 4
+\fBattachment\fR: an attachment of \fB--attach-expect\fR created or changed by the processing (a leftover of an earlier processing does not count). Requires \fB--attach-expect\fR.
+.IP \(bu 4
+\fBstatus\fR: (\fBphase\fR only) the move into the phase success state (see \fB--state-phase\fR) by the skill itself.
+.RE 0
+.IP \(bu 4
+\[lB]\fB--success-match\fR \fIregex\fR\[rB]: (repeatable) A regular expression (JavaScript syntax) an output line has to match, e.g., \fBstatus:\[rs]W*plan integrated\[rs]b\fR.
+.RE 0
+.P
+An unmet criterion is logged, and a failed request is described in its \fB<name>-failed\fR attachment by the first applicable reason: a failed preparing or finishing command, \fBskill reported an error\fR, \fBagent tool
+failed\fR, else the reason of the first unmet criterion (e.g., \fBplan not
+changed\fR, \fBno verdict\fR, \fBno new or changed attachment "<spec>"\fR, or \fBno output line matching "<regex>"\fR).
+.SS "Verdict"
+.RS 0
+.IP \(bu 4
+\[lB]\fB--verdict-label\fR \fIlabel\fR\[rB]: The label after which the verdict is given in the output of a successfully exited agent tool: the verdict is the upper-case word following the label (after any non-word characters) on the last output line carrying it, e.g., \fBAPPROVE\fR for the label \fBREVIEW VERDICT\fR and the line \fB**REVIEW VERDICT**: **APPROVE**\fR. The hook \fBverdict\fR can determine it instead.
+.sp
+A verdict is stored lower-cased as the tag value (e.g., \fBase-agent-qualifier:approve\fR, instead of \fB--tag-success\fR) and mapped to a target state via \fB--state-verdict\fR. It is honored on success only: on a failed processing, the task is settled by \fB--tag-failure\fR and \fB--state-failure\fR instead.
+.IP \(bu 4
+\[lB]\fB--verdict-allow\fR \fIVERDICT\fR\[rB]: (repeatable) An accepted verdict, an upper-case word (default: the verdicts of \fB--state-verdict\fR, else any). A verdict not accepted counts as none. Requires \fB--verdict-label\fR (or the hook \fBverdict\fR).
+.RE 0
+.SS "Attach"
+.P
+An attachment \fIspec\fR is \fIkind\fR or \fImime-type\fR\fB;\fR\fIkind\fR (e.g., \fBtext/x-diff;draft\fR), matching the \fBkind\fR parameter of the attachment type exactly and, if given, its MIME type.
+.RS 0
+.IP \(bu 4
+\[lB]\fB--attach-output\fR \fIkind\fR\[rB]: Store the output lines of the prompt as the task attachment of type \fBtext/plain; charset=utf-8; kind="<kind>"\fR, replacing the one of an earlier processing.
+.IP \(bu 4
+\[lB]\fB--attach-expect\fR \fIspec\fR\[rB]: The attachment the success criterion \fBattachment\fR requires, which must not match the attachment of \fB--attach-output\fR (as this one is always created).
+.IP \(bu 4
+\[lB]\fB--attach-skip\fR \fIspec\fR\[rB]: (\fBphase\fR only) Leave every task already carrying such an attachment unclaimed (e.g., a task already carrying a draft).
+.IP \(bu 4
+\[lB]\fB--attach-changeset\fR \fIkind\fR\[rB]: (with \fB--workdir changeset\fR or \fBtarget\fR only) Store the \fIchange set snapshot\fR -- the view-only, text-only unified diff of the change set (without the \fB.ase\fR directory) -- as the task attachment of type \fBtext/x-diff; charset=utf-8; kind="<kind>"\fR, captured by the agent itself after the processing (before \fB--finish-commit\fR) and replacing the one of an earlier processing in place (keeping its \fBCreated:\fR key), like \fBimplementer\fR and \fBintegrator\fR with the kind \fBchangeset\fR.
+.sp
+With \fB--workdir changeset\fR, it covers the change set of a \fBworktree\fR or \fBbranch:\fR changeset from its fork point from the \fBSource:\fR on, with \fBbase\fR \fIcommit\fR (plus \fB, partial\fR unless the task reached \fB--state-phase\fR) in its \fBDesc:\fR key, while an \fBattachment:\fR changeset other than \fBattachment:\fR\fIkind\fR removes it as obsolete.
+.sp
+With \fB--workdir target\fR, it covers the change of the target branch by the integration of a \fBworktree\fR or \fBbranch:\fR changeset, with \fBbase\fR \fIcommit\fR\fB, merged\fR \fIcommit\fR in its \fBDesc:\fR key, unless the task did not reach \fB--state-phase\fR or the content of the target did not change. Without a change set, the task stays untouched.
+.RE 0
+.SS "Finish"
+.RS 0
+.IP \(bu 4
+\[lB]\fB--finish-commit\fR\[rB]: (with \fB--workdir changeset\fR only) Commit the work onto a \fBbranch:\fR changeset with the message \fIKind\fR\fB:\fR \fItitle\fR \fB(\fR\fIid\fR\fB)\fR and publish it, rescuing a branch which could not be published, like \fBimplementer\fR.
+.IP \(bu 4
+\[lB]\fB--finish-success\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a successful processing, with the environment variables of \fB--prepare-run\fR plus \fBASE_TASK_STATUS\fR, where a failing command fails the finishing.
+.IP \(bu 4
+\[lB]\fB--finish-failure\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a failed processing, with the same environment variables, where a failing command is only reported.
+.RE 0
+.P
+The preparing and finishing commands are limited by the fixed duration of 240 seconds of the preparing resp. finishing of a processing.
+.SH "TEMPLATES"
+.P
+The templates of \fB--prompt-args\fR, \fB--prompt-text\fR, and \fB--prompt-file\fR expand the following placeholders:
+.RS 0
+.IP \(bu 4
+\fB{id}\fR, \fB{title}\fR: The id and the title of the task.
+.IP \(bu 4
+\fB{prompt}\fR: The request prompt, with its whitespace collapsed into single spaces (\fBrequest\fR only).
+.IP \(bu 4
+\fB{source}\fR, \fB{changeset}\fR, \fB{target}\fR: The raw flow values of the frontmatter keys \fBSource:\fR, \fBChangeset:\fR, and \fBTarget:\fR, or their configured defaults \fBproject.task.default.*\fR, with their placeholder \fB{id}\fR replaced by the task id (with every character other than letters, digits, \fB_\fR, and \fB-\fR replaced by \fB-\fR, runs of \fB-\fR reduced to one, and leading and trailing \fB-\fR and \fB_\fR removed, e.g., \fB12\fR for \fB#12\fR and \fBFOO-12\fR for \fBFOO#12\fR).
+.IP \(bu 4
+\fB{source-type}\fR, \fB{source-name}\fR, \fB{changeset-type}\fR, \fB{changeset-name}\fR, \fB{target-type}\fR, \fB{target-name}\fR: The parsed flow values: the type \fBworktree\fR, \fBbranch\fR, or \fBattachment\fR, and the branch resp. attachment name, else empty, where a \fBTarget:\fR of \fBsource\fR reads as the \fBSource:\fR.
+.IP \(bu 4
+\fB{workdir}\fR: The working directory of the processing (see \fB--workdir\fR).
+.IP \(bu 4
+\fB{source-dir}\fR: The temporary worktree of a \fBbranch:\fR source, else empty.
+.IP \(bu 4
+\fB{changeset-worktree}\fR: The ASE worktree id under which the skill finds the changeset, else empty.
+.IP \(bu 4
+\fB{key:\fR\fIHeader\fR\fB}\fR: A frontmatter key \fIHeader\fR of the task.
+.IP \(bu 4
+\fB{param:\fR\fIname\fR\fB}\fR: The value of the parameter \fIname\fR declared by the definition (see \fBPARAMETERS\fR).
+.IP \(bu 4
+\fB{?\fR\fIcond\fR\fB:\fR\fItext\fR\fB}\fR: A conditional, which emits \fItext\fR (with placeholders, but without nested conditionals) only if \fIcond\fR holds, either \fIplaceholder\fR (the placeholder is non-empty) or \fIplaceholder\fR\fB=\fR\fIvalue\fR (the placeholder equals \fIvalue\fR), e.g., \fB{?source-dir: --int-source-dir
+"{source-dir}"}\fR or \fB{?changeset-type=branch:--branch
+{changeset-name}}\fR. A \fB{prompt}\fR used only within \fB{?prompt:\fR\fItext\fR\fB}\fR makes the prompt of the requests optional, e.g., \fB{id}:{?prompt:
+{prompt}}\fR.
+.RE 0
+.P
+All other text, including whitespace, is kept verbatim, \fB{{\fR and \fB}}\fR yield literal braces, and an unknown placeholder (or a malformed or unbalanced one) fails the start.
+.SH "DEFINITION FILES"
+.P
+A definition file carries the same keys as the definition options above (without the leading \fB--\fR), either flat (\fBstate-incoming:
+PLANNED\fR) or nested by group (\fBstate: { incoming: PLANNED }\fR), where a key must not be given both flat and nested, a list value repeats a repeatable option, a flag takes a boolean, and a relative \fBprompt-file\fR is relative to the definition file. A definition file is either:
+.RS 0
+.IP \(bu 4
+a YAML file (\fB.yaml\fR or \fB.yml\fR), declarative only, or
+.IP \(bu 4
+a TypeScript file (\fB.ts\fR or \fB.mts\fR, run via the type stripping of Node.js) or a JavaScript file (\fB.js\fR, \fB.mjs\fR, or \fB.cjs\fR), whose default export is the definition object or a (possibly asynchronous) function returning it, where \fB.mts\fR resp. \fB.mjs\fR avoid the reparsing warning of Node.js outside of a package of \fB"type": "module"\fR.
+.sp
+It is typed via the type \fBAgentDefinition\fR of the package \fB@rse/ase\fR (\fBimport type { AgentDefinition } from "@rse/ase"\fR and \fBexport default { ... } satisfies AgentDefinition\fR, with \fB@rse/ase\fR as a development dependency for the editor only, as the type import is erased). Only such a file can additionally carry \fIhooks\fR (its key \fBhooks\fR, see \fBHOOKS\fR).
+.RE 0
+.P
+Every definition file can additionally declare \fIparameters\fR (its key \fBparams\fR, see \fBPARAMETERS\fR).
+.P
+A definition file can extend a \fIbase definition\fR via its key \fBdefinition\fR: a further definition file (relative to the definition file) or, as \fBbuiltin:\fR\fIkind\fR\fB-\fR\fImode\fR (resp. \fBbuiltin:\fR\fIkind\fR), the definition of a built-in agent.
+.P
+Its options override those of the base definition (also replacing their mutually exclusive alternatives, and with a false flag unsetting the flag of the base definition), its parameter declarations extend those of the same name of the base definition field-wise (e.g., \fBparams: { severity: LOW }\fR changes just the default value), and its hooks replace those of the same name of the base definition. Base definitions can be chained arbitrarily deep, but never cyclic.
+.P
+For example, a \fB.ase/agents/implementer.mts\fR of \fBdefinition: "builtin:implementer-implement"\fR plus a \fBready\fR hook shadows the built-in \fBimplementer\fR while keeping its definition and its \fBpasses\fR hook, and a \fB.ase/agents/reviewer.yaml\fR of \fBdefinition: builtin:qualifier-judge\fR plus its own \fBtag: { name: ase-agent-reviewer }\fR runs a further judging agent of its own tag.
+.SH "PARAMETERS"
+.P
+A definition can declare \fIparameters\fR (its key \fBparams\fR, typed via \fBAgentParam\fR of the package \fB@rse/ase\fR): custom options of the agent, whose values are given on its start via \fB--params\fR \fIname\fR\fB=\fR\fIvalue\fR (resp. via the map \fBparams\fR of its section of a fleet configuration, see \fBase-agent-fleet\fR(1)). A parameter \fIname\fR consists of up to 64 letters, digits, underscores, and dashes, starting with a letter, and is declared by an object of the optional fields:
+.RS 0
+.IP \(bu 4
+\fBdesc\fR: The description of the parameter, cited in its errors.
+.IP \(bu 4
+\fBdefault\fR: The default value of the parameter (else empty).
+.IP \(bu 4
+\fBrequired\fR: Whether a non-empty value is required (default: \fBfalse\fR).
+.IP \(bu 4
+\fBallow\fR: The allowed values (a single value or a list), where an empty value is always allowed unless \fBrequired\fR.
+.RE 0
+.P
+A plain scalar instead of the object declares just the default value (e.g., \fBparams: { severity: HIGH }\fR). The values of all parameters are validated on the start, where an undeclared parameter, a missing required value, and a value not allowed are refused. Each declared parameter provides its value (empty if neither given nor defaulted) as:
+.RS 0
+.IP \(bu 4
+the placeholder \fB{param:\fR\fIname\fR\fB}\fR of the templates (see \fBTEMPLATES\fR), also usable in a conditional like \fB{?param:\fR\fIname\fR\fB:\fR\fItext\fR\fB}\fR;
+.IP \(bu 4
+\fBctx.params.\fR\fIname\fR (resp. \fBctx.params\[lB]"\fR\fIname\fR\fB"\[rB]\fR) of the hooks (see \fBHOOKS\fR);
+.IP \(bu 4
+the environment variable \fBASE_AGENT_PARAM_\fR\fINAME\fR of the commands of \fB--prepare-run\fR, \fB--finish-success\fR, and \fB--finish-failure\fR, with \fINAME\fR the upper-cased \fIname\fR with every \fB-\fR replaced by \fB_\fR, where two parameters of the same such variable are refused.
+.RE 0
+.SH "HOOKS"
+.P
+The \fIhooks\fR of a TypeScript or JavaScript definition file (its key \fBhooks\fR, typed via \fBAgentHooks\fR of the package \fB@rse/ase\fR) are the code-based extensions beyond the declarative options, which not only gate, but also shape the processing. A thrown error never terminates a running agent, but counts like a negative result with the error as its reason.
+.P
+The hooks receive the \fItask\fR (its \fBid\fR, \fBtitle\fR, \fBstatus\fR adapted to the task lifecycle model of the project, its flattened frontmatter \fBkeys\fR, and its \fBtags\fR) and a context \fIctx\fR, which provides:
+.RS 0
+.IP \(bu 4
+\fBagent\fR and \fBlifecycle\fR: The agent (its \fBname\fR, \fBkind\fR, \fBmode\fR, and \fBtag\fR) and the task lifecycle model of the project (its \fBname\fR and its \fBstates\fR).
+.IP \(bu 4
+\fBparams\fR: The values of all declared parameters, by their names (see \fBPARAMETERS\fR).
+.IP \(bu 4
+\fBsignal\fR: An \fBAbortSignal\fR, aborted on the interrupt of the agent (and, within the hooks of a job, on the timeout of its preparing resp. finishing), which a long-running hook should honor.
+.IP \(bu 4
+\fBflow(task, key)\fR: The parsed \fBSource\fR, \fBChangeset\fR, or \fBTarget\fR flow value (\fBtype\fR and \fBname\fR) of the task, or its configured default (where a \fBTarget:\fR of \fBsource\fR reads as the \fBSource:\fR), else \fBnull\fR if invalid.
+.IP \(bu 4
+\fBattachments(task)\fR, \fBplan(task)\fR, \fBtask(id)\fR, \fBtasks()\fR: The attachments of a task (their \fBtype\fR, \fBdesc\fR, and inline \fBdata\fR), the plan body of a task (else \fBnull\fR), a task by its id (else \fBnull\fR), and all tasks, where \fItask\fR is a task or its id.
+.IP \(bu 4
+\fBupdate(task, change)\fR: A change of a task in a single conditional update (retried on a concurrent change, resolving to \fBfalse\fR if the task vanished): \fBkeys\fR to set (or to remove with \fBnull\fR), except \fBStatus\fR, \fBAssignee\fR, \fBTags\fR, and \fBModified\fR; \fBtags\fR to \fBadd\fR (\fItag\fR or \fItag\fR\fB:\fR\fIvalue\fR, replacing the other occurrences of \fItag\fR) and to \fBremove\fR (\fItag\fR with any value, or exactly \fItag\fR\fB:\fR\fIvalue\fR), except the tag of the agent itself; and \fBattach\fR attachments (\fBkind\fR, \fBmime\fR (default: \fBtext/plain\fR), \fBdesc\fR, \fBdata\fR, replacing those of the same kind unless \fBreplace: false\fR), except the processing logs and the processed requests of the agent.
+.IP \(bu 4
+\fBexec(cmd, args, options)\fR: The run of a command without a shell (within the hooks of a job in the working directory of the job, else in the current directory, or in \fBoptions.cwd\fR, with the additional environment variables \fBoptions.env\fR and the standard input \fBoptions.input\fR), limited to 240 seconds and cancelled by \fBsignal\fR, resolving to its exit \fBcode\fR (or \fB-1\fR if it did not exit regularly), \fBstdout\fR, and \fBstderr\fR.
+.IP \(bu 4
+\fBlog(level, message)\fR: A log line of level \fBerror\fR, \fBwarning\fR, or \fBinfo\fR (within the hooks of a job into the processing log of the task, else into the log of the agent).
+.RE 0
+.P
+The hooks of a job additionally receive the \fIjob\fR: its working directory \fBdir\fR, the additional directories \fBdirs\fR granted to the agent tool, the temporary worktree \fBsourceDir\fR of a \fBbranch:\fR source, the ASE worktree id \fBchangesetWorktree\fR of the changeset, and, for \fBrequest\fR, the raw \fBrequest\fR prompt. The hooks are, in the order of their invocation:
+.RS 0
+.IP \(bu 4
+\fBstart(ctx)\fR: The initialization of the agent (e.g., opening a connection) on its start, where a thrown error refuses the start.
+.IP \(bu 4
+\fBorder(tasks, ctx)\fR: The prioritization of the dispatchable tasks (given in natural id order) on each dispatching: the tasks (or their ids) in the order to claim them, where an omitted task is not claimed this time (a failed hook keeps the natural id order and is warned about once per change).
+.IP \(bu 4
+\fBpasses(pred, succ, ctx)\fR: (\fBphase\fR without \fB--unclaimed\fR only, synchronous) Whether the predecessor \fIpred\fR passed the phase of the agent for its successor \fIsucc\fR, or \fBundefined\fR for the default decision by \fB--state-phase\fR and \fB--state-passed\fR (a failed hook lets the successor wait and is warned about once).
+.IP \(bu 4
+\fBready(task, ctx)\fR: Whether a dispatchable task is claimed now, checked right before its claim (after \fB--attach-skip\fR): \fBtrue\fR to claim it, \fBfalse\fR to silently skip it (e.g., as the result of an earlier processing already guards it, like the valid \fBEffort:\fR key for \fBestimator\fR), or the reason to wait for (reported once per change of it).
+.IP \(bu 4
+\fBprepare(task, job, ctx)\fR: The preparing of the job in its working directory, after the commands of \fB--prepare-run\fR, where a thrown error fails the processing without invoking the agent tool.
+.IP \(bu 4
+\fBprompt(task, prompt, job, ctx)\fR: The prompt of the job, given the configured \fIprompt\fR rendered from its template (\fB{ skill, args }\fR or \fB{ text }\fR): \fB{ skill, args }\fR, \fB{ text }\fR, a plain prompt text, or \fBundefined\fR to keep the configured one, where a thrown error fails the processing.
+.IP \(bu 4
+\fBverdict(task, result, ctx)\fR: (after a successful agent tool only) The verdict of the result (an upper-case word, accepted only if listed by \fB--verdict-allow\fR), an empty string for none, or \fBundefined\fR to keep the one found after \fB--verdict-label\fR (if any). This hook can stand in for \fB--verdict-label\fR (also for the criterion \fBverdict\fR and for \fB--state-verdict\fR).
+.IP \(bu 4
+\fBsuccess(task, result, ctx)\fR: An additional success criterion after all others (where \fIresult\fR carries \fBok\fR, the \fBoutput\fR lines, and the found \fBverdict\fR): \fBtrue\fR if met, else \fBfalse\fR or the reason why it is not met.
+.IP \(bu 4
+\fBsettle(task, outcome, ctx)\fR: The settling of the processed task (where \fIoutcome\fR carries its \fBsuccess\fR, the \fBreasons\fR of the unmet success criteria, and the \fBresult\fR), overriding the configured one: its target \fBstate\fR (\fBphase\fR without \fB--unclaimed\fR only, still required to be reachable from the activity state), the value of its \fBtag\fR (\fBphase\fR only, a lower-case value, or \fBnull\fR to untag it, refused if the task would return into an incoming state unguarded by \fB--attach-skip\fR, the hook \fBready\fR, or the handover of a required assignment, see \fB--tag-success\fR), and its \fBassignee\fR (a name, \fBnone\fR, or \fBprevious\fR, but not with \fB--unclaimed\fR), where an omitted field (or \fBundefined\fR for all) keeps the configured settling, and a failed hook keeps the configured settling (and is warned about).
+.IP \(bu 4
+\fBfinish(task, outcome, job, ctx)\fR: The finishing of the job in its working directory, after the finishing of its work (e.g., the commit of \fB--finish-commit\fR) and before \fB--finish-success\fR resp. \fB--finish-failure\fR, where a thrown error fails the finishing of a successful processing (like a failed \fB--finish-success\fR), but is only reported for a failed one.
+.IP \(bu 4
+\fBstop(ctx)\fR: The teardown of the agent (e.g., closing a connection) on its termination, with a fresh \fBsignal\fR (a failed hook is only reported).
+.RE 0
+.SH "AGENT RELAY AND RUNS"
+.P
+An agent of a definition kind resp. an ad-hoc agent announces itself to the agent relay (see \fBase-agent-relay\fR(1)) with its kind (resp. \fBadhoc\fR), its \fB--assign-name\fR as its mode, and, for \fBrequest\fR, its request name (suggested by key \fBR\fR of the task boards). Its runs are recorded per tag (below \fBagent-tag-\fR\fIword\fR\fB/\fR\fIstore-hash\fR of the \fIper-user state directory\fR for the tag \fBase-agent-\fR\fIword\fR), so the recoveries of differently configured agents never affect each other.
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default of \fB--tool\fR.
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The bearer token of the agent relay, if not embedded in its URL.
+.IP \(bu 4
+\fBASE_HEADLESS\fR: Set to \fBtrue\fR for the agent tool processes spawned by the agent.
+.IP \(bu 4
+\fBASE_TASK_ID\fR, \fBASE_TASK_TITLE\fR, \fBASE_TASK_SOURCE\fR, \fBASE_TASK_CHANGESET\fR, \fBASE_TASK_TARGET\fR, \fBASE_AGENT_NAME\fR, \fBASE_AGENT_WORKDIR\fR, \fBASE_AGENT_PARAM_\fR\fINAME\fR, \fBASE_TASK_STATUS\fR: Set for the commands of \fB--prepare-run\fR, \fB--finish-success\fR, and \fB--finish-failure\fR (the latter only for the finishing commands).
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/agents/\fR\fIkind\fR\fB.\fR\fIext\fR: The definition files of the definition kinds of the project.
+.IP \(bu 4
+\fIper-user configuration directory\fR\fB/agents/\fR\fIkind\fR\fB.\fR\fIext\fR: The definition files of the definition kinds of the user.
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.yaml\fR: The process state (process id and process start time) of the agent named \fIname\fR, existing while the agent runs.
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.log\fR: The log of the agent named \fIname\fR run in the background.
+.IP \(bu 4
+\fIper-user state directory\fR\fB/agent-tag-\fR\fIword\fR\fB/\fR\fIstore-hash\fR\fB/\fR\fIrun-id\fR\fB.lock\fR and \fB.json\fR: The run lock and run record of each agent process of the tag \fBase-agent-\fR\fIword\fR, used to recover the tasks of terminated agent processes.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fBstart\fR and \fBstop\fR exit with status 0 on success (also for an agent already running resp. not running) and 1 on any error. \fBstatus\fR exits with status 1 if the agent is not running. \fBlog\fR exits with status 0.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# a qualification agent deciding on the task status by its verdict
+$ ase agent adhoc start -n reviewer --state-incoming IMPLEMENTED \[rs]
+    --state-activity QUALIFYING --state-phase QUALIFIED --workdir changeset-read \[rs]
+    --prompt-skill ase-repo-review --prompt-args "{?changeset-type=branch:--branch {changeset-name}}" \[rs]
+    --verdict-label "REVIEW VERDICT" --state-verdict APPROVE=QUALIFIED --state-verdict REJECT=DECLINED \[rs]
+    --success-criterion exit --success-criterion verdict
+
+# a request agent attaching a lint report (requested via "ase task request <id> lint <prompt>")
+$ ase agent adhoc start -n linter --type request --request-name lint --workdir source \[rs]
+    --prompt-text "Lint the source code changed by task {id} with focus on: {prompt}" \[rs]
+    --success-criterion exit --success-criterion clean --attach-output lint-report
+
+# an agent running a project skill generated by "ase-meta-workflow" on the planned tasks
+$ ase agent adhoc start -n workflow --state-incoming PLANNED --tag-require workflow \[rs]
+    --prompt-skill my-workflow --prompt-args "{id}"
+
+# a further qualification agent of its own tag, based on a built-in definition
+$ ase agent adhoc start -n reviewer -D builtin:qualifier-qualify --tag-name ase-agent-reviewer
+
+# an agent of a definition kind of the project (see .ase/agents/reviewer.mts below)
+$ ase agent reviewer start -p 2
+$ ase agent reviewer log -f
+.fi
+.RE
+.P
+A YAML definition file \fB.ase/agents/linter.yaml\fR, yielding the definition kind \fBlinter\fR:
+.P
+.RS 2
+.nf
+type:               request
+workdir:            source
+request:
+    name:           lint
+prompt:
+    text:           "Lint the source code changed by task {id} with focus on: {prompt}"
+success:
+    criterion:      \[lB] exit, clean \[rB]
+attach:
+    output:         lint-report
+.fi
+.RE
+.P
+A TypeScript definition file \fB.ase/agents/reviewer.mts\fR with hooks, yielding the definition kind \fBreviewer\fR:
+.P
+.RS 2
+.nf
+import type { AgentDefinition } from "@rse/ase"
+export default {
+    type:      "phase",
+    lifecycle: "enterprise",
+    workdir:   "changeset-read",
+    state:     { incoming: "IMPLEMENTED", activity: "QUALIFYING", phase: "QUALIFIED" },
+    tag:       { name: "ase-agent-reviewer", require: "security" },
+    prompt:    { skill: "ase-repo-review", args: "{?changeset-type=branch:--branch {changeset-name}}" },
+    verdict:   { label: "REVIEW VERDICT", allow: \[lB] "APPROVE", "REJECT" \[rB] },
+    success:   { criterion: \[lB] "exit", "verdict" \[rB] },
+    params: {
+        severity: { desc: "severity of the findings a rejecting review has to cite", default: "HIGH", allow: \[lB] "LOW", "MEDIUM", "HIGH" \[rB] }
+    },
+    hooks: {
+        /*  review a task only once its changeset is a branch  */
+        ready: (task, ctx) =>
+            ctx.flow(task, "Changeset")?.type === "branch" ? true : "a \[rs]"branch:\[rs]" changeset",
+
+        /*  require a rejecting review to cite at least one finding of the configured severity  */
+        success: (_task, result, ctx) =>
+            result.verdict !== "REJECT" || result.output.some((line) => new RegExp(`\[rs]\[rs]b${ctx.params.severity}\[rs]\[rs]b`).test(line)) ||
+            `rejecting review without ${ctx.params.severity} findings`
+    }
+} satisfies AgentDefinition
+.fi
+.RE
+.P
+Started via \fBase agent reviewer start --params severity=MEDIUM\fR (resp. with \fBparams: { severity: MEDIUM }\fR in its section of a fleet configuration).
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-agent\fR(1), \fBase-agent-rebooter\fR(1), \fBase-agent-condenser\fR(1), \fBase-agent-researcher\fR(1), \fBase-agent-implementer\fR(1), \fBase-agent-qualifier\fR(1), \fBase-agent-integrator\fR(1), \fBase-agent-editor\fR(1), \fBase-agent-estimator\fR(1), \fBase-agent-relay\fR(1), \fBase-agent-fleet\fR(1), \fBase-task-request\fR(1), \fBase-task-board\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR