# Workflow Template Authoring Guidance

- Workflow templates are reusable instructions for a class of AlpacaLoop work. Write them as operational guidance for future workers, not as a one-off issue plan.
- The issue says what concrete target to handle; the workflow says how that class of work should be handled.
- Keep issue bodies focused on the concrete request, background, success conditions, constraints, and unconfirmed items. Put reusable process guidance in workflow templates.
- Use a Rules section for workflow-wide scope boundaries, safety constraints, notification requirements, compatibility policy, or behavior that should affect every step.
- Use a Required Process section only when a reusable order of operations or decision checklist improves worker judgment. Do not encode the issue's concrete target there.
- Useful process guidance can cover intent confirmation, capability checks, procedure order, plan splitting, evidence capture, shortcut checks, and reusable learning.
- When a workflow class can benefit from existing implementations, libraries, templates, tools, prior issue results, or OSS projects, encode a lightweight reuse-first check before designing from scratch. The check should respect the repository's direction and constraints, such as minimal dependency policy, architecture boundaries, operational simplicity, and preferred local conventions.
- For external or third-party sources, make reuse conditional on compatible license and terms, acceptable source trust and maintenance signals, bounded security/privacy risk, necessity for the workflow's quality bar, and verification inside the repository. Do not require external reuse when it conflicts with project policy, adds unjustified dependency weight, or weakens maintainability.
- When using prior issues, workflow memory, or historical examples as reusable guidance, carry forward only current, relevant, verified decisions, blockers, and lessons; do not generalize stale assumptions, one-off incidents, long transcripts, or unverified conclusions.
- For broad reusable workflows, describe responsibility boundaries, dependency order, expected deliverables, evidence bundles, review or integration boundaries, and final synthesis expectations so workflow planning can decide same-issue tasks versus child issues. Do not hard-code concrete child_issue steps unless the reusable workflow architecture itself requires a nested tracker.
- Before adding a nested workflow module, check whether an existing template can be reused or updated. Add a new module only when the responsibility is reusable, separately executable, and has its own evidence or review boundary.
- 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.
- Use `@workflow <template.md>` only when the referenced template should become a separate nested workflow step. If the current template only needs reference guidance, mention the workflow document path in prose instead.
- Keep only one `@workflow <template.md>` call site per referenced module in the owning template. Explain conditional use in prose instead of repeating the directive in rules and process sections.
- Example: use `@workflow evidence.md` when evidence collection should run as its own nested workflow. Use `.alpaca/workflows/notification/supervisor-slack.md` in prose when the worker should only read notification guidance when relevant.
- For workflows where target work depends on setup, preflight checks, sandbox state, external resources, generated assets, commands, permissions, or shared prerequisites, define an execution-readiness gate before target execution, dependent work, scoring, adoption, or final success. Name the prerequisites, source of truth, validation evidence, and failure routing.
- Encode primary-intent and human-concern guidance as reusable decision criteria, not issue-specific empathy language. Avoid duplicating global `worker-common` or `workflow-common` rules unless the workflow needs sharper domain-specific guidance.
- Before drafting reusable process or capability guidance, reduce the concrete request into a reusable goal contract: primary intent, deliverable quality bar, observable evaluation evidence, and important unknowns. Use 5W1H only as an internal coverage check for the reusable class.
- For broad new service, app, automation, API, integration, or business/product workflow classes, require an early validation gate for unverified success assumptions before dependent implementation. The gate should test or bound target users, demand, adoption or acquisition path, differentiation, trust/safety, data/privacy, authentication, operations, acceptance evidence, and constraints whose failure would make the work ineffective.
- For reusable improvement or optimization workflows, define 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 that prevent proxy success, and claim-boundary reporting.
- For reusable comparison, experiment, or alternative-based optimization workflows, encode the repeatable process rather than one-off candidates: define baseline capture, shared evaluation criteria, candidate generation boundaries, fair-run conditions, evidence collection, selection or deferral rules, rejected-option rationale, adoption steps, rollback or safety checks, and residual-risk reporting.
- For reusable experiment, validation, benchmark, sandbox, or migration workflows, separate the user's target work from wrapper work such as setup, sandbox creation, comparison, evidence collection, and reporting. Preserve source inputs that must be executed or evaluated, distinguish control repositories, sandbox repositories, source repositories, and seed sources, and require evidence that the target work actually started or explicitly mark the result blocked before target execution.
- Do not let successful wrapper work imply successful target work. When target execution never starts, the workflow should record blocked-before-run evidence, defer scoring or adoption, and make the next safe action clear instead of treating the target as complete.
- For workflows that use bounded, sampled, partial, or time-limited execution, require result reporting to state the evidence claim boundary: what the observed run proves, what remains unproven, and whether conclusions are completion-grade, comparison-grade, or partial-confidence only.
- Keep domain-specific experiment details in the workflow only when they are reusable for that class of work. Leave concrete candidates, run duration, target issue ids, repository names, and adoption thresholds to the issue body unless the workflow class requires fixed defaults.
- For reusable workflows that wrap, replay, evaluate, compare, audit, or continue another task, define the boundary between orchestration context and target-task content. Use orchestration context for setup, constraints, evaluation, evidence, and stopping rules; keep the target task's own intent, constraints, and completion evidence as the work being executed or assessed.
- When later review, comparison, audit, continuation, or adoption depends on the workflow result, define the reusable evidence contract at the category level: original input, run conditions, actions taken, outputs or diffs, checks, blockers, decisions, and residual risk. Use concrete filenames, schemas, or artifact paths only when they are reusable for that workflow class; leave one-off storage details to the issue body.
- For capability selection, use `alpaca capability list/search` as the cross-type discovery view before deciding whether the requirement should be a skill, MCP server, or no declared requirement.
- Compare candidates by purpose fit, target narrowness, source trust, and quality signals. When a skill and MCP satisfy the same need equally well, prefer the usable skill; choose MCP when it is the better fit or the workflow truly depends on configured live tool/resource/API/server access.
- Do not declare candidates excluded from workflow requires. They are hidden by default; use `--include-excluded` only when you need to debug why a visible candidate should not be used in `requires.skills` / `requires.mcp`.
- Write the template description as selection guidance, not as a generic summary. It should help `workflow_select` decide when to use the template.
- For each declared target, state the condition that makes the template appropriate. For example, distinguish ordinary issue work, pull request review, unplanned blocker work, and post-completion follow-up work when a template supports multiple targets.
- For `followup` templates, describe the source completion pattern or residual improvement that should trigger this template, such as verification hardening, documentation follow-through, automation, cleanup, monitoring, or a focused investigation.
- `recurring` is not a workflow template target. Recurring behavior comes from issue schedule state; when a template is meant for recurring issue work, declare the `issue` target and write guidance that each recurring child run can complete against bounded history and current evidence. One-shot scheduled issue work also uses the `issue` target; describe only the reusable handling of the issue, not the run time.
- Make real dependencies explicit. Steps that touch the same file, share the same responsibility area, rely on the same verification result, or consume another step's output, decision, contract, data, or generated artifact should be ordered; genuinely independent alternatives can be separate steps with a later integration or selection step.
- Write process guidance for a reusable class of issues. Do not include one-off targets, requested deliverables, repository facts, paths, commands, services, people, labels, schedules, or constraints unless they are part of the reusable process and confirmed from the repository.
- Handoff To Human When should cover ambiguity that remains after accessible evidence is inspected, unavailable credentials or services, irreversible operations, and product or operational judgment. Do not route inspectable or independently fixable verification blockers to humans by default; for fixable blockers that need separate tracking, describe the split or unplanned-child routing expectation instead.
- Success Criteria should define the final output shape and observable completion evidence, including verification, blockers, residual risks, and follow-up split when relevant.
- Keep workflow bodies concise, usually 20 to 60 lines. Split unrelated responsibility clusters into child issues or nested workflows instead of combining them.
- For an undeclared reusable capability gap, split resolution only when the gap blocks safe completion and is likely to recur.
- Before returning a template, self-review it for reusable scope, clear boundaries, evidence quality, actionable final result, and absence of invented repository facts.
