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

Workflow Automation Modes

Use this quick map when deciding what workflow-automation should own.

1. task-entrypoints

Use when the repo needs stable, memorable commands for recurring developer work.

Typical fit:

• make dev
• just test
• npm run ci
• task lint

Choose this mode when:

• humans invoke the commands often
• the main pain is command sprawl or poor discoverability
• the underlying tools already exist and only need a thin wrapper

Avoid this mode when the real problem is cloud deployment or machine provisioning.

2. bootstrap-onboarding

Use when first-run setup or repeated initialization is the main pain.

Typical fit:

• scripts/bootstrap.sh
• make setup
• just bootstrap

Guardrails:

• safe to rerun
• checks prerequisites first
• prompts are optional or avoided by default
• ends with a verification step

3. local-ci-parity

Use when developers need fast confidence before pushing.

Typical fit:

• make ci
• task verify
• act for a subset of GitHub Actions jobs

Guardrails:

• mirror the critical CI checks, not every hosted-runner detail
• name where local and hosted CI intentionally differ
• keep the command fast enough to use regularly

4. hook-guardrails

Use when the main need is local hygiene enforcement.

Typical fit:

• lint/format hooks
• fast unit checks
• secret scanning

Guardrails:

• keep hooks short and deterministic
• mirror policy in CI
• do not hide slow integration suites in hooks

5. repo-maintenance

Use when recurring chores are better handled by bots or schedules than by a developer typing commands.

Typical fit:

• dependency update bots
• scheduled cleanup jobs
• stale-issue handling
• release-note prep

Guardrails:

• define review/approval expectations
• keep bot noise under control
• separate maintenance automation from deployment rollout

Choosing between modes

• If humans type the command often → start with task-entrypoints
• If new contributors are blocked → start with bootstrap-onboarding
• If CI failures are found too late → start with local-ci-parity
• If the main issue is commit-time hygiene → start with hook-guardrails
• If the work is scheduled or bot-driven → start with repo-maintenance
• If everything is messy and duplicated → start with workflow-diagnosis, then pick the new primary mode after cleanup

Handoff Boundaries

Use this table to keep workflow-automation from absorbing neighboring skills.

Simple rule

workflow-automation owns repeatable repo-scoped workflow glue.

That usually means:

• command entrypoints
• bootstrap wrappers
• local CI wrappers
• hook guardrails
• repo maintenance routines

It does not own:

• full machine provisioning
• deployment architecture
• local Git history management
• test strategy policy
• debugging current failures
• production observability design

Mode Packets and Route-outs

Use this sheet after choosing the primary workflow-automation mode.

1. task-entrypoints

Use when humans need one memorable command surface for repeated repo work.

Return:

• one human-facing surface (package.json scripts, Makefile, justfile, or Taskfile.yml)
• 3-6 named entrypoints (setup, dev, test, lint, verify, ci as needed)
• the source-of-truth rule for underlying scripts
• route-outs for environment or deployment concerns that should not be hidden behind the entrypoints

Watch-outs:

• too many synonyms for the same job (check, verify, validate, ci all meaning different things)
• task runners quietly owning deployment or machine setup

2. bootstrap-onboarding

Use when the main pain is first-run setup or repeated repo initialization.

Return:

• one idempotent bootstrap command
• prerequisite checks before mutation
• optional flags/env for non-interactive behavior
• one verification command proving the bootstrap succeeded
• route-out if local services, Docker/devcontainers, or machine-level provisioning become the real blocker

Watch-outs:

• shell prompts in the default path
• setup logic duplicated across docs, shell scripts, and CI
• hidden state that breaks after branch switches or partial failure

3. local-ci-parity

Use when developers need faster feedback than pushing to hosted CI.

Return:

• one local verification command (for example make ci, task verify, npm run ci)
• the critical checks it mirrors
• explicit parity limits (secrets, services, OS matrix, heavy integration environments)
• hosted CI remains the enforcement layer

Watch-outs:

• pretending local parity equals full hosted CI
• cloning CI YAML complexity into local shell scripts
• adding a slow command nobody will run

4. hook-guardrails

Use when commit-time hygiene is the main problem.

Return:

• hook surface (pre-commit, Husky, lefthook, or raw Git hooks)
• fast checks only: format, lint, secret scan, lightweight tests
• CI mirror rule for anything that truly matters
• contributor escape-hatch note if hooks are optional or bypassable

Watch-outs:

• slow hooks that train contributors to skip them
• hooks running large integration suites
• hook configs becoming the only place workflow logic lives

5. repo-maintenance

Use when the repeated work is better handled by schedules or bots.

Return:

• whether the job belongs in Dependabot, Renovate, scheduled CI, or a repo script called by automation
• review cadence / batching rules
• ownership policy (who reviews, who merges, what can auto-close or auto-merge)
• noise-control rules

Watch-outs:

• maintenance PR floods with no owner
• mixing daily developer commands and scheduled chores into one mushy surface
• assuming automation eliminates the need for human triage

6. workflow-diagnosis

Use when the repo has too many front doors already.

Return:

• the current surfaces in play (README, scripts, task runner, hooks, CI, bots)
• what should remain the human-facing front door
• what should move into underlying scripts/config
• what should be deleted, deduped, or renamed
• the steady-state mode after cleanup

Watch-outs:

• preserving redundant names because they are familiar
• adding another wrapper before deleting the broken ones
• letting CI remain the only discoverable source of truth

Route-out map

Simple default

If you are unsure, start with: 1. identify the repeated repo-local task, 2. choose one primary mode, 3. propose one human-facing front door, 4. keep everything else as supporting automation with explicit boundaries.