Script Engineering

Script Engineering

Use this skill for cross-language script selection and for the engineering rules shared by repository automation scripts. Derive the available runtimes, supported platforms, script layout, and validation commands from the target repository and execution environment instead of assuming a universal tool list.

Use the matching language engineering skill when implementation needs language-specific depth. Use justfiles when changing the Just command surface; this skill owns the script behind that surface.

Workflow

1. Inspect repository instructions, script directories, shebangs, file extensions, manifests, version files, lockfiles, task runners, CI images, containers, tests, and documentation.
2. Identify every execution target: developer hosts, Windows or Unix-like systems, containers, CI runners, remote hosts, or production automation.
3. Decide whether the behavior should be a script. Prefer an existing command, task-runner recipe, application module, migration framework, or service when that is the clearer maintained boundary.
4. Choose the least complex language that is already supported across the required targets. Do not add a runtime merely to make a small script more convenient to author.
5. Define inputs, outputs, exit codes, side effects, working-directory rules, dependencies, idempotence expectations, preview behavior, and cleanup before implementing risky or reusable automation.
6. Implement in small testable units. Keep command construction explicit, validate arguments, quote paths and values correctly for the chosen language, and avoid hidden ambient state.
7. Run syntax/static checks and behavioral tests narrowly, then run the repository's broader script, task-runner, and CI-equivalent quality lanes.
8. Report the runtime evidence, language choice, behavior covered, commands run, skipped target platforms, and residual risk.

Establish Runtime Availability

Treat availability as evidence about one target environment, not a fixed list:

• Repository evidence comes first: shebangs, existing scripts, version managers, package manifests, lockfiles, toolchain files, containers, CI configuration, setup docs, and task-runner recipes.
• Confirm the interpreter on each relevant target with a non-mutating lookup such as command -v <interpreter>, type <interpreter>, or PowerShell Get-Command <interpreter>, followed by the appropriate version command when version compatibility matters.
• Distinguish POSIX sh, Bash, and other shells. A working interactive shell does not prove that a script's shebang or requested shell exists elsewhere.
• Distinguish PowerShell 7+ (pwsh) from Windows PowerShell (powershell.exe) when features or platform support differ.
• Treat an agent permission to request or execute a command as authorization, not proof that the interpreter is installed. A script never broadens the agent's edit, shell, network, external-directory, or destructive-action authority.
• If required target availability cannot be established, preserve the existing repository convention or stop and report the uncertainty rather than silently adding a new runtime assumption.

Decide Whether To Script

Do not create a durable script when:

• one short, readable, low-risk existing command or task-runner recipe is enough;
• the behavior is domain or application logic that callers should import and test through the normal application boundary;
• the repository already provides a maintained generator, migration tool, package command, or platform-native mechanism for the operation;
• the work needs a long-running process, durable state, recovery, rich concurrency, or an interactive interface better expressed as an application;
• a new interpreter or test framework would cost more than the automation saves; or
• the script would conceal destructive, credentialed, or remote operations, or work around command approval, sandbox, policy, or audit requirements.

One-off does not automatically mean unscripted. Data migrations, releases, and other high-risk operations often need a reviewed, repeatable implementation with preview, rollback, and evidence rather than an improvised terminal sequence.

Use the smallest durable boundary that remains understandable:

1. keep one short, safe command inline;
2. use a task-runner or package recipe as a discoverable thin entry point;
3. move reusable or branching behavior into an independently tested script; and
4. promote substantial domain behavior, concurrency, state, recovery, or public interfaces into an application module, library, or maintained CLI.

Do not keep growing a shell or package-script body after quoting, parsing, branching, cleanup, or state management becomes the main engineering work.

Choose A Language

Prefer the repository's established language when it satisfies the target platforms and keeps the workflow maintainable.

Load python-engineering for Python implementation, packaging, and pytest/unittest workflow. Load ruby-engineering for Ruby, Bundler, gems, idioms, and Minitest/RSpec workflow. Load powershell-engineering for idiomatic and cross-platform PowerShell implementation, Pester, and PSScriptAnalyzer. Load javascript-typescript-engineering for JavaScript or TypeScript runtime, package, type, lint, and test workflow. Load php-engineering for PHP syntax, Composer, static analysis, process APIs, streams, and exit-code mechanics; load php-testing-quality for PHPUnit/Pest lanes.

