From b32e294f0ac590d744849ac97d3e7b2a6e824100 Mon Sep 17 00:00:00 2001 From: Dustin VanKrimpen Date: Sat, 18 Jul 2026 04:05:16 -0400 Subject: [PATCH] wherefore: add CLI README and LICENSE, bump to 1.1.1 The wherefore CLI package shipped with no README (blank npm page) and no LICENSE file, unlike the dashboard package. Add both and bump 1.1.0 -> 1.1.1 (docs only) so the next publish surfaces them on npmjs.com. Co-Authored-By: Claude Opus 4.8 (1M context) --- packages/wherefore/LICENSE | 21 +++++++++++ packages/wherefore/README.md | 63 +++++++++++++++++++++++++++++++++ packages/wherefore/package.json | 2 +- 3 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 packages/wherefore/LICENSE create mode 100644 packages/wherefore/README.md diff --git a/packages/wherefore/LICENSE b/packages/wherefore/LICENSE new file mode 100644 index 0000000..e474286 --- /dev/null +++ b/packages/wherefore/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 DustinVK + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/wherefore/README.md b/packages/wherefore/README.md new file mode 100644 index 0000000..a3953d5 --- /dev/null +++ b/packages/wherefore/README.md @@ -0,0 +1,63 @@ + + + + wherefore + + +# wherefore + +Set up and drive a [wherefore](https://github.com/DustinVK/wherefore) decision log: the why behind your code, kept as plain markdown in your repo. + +Wherefore records the reasoning behind engineering decisions, what you chose, why, and what you ruled out, so an agent or a teammate can answer "why did we build it this way?" straight from the repo. This CLI scaffolds that log, writes an `AGENTS.md` so any coding agent can read and maintain it, and installs the wherefore skills for the agent(s) you use. + +[![npm](https://img.shields.io/npm/v/wherefore)](https://www.npmjs.com/package/wherefore) +[![license](https://img.shields.io/npm/l/wherefore)](https://github.com/DustinVK/wherefore/blob/main/LICENSE) + +## Quick start + +From your project root: + +```bash +npx wherefore init +``` + +That scaffolds a `wherefore/` log, writes an `AGENTS.md` floor and a `CLAUDE.md` snippet, adds a `dist/` line to `.gitignore`, and installs the skills for whichever agent(s) it detects. Then browse the log as a static dashboard: + +```bash +npx wherefore dashboard dev # live, hot-reloading +npx wherefore dashboard build # static site to ./dist +``` + +`dashboard` is a thin launcher for [`@dustinvk/wherefore-dashboard`](https://www.npmjs.com/package/@dustinvk/wherefore-dashboard). The `wherefore` CLI itself has no build dependencies, so `init` stays fast. + +## What `init` sets up + +Two layers, and either one stands on its own: + +- **`AGENTS.md`, always written.** A plain-markdown spec that tells any agent how to read and write the log. This is the cross-tool floor: it works in any tool that reads `AGENTS.md`, no skills required. +- **Per-agent skills, on by default.** The `capture`, `ask`, `resolve`, and `supersede` skills, installed into the directory your agent discovers. Auto-detected by default; pass `--no-skills` to write just the floor. + +## Options + +``` +wherefore init [--agent ] [--no-skills] [--global] [--force] +``` + +- `--agent ` comma-separated agents to install skills for: `claude`, `codex`, `copilot`, `cursor`, `gemini`, `antigravity`, plus `all` and `auto`. Default is `auto`, which detects the agents your repo already uses and falls back to the shared `.agents/skills/` path when it cannot tell. +- `--no-skills` scaffold the log and `AGENTS.md` floor only; install no skills. +- `--global` install skills into your user-level directories (`~/.claude/skills` and friends) instead of the project. +- `--force` overwrite existing skills and config files. A hand-written `AGENTS.md` is left alone; only a wherefore-managed one is refreshed. + +Each agent maps to the directory it discovers: `claude` reads `.claude/skills`, `codex` reads `.codex/skills`, and `copilot`, `cursor`, `gemini`, and `antigravity` share `.agents/skills`. + +## How the pieces fit + +- **This CLI (`wherefore`)** scaffolds and drives the log from any project. +- **The [Claude Code plugin](https://github.com/DustinVK/wherefore)** ships the same skills for Claude Code users who install from the marketplace. +- **The [dashboard](https://www.npmjs.com/package/@dustinvk/wherefore-dashboard)** renders `wherefore/` as a browsable static site. + +The log itself is plain markdown in your repo. No cloud, no lock-in. + +## License + +MIT. Source at [github.com/DustinVK/wherefore](https://github.com/DustinVK/wherefore). diff --git a/packages/wherefore/package.json b/packages/wherefore/package.json index bf7ea94..7cf18ce 100644 --- a/packages/wherefore/package.json +++ b/packages/wherefore/package.json @@ -1,6 +1,6 @@ { "name": "wherefore", - "version": "1.1.0", + "version": "1.1.1", "description": "Capture and browse a repo-committed decision log. Scaffolds wherefore/, writes AGENTS.md, and installs skills for your coding agent.", "author": "Dustin VanKrimpen", "license": "MIT",