---
title: Follow-Up Workflows
description: Ways to request, configure, and publish independent follow-up issues after source issue or PR completion.
relatedCommands:
  - alpaca issue followup --help
  - alpaca issue create --help
  - alpaca issue show --help
  - alpaca workflow list --help
relatedDocs:
  - config
  - issues
  - workflow-options
  - scheduling
  - workflow-state
  - hierarchical-workflows
  - service-runtime
---

# Follow-Up Workflows

Use this guide when an issue or pull request should create independent work after the source item is complete.

Do not use follow-up for work required to satisfy the source item's current done criteria. Use same-issue replanning or a blocking child issue when the source item must wait for the new work before it can finish.

## Core Behavior

Follow-up issues are independent post-completion work. They do not block or reopen the source issue or PR, and they are not parent/child workflow issues. AlpacaLoop creates new tracker issues or reuses open follow-up issues whose stored origin links match the source item and follow-up request.

The created issue title uses the automatic recommendation item title when available, otherwise the first short explicit follow-up request paragraph, and otherwise the source item title, for example `Source title (#42)`. The body includes a source link, the completed source result, the follow-up request, and a rule that the new issue should run independently. Each follow-up issue stores an origin link back to the source plus a request digest, uses the source item's effective base branch as its merge target, and then runs like a normal managed issue.

Follow-up issues do not copy the source issue's execution contract. AlpacaLoop creates an initial follow-up contract from the follow-up item title and request body; the generated issue body carries source context for the planning run, which may replace the initial contract with the final objective and `doneWhen`. This keeps the follow-up goal independent from the source `doneWhen` while preserving source context in the issue body.

AI budget counters are chain-level guardrails, so a follow-up issue inherits the source `consecutiveAiRuns` and `totalAiRunHours`. If that inherited budget already reaches the configured limit, the new follow-up starts in Needs Human / Run Limit. Comment scan cursors are issue-local, so a follow-up does not inherit the source `lastScannedCommentCursor`.

The follow-up workflow selector is separate from the source issue workflow. Use a template whose frontmatter includes `targets: [followup]`, or inspect available templates with `alpaca workflow list --include-system --target followup`. A selector of `auto` or `auto_select` is stored unresolved and is selected when the follow-up issue runs; if `auto_select` has no candidates, AlpacaLoop stores `no_template` without a `workflow_select` worker run.

Use `alpaca issue show --issue <source-id> --view followup --format text` to inspect the source chain, related work, PR context, and post-completion user comments when planning follow-up from a completed source item. Add `--parents all --limit all` only when the bounded output does not explain the follow-up intent.

Follow-up is not scheduling. Use `alpaca docs show scheduling` when the same source issue should run at a future time or on a repeated cadence. Use follow-up when the source item is complete and the remaining work should be tracked as a separate issue.

## Choose a Path

