---
description: "System workflow for maintaining reusable workflow templates"
targets:
  - issue
  - followup
autoSelect: false
updateMode: strict
requires:
  skills: []
  mcp: []
---
# Workflow Maintenance

## Goal

Create or improve this repository's reusable AlpacaLoop workflow template catalog from the concrete repository purpose, constraints, and desired workflow behavior described in the issue.

## Rules

- Treat the issue body as the source of truth for what this repository is for and which workflow behavior is desired.
- Prefer improving, reusing, demoting, or proposing cleanup for weak existing templates over adding overlapping templates.
- Keep workflow templates reusable. Do not encode one-off issue targets, transient file names, or unverified repository facts as reusable process.
- Treat recurring work as scheduled `issue` workflow behavior, not as a separate workflow template target. Do not create `recurring` target templates.
- Do not create, install, or configure skills or MCP servers in this issue. If reusable capability setup is needed, propose a separate capability issue.
- Do not create or update primary workflow template content by direct Markdown edits. Use direct Markdown edits only for small review fixes after the workflow CLI has produced or updated template content.

## Required Process

- Inspect the repository purpose and local guidance from the issue body and repository. Start with `git rev-parse --show-toplevel`, `git status --short --branch`, `git log --oneline --decorate -20`, and `rg --files -g 'README*' -g 'skills/**/references/**' -g 'AGENTS.md' -g 'CLAUDE.md'`, then read only the relevant files.
- Inspect the current workflow catalog with `alpaca workflow list --include-system --format json`; do not run separate target-specific list commands unless a target needs focused debugging.
- For each target surface being created or maintained, identify the reusable primary intent, deliverable quality bar, observable success evidence, evaluation contract needs for improvement or optimization work, and capability needs before drafting or updating templates.
- For broad new service, app, automation, API, integration, or business/product workflow classes, ensure the template requires an early validation gate for success-critical assumptions before dependent implementation. Examples include target users, demand, adoption or acquisition path, differentiation, trust/safety, data/privacy, authentication, operations, acceptance evidence, and constraints whose failure would make the build ineffective.
- Inspect usable capability context for capabilities needed by that quality bar, using `alpaca capability list` and `alpaca capability search "<capability>" --installed-only` before declaring requirements. Use `alpaca skill list` for final `requires.skills` refs and `alpaca mcp verify --ref <ref>` or `alpaca mcp list` for final `requires.mcp` refs. Do not declare unavailable, unverified, or `excludedFromRequires` candidates as requirements.
- Prefer tracker-visible AlpacaLoop history first: use `alpaca issue list --state open --view compact --format text --limit 20`, bounded target details such as `alpaca issue show --issue <id> --children 1 --limit 5 --format text`, and `alpaca issue list --state closed --view compact --format text --limit 10` when recent completed work matters. Use `alpaca issue search --title "<keyword>" --state all --limit 10 --format text` only when compact snapshots do not identify the relevant issue. Use `alpaca issue log list`, `alpaca issue log show --issue <id> --tail 50`, and `alpaca issue log search` only for explicit log debugging or when the compact tracker history leaves a concrete unanswered question.
- For an empty or initial catalog, use `alpaca workflow create --template-set --prompt "<repository purpose and desired workflow behavior>" --save-draft`, review the draft, apply it with `alpaca workflow create --apply-draft <path>`, and create at least one auto-selectable repo-local candidate for each of `issue`, `pull_request`, `unplanned`, and `followup` unless the issue explicitly narrows the target set. If recurring behavior is desired, make the relevant `issue` workflow reusable for repeated child runs instead of creating a recurring target. If one-shot scheduling is desired, keep the template on the `issue` target and leave run timing to issue schedule state.
- For an existing catalog, use `alpaca workflow update --template-set --path <template.md> --prompt "<maintenance prompt>" --save-draft` for close fits, or `alpaca workflow create --template-set --prompt "<maintenance prompt>" --save-draft` when responsibilities need to be split or stale templates need reuse/update/create decisions together. Review the draft and apply it with the matching `alpaca workflow create --apply-draft <path>` or `alpaca workflow update --apply-draft <path>` command.
- Before deleting a stale repo-local template, inspect inbound usage with `alpaca workflow list --references-to <template.md>`. Use `alpaca workflow delete --path <template.md>` only when references are gone, or `alpaca workflow delete --path <template.md> --cleanup-references --save-draft` when editable referrers need a reviewed cleanup draft. Cleanup removes references; it does not cascade-delete other templates.
- Prefer `<domain>/<role>-<scope>.md` for repo-local template paths. Reuse existing domain folders before adding new ones, and avoid synonym folders for the same domain.
- Validate with `alpaca workflow list --include-system --format json` and `alpaca workflow lint`. Fix validation failures before completing.

## Handoff To Human When

- The repository purpose, desired workflow behavior, or target surfaces remain ambiguous after checking the issue body and available repository evidence.
- Choosing between multiple template architecture options changes team process, review policy, ownership, security posture, or required external services.
- A useful workflow requires a skill or MCP server that is not currently usable and cannot be represented safely without separate capability setup.

## Success Criteria

- The local workflow catalog reflects the issue's requested repository purpose and workflow behavior.
- Empty or initial catalogs have at least one auto-selectable repo-local workflow for each requested target, or for all four standard targets when the issue does not narrow scope.
- Existing catalogs are cleaned up or improved without unnecessary duplicate templates.
- Required skill and MCP refs, when declared, are based on usable `alpaca skill list` refs or `alpaca mcp verify --ref <ref>` success, and are not excluded from workflow requires.
- `alpaca workflow lint` passes.
