@rse/ase 1.0.6 → 2.0.0

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

@@ -0,0 +1,214 @@
+.TH "ASE-AGENT-ESTIMATOR" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent-estimator\fR - Effort Estimation Agent
+.SH "SYNOPSIS"
+.P
+\fBase agent estimator 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-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 estimator status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent estimator 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 estimator stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase agent estimator\fR estimates the effort of tasks, i.e., it stores the expected human time of a task as a T-shirt size in its \fBEffort:\fR frontmatter key (see the skill \fBase-task-estimate\fR). Unlike the phase agents, it drives no phase and supports all task lifecycle models (\fBsolo\fR, \fBteam\fR, and \fBenterprise\fR). It runs in one of two modes (see \fB--mode\fR): the mode \fBphase\fR (the default) estimates the unestimated planned tasks automatically and is intended for the \fIfinal\fR estimation of the tasks, once their plans are complete, while the mode \fBrequest\fR (re-)estimates the tasks in any unfinished status on request and is intended for \fIdry-runs\fR, i.e., provisional estimations of plans still in progress.
+.P
+In the mode \fBphase\fR, the estimator observes the tasks in the state \fBPLANNED\fR, adapted onto the task lifecycle model of the project, i.e., \fBPLANNED\fR for \fBenterprise\fR, \fBPLANNING\fR for \fBteam\fR, and \fBOPEN\fR for \fBsolo\fR (see \fB--state-incoming\fR), which do not carry its tag \fBase-agent-estimator\fR yet, independent of their \fBAssignee:\fR and their \fBAfter:\fR predecessors. Of these, it processes every task which carries no valid \fBEffort:\fR key yet, whose plan is not empty, and which is no explicit epic (a task whose \fBGroup:\fR is its own id, as its effort is the sum of the efforts of its members).
+.P
+The estimator processes each such task \fIunclaimed\fR (see \fB--unclaimed\fR): it neither moves the task into an activity state, nor tags it as active, nor assigns it to itself, and it never changes its status or its assignee. Hence, it keeps no other agent and no human off the task. However, the built-in \fBimplementer\fR by default waits with a \fBPLANNED\fR task until the estimator is done with it (see its parameter \fBeffort-wait\fR in \fBase-agent-implementer\fR(1)), so with both agents running, the tasks are estimated before their implementation. An agent of the kind \fBestimator\fR does not pick up a task already processed by another one on the same host.
+.P
+It estimates the effort via the skill invocation \fBase-task-estimate\fR \fIid\fR, which writes just the \fBEffort:\fR key in a conditional save, i.e., only if the plan was not changed meanwhile (re-estimating the task otherwise), so a concurrent change of the task by another agent or a human is never lost. It writes neither the \fBStatus:\fR nor the \fBModified:\fR key of the task.
+.P
+The estimation succeeds only if the agent tool succeeded, the skill reported no error, and the task afterwards carries a valid \fBEffort:\fR key. A successfully estimated task is left untagged, as its valid \fBEffort:\fR key itself keeps it from being estimated again, until its plan content changes, which drops its then stale \fBEffort:\fR key, so it is estimated again. A task not estimated is tagged with \fBase-agent-estimator\fR instead, so it is not processed again and again (removing this tag requests another estimation).
+.P
+In the mode \fBrequest\fR, the estimator instead processes the \fBestimate\fR requests attached to tasks in any lifecycle status except a finished one (e.g., \fBDRAFTED\fR, which the mode \fBphase\fR never picks up), as requested via \fBase task request\fR \fIid\fR \fBestimate\fR (see \fBase-task-request\fR(1)) resp. key \fBR\fR of the task boards, where a prompt is ignored and hence may be empty. Like the request agent \fBeditor\fR (see \fBase-agent-editor\fR(1)), it claims such a task by tagging it with \fBase-agent-estimate:active\fR and assigning it to itself (deferring a task in an activity status until it changes), estimates its effort via the skill invocation \fBase-task-estimate --force\fR \fIid\fR, i.e., even if it already carries a valid \fBEffort:\fR key, restores its previous assignee, and removes the request on success, else turns it into a failed request (to be re-requested). The estimation succeeds under the same conditions as in the mode \fBphase\fR, so a request for an explicit epic or a task with an empty plan fails.
+.P
+Both modes can run side by side as two agents of the kind \fBestimator\fR under different names (e.g., \fBestimator\fR and \fBestimator-request\fR).
+.P
+On an interrupt, a task being processed in the mode \fBphase\fR is left untouched, while the request of a task being processed in the mode \fBrequest\fR is turned back into a pending one. The estimator works in the project root only, so it neither requires a Git working copy nor \fBgit\fR, and it accepts no \fB--repo\fR and \fB--tempdir\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 estimator\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 estimator start\fR \[lB]\fIoptions\fR\[rB]: Start the estimator 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) 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: \fBestimator\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), 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 \fBestimator\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).
+.IP \(bu 4
+\[lB]\fB-m\fR|\fB--mode\fR \fImode\fR\[rB]: The mode of the agent (default: \fBphase\fR): \fBphase\fR estimates the unestimated tasks in \fBPLANNED\fR automatically and unclaimed (intended for the final estimation), while \fBrequest\fR (re-)estimates the tasks of the \fBestimate\fR requests in any unfinished status (intended for dry-runs). 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: \fBEstimate the effort of unestimated planned tasks\fR (\fBphase\fR) resp. \fBRe-estimate the effort of tasks on request\fR (\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: \fBproject\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: not set. Hence, all task lifecycle models are supported.
+.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, independent of their assignee and predecessors, and without ever changing their status and assignee (\fBphase\fR only). Built-in: enabled (mode \fBphase\fR) resp. not set (mode \fBrequest\fR).
+.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]: The state of the tasks to process (mandatory for \fBphase\fR, repeatable with \fB--unclaimed\fR only), where each state is adapted onto the task lifecycle model of the project. Built-in: \fBPLANNED\fR (i.e., \fBPLANNING\fR for \fBteam\fR and \fBOPEN\fR for \fBsolo\fR) (mode \fBphase\fR) resp. not set (mode \fBrequest\fR). For instance, \fB--state-incoming DRAFTED --state-incoming PLANNED\fR additionally estimates the drafted tasks of the \fBenterprise\fR model in the mode \fBphase\fR.
+.IP \(bu 4
+\[lB]\fB--state-activity\fR \fIstate\fR\[rB]: The state of a task during its processing. Generic default: the incoming state. Built-in: not set. Not allowed, as the estimator processes the tasks unclaimed.
+.IP \(bu 4
+\[lB]\fB--state-success\fR \fIstate\fR\[rB]: The target state on success. Generic default: the incoming state. Built-in: not set. Not allowed, as the estimator processes the tasks unclaimed.
+.IP \(bu 4
+\[lB]\fB--state-failure\fR \fIstate\fR\[rB]: The target state on failure. Generic default: the incoming state. Built-in: not set. Not allowed, as the estimator processes the tasks unclaimed.
+.IP \(bu 4
+\[lB]\fB--state-phase\fR \fIstate\fR\[rB]: The phase success state, into which the skill itself can move a task. Generic default: the success state. Built-in: not set. Not allowed, as the estimator processes the tasks unclaimed.
+.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. Generic default: the phase success state. Built-in: not set. Not allowed, as the estimator processes the tasks unclaimed.
+.IP \(bu 4
+\[lB]\fB--state-verdict\fR \fIVERDICT\fR\fB=\fR\fIstate\fR\[rB]: The target state per verdict (repeatable). Built-in: not set. Not allowed, as the estimator processes the tasks unclaimed.
+.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: \fBase-agent-estimator\fR (mode \fBphase\fR) resp. \fBase-agent-estimate\fR (mode \fBrequest\fR).
+.IP \(bu 4
+\[lB]\fB--tag-success\fR \fItag\fR\[rB]: The tag on success: \fItag-name\fR, \fItag-name\fR\fB:\fR\fIvalue\fR, or \fBnone\fR (\fBphase\fR only). Generic default: \fItag-name\fR. Built-in: \fBnone\fR (mode \fBphase\fR), as the valid \fBEffort:\fR key of an estimated task keeps it from being estimated again, resp. not set (mode \fBrequest\fR).
+.IP \(bu 4
+\[lB]\fB--tag-failure\fR \fItag\fR\[rB]: The tag on failure: \fItag-name\fR, \fItag-name\fR\fB:\fR\fIvalue\fR, or \fBnone\fR (\fBphase\fR only). Generic default: \fItag-name\fR. Built-in: not set.
+.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--tag-retry\fR\[rB]: A shorthand for \fB--tag-failure none\fR, so a failed task is processed again after a growing delay (\fBphase\fR only). 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. As the estimator never assigns a task in the mode \fBphase\fR, it then names the mode of the agent as announced to the agent relay only.
+.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: not set. Not allowed, as the estimator processes the tasks unclaimed.
+.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. Not allowed in the mode \fBphase\fR, as the estimator then processes the tasks unclaimed.
+.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. Not allowed in the mode \fBphase\fR, as the estimator then processes the tasks unclaimed.
+.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: not set (mode \fBphase\fR) resp. \fBestimate\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: not set (mode \fBphase\fR) resp. \fBestimated\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-estimate\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{id}\fR (mode \fBphase\fR) resp. \fB--force {id}\fR (mode \fBrequest\fR), the latter ignoring the request prompt.
+.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 and \fBclean\fR (in both modes, as a re-estimation of the same size leaves the plan content unchanged), where additionally the task has to carry a valid \fBEffort:\fR key afterwards.
+.IP \(bu 4
+\[lB]\fB--success-match\fR \fIregex\fR\[rB]: A regular expression an output line has to match (repeatable). Built-in: not set.
+.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: not set.
+.IP \(bu 4
+\[lB]\fB--attach-skip\fR \fIspec\fR\[rB]: The attachment \[lB]\fImime-type\fR\fB;\fR\[rB]\fIkind\fR leaving a task unclaimed (\fBphase\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-changeset\fR \fIkind\fR\[rB]: The kind of the attachment \fBtext/x-diff;\fR\fIkind\fR storing the change set snapshot of the task (with \fB--workdir changeset\fR or \fBtarget\fR only). Built-in: not set. Not allowed, as the estimator works in the project root.
+.IP \(bu 4
+\[lB]\fB--finish-commit\fR\[rB]: Commit the work onto a \fBbranch:\fR changeset and publish it (with \fB--workdir changeset\fR only). Built-in: not set. Not allowed, as the estimator works in the project root.
+.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 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 and its presence are named after \fBestimator\fR). See \fBase-agent-adhoc\fR(1) for their full semantics.
+.IP \(bu 4
+\fBase agent estimator status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Report whether the estimator agent of the name \fIname\fR (default: \fBestimator\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 estimator 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 estimator agent of the name \fIname\fR (default: \fBestimator\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: \fBestimator\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 estimator stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Stop the estimator agent of the name \fIname\fR (default: \fBestimator\fR) by \fBSIGTERM\fR, waiting (up to 5 minutes) until it aborted its running processings. An agent not running is reported informationally only.
+.RE 0
+.SH "CONFIGURATION"
+.P
+The estimation itself is configured by the keys \fBproject.task.effort.scale\fR, \fBproject.task.effort.factor\fR, \fBproject.task.effort.file\fR, \fBproject.task.effort.line\fR, and \fBproject.task.effort.iteration\fR of the skill \fBase-task-estimate\fR (see \fBase-config\fR(1)).
+.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
+\fIper-user state directory\fR\fB/agent-estimator/\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 estimator agent process, which records the tasks it currently processes, so no other agent of the kind \fBestimator\fR on the same host picks them up.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fBase agent estimator 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 or a missing agent tool). \fBase agent estimator status\fR exits with status \fB1\fR if the agent is not running.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# start the estimator, estimating the planned tasks without a valid effort
+$ ase agent estimator start
+
+# estimate all drafted and planned tasks once, e.g., in a CI context
+$ ase agent estimator start -f -o --state-incoming DRAFTED --state-incoming PLANNED
+
+# start a second estimator of another agent tool as a pool
+$ ase agent estimator start -n estimator-codex -t codex
+
+# additionally start an estimator processing the "estimate" requests,
+# and request the (re-)estimation of a drafted task
+$ ase agent estimator start -n estimator-request -m request
+$ ase task request example-task estimate re-estimate
+.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-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-adhoc\fR(1), \fBase-agent-fleet\fR(1), \fBase-agent-relay\fR(1), \fBase-task\fR(1), \fBase-task-board\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

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

@@ -0,0 +1,185 @@
+.TH "ASE-AGENT-FLEET" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent-fleet\fR - Manage a Fleet of Agents
+.SH "SYNOPSIS"
+.P
+\fBase agent fleet init\fR \[lB]\fB-c\fR|\fB--config\fR \fIfile\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB--lifecycle\fR \fImodel\fR\[rB] \[lB]\fB--force\fR\[rB]
+.P
+\fBase agent fleet start\fR \[lB]\fB-c\fR|\fB--config\fR \fIfile\fR\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]
+.P
+\fBase agent fleet status\fR
+.P
+\fBase agent fleet log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB]
+.P
+\fBase agent fleet stop\fR
+.SH "DESCRIPTION"
+.P
+\fBase agent fleet\fR manages a \fIfleet\fR of agents (see \fBase-agent\fR(1)), and optionally of the agent relay they report to (see \fBase-agent-relay\fR(1)), as given by a YAML configuration file (default: \fB.ase/fleet.yaml\fR). A supervising process runs each member in its own child process (in its own process group) via \fBase agent\fR \fIagent\fR \fBstart --foreground\fR resp. \fBase agent relay start --foreground\fR, and restarts it whenever it exits.
+.P
+All members log into the shared log \fB.ase/agent/fleet.log\fR of the fleet (or, with \fB--foreground\fR, to the terminal), where each line is prefixed with the name of the member writing it (resp. \fBfleet\fR for the fleet itself), padded to the longest name and followed by \fB|\fR (e.g., \fBimplementer | ase: \[lB]...\[rB]: \[lB]INFO\[rB]: ...\fR), and, on a terminal, colored by the name (the fleet in bold red, the relay in red, and all agents in blue).
+.P
+On its start, the fleet first starts the agent relay (if any, waiting up to 10 seconds until it persisted its runtime state), and then all agents in parallel (waiting up to 30 seconds for each one), where it passes the URL of the agent relay via \fB--agent-relay\fR and its actual token via \fB$ASE_AGENT_RELAY_TOKEN\fR to all agents. If any member fails to start, all members are stopped again and the failure is reported. A member exiting during the startup of the others is restarted once the fleet is ready.
+.P
+Afterwards, the fleet restarts every member whenever it exits (e.g., crashed, or stopped individually via \fBase agent\fR \fIagent\fR \fBstop\fR) after a delay starting at 1 second and doubled on each restart in a row up to 5 minutes, which is reset once the member ran for 10 minutes.
+.P
+On termination (\fBSIGTERM\fR, \fBSIGINT\fR, \fBSIGHUP\fR, or \fBSIGQUIT\fR), the fleet first stops all agents (each of which aborts its running processings and puts their tasks back) and then the agent relay (as the agents remove their presence from it), where a repeated signal is forwarded to all remaining members (terminating the agents at once).
+.P
+As each agent runs in its own process, the agents of a fleet do not coordinate their direct use of the Git working copy they are started in, so a working copy should be used directly by a single agent only, while the other agents are given \fBrepo\fR (see \fBase-agent\fR(1)).
+.P
+As the members run in their own process groups, they survive a fleet process killed without a chance to stop them (e.g., via \fBSIGKILL\fR). Such \fIorphaned\fR members, identified by their own runtime state still recording the process recorded by the runtime state of the fleet (resp., for the agent relay, by \fBrelay.yaml\fR still recording it), are stopped by the next \fBase agent fleet start\fR (before starting the new members) or \fBase agent fleet stop\fR.
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase agent fleet init\fR \[lB]\fB-c\fR|\fB--config\fR \fIfile\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB--lifecycle\fR \fImodel\fR\[rB] \[lB]\fB--force\fR\[rB]: Create the initial YAML configuration \fIfile\fR of a fleet for a task lifecycle model. For all models, it contains the section \fBrelay\fR (with all its options commented out, so they fall back to \fBproject.relay.url\fR, \fBproject.relay.crt\fR, and \fBproject.relay.key\fR), the section \fBdefault\fR (with \fBtool\fR, \fBparallel: 1\fR, and \fBtimeout: 60m\fR, plus \fBrepo\fR and \fBtempdir\fR commented out), the edit request agent \fBeditor\fR, the effort estimation agent \fBestimator\fR (mode \fBphase\fR, estimating the planned tasks, i.e., the \fBOPEN\fR tasks for \fBsolo\fR, the \fBPLANNING\fR tasks for \fBteam\fR, and the \fBPLANNED\fR tasks for \fBenterprise\fR, intended for the final estimation), a commented-out effort estimation request agent \fBestimator-request\fR (mode \fBrequest\fR, (re-)estimating the tasks in any unfinished status on request, intended for dry-runs), a commented-out research request agent \fBresearcher-request\fR (mode \fBrequest\fR, intended for topic-driven research), and a commented-out example of an ad-hoc request agent \fBlint\fR (see \fBase-agent-adhoc\fR(1)).
+.sp
+Additionally, it contains per task lifecycle model:
+.RS 4
+.IP \(bu 4
+\fBsolo\fR: no phase agents, as the model has no activity states, so its tasks are driven interactively, while the agents only assist.
+.IP \(bu 4
+\fBteam\fR: the ad-hoc implementation phase agent \fBdeveloper\fR (as the built-in phase agents support the \fBenterprise\fR model only), which claims only the \fBPLANNING\fR tasks explicitly assigned to \fBdeveloper\fR (as the other ones are still planned) into \fBIMPLEMENTING\fR, implements them from their \fBSource:\fR into their \fBChangeset:\fR via the \fBase-task-implement\fR skill, and puts them into \fBSTALLED\fR unless they became \fBIMPLEMENTED\fR.
+.IP \(bu 4
+\fBenterprise\fR: the planning phase agents \fBrebooter\fR, \fBcondenser\fR, and \fBresearcher\fR (mode \fBphase\fR), each processing only the \fBDRAFTED\fR tasks explicitly assigned to it, and the phase agents \fBimplementer\fR (mode \fBimplement\fR, 2 tasks in parallel, waiting for the effort estimation, with its parameter \fBeffort-wait\fR commented out, to be set to \fBfalse\fR if the \fBestimator\fR is removed), \fBqualifier\fR (mode \fBjudge\fR, 2 tasks in parallel, so a human still decides on the qualification), and \fBintegrator\fR (mode \fBsquash\fR).
+.RE 0
+.IP "" 4
+The configuration is checked like on \fBase agent fleet start\fR before it is written, and an already existing \fIfile\fR is overwritten only with \fB--force\fR. Options:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-c\fR|\fB--config\fR \fIfile\fR\[rB]: the YAML configuration file to create (default: \fB.ase/fleet.yaml\fR of the project).
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: the agent tool of all agents, \fBclaude\fR, \fBcopilot\fR, or \fBcodex\fR (default: \fB$ASE_TOOL\fR, else \fBclaude\fR).
+.IP \(bu 4
+\[lB]\fB--lifecycle\fR \fImodel\fR\[rB]: the task lifecycle model, \fBsolo\fR, \fBteam\fR, or \fBenterprise\fR (default: the configured \fBproject.task.lifecycle\fR, else \fBsolo\fR).
+.IP \(bu 4
+\[lB]\fB--force\fR\[rB]: overwrite an already existing configuration file.
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: show the usage information and exit.
+.RE 0
+.IP \(bu 4
+\fBase agent fleet start\fR \[lB]\fB-c\fR|\fB--config\fR \fIfile\fR\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]: Start the fleet of the YAML configuration \fIfile\fR (see \fBCONFIGURATION\fR) in the background (spawning a detached supervising process logging into \fB.ase/agent/fleet.log\fR), and return once all members started successfully, or with \fB--foreground\fR run the fleet in the current process.
+.sp
+The configuration is validated before the fleet starts. An already running fleet is left alone (and is an error with \fB--foreground\fR). With the section \fBrelay\fR, the fleet owns the per-user agent relay, which hence must not run already (stop it first via \fBase agent relay stop\fR, or remove the section \fBrelay\fR). Options:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-c\fR|\fB--config\fR \fIfile\fR\[rB]: the YAML configuration file (default: \fB.ase/fleet.yaml\fR of the project).
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--foreground\fR\[rB]: run the fleet in the current process, logging to the terminal, until it is interrupted (e.g., via \fBCTRL+C\fR) or stopped via \fBase agent fleet stop\fR (default: the option \fBforeground\fR of the section \fBfleet\fR).
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: show the usage information and exit.
+.RE 0
+.IP \(bu 4
+\fBase agent fleet status\fR: Report whether the fleet is running (with its process id and configuration file, and whether it is still starting up), and for each member (with its kind) whether it is running (with its process id) or awaiting its restart, and how often it was restarted. Exits with status 1 if the fleet is not running.
+.IP \(bu 4
+\fBase agent fleet log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB]: Show the log \fB.ase/agent/fleet.log\fR of the fleet run in the background, aggregating the lines of the fleet itself and of all its members, each one prefixed with its name, where the name and the log level tag are colored if the output is a terminal.
+.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. If no log file exists, this is just reported (at log level \fBinfo\fR).
+.IP \(bu 4
+\fBase agent fleet stop\fR: Stop the fleet with all its members, first all agents and then the agent relay, by sending \fBSIGTERM\fR to the fleet process and waiting (up to 5 minutes) until it is gone. With the fleet process already gone (e.g., killed via \fBSIGKILL\fR), its orphaned members are stopped instead (see \fBDESCRIPTION\fR). A not running fleet is reported as such, without an error.
+.RE 0
+.SH "CONFIGURATION"
+.P
+The YAML configuration file of a fleet consists of the following top-level sections, where all options are given by their long names (without the leading \fB--\fR), \fBtrue\fR enables a flag, \fBfalse\fR or an empty value omits an option, and a list repeats an option:
+.RS 0
+.IP \(bu 4
+\fBfleet\fR: (optional) The options of the fleet itself. The only option is \fBforeground\fR (a boolean, the same as \fB--foreground\fR of \fBase agent
+fleet start\fR).
+.IP \(bu 4
+\fBrelay\fR: (optional) The options \fBaddress\fR, \fBport\fR, \fBtoken\fR, \fBcors\fR, \fBtls-cert\fR, and \fBtls-key\fR of \fBase agent relay start\fR (see \fBase-agent-relay\fR(1)). The presence of this section (even if empty) lets the fleet run and own the per-user agent relay.
+.sp
+Its options not given fall back as follows: \fBaddress\fR, \fBport\fR, and \fBtoken\fR to those of the configured \fBproject.relay.url\fR (its embedded token, else \fB$ASE_AGENT_RELAY_TOKEN\fR, else \fBproject.relay.token\fR), if it addresses a local address of this host (else this is warned about and \fBproject.relay.url\fR is not adopted), where a deviating \fBaddress\fR or \fBport\fR (resp. a \fBtls-cert\fR with an adopted \fBproject.relay.url\fR selecting HTTP) is warned about, as the task boards following \fBproject.relay.url\fR then do not see the agents of the fleet; and \fBtls-cert\fR and \fBtls-key\fR to \fBproject.relay.crt\fR and \fBproject.relay.key\fR (unless an adopted \fBproject.relay.url\fR selects HTTP), where an adopted \fBproject.relay.url\fR selecting HTTPS requires both.
+.IP \(bu 4
+\fBdefault\fR: (optional) The default options of all agents: \fBtool\fR, \fBparallel\fR, \fBtimeout\fR, \fBrepo\fR, \fBtempdir\fR, and \fBagent-relay\fR (see \fBase-agent\fR(1)), each one applied only to the agents supporting it (e.g., \fBrepo\fR not to \fBrebooter\fR), and overridden by the section of an agent. The option \fBagent-relay\fR is not allowed together with the section \fBrelay\fR.
+.IP \(bu 4
+\fIname\fR: One section per agent, named by its agent name (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), with the options of \fBase agent\fR \fIkind\fR \fBstart\fR and an optional \fBkind\fR (default: the section name), i.e., one of the built-in kinds \fBrebooter\fR, \fBcondenser\fR, \fBimplementer\fR, \fBqualifier\fR, \fBintegrator\fR, \fBeditor\fR, \fBestimator\fR, and \fBresearcher\fR, a definition kind of the project or the user, or \fBadhoc\fR (see \fBase-agent-adhoc\fR(1)). Hence, an agent of a definition kind is given by a section of its kind (or with \fBkind:\fR \fIkind\fR), and an agent defined inline by a section with \fBkind: adhoc\fR.
+.sp
+The options of the definitions can also be nested by group, like in a definition file (e.g., \fBprompt: { text: ... }\fR), where a key must not be given both flat and nested. The values of the parameters declared by the definition are given by the map \fBparams\fR (e.g., \fBparams: { severity: high }\fR), which repeats the option \fB--params\fR \fIname\fR\fB=\fR\fIvalue\fR per parameter.
+.sp
+The \fBdefinition\fR of \fBkind: adhoc\fR (unless a \fBbuiltin:\fR one) is relative to the configuration file, where hooks can be given only through a TypeScript or JavaScript definition file. A section without any options (an empty value) runs the agent of the kind of its name with its defaults.
+.RE 0
+.P
+The following is refused, as the definitions of all agents are already resolved and validated on the start of the fleet:
+.RS 0
+.IP \(bu 4
+the options \fBname\fR (given by the section name), \fBone-shot\fR (as the members are restarted), \fBforeground\fR, and \fBhelp\fR in the section of an agent, and \fBagent-relay\fR there together with the section \fBrelay\fR;
+.IP \(bu 4
+an unknown section option of \fBfleet\fR, \fBrelay\fR, or \fBdefault\fR, an invalid option name (other than lower-case letters, digits, and dashes), and a value other than a string, a number, a boolean, or a list of strings and numbers (resp., for \fBparams\fR, a map of strings, numbers, and booleans);
+.IP \(bu 4
+an unknown agent kind, and an option unknown to the \fBstart\fR command of the agent kind;
+.IP \(bu 4
+more than one agent of a built-in kind processing serially only (i.e., \fBintegrator\fR), and two agents processing serially only on the same tag (e.g., two agents of \fB--serial\fR definitions of the same resolved \fB--tag-name\fR, or one next to \fBintegrator\fR with its tag \fBase-agent-integrator\fR);
+.IP \(bu 4
+a configuration without any agent.
+.RE 0
+.P
+Before the fleet starts, the structure of the configuration, the option names, the option syntax, and the definitions of the agents are checked, while the remaining option values (e.g., \fBparallel\fR or \fBtool\fR) are checked only once the corresponding member starts.
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default of \fB--tool\fR of \fBase agent fleet init\fR, and of the agents without a \fBtool\fR option.
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The fallback token of the agent relay of the section \fBrelay\fR, if not embedded in \fBproject.relay.url\fR. The fleet passes the actual token of its agent relay to all agents through this variable.
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/fleet.yaml\fR: The default configuration of the fleet, written by the user (or initially created via \fBase agent fleet init\fR) and intended to be versioned.
+.IP \(bu 4
+\fB.ase/agent/fleet.yaml\fR: The process state of the running fleet: its process id and process start time, its configuration file, whether all its members completed their initial startup, and the kind, process id (\fBnull\fR while awaiting its restart), and number of restarts of each member. It exists while the fleet runs.
+.IP \(bu 4
+\fB.ase/agent/fleet.log\fR: The shared log of the fleet run in the background and of all its members.
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.yaml\fR: The process state of the member agent named \fIname\fR, existing while it runs.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fBinit\fR, \fBstart\fR, and \fBstop\fR exit with status 0 on success (also for a fleet already running resp. not running) and 1 on any error. \fBstatus\fR exits with status 1 if the fleet is not running. \fBlog\fR exits with status 0.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# create the initial configuration of a fleet, and start and follow it
+$ ase agent fleet init -t claude --lifecycle enterprise
+$ ase agent fleet start
+$ ase agent fleet status
+$ ase agent fleet log -f
+
+# stop the fleet with all its members
+$ ase agent fleet stop
+.fi
+.RE
+.P
+A configuration \fB.ase/fleet.yaml\fR with the agent relay, the built-in agents, two editors of different agent tools, an agent of the definition file \fB.ase/agents/reviewer.mts\fR, and an ad-hoc request agent:
+.P
+.RS 2
+.nf
+fleet:
+    foreground: true
+relay:
+    port:     4711
+default:
+    tool:     claude
+rebooter:
+implementer:
+    parallel: 2
+editor-claude:
+    kind:     editor
+editor-codex:
+    kind:     editor
+    tool:     codex
+reviewer:
+    parallel: 2
+    params:
+        severity: high
+lint:
+    kind:     adhoc
+    type:     request
+    prompt:
+        text: "Lint the source code of task {id} with focus on: {prompt}"
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-agent\fR(1), \fBase-agent-adhoc\fR(1), \fBase-agent-relay\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-task-board\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR