Tools
Repository tooling with stable command entry points and documented contracts — small applications that own a workflow, rather than glue around one.
- Kind
- Architecture
- Domain
- Environment & Tooling
- Applies at
tools/- Status
- Stable
- Source · managed
tools/README.md
01 Defines
The home for reusable command implementations — local development, CI, validation, generation, and maintenance utilities — that have clear inputs, outputs, execution flows, and a contract documented beside the code.
02 Applies when
- Behaviour has enough structure to be treated as a small application rather than a thin script.
- Several callers — make, CI, a developer — rely on the same stable command.
- A utility is likely to be useful in other repositories.
03 Boundaries
- Orchestration-specific glue stays in
scripts/or make modules. - Reusable behaviour does not live in workflow YAML.
- A tool’s contract never depends on undocumented behaviour of the script that calls it.
Expected behaviour
- 01Inputs and outputs are explicit, and configuration is preferred over hidden convention.
- 02Each tool offers a stable command entry point that callers can depend on.
- 03The contract is documented near the implementation.
- 04A tool may be written in any suitable language, such as C#, as long as its entry point is stable.
- 05Repository-specific assumptions are kept out of tools likely to be shared.
Behaviour#
A tool owns a workflow. Where a script runs a few existing commands in a particular order, a tool defines what it accepts, what it produces, and how it gets from one to the other — and that definition is what callers depend on.
Because callers depend on it, the entry point is treated as stable. The implementation behind it can change language, structure, or dependencies; the command and its contract stay put.
- 01 Recipe A line or two of shell inside a make target Make Module Registries
- 02 Script Grows into a narrow helper with arguments and exit codes Scripts
- 03 Tool Gains its own contract, structure, and documentation
- 04 Shared toolkit Moves out of the repository once it carries no repository-specific assumptions
Not everything travels the whole path. Most glue is well served as a script;
the move to tools/ is for behaviour that has become a product of its own.
Scripts and tools#
| Question | Script | Tool |
|---|---|---|
| What does it own? | A narrow step for its caller | A defined workflow |
| Where is its contract? | Arguments, environment, exit code | Documented beside the implementation |
| What may it call? | Existing commands and tools | Its own code; not undocumented scripts |
| Where might it end up? | Stays in the repository | A shared toolkit |
Layout#
- tools/
- .assets/ The README icon
- README.md The managed standard for this directory Managed Standard Files
This repository carries the standard and no tools yet: its automation is still small enough to live in Scripts and make modules. The directory exists so the boundary is in place before the first tool needs it.
Connections