---
title: Hierarchical Workflows
description: Parent and child issue behavior, nested workflow references, continuation choices, start approval, and workflow state interpretation.
relatedCommands:
  - alpaca issue show --help
  - alpaca workflow lint --help
  - alpaca issue followup --help
relatedDocs:
  - workflow-templates
  - decision-guide
  - scheduling
  - follow-up
  - workflow-state
  - issues
  - workflow-options
  - config
---

# Hierarchical Workflows

Use this guide when interpreting parent/child workflow behavior, nested workflow references, unplanned child issues, recurring children, follow-up issues, or start approval state.

## Runtime Shape

AlpacaLoop stores shared workflow state in managed tracker comments and projects the user-visible state through labels and workflow updates. The current queue labels and `alpaca issue show` output are the safest way to inspect state.

Workflow runtime behavior is determined by the active workflow surface and the current plan step kind. Template filenames or role labels do not decide whether a run is parent work, child work, or PR work.

## Parent and Child Issues

Plans can contain normal task steps, nested workflow references, or `child_issue` steps. A `child_issue` step creates or reuses a tracker issue with its own objective and completion checks. The parent waits while the child is open, then records the child result before continuing. For parallel controller children, closed children whose workflow plan is complete can be recorded on the parent before sibling children close.

Child issues plan from their own starting context, including the parent result that created them. If a child objective is still broad, it can create deeper `child_issue` steps instead of absorbing unrelated work into one issue. Grandchild issues are normal when they emerge from child-level evidence; they are not pre-planned by the top parent.

Child issue types commonly seen by users:

- Controller child: a planned child issue created from a parent workflow step.
- Unplanned child: a blocking child issue created when execution discovers separate work with its own objective.
- Recurring child: a child issue created from a recurring parent schedule. Run `alpaca docs show scheduling` for cadence, overlap, first-run, and auto-stop behavior.
- Setup child: a blocker for missing workflow templates, workflow template fit gaps, required skills, or required MCP refs.

Controller children and ordinary unplanned children branch from the parent issue branch, then unblock back into that parent. Recurring, setup, and reusable skill/MCP resolution children keep using the parent issue's effective base branch. Follow-up issues are not children; they independently use the source item's effective base branch and inherit chain-level AI budget counters. New controller and ordinary unplanned child issues inherit the configured run limits and worker settings, but start with fresh consumed AI budget instead of inheriting the parent's used run count or runtime hours. Planned controller children also use `followup.childIssuePolicy`: `inherit` copies only the parent follow-up proposal policy and approval mode, while `off` disables child follow-up; unplanned children do not use this setting.

Use `alpaca issue show --issue <id> --children 1 --limit 5` to inspect recent child history and current relationships. Use `--children all --limit all` only when the bounded output leaves a concrete question about full child history.

## Child Progress Display

Use the parent workflow state comment to interpret planned controller child steps. Use `alpaca issue show --issue <id> --children 1 --limit 5` when you need the linked child issue list, including current controller children. Use `--children all --limit all` only when the bounded child history hides the relationship you need to inspect.

A controller child step can appear in three common unfinished states:

- `In progress`: the child step has a child issue reference, such as `#894`, and the parent workflow is not paused. For parallel controller children, more than one materialized child step can show `In progress` at the same time because the parent is waiting for each referenced child to finish.
- `Not started`: the child step has not been materialized yet, so the machine state still has no child issue reference. In `alpaca issue show --children`, the same unmaterialized controller child appears with its child key and a pending state instead of a tracker issue link.
- `Not started` while paused: the child step has a child issue reference, but the parent workflow is waiting for human input, start approval, or foreign input approval. The child reference still identifies the child issue; the display avoids showing active progress while the parent workflow is paused.

When a controller child issue finishes and closes with a completed workflow plan, the parent records the child result on the corresponding step before it can continue to dependent parent steps. If all child issues are closed but a parent step still shows `Not started`, check that the parent has reflected each child result and that later parent dependencies are satisfied.

## Replanning

Replan from the issue where the new instruction arrived. `replan` and `revise_plan` update the existing plan with an incremental `planPatch`: unchanged work is omitted, completed evidence is preserved, and the resulting canonical workflow state still stores a full current plan. Normal replans update the latest canonical workflow state comment instead of appending a new canonical snapshot.

For controller children, keep stable `childKey` values and preserve existing `childIssueRef` links. If an unstarted child contract changes, the parent can update the child issue before it starts. If a started child contract changes, queue that child for its own replan or hand off for human review; do not silently rewrite, detach, or cancel it from the ancestor plan. Detach means the child remains visible but no longer blocks the parent. Cancel means the child work itself should stop.

For `workflow_ref`, preserve control-plane metadata such as `callSiteId`, `expansionGroupId`, `originSubtreeKey`, and source template identity. Refresh or remove workflow_ref subtrees only when doing so does not discard completed evidence or materialized child issue side effects.

## Nested Workflow References

Use `@workflow <template-path>` only when the referenced template should expand into its own nested workflow step. Use a plain workflow document path in prose when the current step should read and follow guidance without creating a separate planned step.

Before adding a nested workflow reference, prefer reusing or updating an existing template. Add a new nested module only for a distinct reusable responsibility boundary, not for each issue step, file, bullet, or phase label. Reference each nested module once from the owning template; repeated `@workflow` directives for the same template create duplicate planned steps and fail validation.

`maxNestedWorkflowDepth` limits expansion. `0` disables nested workflow expansion.

## Start Approval and Human Approval

Start approval is a plan-start gate. When required, AlpacaLoop publishes the plan and waits for the current assignee to comment `/alpaca start` or run `alpaca issue start --issue <id>`. This is separate from final review, execution-time questions, credentials, unsafe operations, and `wait_human` handoffs.

Foreign input approval is different. When non-assignee input needs approval, the assignee can resume by commenting `/alpaca approve` or by running `alpaca issue approve --issue <id>`. The CLI command posts the same approval comment after confirming that the authenticated tracker user is the issue's single assignee. Use exact first-line commands; additional inline arguments are not part of these approvals.

If a normal comment arrives during start approval, AlpacaLoop may treat it as plan revision input and keep execution stopped until a valid `/alpaca start` comment or `alpaca issue start --issue <id>` command is accepted.

## Completion and Follow-Up

A parent issue closes only after all required parent steps are complete. Finishing all children is not enough if later same-issue steps remain.

Follow-up issues are independent post-completion work. They do not block the source issue and they do not copy the source execution contract. A follow-up gets a fresh objective/`doneWhen` seed from the follow-up request while inheriting chain-level AI budget counters such as `consecutiveAiRuns` and `totalAiRunHours`; issue-local scan cursors are not inherited. Use `--followup-proposal`, `--followup-proposal-approval`, `--followup-preferred-workflow-template`, `--followup-auto-maintain-templates`, `--followup-max-main-work-issues`, `--followup-max-maintenance-issues`, or the configured follow-up request label to control follow-up behavior.

## Related Docs

- `alpaca docs show workflow-templates`
- `alpaca docs show decision-guide`
- `alpaca docs show scheduling`
- `alpaca docs show follow-up`
- `alpaca docs show workflow-state`
- `alpaca docs show issues`
- `alpaca docs show workflow-options`
- `alpaca docs show config`
