v0.1.0 to v0.2.0

---

name: script-simplification

description: Inventory and simplify repository scripts with caller evidence, smaller ownership boundaries, standard tools where they preserve the full contract, and focused validation. Use when asked for script cleanup, unused commands, duplicate wrappers, or excessive automation logic. Skip performance tuning without a maintenance goal and broad repo health audits.

license: Apache-2.0

metadata:

author: stark-ai-de

category: repo-maintenance

internal: true

---

# Script Simplification

## Goal

Reduce the number of mechanisms a maintainer must understand while preserving

the behavior and safeguards that callers rely on. A shorter diff alone is not

evidence of improvement.

## When to use

- The user asks to simplify, consolidate, or remove repository scripts or CLI

entry points.

- A script duplicates a workflow, package command, generated wrapper, or

standard tool and its actual use needs checking.

- Several repositories need separately reviewable script cleanup.

## When not to use

- The task is only runtime performance tuning, dependency updates, or a broad

health audit without a script-maintenance goal.

- A focused failed pipeline needs diagnosis first; use the repository's CI

debugging workflow.

- A change primarily decides architecture or moves runtime ownership; use the

repository's architecture workflow before script cleanup.

- The only proposed change is a language port, line-count reduction, or new

helper framework with no demonstrated maintenance benefit.

## Inputs to inspect

- User scope and authorization; exact repository, default branch, worktree,

uncommitted changes, and repository instructions or accepted decisions.

- Script files and generated sources, package commands, CI and release jobs,

docs, runbooks, operator commands, and tests that invoke them.

- Required outputs, side effects, authentication, ownership, size/time bounds,

concurrency behavior, error handling, and pinned tool versions.

## Workflow

1. Establish the current source and rules. For multiple repositories, record

independent baselines and changes; respect the requested order and give each

repository its own reviewable diff. Do not manufacture a change where none

is useful.

2. Inventory every Python, shell, JavaScript/TypeScript, PowerShell, Nix

runtime helpers, operator commands, tests, fixtures, and generated copies. Use

[the inventory and decision guide](references/inventory-and-decisions.md).

3. Trace each proposed removal or consolidation through static callers and

manual operations. Search workflows, package scripts, docs, runbooks, and

platform-specific entry points. Treat absence from source imports as

4. Compare alternatives against the whole contract. Prefer an existing tool or

framework function only when it preserves required auth, evidence, limits,

errors, and side effects with less maintenance. Keep small domain-specific

coordinators, safety checks, and stable public entry points when needed.

and documentation, preserve generated-source ownership, and avoid a new

plugin, hook, dependency, or language port unless its net benefit is proven.

stable. Distinguish local tests, current-head CI, and real operational proof;

necessary helpers retained with reasons, validation results, and open gates.

If a PR was requested, publish one per repository under the user's authority

and read back its head, diff, and CI state.

## Safety rules

- Follow the target repository's instructions and accepted architecture. Do

not weaken provenance, access, approval, rollback, time, or size boundaries

to make a script smaller.

- Treat scripts that deploy, publish, change credentials, delete data, or alter

production state as write-capable. Inspect them without running those paths

unless the user authorized the exact operation.

- Do not activate or replace an automation writer as part of cleanup alone.

Keep one owner for each output or proposed change.

- Preserve unrelated edits. Do not infer merge or deployment authority from

authorization to create a PR.

## References

- [Inventory and decision guide](references/inventory-and-decisions.md):

classification fields, replacement checks, examples, and report shape.

## Scripts

No bundled scripts. Use the target repository's existing tools and checks.

## Output format

For each repository, give the decision, concrete before/after maintenance

burden, changed or retained helpers, caller evidence, validation and CI status,

and remaining operational gates. Link a requested PR or explain why no safe,

useful change was found.

## Completion criteria

- Every removed entry point has a caller check, including manual operations.

- Each retained helper has a distinct reason; replacements preserve the full

contract and have a smaller maintenance surface.

- The affected behavior and negative paths have current evidence, with missing

CI or live qualification marked explicitly.

## Failure modes

If callers, the owner contract, pinned tools, or operational authority cannot

be established, leave the risky part unchanged and report the precise gap.

Continue independent, authorized cleanup where possible.