| Need | Use | Result |
| --- | --- | --- |
| Create a follow-up issue now | `alpaca issue followup --issue <id>` | Forces an explicit follow-up request and creates or reuses the follow-up issue immediately. |
| Create a scheduled or recurring follow-up issue now | `alpaca issue followup --issue <id> --prompt "<request with timing or cadence>"` | Stores the request in the follow-up issue body so normal setup/autofill can infer one-shot or recurring scheduling. |
| Preview the immediate result | `alpaca issue followup --issue <id> --dry-run` | Prints the selected follow-up workflow without creating an issue, comment, or label update. |
| Ask the worker to decide after completion | First-line comment `/alpaca --followup-proposal if_needed` or `alpaca issue create ... --followup-proposal if_needed` | Stores proposal policy `if_needed`; follow-up issues are created only for positive `workflow_closing` recommendation items. |
| Explicitly request one from the tracker UI | Add the configured follow-up request label, default `AI: Follow-up` | Stores policy `always`; AlpacaLoop creates or reuses a follow-up issue after the source item is complete, including from closed-item scans. |
| Require confirmation before publication | Comment `/alpaca --followup-proposal-approval confirm` on the first non-empty line | Stores proposal approval `confirm`; AlpacaLoop posts a follow-up proposal comment and waits for the follow-up request label before creating issues. |
| Prefer templates during automatic recommendation | Comment `/alpaca --followup-preferred-workflow-template <path|no_template[,path...]|default>` on the first non-empty line | Adds the path as a priority hint in the `workflow_closing` follow-up recommendation prompt. It is repeatable, not an allowlist, and does not force issue creation. `default` clears the item-level template override. |
| Override automatic recommendation caps | Comment `/alpaca --followup-max-main-work-issues <0..5|default>` and/or `/alpaca --followup-max-maintenance-issues <0..5|default>` on the first non-empty line | Overrides the source item's automatic follow-up caps. `default` clears that category override. |
| Allow follow-up workflow template maintenance | Comment `/alpaca --followup-auto-maintain-templates <true|false|default>` on the first non-empty line | Controls whether created follow-up issues may request missing or improved workflow templates through `auto`. |
| Disable pending automatic follow-up | `/alpaca --followup-proposal off` or `alpaca issue create ... --followup-proposal off` | Stores proposal policy `off` and consumes a pending follow-up request label. |

## Examples

Create a follow-up issue now after reviewing the source issue:

```bash
alpaca issue followup --issue 123 --dry-run
alpaca issue followup --issue 123 --workflow auto
alpaca issue followup --issue 123 --prompt "Check the release state once in one week."
```

Ask the worker to decide at completion time for a new issue:

```bash
alpaca issue create --prompt "Improve cache invalidation for stale profile data." --followup-proposal if_needed
```

Ask the worker to decide at completion time for an existing tracker item:

```md
/alpaca --followup-proposal if_needed
```

Put the actual follow-up criteria in the issue body or a normal human comment; explanatory text after the `/alpaca ...` command is treated as immediate same-issue replan context.

## Immediate Command

`alpaca issue followup --issue <id>` is the direct path when a human wants an independent post-completion follow-up issue now instead of waiting for normal source completion. Add `--prompt <text>` to write a concrete follow-up request into the created issue body. When that text says the work should run once later or on a cadence, the follow-up issue goes through normal workflow setup/autofill and can become scheduled or recurring. Add `--workflow <auto|auto_select|no_template|path>` to choose the follow-up workflow selector. `no_template` creates the follow-up issue with the built-in default follow-up workflow, and an explicit path must point to a follow-up-capable template when the issue is published.

The command writes follow-up publication state back to the source item and clears the follow-up request label after a newly created follow-up issue or an unrecorded reused follow-up issue. Already recorded follow-up publications are treated as complete on later scans or reruns, so AlpacaLoop does not post another created-feedback comment or run issue-creation event hooks for the same follow-up request. It can also run against a closed source item as long as the tracker item is an eligible issue or pull request.

## Workflow Option

`--followup-proposal if_needed` means "decide at completion time." `--followup-proposal always` always requests follow-up proposal generation, and `--followup-proposal off` disables it. `--followup-proposal-approval auto` publishes accepted recommendations immediately, `confirm` always posts a proposal comment first, and `confirm_if_needed` lets the worker mark individual recommendation items for confirmation.

Use this on a new issue with `alpaca issue create ... --followup-proposal if_needed`, or on an existing item by adding a tracker comment whose first non-empty line is `/alpaca --followup-proposal if_needed`. The `workflow_closing` worker can then recommend zero or more follow-up items, each with a `category`, title, body, reason, optional `workflowTemplate`, and optional per-item `proposalApproval`. AlpacaLoop creates up to `followup.maxIssuesPerSource.mainWork` `mainWork` issues and up to `followup.maxIssuesPerSource.maintenance` `maintenance` issues from those items unless the item is waiting for confirmation. If the recommendation is negative, absent, or has no items, AlpacaLoop records the skip and closes the source normally.

