@rse/ase 1.0.7 → 2.0.0

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

@@ -0,0 +1,217 @@
+.TH "ASE-AGENT-RESEARCHER" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent-researcher\fR - Research Agent
+.SH "SYNOPSIS"
+.P
+\fBase agent researcher start\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fBclaude\fR|\fBcopilot\fR|\fBcodex\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-m\fR|\fB--mode\fR \fBphase\fR|\fBrequest\fR\[rB] \[lB]\fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR \fIvalue\fR \[lB]...\[rB]\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]
+.P
+\fBase agent researcher status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent researcher 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 researcher stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase agent researcher\fR researches for the plans of tasks, combining a Web research with a grounding in the source artifacts of the project (see the skill \fBase-task-research\fR). It runs in one of two modes (see \fB--mode\fR): the mode \fBphase\fR (the default) researches the plans of the tasks explicitly assigned to it in the \fBPlanning\fR phase of the \fBenterprise\fR task lifecycle model and is intended for \fIresearching and grounding the plan content\fR, while the mode \fBrequest\fR processes the research requests of tasks in any task lifecycle model and is intended for \fItopic-driven research\fR.
+.P
+In the mode \fBphase\fR (refused for any task lifecycle model other than \fBenterprise\fR), as a plan is researched only on the explicit request of a human, the researcher claims only the tasks in the state \fBDRAFTED\fR whose \fBAssignee:\fR frontmatter key already is its agent name (default: \fBresearcher\fR), i.e., which a human assigned to the researcher. Such a task is claimed immediately, without waiting for its \fBAfter:\fR predecessors (and, for an explicit epic, its group members), except for a predecessor still being processed by a researcher in the mode \fBphase\fR or a cancelled \fBAfter:\fR predecessor. It moves each claimed task into \fBPLANNING\fR, tags it with \fBase-agent-researcher:active\fR, and researches the plan itself via the skill invocation \fBase-task-research
+--refine\fR \fIid\fR in the working copy, grounded in the \fBSource:\fR of the task (like in the mode \fBrequest\fR, see below), appending the research report to the \fBresearch\fR attachment of the task and refining the plan by the recommendations of the report. The processing succeeds under the same conditions as in the mode \fBrequest\fR. Afterwards, on success as well as on failure, the researcher puts the task back into \fBDRAFTED\fR, removes its tag, and unassigns it. As the task is no longer assigned to the researcher, it is not claimed again, while assigning it to the researcher again requests another research. On an interrupt, the task is put back, untagged and with its previous assignee (i.e., still assigned to the researcher), into \fBDRAFTED\fR.
+.P
+In the mode \fBrequest\fR, the researcher processes the research requests of tasks. Like the request agent \fBeditor\fR, it is then bound to no phase and supports all task lifecycle models (\fBsolo\fR, \fBteam\fR, and \fBenterprise\fR).
+.P
+A research request is added by key \fBR\fR of the task board (see \fBase-task-board\fR(1)) or by \fBase task request\fR \fIid\fR \fBresearch\fR \[lB]\fItopic\fR\[rB] (see \fBase-task-request\fR(1)) as an attachment of type \fBtext/plain; charset=utf-8; kind="research"\fR with the topic as its data, mirrored in the tag \fBase-agent-research:pending\fR of the task (aggregated as \fB:active\fR while one is processed and as \fB:failed\fR once one failed). The topic is optional: a request without a topic researches the task plan itself.
+.P
+The researcher observes the tasks with this tag, except those in an activity status of the task lifecycle model, where the task is actively worked on (\fBteam\fR: \fBIMPLEMENTING\fR; \fBenterprise\fR: \fBPLANNING\fR, \fBIMPLEMENTING\fR, \fBQUALIFYING\fR, and \fBINTEGRATING\fR), and those still held by a phase agent (tagged \fBase-agent-\fR\fIkind\fR\fB:active\fR), which wait until their status changes resp. their tag is released.
+.P
+It claims the oldest request of such a task in a single conditional save by turning it into \fBkind="research-running"\fR and setting the \fBAssignee:\fR of the task to its agent name (remembering the previous assignee in the request), which keeps all other agents off the task during the research without touching its status. The request of a finished task is turned into \fBkind="research-failed"\fR instead.
+.P
+It then researches the topic via the skill invocation \fBase-task-research --refine\fR \fIid\fR\fB:\fR \[lB]\fItopic\fR\[rB] (with the whitespace of the topic collapsed) in the working copy, grounded in the \fBSource:\fR of the task, where a \fBbranch:\fR\fIname\fR source is checked out in the temporary, detached Git worktree \fB.ase/worktree/.temp/\fR\fIid\fR\fB-researcher\fR, passed to the skill via its internal option \fB--int-source-dir\fR, and removed afterwards. The skill combines a Web research with a grounding in the source artifacts of the project, appends its research report to the \fBresearch\fR attachment of the task (of type \fBtext/markdown;
+charset=utf-8; kind="research"\fR), and refines the plan by the recommendations of the report, all in a single save, which happens only if the task was not changed meanwhile.
+.P
+Finally, in a single save, the researcher restores the previous assignee of the task (unless reassigned meanwhile) and removes the request if the \fBresearch\fR attachment was created or changed and the skill reported the attached research, or else turns it back into \fBkind="research"\fR on an interrupt, resp. into \fBkind="research-failed"\fR (with the reason, e.g., \fBskill reported an error\fR, \fBagent tool failed\fR, or \fBno new or changed attachment "text/markdown;research"\fR) otherwise.
+.P
+A finalization failing even after its retries is retried on every further dispatching.
+.P
+On its start in the mode \fBrequest\fR, the researcher marks the requests left in \fBkind="research-running"\fR by any terminated researcher process of the same user on the same host (whose run lock is gone or stale and whose process is no longer alive) as failed (\fBkind="research-failed"\fR), and restores the previous assignees of their tasks.
+.P
+Both modes can run side by side as two agents of the kind \fBresearcher\fR under different names (e.g., \fBresearcher\fR and \fBresearcher-request\fR). See \fBase-agent\fR(1) for the common mechanics of all agents.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information of \fBase agent researcher\fR (or of the given sub-command) only.
+.RE 0
+.P
+All other options belong to the sub-commands (see \fBCOMMANDS\fR).
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase agent researcher start\fR \[lB]\fIoptions\fR\[rB]: Start the researcher agent in the background, logging into \fB.ase/agent/\fR\fIname\fR\fB.log\fR. The agent is validated and initialized (e.g., its agent tool is looked up and the task lifecycle model is checked) before the command returns (waiting up to 30 seconds), so a failing agent is reported together with the tail of its log. An agent of the same name already running is left alone. The options are:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: The name of the agent (default: \fBresearcher\fR): up to 64 letters, digits, underscores, and dashes, starting with a letter or digit, other than the name of another agent kind, \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, 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. Agents of the kind \fBresearcher\fR under different names form a pool, competing for the same tasks and processing them in parallel to each other.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: The headless agent tool processing the tasks: \fBclaude\fR (\fIAnthropic Claude Code CLI\fR), \fBcopilot\fR (\fIGitHub Copilot CLI\fR), or \fBcodex\fR (\fIOpenAI Codex CLI\fR) (default: \fB$ASE_TOOL\fR, else \fBclaude\fR). Its command 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 by this agent (default: \fB1\fR), a positive integer.
+.IP \(bu 4
+\[lB]\fB-T\fR|\fB--timeout\fR \fIduration\fR\[rB]: The maximum duration of processing a task (the run of the agent tool), as \fInumber\fR \fIunit\fR (without a space) with \fIunit\fR \fBs\fR (seconds), \fBm\fR (minutes), or \fBh\fR (hours) (default: \fB60m\fR). A processing exceeding it is aborted and counts as failed.
+.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 the agent processes no task anymore -- intended for CI contexts like GitHub Actions, and not allowed in a fleet. A check of the task store failing three times in a row then terminates the agent with a non-zero exit status (instead of being retried endlessly after a growing delay).
+.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] resp. \fBases://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB]\[lB]\fB?insecure\fR\[rB] for HTTPS (default: the configured \fBproject.relay.url\fR, else none). See \fBAGENT RELAY\fR in \fBase-agent\fR(1). In the mode \fBrequest\fR, the agent is announced there as processing the \fBresearch\fR requests, which may have an empty prompt.
+.IP \(bu 4
+\[lB]\fB-r\fR|\fB--repo\fR \fIurl\fR\[rB]: The Git repository to clone once into the temporary directory of the agent, where every task without a \fBworktree\fR value is processed in its own temporary Git worktree of this clone (default: none, i.e., all tasks are processed in the Git working copy the agent is started in, which is hence mandatory).
+.sp
+Requires a task store not located in the working copy (i.e., not a local \fBase:\fR\fIpath\fR one). See \fBWORKING COPY, CLONES, AND WORKTREES\fR in \fBase-agent\fR(1).
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--tempdir\fR \fIdir\fR\[rB]: Create the temporary directory of the agent as the sub-directory \fIname\fR of \fIdir\fR, where \fB%p\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). 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.
+.IP \(bu 4
+\[lB]\fB-m\fR|\fB--mode\fR \fImode\fR\[rB]: The mode of the agent (default: \fBphase\fR): \fBphase\fR researches and grounds the plans of the tasks explicitly assigned to the researcher in \fBDRAFTED\fR, while \fBrequest\fR researches the topics of the \fBresearch\fR requests of the tasks in any task lifecycle model. An invalid mode is an error. The built-in values of the following options are given per mode where they differ, and in the mode \fBrequest\fR, the options for \fBphase\fR only (\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 not allowed.
+.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. Built-in: \fBResearch and ground the plans of assigned tasks\fR (mode \fBphase\fR) resp. \fBResearch topics for tasks on request\fR (mode \fBrequest\fR).
+.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. Built-in: a description of the operation of the mode.
+.IP \(bu 4
+\[lB]\fB--type\fR \fBphase\fR|\fBrequest\fR\[rB]: The processing type: \fBphase\fR claims the tasks by their lifecycle status, \fBrequest\fR processes the prompt requests attached to the tasks. Generic default: \fBphase\fR. Built-in: \fBphase\fR (mode \fBphase\fR) resp. \fBrequest\fR (mode \fBrequest\fR).
+.IP \(bu 4
+\[lB]\fB--workdir\fR \fIkind\fR\[rB]: The working directory of the agent tool: \fBproject\fR, \fBsource\fR, \fBchangeset\fR, \fBchangeset-read\fR, or \fBtarget\fR. Generic default: \fBproject\fR. Built-in: \fBsource\fR.
+.IP \(bu 4
+\[lB]\fB--lifecycle\fR \fImodel\fR\[rB]: A supported task lifecycle model (\fBsolo\fR, \fBteam\fR, or \fBenterprise\fR, repeatable). Generic default: every model containing all given states, resp. all models for \fBrequest\fR and with \fB--unclaimed\fR. Built-in: \fBenterprise\fR (mode \fBphase\fR) resp. not set (mode \fBrequest\fR). Hence, all task lifecycle models are supported in the mode \fBrequest\fR.
+.IP \(bu 4
+\[lB]\fB--serial\fR\[rB]: Process the tasks serially only, ignoring \fB--parallel\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--unclaimed\fR\[rB]: Process the tasks of the incoming states without claiming them (\fBphase\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--params\fR \fIname\fR\fB=\fR\fIvalue\fR\[rB]: The value of a parameter declared by the definition (repeatable). Built-in: none declared.
+.IP \(bu 4
+\[lB]\fB--state-incoming\fR \fIstate\fR\[rB]: A state of the tasks to claim (mandatory for \fBphase\fR, repeatable with \fB--unclaimed\fR or \fB--state-activity\fR only). Built-in: \fBDRAFTED\fR (mode \fBphase\fR).
+.IP \(bu 4
+\[lB]\fB--state-activity\fR \fIstate\fR\[rB]: The state of a task during its processing. Built-in: \fBPLANNING\fR (mode \fBphase\fR).
+.IP \(bu 4
+\[lB]\fB--state-success\fR \fIstate\fR\[rB], \[lB]\fB--state-failure\fR \fIstate\fR\[rB]: The target state on success resp. failure, or \fBprevious\fR for the incoming state of the claim. Built-in: \fBDRAFTED\fR (mode \fBphase\fR).
+.IP \(bu 4
+\[lB]\fB--state-phase\fR \fIstate\fR\[rB]: The phase success state. Built-in: not set (mode \fBphase\fR), hence \fBDRAFTED\fR.
+.IP \(bu 4
+\[lB]\fB--state-passed\fR \fIstate\fR\[rB]: The first state from which on a task has passed the phase for its \fBAfter:\fR successors. Built-in: not set (mode \fBphase\fR), hence \fBDRAFTED\fR, the first state, so the predecessors impose no gate.
+.IP \(bu 4
+\[lB]\fB--tag-name\fR \fItag\fR\[rB]: The tag of the processed tasks (\fBase-agent-\fR\fIword\fR). Generic default: \fBase-agent-\fR\fIname\fR, resp. for \fBrequest\fR always \fBase-agent-\fR\fIrequest-name\fR. Built-in: not set (mode \fBphase\fR, hence \fBase-agent-researcher\fR) resp. \fBase-agent-research\fR (mode \fBrequest\fR, derived from the request name \fBresearch\fR).
+.IP \(bu 4
+\[lB]\fB--tag-success\fR \fItag\fR\[rB], \[lB]\fB--tag-failure\fR \fItag\fR\[rB]: The tag on success resp. failure (\fBphase\fR only). Built-in: \fBnone\fR (mode \fBphase\fR), as the unassignment of a processed task keeps it from being claimed again.
+.IP \(bu 4
+\[lB]\fB--tag-require\fR \fItag\fR\[rB]: A tag a claimable task has to carry (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-exclude\fR \fItag\fR\[rB]: A tag a claimable task must not carry (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-name\fR \fIwho\fR\[rB]: The assignee under which the tasks are claimed, held, recognized, and released, and which names the agent-owned worktrees. Generic default: the agent name. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-required\fR\[rB]: Claim only the tasks explicitly assigned to \fIwho\fR of \fB--assign-name\fR (\fBphase\fR only). Built-in: enabled (mode \fBphase\fR).
+.IP \(bu 4
+\[lB]\fB--assign-success\fR \fIwho\fR\[rB]: The assignee of a task after its successful processing: a name, \fBnone\fR, or \fBprevious\fR. Generic default: \fBnone\fR for \fBphase\fR, \fBprevious\fR for \fBrequest\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-failure\fR \fIwho\fR\[rB]: The assignee of a task after its failed processing: a name, \fBnone\fR, or \fBprevious\fR. Generic default: \fBnone\fR for \fBphase\fR, \fBprevious\fR for \fBrequest\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--request-name\fR \fIname\fR\[rB]: The name of the processed requests (\fBrequest\fR only). Generic default: the agent name. Built-in: \fBresearch\fR (mode \fBrequest\fR).
+.IP \(bu 4
+\[lB]\fB--request-done\fR \fIword\fR\[rB]: The word naming a processed task in the log lines (\fBrequest\fR only). Generic default: \fBprocessed\fR. Built-in: \fBresearched\fR (mode \fBrequest\fR).
+.IP \(bu 4
+\[lB]\fB--prompt-skill\fR \fIname\fR\[rB]: The skill to invoke (mutually exclusive with \fB--prompt-text\fR and \fB--prompt-file\fR). Built-in: \fBase-task-research\fR.
+.IP \(bu 4
+\[lB]\fB--prompt-args\fR \fItemplate\fR\[rB]: The argument template of the skill. Generic default: \fB{id}\fR for \fBphase\fR, \fB{id}: {prompt}\fR for \fBrequest\fR. Built-in: \fB--refine{?source-dir: --int-source-dir
+"{source-dir}"} {id}\fR (mode \fBphase\fR) resp. \fB--refine{?source-dir:
+--int-source-dir "{source-dir}"} {id}:{?prompt: {prompt}}\fR (mode \fBrequest\fR), where the conditional \fB{?prompt:...}\fR makes the prompt optional.
+.IP \(bu 4
+\[lB]\fB--prompt-text\fR \fItemplate\fR\[rB]: The prompt text template to invoke instead of a skill. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--prompt-file\fR \fIfile\fR\[rB]: The file with the prompt text template to invoke instead of a skill. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--prepare-run\fR \fIcmd\fR\[rB]: A shell command run in the working directory before the prompt (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--success-criterion\fR \fIcriterion\fR\[rB]: A success criterion: \fBexit\fR, \fBclean\fR, \fBchanged\fR, \fBverdict\fR, \fBattachment\fR, or \fBstatus\fR (repeatable). Generic default: \fBexit\fR and \fBclean\fR for \fBphase\fR, \fBclean\fR and \fBchanged\fR for \fBrequest\fR. Built-in: \fBexit\fR, \fBclean\fR, and \fBattachment\fR.
+.IP \(bu 4
+\[lB]\fB--success-match\fR \fIregex\fR\[rB]: A regular expression an output line has to match (repeatable). Built-in: \fBstatus:\[rs]W*research
+attached\[rs]b\fR.
+.IP \(bu 4
+\[lB]\fB--verdict-label\fR \fIlabel\fR\[rB]: The label after which the verdict is given in the output. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--verdict-allow\fR \fIVERDICT\fR\[rB]: An accepted verdict (repeatable). Generic default: the verdicts of \fB--state-verdict\fR, else any. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-output\fR \fIkind\fR\[rB]: The kind of the attachment storing the output lines of the prompt. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-expect\fR \fIspec\fR\[rB]: The attachment \[lB]\fImime-type\fR\fB;\fR\[rB]\fIkind\fR to be created or changed by the processing for the success criterion \fBattachment\fR. Built-in: \fBtext/markdown;research\fR.
+.IP \(bu 4
+\[lB]\fB--finish-success\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a successful processing. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--finish-failure\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a failed processing. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--foreground\fR\[rB]: Run the agent in the current process instead, logging to the terminal, until it is interrupted (e.g., via \fBCTRL+C\fR) or stopped, where an agent of the same name already running is an error.
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show the usage information of the sub-command only.
+.RE 0
+.IP "" 4
+The options \fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR above override the built-in definition of the mode of the agent (where an option also replaces its mutually exclusive alternatives, e.g., \fB--prompt-text\fR replaces the skill of \fB--prompt-skill\fR), while the agent keeps the identity of its kind (its runs, its presence, and its agent-owned worktrees are named after \fBresearcher\fR). See \fBase-agent-adhoc\fR(1) for their full semantics.
+.IP \(bu 4
+\fBase agent researcher status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Report whether the researcher agent of the name \fIname\fR (default: \fBresearcher\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 (exit status 1).
+.IP \(bu 4
+\fBase agent researcher 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 researcher agent of the name \fIname\fR (default: \fBresearcher\fR) run in the background, where an agent of a fleet logs into the log of the fleet instead (see \fBase-agent-fleet\fR(1)). Without a log file, an informational message is shown only. The options are:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--follow\fR\[rB]: Show the last \fIn\fR lines (default: 10) and then follow all newly appended lines, in the style of \fBtail -f\fR, until interrupted.
+.IP \(bu 4
+\[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB]: Show the last \fIn\fR lines only (default: all, or 10 with \fB--follow\fR).
+.IP \(bu 4
+\[lB]\fB--name\fR \fIname\fR\[rB]: The name of the agent (default: \fBresearcher\fR), given in its long form only, as \fB-n\fR is the short form of \fB--lines\fR.
+.RE 0
+.IP \(bu 4
+\fBase agent researcher stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Stop the researcher agent of the name \fIname\fR (default: \fBresearcher\fR) by \fBSIGTERM\fR, waiting (up to 5 minutes) until it aborted its running processings and put their tasks back. An agent not running is reported informationally only.
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default agent tool of \fB--tool\fR (default: \fBclaude\fR).
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The bearer token of the agent relay, if not embedded in the URL of \fB--agent-relay\fR resp. \fBproject.relay.url\fR.
+.IP \(bu 4
+\fBASE_HEADLESS\fR: Set to \fBtrue\fR for the agent tool processes spawned by the agent.
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.yaml\fR: The process state (kind, process id, and process start time) of the agent, existing while it runs.
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.log\fR: The log of the agent run in the background.
+.IP \(bu 4
+\fB.ase/worktree/.temp/\fR\fIid\fR\fB-researcher\fR: The temporary, detached Git worktree of a \fBbranch:\fR source of a task during its research (where a \fB#\fR of the task id is replaced by \fB_\fR).
+.IP \(bu 4
+\fIper-user state directory\fR\fB/agent-researcher/\fR\fIstore-hash\fR\fB/\fR\fIrun-id\fR\fB.lock\fR and \fB.json\fR: The run lock and the run record of each researcher agent process, used to recover the research requests of terminated agent processes (see \fBINTERRUPTS AND RECOVERY\fR in \fBase-agent\fR(1)).
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fBase agent researcher start\fR exits with status \fB0\fR once the agent started (or was already running), resp. once a foreground agent terminated regularly, and with status \fB1\fR on any error (e.g., an invalid option, a task lifecycle model other than \fBenterprise\fR in the mode \fBphase\fR, or a missing agent tool). \fBase agent researcher status\fR exits with status \fB1\fR if the agent is not running.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# research and ground the plans of the tasks assigned to the researcher
+$ ase agent researcher start
+
+# request the research of a drafted task by assigning it to the researcher
+$ ase task assign FOO-42 researcher
+
+# process the research requests of the task board
+$ ase agent researcher start -n researcher-request -m request
+
+# request a research of a topic for a task from the command line
+$ ase task request FOO-42 research "streaming JSON serialization of large data sets"
+
+# request a research of the task plan itself (without a topic)
+$ ase task request FOO-42 research
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-agent\fR(1), \fBase-agent-rebooter\fR(1), \fBase-agent-condenser\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-task-request\fR(1), \fBase-agent-adhoc\fR(1), \fBase-agent-fleet\fR(1), \fBase-agent-relay\fR(1), \fBase-task\fR(1), \fBase-task-board\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-agent.1

@@ -0,0 +1,264 @@
+.TH "ASE-AGENT" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent\fR - Autonomous Task Lifecycle Agents
+.SH "SYNOPSIS"
+.P
+\fBase agent\fR \fIagent\fR \fBstart\fR \[lB]\fIagent-options\fR\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]
+.P
+\fBase agent\fR \fIagent\fR \fBstatus\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent\fR \fIagent\fR \fBlog\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\fR \fIagent\fR \fBstop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent relay\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR \[lB]\fIoptions\fR\[rB]
+.P
+\fBase agent fleet\fR \fBinit\fR|\fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR \[lB]\fIoptions\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase agent\fR runs the autonomous, headless agents of \fIASE\fR. Each agent observes the tasks of the task store of the project (see \fBase-task\fR(1)), claims the tasks it is responsible for, processes each of them by an \fIASE\fR skill (or a prompt text) through a headless agent tool (\fIAnthropic Claude Code CLI\fR, \fIGitHub Copilot CLI\fR, or \fIOpenAI Codex CLI\fR), and settles the task afterwards (status, tag, and assignee), until it is interrupted or stopped.
+.P
+The \fIagent\fR is one of the following agent kinds:
+.RS 0
+.IP \(bu 4
+the built-in phase agents \fBimplementer\fR, \fBqualifier\fR, and \fBintegrator\fR, which each drive one phase of the \fBenterprise\fR task lifecycle model, so that the three agents together realize the model from the planned to the integrated tasks,
+.IP \(bu 4
+the built-in phase agents \fBrebooter\fR and \fBcondenser\fR, which re-create resp. condense the plans of the tasks of the \fBPlanning\fR phase of the \fBenterprise\fR task lifecycle model explicitly assigned to them (\fBDRAFTED\fR > \fBPLANNING\fR > \fBDRAFTED\fR),
+.IP \(bu 4
+the built-in request agent \fBeditor\fR, which processes the edit requests of tasks in any task lifecycle model,
+.IP \(bu 4
+the built-in agent \fBestimator\fR, which estimates the effort of tasks in any task lifecycle model, without claiming them (mode \fBphase\fR, intended for the final estimation), resp. on request (mode \fBrequest\fR, intended for dry-runs),
+.IP \(bu 4
+the built-in agent \fBresearcher\fR, which researches and grounds the plans of the tasks of the \fBPlanning\fR phase of the \fBenterprise\fR task lifecycle model explicitly assigned to it (mode \fBphase\fR), resp. researches a topic (or the plan itself) for tasks in any task lifecycle model on request (mode \fBrequest\fR, intended for topic-driven research),
+.IP \(bu 4
+an agent of a \fIdefinition kind\fR, whose entire behavior is configured by a definition file \fIkind\fR\fB.\fR\fIext\fR of the project or of the user,
+.IP \(bu 4
+the \fBadhoc\fR agent, whose entire behavior is configured by its options.
+.RE 0
+.P
+Each agent runs in its own process, either detached in the background (the default) or, with \fB--foreground\fR, in the current process. Several agents are best run together as a \fIfleet\fR (see \fBase-agent-fleet\fR(1)), and each agent can pass its live presence to the task boards through an \fIagent relay\fR (see \fBase-agent-relay\fR(1)).
+.P
+The eight built-in agents are not hard-coded, but each mode of them is a declarative \fIdefinition\fR, run by the same agent engine as the agents of the definition kinds and the \fBadhoc\fR agent. Hence, every agent accepts all options \fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR of the definitions (see \fBase-agent-adhoc\fR(1)), which override the definition of the agent, while a built-in agent keeps the identity of its kind: its runs, its presence (with its mode), its tags, and its agent-owned worktrees (\fIid\fR\fB-\fR\fIkind\fR) are named after its kind.
+.SH "AGENT NAMES"
+.P
+Every agent has a \fIname\fR (option \fB--name\fR, default: its kind, e.g., \fBimplementer\fR or \fBadhoc\fR), which consists of up to 64 letters, digits, underscores, and dashes, starting with a letter or digit, and which must not be the name of another agent kind, \fBrelay\fR, or \fBfleet\fR.
+.P
+The name is used in the log lines of the agent (also in the shared processing log attachment \fBagent\fR), as the \fBAssignee:\fR of the tasks it processes, for its temporary directory, and for its process files \fB.ase/agent/\fR\fIname\fR\fB.yaml\fR and \fB.ase/agent/\fR\fIname\fR\fB.log\fR. Hence, multiple agents of the same kind are started under different names, e.g., \fBase agent implementer start -n impl-claude -t claude\fR and \fBase agent implementer start -n impl-codex -t codex\fR.
+.P
+The agents of the same kind form a \fIpool\fR: they compete for the same tasks, share the same tag (per mode), and process their tasks in parallel to each other.
+.SH "TASK CLAIMING"
+.P
+A \fIphase\fR agent (all built-in agents except \fBeditor\fR, \fBestimator\fR, and \fBresearcher\fR in the mode \fBrequest\fR, and every definition of \fB--type
+phase\fR without \fB--unclaimed\fR) observes the tasks in its \fIincoming\fR state(s) which do not yet carry its \fItag\fR (plain or with any value) in their \fBTags:\fR frontmatter key, and whose \fBAssignee:\fR frontmatter key is either still empty or already the assignee name of the agent (default: its name), so a task can be pre-assigned to a particular agent of a pool, while a task assigned to anybody else (e.g., a human) is left alone.
+.P
+An agent can require a task to be already assigned to it (like \fBrebooter\fR, \fBcondenser\fR, and \fBresearcher\fR in the mode \fBphase\fR, see \fB--assign-required\fR). Such an agent can leave a processed task untagged (see \fB--tag-success none\fR), as the unassignment of the task keeps it from being claimed again, while assigning it to the agent again requests another processing.
+.P
+The tag of a built-in agent is \fBase-agent-\fR\fIkind\fR, resp. one per mode for \fBimplementer\fR in mode \fBdraft\fR (\fBase-agent-implementer-draft\fR). The tag of any other agent is \fBase-agent-\fR\fIname\fR (see \fB--tag-name\fR).
+.P
+The agent claims each dispatchable task (in natural task id order, re-checked on every change of the task store) in a single conditional save of the task (retried on a concurrent change), which moves it into its \fIactivity\fR state, tags it with the value \fBactive\fR (so no other agent of this kind picks it up, even if the skill itself puts it back into the incoming state during its processing), and sets its \fBAssignee:\fR to the agent (for information only, as the tag alone guards the task).
+.P
+A task meanwhile tagged or (re)assigned is silently skipped instead.
+.P
+After the processing, again in a single conditional save, the task is unassigned (only if still assigned to the agent, and not meanwhile to somebody else, e.g., the \fBeditor\fR agent), tagged with its plain tag (or with the label of the processing as its value, like the verdict of \fBqualifier\fR), so no agent of this kind picks it up again, and moved into its \fIsuccess\fR or \fIfailure\fR (parking) state, where the pseudo state \fBprevious\fR restores the incoming state the task was claimed from (for an agent claiming tasks from multiple incoming states).
+.P
+A processing failure, or a processing exceeding the duration of \fB--timeout\fR, always leads to the failure state. A task whose status the skill itself moved elsewhere is tagged, too, and left in that state.
+.P
+The preparing of a processing (e.g., creating a worktree) and its finishing (e.g., committing and pushing a branch) are each limited to a fixed duration of 240 seconds, where exceeding it also leads to the failure state.
+.P
+A task the skill already put into the success state, but whose finishing failed (e.g., a branch which could not be pushed), and a task whose resulting state is not reachable from its current state, is instead tagged with the value \fBfailed\fR, unassigned, and left in its state for a manual intervention (which removes the tag), while the failure is logged as an error. A final status update of a processed task which fails even after its retries is retried in the background with a growing delay.
+.P
+A \fIrequest\fR agent (\fBeditor\fR, \fBestimator\fR and \fBresearcher\fR in the mode \fBrequest\fR, and every definition of \fB--type request\fR) instead processes the prompt requests attached to tasks in any lifecycle status (see \fBase task request\fR in \fBase-task-request\fR(1), \fBase-agent-editor\fR(1), and \fBase-agent-researcher\fR(1)).
+.P
+An \fIunclaimed\fR phase agent (\fBestimator\fR in the mode \fBphase\fR, and every definition of \fB--type phase\fR with \fB--unclaimed\fR) instead processes every task in one of its incoming states (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) which does not carry its tag yet, independent of its assignee and its predecessors, without claiming it: it neither moves the task into an activity state, nor tags it as active, nor assigns it to itself, and it settles the task by its tag only, so it never changes its status and its assignee and keeps no other agent off it (see \fBase-agent-estimator\fR(1)).
+.SH "PREDECESSORS"
+.P
+A phase agent claims a task only once all its predecessors passed the phase of the agent (or no longer exist). The predecessors of a task are the tasks of its \fBAfter:\fR frontmatter key and, for an explicit epic (a task whose \fBGroup:\fR is its own id), implicitly all other tasks of its group. An agent whose passed state (see below) is the first state of the task lifecycle model (like \fBrebooter\fR, \fBcondenser\fR, and \fBresearcher\fR in the mode \fBphase\fR, with \fBDRAFTED\fR) hence imposes no gate, except for a predecessor still being processed by an agent of its kind or a cancelled \fBAfter:\fR predecessor.
+.P
+A predecessor has passed the phase once it is in or beyond the \fIpassed\fR state of the agent (see \fB--state-passed\fR), or in the \fIsuccess\fR state and tagged as processed, where a predecessor still tagged by an agent of this kind with the value \fBactive\fR (while in the success state or not finished) resp. \fBfailed\fR (while still in the success state) has not passed it yet.
+.P
+A cancelled \fBAfter:\fR predecessor never passes (as the task might depend on its never delivered result), while a cancelled member of an epic counts as dropped from it. A predecessor status foreign to the lifecycle model counts as the state it maps onto.
+.P
+A task still waiting for its predecessors is reported once (per change of the reason), while a task referencing unknown predecessors (treated as passed), waiting for cancelled predecessors, or waiting in a dependency cycle is warned about once. A task with predecessors is re-checked against a fresh listing right before its claim.
+.SH "PROCESSING"
+.P
+Each task is processed through the headless agent tool of \fB--tool\fR, with the environment variable \fBASE_HEADLESS=true\fR and without any standard input, i.e., via
+.RS 0
+.IP \(bu 4
+\fBclaude\fR \[lB]\fB--add-dir\fR \fIdir\fR ...\[rB] \fB-p --output-format stream-json
+--verbose --disallowedTools AskUserQuestion --permission-mode auto
+--permission-prompts none\fR \fIprompt\fR,
+.IP \(bu 4
+\fBcopilot\fR \[lB]\fB--add-dir\fR \fIdir\fR ...\[rB] \fB--allow-all-tools --no-ask-user
+--no-color --output-format json -p\fR \fIprompt\fR, resp.
+.IP \(bu 4
+\fBcodex exec\fR \[lB]\fB--add-dir\fR \fIdir\fR ...\[rB] \fB--json --approve-for-me
+--color never\fR \fIprompt\fR,
+.RE 0
+.P
+where risky actions are denied or automatically reviewed instead of being prompted for, and where each additional directory a skill needs access to besides its working directory is granted through an additional \fB--add-dir\fR \fIdir\fR. A skill \fIprompt\fR is \fB/\fR\fIskill\fR \fIargs\fR (\fBclaude\fR and \fBcopilot\fR) resp. \fB$\fR\fIskill\fR \fIargs\fR (\fBcodex\fR), where an un-namespaced \fIASE\fR skill (\fBase-*\fR) gets the plugin namespace \fBase:\fR for \fBclaude\fR only.
+.P
+The agent tool and, for an agent of a working directory other than \fBproject\fR (i.e., all built-in agents except \fBrebooter\fR, \fBcondenser\fR, and \fBestimator\fR, see \fB--workdir\fR), \fBgit\fR have to be found in \fB$PATH\fR.
+.P
+All processing information, including the output of the agent tool (which streams its agent messages, tool calls, failures, and final result as JSONL events), is logged (to standard error, see \fBase\fR(1), resp. to the log file of the agent) with timestamp prefixes in real time, followed by the usage of the agent tool as wall time (measured locally), output tokens (of \fBclaude\fR and \fBcodex\fR), and costs in USD (of \fBclaude\fR only), with \fBn/a\fR for what the agent tool does not report.
+.P
+At the end of each processing, the log lines of the processing (with at most 20 lines of each agent message) are appended to the attachment of the task with the type \fBtext/plain; charset=utf-8; kind="agent"\fR (created if not existing yet), which is shared by all agents, whose log lines carry their name. If the AI usage accounting is enabled (\fBtelemetry.enabled\fR), the usage is additionally booked onto the usage attachment of the task (without any human time and costs, as the agent runs unattended).
+.SH "INTERRUPTS AND RECOVERY"
+.P
+On an interrupt (\fBSIGINT\fR, \fBSIGTERM\fR, \fBSIGHUP\fR, or \fBSIGQUIT\fR, e.g., by \fBase agent\fR \fIagent\fR \fBstop\fR), and on the failure of a concurrently run agent, the running processings are aborted and their tasks are put back, untagged and with their previous assignee, into the incoming state (while a task processed unclaimed is left untouched), while a repeated signal terminates the process at once (leaving the claimed tasks to the recovery described below).
+.P
+The claimed tasks of each run are recorded under a run lock in the \fIper-user state directory\fR (below a sub-directory per task store, as task ids are unique per task store only).
+.P
+Hence, the tasks of an agent terminated without this cleanup (e.g., killed or crashed) are recovered on the next start of an agent of its kind for the same task store on the same host by the same user: a task still in the activity state is put back the same way, and any other task still tagged as \fBactive\fR is tagged plain (as processed), but only while it is still assigned to the terminated agent and not claimed meanwhile by a live agent, where concurrently started agents never recover the same run.
+.P
+The requests left in processing by a terminated request agent are marked as failed instead, and the previous assignees of their tasks are restored.
+.SH "WORKING COPY, CLONES, AND WORKTREES"
+.P
+The agents follow the \fBSource:\fR, \fBChangeset:\fR, and \fBTarget:\fR frontmatter keys of a task (or their configured defaults \fBproject.task.default.source\fR, \fBproject.task.default.changeset\fR, and \fBproject.task.default.target\fR, see \fBase-config\fR(1)). Their values are:
+.RS 0
+.IP \(bu 4
+\fBworktree\fR: the Git working copy the agent is started in. For it, the agents create no own Git worktree, but work in the working copy directly, just adjusting its checked-out branch.
+.sp
+As concurrently processed tasks would interfere there, an agent handles at most one task at a time in the working copy itself (other tasks waiting until it is free again). This coordination does not extend to other agents (each running in its own process, also within a fleet) or humans working in the same working copy, so a working copy should be used directly by a single agent only, while the other agents are given \fB--repo\fR (or process tasks without \fBworktree\fR values only).
+.IP \(bu 4
+\fBbranch:\fR\fIname\fR: the Git branch \fIname\fR, checked out in an \fIASE\fR worktree below \fB.ase/worktree/\fR where needed, which 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, e.g., \fBfeature-x\fR for \fBfeature/x\fR).
+.IP \(bu 4
+\fBattachment:\fR\fIname\fR: the task attachment \fIname\fR (a change set as a diff), handled by the skills (\fBChangeset:\fR only).
+.IP \(bu 4
+\fBsource\fR (\fBTarget:\fR only): the \fBSource:\fR of the task.
+.RE 0
+.P
+The placeholder \fB{id}\fR of a branch or attachment \fIname\fR reads as the id of the task (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), e.g., the \fBChangeset:\fR default \fBbranch:cs-{id}\fR implements every task onto its own branch.
+.P
+Without \fB--repo\fR, all tasks are processed in the Git working copy the agent is started in, which is hence mandatory (except for an agent of the working directory \fBproject\fR, like \fBrebooter\fR, \fBcondenser\fR, and \fBestimator\fR, which work in the project root only, where \fBrebooter\fR, \fBcondenser\fR, and \fBestimator\fR do not accept \fB--repo\fR and \fB--tempdir\fR at all, while any other such agent ignores them).
+.P
+With \fB--repo\fR \fIurl\fR, each agent instead clones the Git repository \fIurl\fR once into its temporary directory (removed on termination) and processes every task without a \fBworktree\fR value in its own temporary Git worktree of this clone (below \fBwork/\fR of the temporary directory), where the Git operations on the clone are serialized: before each task, its default branch and the branches of the task (unless checked out for another task) are refreshed from the origin, and afterwards a changed \fBbranch:\fR changeset resp. target is pushed back to the origin, where a rejected push fails the task.
+.P
+If such a push fails after the skill already put the task into its success state, the work is kept as the branch \fBase-agent-rescue/\fR\fIid\fR in the clone, the task is tagged with the value \fBfailed\fR, and the temporary directory is preserved (instead of being removed on termination) for a manual recovery.
+.P
+Only a task with a \fBworktree\fR value then requires the agent to be started inside a Git working copy. As the skills run inside the clone, \fB--repo\fR requires a task store not located in the working copy (i.e., not a local \fBase:\fR\fIpath\fR one).
+.P
+In the names of all \fIASE\fR worktrees derived from a task id, a \fB#\fR of the id (e.g., of the \fBseq:#%d\fR id scheme of the issue tracker task stores) is replaced by \fB_\fR, as neither a worktree name nor a branch name can carry it.
+.P
+The temporary directory of an agent holds the clone and other temporary files: by default, it is securely created as a fresh, private directory \fBase-agent-\fR\fIname\fR\fB-\fR\fIrandom\fR below the system temporary directory, while \fB--tempdir\fR \fIdir\fR forces it to be the sub-directory \fIname\fR of \fIdir\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.
+.P
+A missing \fIdir\fR is created private to the current user (and removed again on termination if empty), while an existing \fIdir\fR has to be a directory (no symbolic link) owned by the current user. A sub-directory \fIname\fR left over by an earlier run is removed only if its owning process is no longer alive and it holds no work preserved for a manual recovery, and otherwise refused.
+.SH "AGENT RELAY"
+.P
+With an agent relay (\fB--agent-relay\fR \fIurl\fR, else the configured \fBproject.relay.url\fR, given as \fBase://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB] resp. \fBases://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB]\[lB]\fB?insecure\fR\[rB] for HTTPS, optionally without certificate verification), each agent additionally passes its live presence to the task boards (see \fBase-task-board\fR(1)): its state (\fBwaiting\fR, or \fBbusy\fR with the ids of its tasks) immediately on every change, its usage of the agent tool (in total and by its last job) immediately after each finished job, its new processing log lines (coalesced to at most four announcements per second), and a heartbeat every 10 seconds, and it removes its presence on termination.
+.P
+The relay requires an explicit \fBproject.id\fR. Its bearer token is the one embedded in the URL, else \fB$ASE_AGENT_RELAY_TOKEN\fR, else \fBproject.relay.token\fR, else the token of the locally started agent relay (or of the locally started task store co-hosting it), if the URL addresses it.
+.P
+An unreachable relay is warned about once per outage and never disturbs the processing of the tasks, where the not yet passed log lines are kept (at most 100) and passed once the relay is reachable again. A presence rejected by the relay is warned about with its reason and retried after a growing delay (from 1 up to 15 minutes).
+.SH "DEFINITION KINDS"
+.P
+A \fIdefinition kind\fR is an agent kind of its own, discovered from a 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), where a definition kind of the project shadows one of the user, and both shadow a built-in agent of the same kind (whose \fB--mode\fR then no longer exists). For instance, \fB.ase/agents/reviewer.mts\fR yields \fBase agent reviewer start\fR.
+.P
+The extensions are, in descending precedence, \fB.yaml\fR, \fB.yml\fR, \fB.ts\fR, \fB.mts\fR, \fB.js\fR, \fB.mjs\fR, and \fB.cjs\fR. The definition files are discovered on the commands \fBase agent\fR ... only, 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 kind name \fBadhoc\fR, \fBrelay\fR, or \fBfleet\fR, or of an already discovered kind name in the same directory is skipped with a warning.
+.P
+An agent of a definition kind accepts the same options as \fBase agent adhoc start\fR, except \fB--definition\fR, and \fB--repo\fR and \fB--tempdir\fR are silently ignored with \fB--workdir project\fR. See \fBase-agent-adhoc\fR(1) for the format of the definition files, all options of the definitions, their templates, their hooks, and example definitions.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information of \fBase agent\fR (or of the given sub-command) only.
+.RE 0
+.P
+All other options belong to the sub-commands (see \fBCOMMANDS\fR and the manual pages of the agent kinds).
+.SH "COMMANDS"
+.P
+The following sub-command groups exist:
+.RS 0
+.IP \(bu 4
+\fBase agent rebooter\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent re-creating the plans of the \fBDRAFTED\fR tasks of the \fBenterprise\fR task lifecycle model explicitly assigned to it from scratch, putting them back into \fBDRAFTED\fR afterwards. See \fBase-agent-rebooter\fR(1).
+.IP \(bu 4
+\fBase agent condenser\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent compressing the wording of the plans of the \fBDRAFTED\fR tasks of the \fBenterprise\fR task lifecycle model explicitly assigned to it, putting them back into \fBDRAFTED\fR afterwards. See \fBase-agent-condenser\fR(1).
+.IP \(bu 4
+\fBase agent implementer\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent of the \fBImplementation\fR phase of the \fBenterprise\fR task lifecycle model, implementing the tasks from their \fBSource:\fR into their \fBChangeset:\fR, resp. drafting their implementation. See \fBase-agent-implementer\fR(1).
+.IP \(bu 4
+\fBase agent qualifier\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent of the \fBQualification\fR phase of the \fBenterprise\fR task lifecycle model, reviewing the \fBChangeset:\fR of the tasks. See \fBase-agent-qualifier\fR(1).
+.IP \(bu 4
+\fBase agent integrator\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent of the \fBIntegration\fR phase of the \fBenterprise\fR task lifecycle model, integrating the \fBChangeset:\fR of the tasks into their \fBTarget:\fR. See \fBase-agent-integrator\fR(1).
+.IP \(bu 4
+\fBase agent editor\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent processing the edit requests of tasks in any task lifecycle model. See \fBase-agent-editor\fR(1).
+.IP \(bu 4
+\fBase agent estimator\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent estimating the effort of the tasks without a valid \fBEffort:\fR key in any task lifecycle model, without claiming them (mode \fBphase\fR, intended for the final estimation), resp. of the tasks of the \fBestimate\fR requests (mode \fBrequest\fR, intended for dry-runs). See \fBase-agent-estimator\fR(1).
+.IP \(bu 4
+\fBase agent researcher\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent researching the plans of the \fBDRAFTED\fR tasks of the \fBenterprise\fR task lifecycle model explicitly assigned to it (mode \fBphase\fR, intended for researching and grounding the plan content), resp. processing the research requests of tasks in any task lifecycle model (mode \fBrequest\fR, intended for topic-driven research), appending a research report, grounded in the Web and in the source artifacts of the project, to the \fBresearch\fR attachment of the tasks. See \fBase-agent-researcher\fR(1).
+.IP \(bu 4
+\fBase agent\fR \fIkind\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The agent of the definition kind \fIkind\fR (see \fBDEFINITION KINDS\fR), with the same sub-commands and options as \fBase agent adhoc\fR, except \fB--definition\fR. See \fBase-agent-adhoc\fR(1).
+.IP \(bu 4
+\fBase agent adhoc\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: An ad-hoc agent, whose entire behavior is given by its options. See \fBase-agent-adhoc\fR(1).
+.IP \(bu 4
+\fBase agent relay\fR \fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: The per-user agent relay server, passing the live presence of the agents to the task boards. See \fBase-agent-relay\fR(1).
+.IP \(bu 4
+\fBase agent fleet\fR \fBinit\fR|\fBstart\fR|\fBstatus\fR|\fBlog\fR|\fBstop\fR: A fleet of agents (and of the agent relay they report to), running each in its own process and restarting it whenever it exits. See \fBase-agent-fleet\fR(1).
+.RE 0
+.P
+The sub-commands of every agent kind \fIagent\fR are:
+.RS 0
+.IP \(bu 4
+\fBase agent\fR \fIagent\fR \fBstart\fR \[lB]\fIagent-options\fR\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]: Start the agent in the background, logging into \fB.ase/agent/\fR\fIname\fR\fB.log\fR. The agent is validated and initialized (e.g., its agent tool is looked up and the task lifecycle model is checked) before the command returns (waiting up to 30 seconds), so a failing agent is reported together with the tail of its log. An agent of the same name already running is left alone (exit status 0).
+.sp
+With \fB--foreground\fR, the agent runs in the current process instead, logging to the terminal, until it is interrupted or stopped, where an agent of the same name already running is an error.
+.IP \(bu 4
+\fBase agent\fR \fIagent\fR \fBstatus\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Report whether the agent of the name \fIname\fR (default: its kind) is running (with its process id).
+.IP \(bu 4
+\fBase agent\fR \fIagent\fR \fBlog\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 of the name \fIname\fR (default: its kind) run in the background, where an agent of a fleet logs into the log of the fleet instead (see \fBase-agent-fleet\fR(1)). With \fB--lines\fR, only the last \fIn\fR lines are shown. With \fB--follow\fR, the last \fIn\fR lines (default: 10) are shown and then all newly appended lines are followed until interrupted. As \fB-n\fR is the short form of \fB--lines\fR, the name is given via \fB--name\fR only.
+.IP \(bu 4
+\fBase agent\fR \fIagent\fR \fBstop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Stop the agent of the name \fIname\fR (default: its kind) by \fBSIGTERM\fR, waiting (up to 5 minutes) until it aborted its running processings and put their tasks back.
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default agent tool of \fB--tool\fR (default: \fBclaude\fR).
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The bearer token of the agent relay, if not embedded in the URL of \fB--agent-relay\fR resp. \fBproject.relay.url\fR.
+.IP \(bu 4
+\fBASE_HEADLESS\fR: Set to \fBtrue\fR for the agent tool processes spawned by the agents.
+.IP \(bu 4
+\fBPATH\fR: Searched for the agent tool (\fBclaude\fR, \fBcopilot\fR, or \fBcodex\fR) and \fBgit\fR.
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.yaml\fR: The process state (kind, 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
+\fB.ase/agents/\fR\fIkind\fR\fB.\fR\fIext\fR, \fIper-user configuration directory\fR\fB/agents/\fR\fIkind\fR\fB.\fR\fIext\fR: The definition files of the definition kinds of the project resp. of the user.
+.IP \(bu 4
+\fB.ase/worktree/\fR: The \fIASE\fR worktrees created by the agents (and the skills).
+.IP \(bu 4
+\fIper-user state directory\fR\fB/agent-\fR\fIkind\fR\fB/\fR\fIstore-hash\fR\fB/\fR\fIrun-id\fR\fB.lock\fR and \fB.json\fR: The run lock (a directory, refreshed periodically and considered stale after 30 seconds without refresh) and the run record (process id, process start time, and claimed tasks) of each agent process of agent \fIkind\fR (\fBrebooter\fR, \fBcondenser\fR, \fBimplementer\fR, \fBqualifier\fR, \fBintegrator\fR, \fBeditor\fR, \fBestimator\fR, or \fBresearcher\fR, resp. \fBtag-\fR\fIword\fR per tag \fBase-agent-\fR\fIword\fR of the agents of the definition kinds and of \fBadhoc\fR), where \fIstore-hash\fR is the first 12 hex digits of the SHA-1 digest of the identity of the task store.
+.sp
+On termination, the lock is removed, and so is the record, unless it still records claimed tasks.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fBase agent\fR \fIagent\fR \fBstart\fR exits with status \fB0\fR once the agent started (or was already running), resp. once a foreground agent terminated regularly, and with status \fB1\fR on any error (e.g., an invalid option, a missing agent tool, an unsupported task lifecycle model, or, with \fB--one-shot\fR, a task store failing three checks in a row). \fBase agent\fR \fIagent\fR \fBstatus\fR exits with status \fB1\fR if the agent is not running. \fBase agent\fR without a sub-command shows its usage information and exits with status \fB1\fR.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# start the phase agents of the "enterprise" lifecycle model
+$ ase agent rebooter start
+$ ase agent condenser start
+$ ase agent researcher start
+$ ase agent implementer start -p 2
+$ ase agent qualifier start -m judge
+$ ase agent integrator start -m squash
+
+# start two implementers of different agent tools as a pool
+$ ase agent implementer start -n impl-claude -t claude
+$ ase agent implementer start -n impl-codex -t codex
+
+# follow the log of an agent and stop it again
+$ ase agent implementer log -f --name impl-codex
+$ ase agent implementer stop -n impl-codex
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-agent-rebooter\fR(1), \fBase-agent-condenser\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-researcher\fR(1), \fBase-agent-adhoc\fR(1), \fBase-agent-relay\fR(1), \fBase-agent-fleet\fR(1), \fBase-task\fR(1), \fBase-task-board\fR(1), \fBase-task-request\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-artifact-list.1

@@ -0,0 +1,38 @@
+.TH "ASE-ARTIFACT-LIST" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-artifact-list\fR - Resolve Artifact Kinds to Project-Relative File Paths
+.SH "SYNOPSIS"
+.P
+\fBase artifact list\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB--kind\fR \fIkinds\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase artifact list\fR resolves one or more artifact kinds of the project to the project-relative (POSIX-style) paths of their files, driven by the configuration keys \fBproject.artifact.\fR\fIkind\fR\fB.basedir\fR and \fBproject.artifact.\fR\fIkind\fR\fB.files\fR and honoring the Git exclude rules, as described in \fBase-artifact\fR(1).
+.P
+The files of each kind are printed sorted, one per line, as a bullet list (\fB- \fR\fIfile\fR). When more than one kind is requested, the list of each kind is preceded by a header line \fB# \fR\fIkind\fR\fB:\fR. The kinds are printed in the requested order, while the partitioning of the files among the kinds always follows the fixed precedence \fBspec\fR, \fBcode\fR, \fBdocs\fR, \fBinfr\fR, with \fBothr\fR as the implicit catch-all.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB--kind\fR \fIkinds\fR\[rB]: A comma-separated list of the artifact kinds to resolve, out of \fBspec\fR, \fBcode\fR, \fBdocs\fR, \fBinfr\fR, and \fBothr\fR (default: \fBspec,code,docs,infr,othr\fR, i.e., all kinds). Whitespace around the kinds is ignored. An unknown kind is an error.
+.RE 0
+.SH "EXIT STATUS"
+.P
+Exits with status \fB0\fR on success, and with status \fB1\fR on an unknown kind or an invalid configuration (e.g., a base directory escaping the project root).
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# list the source code files of the project
+$ ase artifact list --kind code
+
+# list the specification and documentation files, each with a header
+$ ase artifact list --kind spec,docs
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-artifact\fR(1), \fBase-artifact-name\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-artifact-name.1

@@ -0,0 +1,39 @@
+.TH "ASE-ARTIFACT-NAME" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-artifact-name\fR - Resolve a Filename within an Artifact Kind
+.SH "SYNOPSIS"
+.P
+\fBase artifact name\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB--kind\fR \fIkind\fR\[rB] \fIfilename\fR
+.SH "DESCRIPTION"
+.P
+\fBase artifact name\fR resolves a \fIfilename\fR, given relative to the base directory of an artifact \fIkind\fR, to a project-relative (POSIX-style) path by prefixing it with the configured base directory \fBproject.artifact.\fR\fIkind\fR\fB.basedir\fR (see \fBase-artifact\fR(1)), and prints it. The file does not have to exist. The skills use it to name a new file of a kind, e.g., a new specification or source code file.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB--kind\fR \fIkind\fR\[rB]: The artifact kind whose base directory is used: \fBspec\fR, \fBcode\fR, \fBdocs\fR, or \fBinfr\fR (default: \fBcode\fR). The implicit catch-all kind \fBothr\fR has no base directory and is rejected.
+.RE 0
+.SH "ARGUMENTS"
+.RS 0
+.IP \(bu 4
+\fIfilename\fR: The filename, relative to the base directory of the kind. Backslashes are converted to slashes and leading slashes are stripped. It must not be empty and must not contain any \fB..\fR segment.
+.RE 0
+.SH "EXIT STATUS"
+.P
+Exits with status \fB0\fR on success, and with status \fB1\fR on an unknown or unsupported kind, an empty filename, or a filename with a \fB..\fR segment.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# resolve a source file name (with the default "project.artifact.code.basedir" of "src")
+$ ase artifact name --kind code lib/util.ts
+src/lib/util.ts
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-artifact\fR(1), \fBase-artifact-list\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR