---
title: Workflow State
description: Managed labels, workflow updates, resume behavior, and status interpretation.
relatedCommands:
  - alpaca issue list --help
  - alpaca issue show --help
  - alpaca issue disable --help
  - alpaca issue enable --help
  - alpaca labels sync --help
relatedDocs:
  - quick-start
  - issues
  - scheduling
  - follow-up
  - service-runtime
  - workflow-options
  - hierarchical-workflows
  - maintenance
---

# AlpacaLoop Workflow State

Use this guide when interpreting managed labels, workflow updates, resume behavior, or status questions.

## Key Commands

```bash
alpaca issue list -h
alpaca issue show -h
alpaca issue disable -h
alpaca issue enable -h
alpaca issue unlock -h
alpaca labels sync -h
alpaca state patch -h
```

## Workflow Labels

Use `ticketTracker.workflowLabels` in `alpaca.config.json` as the source of truth for managed label names. Queue state defaults are `AI: Ready`, `AI: Running`, `AI: Needs Human`, `AI: Working in PR`, `AI: Scheduled`, `AI: Recurring`, and `AI: Disabled`.

Use `ticketTracker.workflowLabels.aiFollowUp`, default `AI: Follow-up`, for the follow-up request label. Use `ticketTracker.workflowLabels.aiCoolingDown`, default `AI: Cooling Down`, as an auxiliary label on `AI: Scheduled` issues waiting for AI quota or capacity recovery.

The follow-up label is request input, not a queue state. AlpacaLoop preserves it until the follow-up request is processed, including on closed items that still need follow-up scanning.

Use `alpaca docs show scheduling` for the behavior behind `AI: Scheduled`, `AI: Recurring`, and recurring children. Use `alpaca docs show follow-up` for follow-up request handling.

If `workflowLabels` changes, run `alpaca labels sync` to create any missing labels. Existing issues with old labels are not migrated automatically.

Closed or merged items are not runnable. AlpacaLoop removes stale workflow status and auxiliary managed labels from closed items during service sync, while preserving user labels and pending follow-up request labels.

Default intent:

- `AI: Ready`: AlpacaLoop can process the issue now.
- `AI: Running`: AlpacaLoop is running or has accepted a continuation for the issue. It may hold active AI ownership, or it may be waiting for the service to launch the next worker after a human resume. A human can release active or stale ownership with `alpaca issue unlock`.
- `AI: Needs Human`: Human input or inspection is required before continuing. If `AI: Ready` is also present, AlpacaLoop treats the issue as runnable and prioritizes `AI: Ready`.
- `AI: Working in PR`: Work moved to a pull request.
- `AI: Scheduled`: AlpacaLoop will promote the issue to `AI: Ready` when its one-shot schedule or cooldown is due.
- `AI: Cooling Down`: AlpacaLoop is waiting for AI quota or capacity recovery and will retry through the scheduled queue.
- `AI: Recurring`: AlpacaLoop monitors the issue as a recurring parent.
- `AI: Disabled`: AlpacaLoop must not process this issue automatically. Use `alpaca issue disable` to add this rule without changing the current status, and `alpaca issue enable` to remove only this rule.

AlpacaLoop closes an issue after a workflow reaches terminal success, unless the workflow is recurring or is waiting on PR handoff. `proceed` advances the workflow to the next step; it does not mean the issue should bounce between `AI: Running` and `AI: Ready` on every step.

When work moves to a pull request, the source issue becomes `AI: Working in PR` and the PR thread carries the next review or merge work. Closed or merged items are not runnable queue entries.

## Progress Updates

Use this shape:

```md
## In progress: Updating the plan

Implemented the requested change and prepared the next AI pass.

**What AI will do next**

AI will run another worker cycle.

<details>
<summary>Details</summary>

- Event: replan queued
- Run count: 1
- Run time: 15m
- AI status: Running

</details>
```

Required parts:

