--- name: ki-repo-tools ki-kind: governance ki-applicability: detected ki-depends-on: [] ki-shared-dependencies: [ki-skills:rubric] contributes: ['.githooks/pre-commit'] description: > Audit or scaffold a KI `tools-*` repository containing one CLI, installer, releases, changelog, CI, help, completion, and optional manual. Use `ki-repo-homebrew-tap` for formulae, `ki-engineering` for TypeScript/Bun, and `ki-repo` for universal files. argument-hint: 'audit | conform | help | educate | refresh' --- # Knowledge Islands tool-repo standard You are helping audit, conform, or scaffold a **`tools-*` repo** — a repo holding exactly **one** standalone command-line tool, distributed two ways: a `curl | bash` installer at the repo root, and a companion Homebrew formula that lives in the tap. [`tools-mgit`](https://github.com/knowledgeislands/tools-mgit) (Bash) and [`tools-ki`](https://github.com/knowledgeislands/tools-ki) (TypeScript/Bun) are the reference implementations. The standard governs shared shape and public interface conventions, not a language or the tools' individual behaviour. This skill rides on `ki-repo` (local files, GitHub settings) but **not** `ki-engineering` — a bash tool has no TypeScript/Bun toolchain to govern, so no `ki-engineering` declaration is assumed (the same pattern `ki-repo-kb` follows). If the tool grows a `package.json`, that changes: it then declares `[skills.ki-engineering]` too and defers its lint/test there (see the capability rule below). The full, quotable standard lives in [the tool-repository standard](references/standards-tool-repositories.md), including the common root `help`, `completion`, `diag`, and `doctor` contract, conditional recovery commands, and the split between shared policy and repository-local guidance. [Command-line conventions](references/standards-cli-conventions.md) give the Unix and Linux syntax, common flag letters, symbolic-link options, streams, exit statuses, `NO_COLOR` and terminal behaviour, and XDG directories as design guidance for a tool's own options. [Tool shared code](references/standards-tool-shared-code.md) owns optional installer and release-packaging profiles. The line-by-line pass/fail items live in [the generated rubric](references/rubric.md). `ki repo audit` and `ki repo conform` inspect the structured mechanical contract directly through the host. They never execute a target binary, installer, package manager, CI workflow, or network validator; runtime and release evidence are explicit separate diagnostics. ## Container, not contents This skill judges the **container** and a small shared public interface — not the quality of the tool's own implementation: - **In scope:** the `bin/` layout and its exec bit, required developer delivery-guide paths, `install.sh`, local release-marker shape, `CHANGELOG.md`, CI source shape, test-suite presence, completion, manual authoring and distribution, and the capability conditionals below. Runtime `--version`, installer, CI, and release execution remain separate evidence. - **Out of scope:** whether tool-specific operations are correct, well-factored, or fast. That is the tool author's concern (and, for a shell tool, shellcheck + bats — which this skill checks are _wired_, not what they _find_). The Homebrew tap and its formula are `ki-repo-homebrew-tap`'s; the repo's README, LICENSE, and GitHub settings are `ki-repo`'s. ## The canonical shape at a glance ```text tools-/ ├── bin/ # THE executable — chmod +x (git tracks the exec bit). Answers --version. ├── install.sh # curl installer: honours env overrides (target dir + version), verifies the │ # download, is idempotent, and publishes/links a manual when one exists. ├── tests/ or src/tests/ # executable test suite (a *.bats suite under tests/ for a shell tool). Expected. ├── .github/workflows/*.yml # CI: lint + test on every push. Expected. ├── man/.1 # Optional manual source; when present, CI runs mandoc -T lint. ├── CHANGELOG.md # Consolidated pre-1.0 baseline or dated 1.0+ release history. ├── docs/guides/developer/ │ ├── definition-of-done.md # Required; repository-defined delivery-readiness guide. │ └── releasing.md # Required; repository-defined release guide. ├── README.md · LICENSE # ki-repo's job — not governed here. └── .ki.toml # qualified ki-repo + ki-repo-tools declarations (the opt-in marker). ``` `bin/` with ≥1 executable file and both developer delivery guides are hard requirements (**FAIL** if missing); every other expected surface is **WARN** — expected but not ship-stopping. The guide contents remain repository-defined. The companion Homebrew formula lives in the tap repo (`homebrew-`, `Formula/.rb`), governed by `ki-repo-homebrew-tap` — cross-reference it, don't reproduce it. ## The capability-conditional rule Mirrors `ki-engineering`'s capability-conditional pattern: what the repo _is_ decides which checks apply, so the same standard covers a bash tool and a TS tool without forking. - **Shell entrypoint** (the primary `bin/` file has a `bash`/`sh` shebang): it MUST be shellcheck-clean in CI (a workflow references `shellcheck`) and ship a `bats` suite that CI runs (a `*.bats` file under `tests/` and a workflow that references `bats`). Every `[[ ]]` or `!` assertion in that suite ends `|| false`, because under macOS Bash 3.2 such an assertion failing mid-test does not fail the test (`SHELL-FATAL`, WARN; evidence tools-mgit `00ef0de`). - **A `package.json` appears** (a TS/Bun tool): the repo defers lint/test to `ki-engineering` and MUST also declare `[skills.ki-engineering]` in its `.ki.toml`. The shell checks don't apply. - **A physical `man/.1` page appears**: CI MUST run `mandoc -T lint man/.1`, directly or through the repository's native task runner. The release installer and its `--link` mode publish or link that manual alongside the executable. - **Another language** (Python, Go, …): defer to that language's own toolchain; the container checks (bin, install.sh, versioning, changelog, CI, tests) still apply. ## The qualified `ki-repo-tools` marker A `tools-*` repo opts into this standard by declaring `[skills.ki-repo-tools]` in `.ki.toml`. A keyless table leaves installer and packaging files repository-owned. The optional `profile` plus its validated parameters selects one managed delivery projection; every other key is rejected. `ki-repo` owns selecting the declaration, and conformance never selects a profile or overwrites modified managed files. ## Change and release readiness Before presenting any tool change for review, read [the change-readiness checklist](references/standards-change-readiness.md). It keeps shared documentation, verification, and authority questions in one place while each repository's developer guide retains its own executable gates and recovery detail. Before preparing or reviewing a tool release, read [the release-readiness checklist](references/standards-release-readiness.md). Its [release-on-demand policy](references/standards-release-readiness.md#release-on-demand) is the one rule for when any KI tooling project releases: hold by default, release only when something needs it, and never release as part of delivering work. The checklist consolidates the existing version, documentation, validation, and distribution obligations into one staged human checklist; it does not create another skill mode or take ownership from `ki-engineering` or `ki-repo-homebrew-tap`. ## Operating modes Every governance skill carries the universal four **AUDIT · CONFORM · EDUCATE · REFRESH**; EDUCATE here scaffolds a new tool repo. Invoked as `help` / `-h` / `?`, it explains itself and stops — the generated HELP block (name, purpose, invocation, modes, off-ramps), taking no action. With no mode it does the same, then, in an interactive session only, offers the mode choice via `AskUserQuestion`, prompting for any `argument-hint` target the chosen mode shows. The four procedures remain on demand because each coordinates work outside the hosted catalogue: AUDIT and CONFORM sequence `ki-repo`, the conditional `ki-engineering` layer, and explicit release checks; EDUCATE scaffolds a new repository; REFRESH reconciles moving external specifications. Each file owns one mode so invoking one never loads an unrelated procedure. ### Mode AUDIT → Read [references/mode-audit.md](references/mode-audit.md) ### Mode CONFORM → Read [references/mode-conform.md](references/mode-conform.md) ### Mode EDUCATE → Read [references/mode-educate.md](references/mode-educate.md) ### Mode REFRESH → Read [references/mode-refresh.md](references/mode-refresh.md) ### Mode HELP Invoked as `help`, `-h`, or `?`, explain the skill, invocation, modes, capability conditionals, and off-ramps, then stop. With no recognisable mode, provide the same explanation and only offer a mode choice in an interactive session. ## Notes - The standard is anchored to `tools-mgit` and `tools-ki`, plus external specs (shellcheck, bats, keep-a-changelog, semver, XDG, POSIX utility conventions, GNU coding standards, clig.dev, `NO_COLOR`) — the tracked [source list](references/sources.md) records them; Mode REFRESH re-fetches on the declared cadence. - Refer to another skill by its `name` (`ki-repo`, `ki-engineering`, `ki-repo-homebrew-tap`), never a file path — skills are relocatable. - Hosted execution carries no private checker, reporter, or compatibility wrapper. The skill intentionally has no top-level public script; its executable governance surface is `scripts/rubric/items/index.ts`, loaded directly by `ki`. - No `exemplars.md` is bundled: the canonical tree and capability table above, plus the complete installer and release guidance in the standard, already illustrate the reusable shapes; a separate exemplar would duplicate them.