---
title: Workflow Template Authoring
description: Authoring rules for reusable workflow templates, including scope, process guidance, handoff, success criteria, and capability requirements.
relatedCommands:
  - alpaca workflow create --help
  - alpaca workflow update --help
  - alpaca workflow delete --help
  - alpaca workflow lint --help
  - alpaca workflow list --help
relatedDocs:
  - workflow-templates
  - command-flows
  - capabilities
  - publishing
  - hierarchical-workflows
---

# Workflow Template Authoring

Use this guide when writing or reviewing reusable workflow templates. Keep templates as durable process guidance for a class of work, not as a one-off issue plan.

## Responsibility Boundary

- The issue body holds the concrete request, background, success criteria, constraints, and unresolved questions.
- Workflow options store workflow selection, schedules, workers, run limits, base branch, side workflow selectors, follow-up behavior, and approval overrides.
- The workflow template defines reusable guidance: primary intent, deliverable quality bar, rules, process options, handoff boundaries, evidence expectations, success criteria, and required capabilities.
- AlpacaLoop owns tracker labels, comments, issue closing, dependency materialization, PR handoff, and decision JSON validation. Do not model those control-plane effects as worker steps.

## Template Shape

Workflow templates live under `.alpaca/workflows/` and use normalized relative `.md` paths with no whitespace. Filename suffixes are only identifiers; selectability comes from frontmatter.

Frontmatter supports `description`, `targets`, `autoSelect`, `updateMode`, `requires.skills`, and `requires.mcp`. `targets` uses `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: false` makes a template explicit-only. `updateMode` controls workflow CLI updates.

Template bodies should use clear headings in the configured output language when they improve worker judgment. Useful sections are reusable goal or intent, rules, required process, handoff conditions, and success criteria. `alpaca workflow lint` validates machine-readable directives and references, not literal heading names.

## Process Guidance

Write reusable process guidance, not the issue's concrete target. Keep cross-cutting constraints in rules, and keep required process focused on steps that genuinely improve future worker judgment.

Good guidance includes:

- Confirm the primary intent, success conditions, and in-scope human concerns before expanding work.
- For abstract requests, reduce the concrete issue into a reusable goal contract: primary intent, audience or consumer, deliverable or target state, quality bar, observable success evidence, constraints, unknowns, shared readiness, and integration responsibility. Use 5W1H as an internal coverage checklist, not as required template headings.
- For reusable improvement or optimization workflows, include the evaluation contract pattern: baseline or current-state discovery, metric or evaluation axis, source of truth, measurement window policy, target or decision threshold policy, guardrails or non-goals, and claim-boundary reporting.
- Inspect available capabilities, credentials, required skills, MCP refs, and human-only boundaries.
- Preserve explicit user or template procedure order; otherwise derive order from dependencies and evidence.
- Split work by responsibility boundary, deliverable, evidence bundle, and review or integration boundary, not by every file or bullet.
- Record observable evidence from commands, files, APIs, tracker state, child issue results, or logs.
- Avoid invented facts, skipped verification, and hidden residual risk.

## Nested Module References

Before adding a nested workflow module, inspect the existing catalog and prefer `reuse_existing` when a template already fits, `update_existing` when a close template should own the reusable responsibility, and `create_new` only when the catalog lacks a suitable reusable boundary.

Use `@workflow <template-path>` only when the referenced template should become a separate nested workflow step with its own execution evidence. Keep one `@workflow` call site per referenced module in the owning template, and explain conditional applicability in prose instead of repeating the directive. Use a plain workflow document path, such as `.alpaca/workflows/notification/supervisor-slack.md`, when the current template or step should only read reference guidance. Do not split templates by issue step, file, bullet, phase label, or convenience alone.

Prefer `<domain>/<role>-<scope>.md` for repository-local template paths. Reuse an existing domain folder for the same purpose before creating a new folder, and avoid synonym folders for the same domain.

## Handoff and Success

Handoff guidance should tell the worker when to stop after accessible evidence has been inspected. Use it for missing credentials, unsafe operations, unavailable services, product judgment, approvals, or genuinely ambiguous human preference. If the repo, tracker, CLI output, logs, local docs, available skills, MCP tools, or permitted research can answer the question, instruct the worker to inspect those first.

Success criteria should describe observable completion evidence. Include expected result shape, verification evidence, blockers, residual risks, and follow-up split when relevant. Do not put issue closing, labels, PR merge, publish behavior, comment formatting, or decision JSON fields in success criteria.

Use `continuation.strategy: "replan_same_issue"` only when the remaining work still belongs on the same issue but the current plan cannot satisfy issue-level success criteria. Use `continuation.strategy: "spawn_child_issue"` only for a blocker with its own objective, outputs, completion checks, and at least one separate-tracking reason such as an independent deliverable, evidence bundle, review or integration boundary, materially different responsibility area, or likely multiple AI cycles. Use follow-up workflows for independent post-completion improvements.

## Capabilities

Before declaring required capabilities, decide whether the workflow's primary intent, deliverable quality bar, or observable evaluation evidence truly needs specialized support. Use `alpaca capability list/search` as the cross-type discovery view, compare skill and MCP candidates by purpose fit, target narrowness, source trust, and quality signals, and prefer the usable skill only when candidates satisfy the same need equally well.

After capability discovery shows that a skill requirement is the right fit, use `alpaca skill list` to confirm the final `requires.skills` refs, and store only refs that are usable for required skills and not excluded from workflow requires. After capability discovery shows that MCP is the right fit, use `alpaca mcp list` or `alpaca mcp verify` to confirm the final `requires.mcp` refs, and store only usable refs that are not excluded from workflow requires. Catalog ids and install candidates are discovery inputs, not requirement refs until installed or verified.

## Related Docs

- `alpaca docs show workflow-templates`
- `alpaca docs show command-flows`
- `alpaca docs show capabilities`
- `alpaca docs show publishing`
- `alpaca docs show hierarchical-workflows`
