Workflow Automation

Use this skill as the repo's routing-first recurring workflow automation anchor.

The job is not to dump a giant Makefile, shell-script pile, hook config, and CI YAML blob. The job is to:

classify the recurring workflow,
choose one primary automation mode,
keep local entrypoints, hooks, CI mirrors, and scheduled maintenance honest about scope,
emit one reusable packet with clear route-outs.

Read these support docs first:

If the main ask is:

machine/runtime provisioning, local services, devcontainers, or cross-machine reproducibility → use system-environment-setup
deployment rollout, hosted CI/CD architecture, preview/staging/prod promotion, or rollback design → use deployment-automation or vercel-deploy
branch/rebase/recovery/push safety → use git-workflow
test-depth / merge-gate policy → use testing-strategies
runtime telemetry / alerts / production visibility → use monitoring-observability

When to use this skill

Replace README command sprawl with one repeatable repo-owned command surface
Choose between package scripts, Make, just, Task, shell entrypoints, hooks, CI wrappers, or maintenance bots
Design setup, bootstrap, dev, test, lint, verify, or ci commands for a repo
Tighten the boundary between local workflow glue and hosted CI enforcement
Decide whether a repeated chore belongs in hooks, a task runner, or scheduled automation
Diagnose a messy workflow layer spread across docs, scripts, hooks, and CI YAML

When not to use this skill

The real blocker is machine setup, service topology, toolchain pinning, or container/devcontainer reproducibility
The real blocker is release/deploy architecture or cloud runtime automation
The real blocker is Git collaboration/recovery rather than repo command design
The real blocker is test strategy policy rather than how commands are exposed
The commands are already obvious and the only job is trivial implementation

Instructions

Step 1: Normalize the request

Capture the request in this form first:

workflow_intake:
  primary_goal: task-entrypoints | bootstrap-onboarding | local-ci-parity | hook-guardrails | repo-maintenance | workflow-diagnosis | hybrid
  repo_shape: single-app | app-plus-services | monorepo | library-cli | docs-content | game-project | unknown
  current_surface: package-scripts | make-just-task | shell-scripts | ci-workflows | hooks | bots-schedules | mixed | none | unknown
  main_pain:
    - command-sprawl
    - onboarding-drift
    - local-vs-ci-mismatch
    - interactive-script
    - cross-platform-friction
    - duplicated-logic
    - hook-friction
    - bot-noise
    - unclear-owner
    - unknown
  blast_radius: local-dev-loop | repo-plus-ci | multi-team-repo | unknown
  confidence: high | medium | low

If the request is vague, assume the smallest obvious repo-local recurring workflow interpretation and state the assumption.

Step 2: Choose exactly one primary mode

Pick one mode for the current run:

task-entrypoints — one memorable command surface for recurring human-invoked work
bootstrap-onboarding — first-run setup, seed/init, or repeated repo initialization
local-ci-parity — one local verification command that mirrors the critical CI checks
hook-guardrails — fast local hygiene checks before commit/push
repo-maintenance — dependency updates, scheduled cleanup, release-prep chores, stale-item automation
workflow-diagnosis — the workflow layer is messy and needs simplification before more automation is added

Use workflow-diagnosis when the repo currently has too many front doors and you need to simplify before picking the new steady-state mode.

Step 3: Pick the smallest automation surface

Use these defaults:

package scripts / Make / just / Task for the human-facing entrypoint layer
hooks for fast deterministic guardrails only
hosted CI for enforcement, matrices, schedules, and secrets-dependent work
local CI wrappers when faster pre-push feedback is the point
bots / schedules when the work is recurring maintenance rather than a command humans should type every day

Do not let repo automation silently absorb environment provisioning or deployment architecture.

Step 4: Keep the workflow invariants visible

These rules should survive every answer:

prefer one obvious front door over many partially documented ones
keep bootstrap flows idempotent and non-interactive by default
hooks must stay short, deterministic, and mirrored in CI because local bypass exists
local CI parity should mirror the critical checks, not every hosted-runner detail
scheduled maintenance needs an owner/review policy, not just a bot config
name where local and hosted automation intentionally differ

Step 5: Build the workflow automation packet

Return this structure:

# Workflow Automation Packet

## Recommended mode
- Mode: task-entrypoints | bootstrap-onboarding | local-ci-parity | hook-guardrails | repo-maintenance | workflow-diagnosis
- Why this mode fits: ...

## Current state
- Repo shape: ...
- Current surface: ...
- Main pain: ...
- Blast radius: ...
- Confidence: high | medium | low

## Recommended surface
- Human-facing entrypoint: ...
- Supporting hooks / CI / schedules: ...
- What stays out of scope: ...

## Safest next move
1. ...
2. ...
3. ...

## Guardrails
- Idempotency / non-interactive behavior: ...
- Local vs CI boundary: ...
- Ownership / review policy: ...

## Route-outs
- `system-environment-setup` when ...
- `deployment-automation` / `vercel-deploy` when ...
- `git-workflow` when ...
- `testing-strategies` when ...

Step 6: Use the mode packets, not a giant tool catalog

Pull the exact packet shape from references/mode-packets-and-route-outs.md.

Rules:

task-entrypoints should collapse multiple commands into one discoverable human surface
bootstrap-onboarding must end with a verification command and state prerequisite boundaries
local-ci-parity must call out parity limits such as secrets, services, or matrix differences
hook-guardrails must stay fast enough that contributors do not immediately bypass them
repo-maintenance must include review cadence / batching / noise control expectations
workflow-diagnosis must simplify and dedupe before proposing another layer

Output format

Return a short Workflow Automation Packet or Automation Hardening Brief.

Required qualities:

classify the workflow before prescribing tools
choose one primary mode
prefer the smallest useful surface
keep local commands, hooks, CI, and schedules honest about their boundaries
make route-outs explicit instead of letting the skill absorb neighboring jobs

Examples

Example 1: messy command surface

Input: "This repo has README commands, a stale Makefile, and random scripts. We need one repeatable automation layer for dev, test, and lint." Output direction: choose workflow-diagnosis, consolidate to one human-facing surface, then route deployment/environment concerns away.

Example 2: local verification before push

Input: "Developers keep pushing just to discover CI failures. I want one local command that mirrors CI enough to catch problems earlier." Output direction: choose local-ci-parity, add one ci wrapper, and state parity limits instead of promising full CI reproduction.

Example 3: onboarding pain

Input: "New contributors need to install tools, copy env files, seed data, and run setup every time they switch branches." Output direction: choose bootstrap-onboarding, recommend one idempotent bootstrap entrypoint, and hand broad machine/service setup to system-environment-setup.

Example 4: scheduled repo chores

Input: "Dependency updates and cleanup tasks keep slipping. Should this live in scripts, hooks, or scheduled automation?" Output direction: choose repo-maintenance, recommend bots/schedules plus review rules, and keep daily developer entrypoints separate.

Best practices

Start from the repeated workflow, not from a favorite tool.
Prefer one discoverable front door over many half-owned surfaces.
Keep repo-local glue separate from environment, deployment, Git policy, and observability.
Treat interactive prompts as a last resort.
If local and CI differ, say exactly where and why.
Simplify and dedupe before adding more automation.

workflow-automation