---
title: Workflow Templates
description: Reusable workflow template creation, updates, linting, selection, nested workflow references, and system workflows.
relatedCommands:
  - alpaca workflow create --help
  - alpaca workflow update --help
  - alpaca workflow delete --help
  - alpaca workflow lint --help
  - alpaca workflow list --help
  - alpaca eject --help
relatedDocs:
  - workflow-template-authoring
  - command-flows
  - capabilities
  - workflow-options
  - hierarchical-workflows
  - setup
---

# Workflow Templates

Use this guide when creating, updating, selecting, validating, or publishing reusable workflow templates.

## When to Use

- Use `alpaca workflow create` when prompt mode should decide whether to reuse, update, or create a reusable workflow template, or when manual mode should create a new template.
- Use `alpaca workflow update` when an existing template should be improved.
- Use `alpaca workflow delete` when a repo-local template should be removed after checking references.
- Use `alpaca workflow list` to inspect non-system selectable templates.
- Use `alpaca workflow lint` before publishing workflow template changes.
- Use `alpaca eject workflows` when packaged system workflows need repo-local customization.

## Key Commands

```bash
alpaca workflow create -h
alpaca workflow update -h
alpaca workflow delete -h
alpaca workflow list -h
alpaca workflow lint -h
alpaca publish -h
```

## Core Behavior

Repo-local workflow templates live under `.alpaca/workflows`. Packaged system workflows use `__system/...` identifiers and can be ejected when the repository needs a local override.

Workflow template frontmatter describes the template. Important fields include `description`, `targets`, `autoSelect`, `updateMode`, `requires.skills`, and `requires.mcp`. `targets` controls where a template can be selected, such as `issue`, `pull_request`, `unplanned`, or `followup`. `recurring` is not a target; recurring behavior uses an `issue` workflow plus issue schedule state such as `--every` or `--cron`. `autoSelect` controls whether automatic selection can choose it.

Prompt mode can inspect the existing catalog and return a reuse, update, or create decision. When it drafts or updates content, it can set template path, description, targets, auto-selection eligibility, required skill refs, required MCP refs, and body. Manual mode writes explicit content or a generic scaffold. `--save-draft` writes review JSON without changing templates; `--apply-draft <path|->` applies a reviewed draft without rerunning the worker.

Template-set mode lets one prompt produce a coordinated set of create, update, reuse, and update-path move decisions. Use it when a request may require several reusable templates rather than one file, but keep the set to the smallest cohesive reusable architecture instead of creating one template per issue step. `update_existing` may move paths only in template-set mode; non-template-set update keeps the fixed target path. Prefer `<domain>/<role>-<scope>.md` paths, reuse existing domain folders before adding new ones, and avoid synonym folders for the same domain.

`alpaca workflow list --target <issue|pull_request|unplanned|followup>` shows non-system user-selectable templates for a target. Add `--include-system` when you need system workflows in the output. Merge uses the built-in merge surface plus the `merge-guidance` system prompt instead of a workflow template.

`alpaca workflow list --references-to <template.md>` shows workflow templates and config selectors that reference a template. Use it before deleting or moving a template. `alpaca workflow delete --path <template.md>` deletes only repo-local templates and blocks while references remain. Use `--cleanup-references --save-draft` to prepare reviewed updates for editable referring templates; this cleans references but does not cascade-delete other templates.

For experiment-style issue work, inspect selectable templates with `alpaca workflow list --target issue --format json` before choosing a path. Use `experiment/optimization-prompt.md` when the issue should compare prompt, system-prompt, or workflow-prompt alternatives under shared evaluation conditions and then adopt or defer based on evidence. Use `experiment/arm-benchmark.md` when the issue should run one isolated baseline, control, or variant arm and collect structured evidence without comparing candidates or adopting changes unless the issue explicitly asks for that. For broad comparisons with separately tracked alternatives, keep synthesis on the parent issue and use child issues only when each alternative needs its own objective, outputs, completion checks, and at least one separate-tracking reason such as independent evidence, review boundary, or likely multiple AI cycles.