When a proposal is waiting for confirmation, add human comments to request candidate additions, revisions, or removals, then add the follow-up request label. AlpacaLoop runs a dedicated proposal review worker over comments added after the proposal comment and creates issues from the reviewed candidate list. Approved proposal items are explicit human-approved work and are not limited by `followup.maxIssuesPerSource`.

When AlpacaLoop posts a follow-up generation result, automatic recommendations include a category summary table. The table shows created or reused issue counts, the configured `mainWork` and `maintenance` caps, and notes such as created issue IDs, skipped or failed item counts, and categories with no recommendation.

For automatic judgment, only the final `workflow_closing` prompt includes `followup-recommendation-guidance` when the follow-up proposal policy is not `off`. The guidance tells the worker to compare latest user instructions, source issue body, execution contract, plan, step results, PR/merge result, and evidence; plan completion alone is not enough. It recommends only independently trackable work from the same source issue, classifies `mainWork` as continuation of the source issue's main requested work and `maintenance` as reusable execution/workflow-environment improvement, excludes follow-up items generated inside child issues, merges duplicate candidates before returning items, inspects `alpaca workflow list --include-system --target followup --format json` when feasible, and does not treat missing follow-up templates as a reason to skip useful follow-up work. `followup.preferredWorkflowTemplates` and `--followup-preferred-workflow-template` are listed as priority candidates in that prompt only; remaining capacity may still use other listed templates or `no_template`. `--followup-max-main-work-issues` and `--followup-max-maintenance-issues` override the source item caps without changing repo defaults. If source completion depends on a pull request merge, AlpacaLoop runs `workflow_closing` and attempts follow-up publication during PR merge finalization.

## Request Label

The configured `ticketTracker.workflowLabels.aiFollowUp` label, default `AI: Follow-up`, is explicit human input. It is not a queue state like `AI: Ready`. AlpacaLoop converts the label into canonical follow-up state and removes the label after the request is recorded or after successful closed-item follow-up publication. When a label-only request has no explicit follow-up body, post-completion source issue comments from users are used as the follow-up request text; bot, managed, and command-only comments are ignored.

If the source item is already closed, the service scans closed items with the follow-up request label. A label-only closed request uses the stored canonical follow-up state if it exists, otherwise it materializes default follow-up state from `followup.proposalPolicy` and `followup.proposalApproval`. This materializes the labeled request only; it does not migrate unrelated existing closed items. A command-only comment on a closed item is not enough for closed scanning unless it was already converted into canonical follow-up state before closure.

When follow-up creation fails because a template is missing or source-state publication fails, the label can remain in place so the request can be retried after the problem is fixed. If the closed source item's latest canonical workflow state comment is invalid, the service skips that source, leaves the follow-up request label in place, and continues scanning other sources.

## Watch Outs

- Use `--followup-proposal if_needed` for automatic judgment; use the request label or `alpaca issue followup` when a human definitely wants a follow-up issue.
- Automatic follow-up can create multiple issues, but only up to the category caps in `followup.maxIssuesPerSource`; explicit follow-up requests create one issue per request.
- Planned `child_issue` issues use `followup.childIssuePolicy`: `inherit` copies only the parent's follow-up proposal policy and approval mode to newly created child issues, while `off` disables child follow-up. Existing child issues are not migrated.
- Put `/alpaca ...` commands on the first non-empty line of the tracker comment. Extra explanatory text after the command is same-issue replan context; recurring or scheduled run instructions belong in the issue body instead.
- A follow-up issue is independent post-completion work. Use a child issue instead when the source issue must wait on the new work before it can finish.
- A recurring issue is for repeated work on a cadence. A follow-up issue is for independent post-completion work.

## Related Docs

- `alpaca docs show issues`
- `alpaca docs show config`
- `alpaca docs show workflow-options`
- `alpaca docs show scheduling`
- `alpaca docs show workflow-state`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show service-runtime`
