workflow-automation

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:

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

Read these support docs first:

• references/automation-modes.md
• references/mode-packets-and-route-outs.md
• references/handoff-boundaries.md

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:

1. task-entrypoints — one memorable command surface for recurring human-invoked work
2. bootstrap-onboarding — first-run setup, seed/init, or repeated repo initialization
3. local-ci-parity — one local verification command that mirrors the critical CI checks
4. hook-guardrails — fast local hygiene checks before commit/push
5. repo-maintenance — dependency updates, scheduled cleanup, release-prep chores, stale-item automation
6. 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

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

References

• Task: The Modern Task Runner
• Just Programmer's Manual
• mise tasks
• pre-commit
• GitHub Actions documentation
• act documentation
• Development containers