`alpaca workflow lint --path <template>` checks the selected template and nested workflow references strictly, including required skill/MCP availability. Use the targeted form as the readiness check for a template you are selecting, editing, or publishing. `alpaca workflow lint` without `--path` checks the full catalog structure strictly but reports required capability availability as warnings, because unselected templates may require capabilities that are not configured for the current repository.

Nested workflow references use `@workflow <template-path>` when the referenced template should be expanded and planned as its own step. Use a prose path reference when the current step should simply read and follow a document without creating a separate planned step; `@workflow` is an operational directive, not just a link.

`maxNestedWorkflowDepth` in `alpaca.config.json` limits nested workflow expansion. `0` disables nested workflows.

System workflows can be ejected to `.alpaca/workflows/__system/`. Non-ejected system workflows use packaged fallbacks. Workflow selectors accept `auto`, `auto_select`, `no_template`, or a template path. `auto` lets `workflow_select` use a candidate template, use the target's built-in default workflow, or request a missing reusable template. `auto_select` only chooses an existing candidate or `no_template`; when no candidates exist, AlpacaLoop falls back to `no_template` without a `workflow_select` worker run. `no_template` keeps that selector name but resolves at runtime to the target's built-in system default workflow, such as `__system/default-issue.md` or `__system/default-followup.md`. Auto-selected templates are fit-reviewed before planning. Template requests during normal run execution create or reuse a blocking `missing-workflow-template` setup issue; prompt-mode issue creation stores unresolved auto/auto_select workflow selection so workflow setup handles that choice after the parent issue exists. If the selected template narrows or contradicts the parent request, AlpacaLoop creates or reuses a blocking `workflow-template-fit` setup issue.

Packaged system workflows are selected by their `__system/...` path:

| System workflow | How users reach it | Purpose |
| --- | --- | --- |
| `__system/workflow-maintenance.md` | Pass it with `alpaca issue create --workflow __system/workflow-maintenance.md`, or include it as a follow-up recommendation preference with `--followup-preferred-workflow-template`. | Create or refresh reusable repository workflow templates from a repository-purpose prompt. It is explicit-only and is not auto-selected for ordinary issues or follow-ups. |
| `__system/skill-resolution.md` | Use `alpaca skill create --prompt <gap request>`, a missing required-skill setup issue, or a skill-capability follow-up preferred with `--followup-preferred-workflow-template`. | Resolve missing reusable skill support before the parent workflow continues. |
| `__system/mcp-resolution.md` | Use `alpaca mcp create --prompt <gap request>`, a missing required-MCP setup issue, or an MCP-capability follow-up preferred with `--followup-preferred-workflow-template`. | Resolve missing reusable MCP server support before the parent workflow continues. |

Workflow template setup issues, including `missing-workflow-template` and `workflow-template-fit`, use `__system/workflow-maintenance.md`. They should prepare templates through `alpaca workflow create/update --template-set --prompt --save-draft` plus reviewed draft apply, not primary direct Markdown editing.

Optional repository system prompts live under `.alpaca/system-prompts/` after `alpaca eject system-prompts`, or at paths configured by `paths.systemPrompts`. They are repository guidance, not workflow templates. Run `alpaca docs show setup` for the table of which system prompt applies to each worker run. They can shape worker quality and style, but core schemas, validation, security, and control-plane behavior must come from AlpacaLoop itself.

## Watch Outs

- Catalog IDs and marketplace candidates are not valid `requires.skills` values until the skill is installed or enabled and visible in `alpaca skill list`.
- MCP install candidates are not valid `requires.mcp` proof until `alpaca mcp verify` confirms the ref.
- The service does not publish local template edits automatically. Use `alpaca publish --path .alpaca/workflows` when workflow-only edits should become visible.

## Related Docs

- `alpaca docs show workflow-template-authoring`
- `alpaca docs show command-flows`
- `alpaca docs show capabilities`
- `alpaca docs show workflow-options`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show setup`
