---
title: Command Flows
description: Issue, draft, workflow template, and event hook command entry points.
relatedCommands:
  - alpaca issue --help
  - alpaca workflow --help
  - alpaca event-hook --help
relatedDocs:
  - quick-start
  - issues
  - scheduling
  - workflow-templates
  - workflow-template-authoring
  - event-hooks
  - publishing
---

# AlpacaLoop Command Flows

Use this guide after the `alpaca` skill has triggered and the user request involves creating issues, applying reviewed drafts, creating/updating/deleting workflow templates, or finding the event hook entry point. Before running any command, inspect the relevant leaf command with `-h`; CLI help is the source of truth for current options.

## Key Commands

```bash
alpaca issue create -h
alpaca workflow create -h
alpaca workflow update -h
alpaca workflow delete -h
alpaca publish -h
alpaca event-hook -h
```

## Issue and Draft Apply Flows

Use `alpaca issue create` only after the user explicitly asks to create, file, record, or publish work as an issue or ticket.

For an explicit issue/ticket creation request:

1. If the user asks to create, file, record, or publish the issue now, run `alpaca issue create -h`, then run `alpaca issue create --prompt "<request>"` with any confirmed metadata options and report the created issue.
2. If the user asks to review first or approval is unclear, run `alpaca issue create -h`, then run `alpaca issue create --prompt "<request>" --save-draft`. Read the printed draft file and show the selected issue template, title, body, unconfirmed fields, and labels. Show workflow options only when the draft JSON contains `workflowOptions`.
3. After clear approval of a saved draft, publish the same draft JSON with `alpaca issue create --apply-draft <path|->`; do not rerun prompt mode for the approved issue.

The `alpaca issue create -h` page separates issue creation options from initial workflow options. The workflow option keys match `/alpaca ...` issue comments.

Prompt mode drafts only issue title, body, and provider Markdown issue template selection. It does not let the worker decide tracker metadata or workflow metadata directly. Workflow setup and option autofill run after the issue body is finalized.

For repository workflow maintenance, create an issue whose prompt describes this repository's purpose and bind it to the packaged system workflow:

```bash
alpaca issue create --prompt "Describe this repository's purpose and desired workflow behavior." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off
```

`__system/workflow-maintenance.md` is explicit-only and is not auto-selected for ordinary issues or follow-ups.

Keep the request split this way:

- Put repository purpose, desired workflow behavior, target surfaces, and constraints in the prompt or body.
- Put worker choice, run limits, base branch, schedules, and workflow selectors in CLI options.
- Let workflow maintenance inspect existing workflows and visible skill/MCP state.
- Workflow maintenance should not create, install, or configure skills or MCP servers. Split that into explicit capability work when the user asks for it.

Run `alpaca docs show scheduling` before adding one-shot or recurring schedule options to workflow maintenance issues.

## Workflow Template Drafts

Use `alpaca workflow create -h`, `alpaca workflow update -h`, or `alpaca workflow delete -h` before selecting prompt/manual/delete/apply-draft modes.

Use `alpaca workflow create/update --save-draft` when a user wants to review workflow template content before it is written; read the printed draft file. Prompt mode may reuse an existing template, update a close template, or create a missing reusable template. Use `--template-set` when one prompt may need multiple reusable workflow template create/update/reuse decisions, keeping the result to the smallest cohesive reusable set.

`update_existing` may move paths only in template-set mode. Non-template-set `workflow update` keeps the fixed target path.

Workflow template setup issues, including `missing-workflow-template` and `workflow-template-fit` preflight blockers, run through `__system/workflow-maintenance.md`. Use `alpaca workflow create/update --template-set --prompt --save-draft` for the primary template changes, then apply the reviewed draft; direct Markdown edits should only be small post-draft review fixes.

For a single template, show the resolved path, description, required skills, required MCP refs, body, and update base digest when present. For a template set, show each item action and path, create/update item description, required skills, required MCP refs, body, update base digest and impact when present, and reuse reason for reuse items.

Apply only after review, using the same draft JSON with `alpaca workflow create --apply-draft <path|->`, `alpaca workflow update --apply-draft <path|->`, or `alpaca workflow delete --apply-draft <path|->`; do not rerun prompt mode for the approved template. Update and delete drafts include the original template digest and fail if the template changed before apply.

Use `alpaca publish --path .alpaca/workflows` after workflow create/update/delete when only workflow template edits should be published. The service does not publish local edits automatically.

## Workflow Template References

Workflow template filenames are identifiers. Selectability is declared with frontmatter `targets`, and automatic selection eligibility is declared with `autoSelect`.

Use `alpaca workflow create --target <target>` to declare where a template can be selected, and `--no-auto-select` when the template should be explicit-only.

Use `alpaca workflow list --target <issue|pull_request|unplanned|followup>` to inspect non-system user-selectable templates. Add `--include-system` when you need to inspect system workflows. Use `alpaca workflow list --references-to <template.md>` before deleting or moving a template. Merge uses the built-in merge surface plus the `merge-guidance` system prompt instead of a workflow template.

When workflow selection is `auto`, `workflow_select` decides whether to use a candidate template, use `no_template`, or request a missing reusable template. When workflow selection is `auto_select`, `workflow_select` may choose an existing candidate or `no_template`, and AlpacaLoop falls back to `no_template` without a worker selection run when there are no candidates. Choose `use_template` when one listed candidate clearly fits the work class and adds useful reusable sequencing, judgment, safety checks, or coordination guidance without narrowing or contradicting the request. Choose `no_template` for simple, one-off, or ordinary work where a repository-specific reusable template would mostly restate obvious planning steps; it resolves to the target's built-in system default workflow. Choose `request_template` only when the slot is `auto`, reusable workflow guidance would materially improve safety, consistency, repeatability, or required coordination, and no listed candidate fits. A template request during run execution creates or reuses a blocking `missing-workflow-template` setup issue. Prompt-mode issue creation stores unresolved auto/auto_select workflow selection, so this same workflow setup path runs after the parent issue exists. Auto-selected templates are fit-reviewed before planning; a mismatch creates or reuses a blocking `workflow-template-fit` setup issue instead of launching the parent workflow.

Use `@workflow <template-path>` only when the referenced template should be expanded as a nested workflow and planned as its own step. The directive is operational, not just a link.

Mention a repo-local workflow document path such as `.alpaca/workflows/notification/supervisor-slack.md` in prose when that file exists in the target repository and the current workflow or current step should read and follow that document without creating a separate planned step.

For cross-cutting guidance that applies when any step reaches a condition, such as supervisor Slack notification before `wait_human`, prefer a prose document path reference unless a distinct child workflow step is intentionally desired.

Before adding a nested workflow reference, check whether an existing template can be reused or updated. Create a new referenced module only for a distinct reusable responsibility boundary with its own evidence, review, or integration boundary.

## Publish Event Hooks

Use `alpaca docs show event-hooks` for event hook setup and behavior.

Before executing a hook command, inspect the leaf help with `alpaca event-hook <subcommand> -h`. Treat `event-hook test` as a real run because hooks may perform external side effects.

## Related Docs

- `alpaca docs show issues`
- `alpaca docs show scheduling`
- `alpaca docs show workflow-templates`
- `alpaca docs show workflow-template-authoring`
- `alpaca docs show event-hooks`
- `alpaca docs show publishing`