- A status heading in `## Status: title` form, such as `## Needs input: Plan created`, `## In progress: Work started`, `## Complete: Work is complete`, or `## Failed: Attention is needed`.
- A short summary immediately after the heading.
- One action heading: `**What I need from you**`, `**What AI will do next**`, or `**Next step**`.
- A `<details><summary>Details</summary>` block.
- Bullet metadata for `Event` and `Run count`; include `Run time` when available.

Do not duplicate data that the configured tracker already stores.

Workflow update comments explain what happened and what happens next. They are not workflow commands and should not be treated as worker instructions for the next run.

For Needs Human comments, keep the visible action note self-contained and readable for non-engineers first. Put the specific decision or preparation needed under `**What I need from you**`, use short bullets when multiple action items are needed, include the recommended path and a safe alternative, and avoid internal execution terms such as runner, workflow, MCP, continuation, blocker, token file, or environment unless the person already used them or the term is unavoidable. When setup depends on an external service, link official setup documentation with human-readable labels and a short note about what each page is for instead of pasting bare URL lists. Do not ask people to paste secrets into issues, repositories, or logs, and do not include reply examples unless the person explicitly asks for them. Use plain Markdown paragraphs, lists, and links instead of HTML details or collapsible sections.

Example:

```md
## Needs input: Review the next action

Production readiness was checked. The repository is ready for deployment work, but the production domain, analytics IDs, Search Console verification choice, and publication approval are still missing.

**What I need from you**

Decision needed:

- Continue with production publication after the domain, analytics ID, Search Console choice, and publication approval are prepared.
- Keep production publication on hold and continue only with non-production checks.

Preparation needed:

- Ask the person with access to the hosting and analytics accounts to prepare the production domain and analytics ID.
- Ask the person with Search Console access to choose the verification method.
- Confirm whether publication is approved.

Cautions:

- Do not paste secrets, tokens, or private verification values into the issue, repository, or logs.
- Use the project's safe secret-setting method for any credential values.

Reference:

- [Cloudflare Pages custom domains](https://developers.cloudflare.com/pages/configuration/custom-domains/) - How to connect the production domain.
- [Find your GA4 measurement ID](https://support.google.com/analytics/answer/12270356) - Where to find the analytics ID.
- [Verify site ownership in Search Console](https://support.google.com/webmasters/answer/9008080) - How to choose a site verification method.
```

## When You Add a Comment

When you add a normal comment to a managed issue, AlpacaLoop reads it before continuing.

If AI is already working, it first checks the new comment and tries the work again with that comment included. If the current plan still fits, AI continues without changing the plan.

If the comment changes what needs to be done, AlpacaLoop updates only the needed unfinished part of the plan. Completed work and existing child issues are kept. When a child issue also needs its own update, AlpacaLoop queues that child issue to be reviewed separately instead of silently rewriting it from the parent.

If the issue is waiting for plan approval, a normal comment is treated as feedback on the plan. AI updates the plan, then waits for approval again.

## Resume and Progress Questions

When resuming, read past workflow update comments, read human replies after the latest Needs Human handoff, and use the current workflow labels as the primary queue signal.

For `question`, `run_limit`, `review_ready`, and `system_error` Needs Human handoffs, a fresh plain human comment after the handoff resumes service work by moving the issue to `AI: Running`. Manually setting `AI: Ready` remains the explicit foreground-run resume path.

When one of those human-input handoffs resumes, AlpacaLoop clears the handoff reason and resets run-count and run-hours accounting before the next worker claim.

For repo-wide status or progress questions without a specific issue, run `alpaca issue list --days 14 --state open --format markdown --limit 20` first. For assigned-work questions, add `--me` for the authenticated tracker user or repeat `--assignee <login>` for specific users.

For a specific issue detail question, run `alpaca issue show --issue <id> --format markdown`. Add `--children 1 --limit 5` when the question is about related child issues, recurring runs, or unplanned child issues; use `--children all --limit all` only when full child history is needed.

Use `alpaca doctor` or `alpaca service status` only when the user explicitly asks about service state or health.

## Related Docs

- `alpaca docs show issues`
- `alpaca docs show scheduling`
- `alpaca docs show follow-up`
- `alpaca docs show service-runtime`
- `alpaca docs show workflow-options`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show maintenance`
