From 829341a3d5c79c317cab6a7dab4b3bbcdf525b95 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 15:16:55 +0000 Subject: [PATCH] =?UTF-8?q?docs(ai-coding):=20=F0=9F=93=9D=20drop=20config?= =?UTF-8?q?.functions=20from=20the=20shell=20conventions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01EMd1RK3NbEYFh5doLg3b53 --- .../stubs/.agents/instructions/shell.instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ai-coding/stubs/.agents/instructions/shell.instructions.md b/src/ai-coding/stubs/.agents/instructions/shell.instructions.md index 83a05674..62382153 100644 --- a/src/ai-coding/stubs/.agents/instructions/shell.instructions.md +++ b/src/ai-coding/stubs/.agents/instructions/shell.instructions.md @@ -31,7 +31,7 @@ Never write inline `apt-get`/`apk`/`sudo` branching. Install system packages wit ### Source only `zz-*` scripts -A managed script (anything installed or run through `zz-use`/`zz-setup`) sources nothing but `zz-*` scripts: `. zz-colors`. Shared logic never travels through `.`, because a sourced file shares the caller's shell (variables, `set -e`, traps, `$0`) and breaks the moment the two drift apart. Put it in a command on `PATH` and call it (`vps-network public-ip`, `zz-persist -r KEY`), with its own `zz-use` line and arguments. Two things may still be sourced: a data file in shell syntax that is not a script of the repo (`/etc/os-release`, a settings file the user provides, read under a comment saying so), and a `config.functions` step, which `zz-setup` sources (see below). +A managed script (anything installed or run through `zz-use`/`zz-setup`) sources nothing but `zz-*` scripts: `. zz-colors`. Shared logic never travels through `.`, because a sourced file shares the caller's shell (variables, `set -e`, traps, `$0`) and breaks the moment the two drift apart. Put it in a command on `PATH` and call it (`vps-network public-ip`, `zz-persist -r KEY`), with its own `zz-use` line and arguments. One thing may still be sourced: a data file in shell syntax that is not a script of the repo (`/etc/os-release`, a settings file the user provides, read under a comment saying so). ### Logging @@ -88,7 +88,7 @@ Write `#!/bin/sh` scripts that run under dash and busybox. No bashisms: A repository run by `zz-setup /` is a set of workspaces, one folder per step. A step's `run.sh` follows the rules above and also these: - **Runnable step**: the folder holds `package.json` and `run.sh`. `package.json` declares `bin: {"": "run.sh"}` and `engines: {"zz-setup": "*"}`; without `engines.zz-setup` the folder is a library, never proposed as a step. The folder is a root `workspaces` entry. Order comes from `config.order`, never from the folder name. -- **Actions**: set `config.functions: true` and define `up()`, `down()` and `summary()` (plus any extra action, called with `zz-setup -o -a `); `zz-setup` sources the bin from its own directory and calls the one asked, so the file has no dispatch code and is not run on its own (`zz-setup ./ -o ` runs a local checkout). `config.summary: true` makes `zz-setup` print the step's `summary()` after a run. Without `config.functions` the bin is run with `up` or `down` as its first argument. `up` and `down` are idempotent: a re-run repairs, never fails on what already exists. `down` undoes only what `up` created. `zz-setup` runs `down` steps in reverse order, then `up` steps in order. +- **Actions**: the bin is run with `up` or `down` as its first argument (`zz-setup -o -a ` passes any other); a `config.summary: true` step also answers `summary`, printed after a run. `up` and `down` are idempotent: a re-run repairs, never fails on what already exists. `down` undoes only what `up` created. `zz-setup` runs `down` steps in reverse order, then `up` steps in order. - **Inputs**: declare every variable in `config.inputs` (`description`, `required`, `default`, `secret`). Read it from the environment; `zz-setup` resolves environment, then env file, then default. A step never prompts: it runs without a terminal and `sudo` drops the environment. Document each input in the step README. - **Secrets**: generate once, then reuse. Store with `zz-persist -s` (owner-only env file), never echo to a log line other than the final summary, and mark the input `"secret": true`. - **Dependencies**: list other steps in `dependencies` or `peerDependencies`; `zz-setup` enables them. Steps that cannot share a host name each other in `config.conflicts`. Shared logic lives in scripts that are called, never sourced (see "Source only `zz-*` scripts"): a folder with a `bin` and no `engines.zz-setup` is a script, not a step, and a step reaches it by path (`$(dirname "$0")/../