Do not select zsh or Fish merely because it is the author's interactive shell. Interactive convenience is not evidence that CI, containers, developer hosts, or production targets provide that shell.

Script Contract And Safety

• Keep scripts deterministic and non-interactive by default. Make prompts an explicit user-facing mode, never an accidental CI or agent dependency.
• Use documented arguments and environment variables. Validate required values and return nonzero exit codes with actionable stderr on failure.
• Keep machine-readable stdout stable when other tools consume it; send progress and diagnostics to stderr.
• Resolve working-directory and relative-path behavior deliberately. Do not assume the caller starts beside the script unless that is the documented contract.
• Use temporary directories or files with collision-safe creation and guaranteed cleanup. Load random-data-identifiers when generated names, nonces, tokens, fixtures, or reproducible randomness are material.
• Prefer idempotent behavior. For destructive, remote, production, or credentialed operations, provide a meaningful preview or dry-run, validate the exact target, and make the apply step explicit.
• Never print secrets. Avoid eval, dynamically assembled shell command strings, and interpolation of untrusted values into a shell; prefer argument arrays or direct process APIs.
• Pin or otherwise reproducibly provision non-standard interpreters, linters, runners, and helper binaries through the repository's existing dependency workflow.

Test Scripts

Start with observable behavior: arguments, environment inputs, stdout, stderr, exit status, created or changed files, cleanup, and external-command boundaries. Use temporary isolated fixtures and test failure paths as well as success.

Static analysis is not a substitute for behavioral tests. Conversely, do not add a test framework for a trivial wrapper when a syntax check plus one repository smoke test provides proportionate confidence. Adding or downloading a runner, linter, interpreter, binary, or installer invokes dependency-supply-chain-review; do not copy unpinned curl | shell installation examples into project workflows.

Use test-driven-development when new behavior or a regression can be driven through Red-Green-Refactor. Use systematic-debugging first for an active unexplained script failure.

Use Scripts With Just

When a repository uses Just, expose supported workflows through small, documented recipes and keep substantial logic in independently testable scripts:

• Keep one short command inline when quoting, control flow, and reuse remain obvious. A shebang recipe can hold a modest self-contained operation.
• Move reusable logic, functions, substantial branching, robust argument parsing, or independently tested behavior to the repository's established script directory. Keep the recipe a thin parameterized wrapper.
• Resolve script paths from the Justfile location rather than relying on the caller's current directory.
• Pass deliberate arguments through the recipe instead of duplicating defaults, environment parsing, validation, or business rules in both layers.
• Provide narrow script-test recipes and include them in the repository's normal check or verification lane when local conventions support that shape. Derive actual recipe names from the repository rather than inventing universal names.
• Pair risky apply recipes with preview/status recipes and preserve the same target validation inside the script; a task-runner confirmation prompt is not the only safety control.

Load justfiles for recipe syntax, parameters, groups, imports/modules, shell configuration, listing behavior, and Just validation.

Workflow Routing

• Load ci-release-engineering when the change affects hosted workflow triggers, jobs, permissions, artifacts, or automated release behavior; scripts own only the commands that workflow runs.
• Load container-engineering when changing Dockerfile, OCI image, or Compose behavior; scripts own only their contained automation contract.
• Load security-review for concrete scripts that handle credentials, secrets, auth, command execution, untrusted input, paths, privileged operations, or remote/production targets. Use security-review-evidence when captured output, fixtures, or reports may contain sensitive values.
• Consult current official documentation for version-specific behavior of an external interpreter, runner, linter, task runner, or module after inspecting the repository's pinned version and local usage.

Completion Evidence

Report:

• the repository and target-environment evidence used to establish runtimes;
• why a script was appropriate and why the selected language fit better than the credible local alternatives;
• changed script, tests, task-runner, dependency, and documentation files;
• syntax, static-analysis, behavioral, platform, and broader quality checks run; and
• skipped target environments, unverified interpreter assumptions, and residual operational or security risk.