---
title: Workflow Options
description: Issue and PR workflow overrides, /alpaca command comments, workflow selectors, workers, run limits, and links to schedule and follow-up behavior.
relatedCommands:
  - alpaca issue create --help
  - alpaca issue approve --help
  - alpaca issue start --help
  - alpaca issue followup --help
relatedDocs:
  - quick-start
  - issues
  - scheduling
  - follow-up
  - workflow-templates
  - workflow-state
  - hierarchical-workflows
  - config
---

# Workflow Options

Use this guide when setting initial workflow options on a new issue or interpreting `/alpaca ...` command comments.

## When to Use

- Use workflow options on `alpaca issue create` to seed an issue's workflow configuration at creation time.
- Use a first-line `/alpaca ...` issue comment when changing workflow options on an existing tracker item.
- Use this guide when deciding between `auto`, `auto_select`, `no_template`, and an explicit workflow template path.
- Use `alpaca docs show scheduling` for one-shot schedules, recurring parent issues, first-run options, and auto-stop behavior.
- Use `alpaca docs show follow-up` for follow-up issue creation and automatic follow-up judgment.

## Key Commands

```bash
alpaca issue create -h
alpaca issue approve -h
alpaca issue start -h
alpaca issue followup -h
alpaca docs show scheduling
alpaca docs show follow-up
alpaca docs show workflow-templates
alpaca docs show config
```

## Option Paths

Use `alpaca issue create ... <workflow options>` only for initial issue setup. It accepts option tokens such as `--workflow`, `--base-branch`, `--max-ai-runs`, and scheduling options. It does not accept tracker-comment body text after `/alpaca ...`.

Use a tracker comment when changing an existing item:

```text
/alpaca --workflow review.md --max-ai-runs 8
```

The `/alpaca ...` line must be the first non-empty line. Body text after workflow options becomes immediate same-issue replan context when the command supports it. Text that only mentions `/alpaca` later in a normal sentence, an `alpacaloop` URL, or a `skills/alpaca/...` path is not a command.

## Core Behavior

Workflow selectors choose which reusable workflow template should apply to a target. `--workflow`, `--pr-workflow`, and `--unplanned-workflow` accept `auto`, `auto_select`, `no_template`, or a path. `auto` asks `workflow_select` to choose whether to use an auto-selectable candidate, use `no_template` for that target, or request a missing reusable template. `auto_select` asks `workflow_select` to choose an existing auto-selectable candidate or `no_template` when candidates exist; if there are no candidates, AlpacaLoop stores `no_template` without a worker selection run. `no_template` keeps that selector name but resolves at runtime to the target's built-in system default workflow. For follow-up, issue creation is controlled separately by `followup.proposalPolicy`, `followup.proposalApproval`, and request labels. An explicit path selects a specific workflow template.

For issue body setup and issue-create prompt flows, setup does not resolve `auto` or `auto_select` template selection. Prompt-mode issue creation stores unresolved selectors; issue body setup may publish non-template options first, then normal execution handles workflow selection after the parent issue exists.

`--followup-proposal <off|if_needed|always|default>` controls whether follow-up recommendations are generated; `--followup-proposal-approval <auto|confirm|confirm_if_needed|default>` controls whether proposed items are published immediately or wait for confirmation; `--followup-preferred-workflow-template <path|no_template[,path...]|default>` adds priority template hints for the `workflow_closing` follow-up recommendation prompt and is repeatable; `--followup-auto-maintain-templates <true|false|default>` chooses whether follow-up issue workflow selection may request missing or updated templates; `--followup-max-main-work-issues <0..5|default>` and `--followup-max-maintenance-issues <0..5|default>` override automatic follow-up category caps for this source item. For repo defaults, automatic judgment, immediate creation, label requests, and closed-item behavior, run `alpaca docs show follow-up` and `alpaca docs show config`.

Schedule options control one-shot scheduled runs and recurring parent issues. Use `alpaca docs show scheduling` for `--run-at`, `--run-after`, `--every`, `--cron`, first-run controls, auto-stop controls, duration formats, time zones, and recurring child behavior.

Execution overrides include `--default-worker`, `--thinking-worker`, `--base-branch`, `--max-ai-runs`, `--max-ai-hours`, `--recurring-max-active-children`, `--recurring-update-child-title-after-plan`, `--foreign-approval-scope`, `--workflow-start-new-plan`, `--workflow-start-replan`, `--workflow-start-scope`, `--requirements-setup-skills`, and `--requirements-setup-mcp`. Most accept `default` to return to config behavior. Worker overrides must name a configured built-in worker or custom worker id from `customWorkers`. `--default-worker` affects ordinary execution, and `--thinking-worker` affects planning, selection, reconciliation, autofill, and draft-style worker runs before they fall back to default workers. `--base-branch` stores the issue's effective base branch, which becomes its pull-request merge target.

Pull request related overrides include `/alpaca pr`, `--issue-completion-target`, `--pr-review`, `--pr-merge`, `--pr-workflow`, and `--default-reviewers`. `/alpaca pr` sets the completion target to pull request and leaves review and merge policies at their effective defaults. `--issue-completion-target` accepts pause-on-issue, pull-request, or default. `--pr-review` accepts never, if-needed, always, or default. `--pr-merge` accepts manual, auto, or default.

For the full mapping between `alpaca.config.json` keys and Issue/PR override options, run `alpaca docs show config` and see "Settings and Issue Overrides".

`--max-ai-runs <count|default>` limits consecutive AI runs before human input is required. `--max-ai-hours <hours|off|default>` limits total AI work hours before human input is required. When either limit is reached, AlpacaLoop stops and publishes a needs-human run-limit message instead of continuing automatically.

When `aiWorkflowOptionAutofill` is `on`, AlpacaLoop can infer workflow options from issue bodies and fresh comments. Explicit command options remain the clearest way to avoid ambiguity.

On existing tracker items, workflow command comments must put `/alpaca ...` on the first non-empty line. `/alpaca approve` is for foreign input approval, and `alpaca issue approve --issue <id>` is the equivalent CLI path for the issue's single assignee. `/alpaca start` is for start approval after a plan is waiting for confirmation, and `alpaca issue start --issue <id>` is the equivalent CLI path for the issue's single assignee. Do not use those commands as general natural-language requests.

## Watch Outs

- Store product requirements in issue body text. Store worker choice, run limits, schedules, base branch, and workflow selectors in workflow options.
- Treat extra text after a tracker comment `/alpaca ...` command as immediate same-issue replan context. Do not put future recurring or scheduled run instructions there; put them in the issue body.
- Ensure the configured remote base branch exists before the first managed issue or service run. `alpaca doctor` reports a missing remote base branch and suggests pushing it or rerunning `alpaca init --base-branch <existing-branch>`.
- An explicit workflow selection skips workflow selection. Use it only when the target template is known.
- Recurring parent issues should usually stay open while monitoring or repeated work remains active; run `alpaca docs show scheduling` before changing their schedule.

## Related Docs

- `alpaca docs show issues`
- `alpaca docs show scheduling`
- `alpaca docs show follow-up`
- `alpaca docs show workflow-templates`
- `alpaca docs show workflow-state`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show config`
