Skip to content

Add the wherefore CLI: init scaffolding + opt-in multi-agent skills#6

Draft
DustinVK wants to merge 13 commits into
mainfrom
feature/init-command
Draft

Add the wherefore CLI: init scaffolding + opt-in multi-agent skills#6
DustinVK wants to merge 13 commits into
mainfrom
feature/init-command

Conversation

@DustinVK

@DustinVK DustinVK commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

What this does

Adds packages/wherefore, a dependency-light CLI published as wherefore, and reshapes how a project gets set up.

  • npx wherefore init scaffolds a wherefore/ log, writes an AGENTS.md so any coding agent can read it, adds a CLAUDE.md snippet, and updates .gitignore / package.json.
  • npx wherefore dashboard is a thin launcher that spawns @dustinvk/wherefore-dashboard on demand, so the CLI itself has no astro dependency and init stays fast.

Earlier iterations of this branch put init inside the astro-heavy dashboard package and installed skills by default. That dragged the whole dashboard build stack into a text-scaffolding command, and installing agent skills on everyone quietly reversed the project's "AGENTS.md is the cross-tool floor" decision. This reshapes both.

Highlights

  • New lean wherefore package. No runtime dependencies.
  • Skills are opt-in, not default. Plain init writes only the AGENTS.md floor plus the scaffold. Skills install only with --skills / --agent / --global.
  • Multi-agent targeting. --agent claude,codex,copilot,cursor,gemini,antigravity (plus all and auto) maps each agent to the skills dir it discovers: .claude/skills, .codex/skills, or the shared .agents/skills. --global maps to the matching ~/ dirs; unknown agents error.
  • Dashboard reverted to build/dev only; its init now redirects to npx wherefore init.
  • Atomic skill install (temp dir + rename), a non-zero exit on partial failure, and format-preserving edits to the consumer's package.json / .gitignore / CLAUDE.md.

Status and scope

  • Skills are marked experimental in --help. Whether to ship per-agent skills at all, or rely solely on the AGENTS.md floor, is logged as the open question Q-008. Not published to npm yet.
  • The skills are copied as-is, not yet adapted per agent (the /wherefore:* triggers and the "Claude Code skill" attribution are recorded as known limitations in the log entry).

Testing

  • packages/wherefore: 13 automated tests (default-off skills, the per-agent / all / auto / unknown / global / force paths, the launcher, and the CLAUDE.md / gitignore / package.json regressions). packages/wherefore-dashboard: 11, still green after the revert.
  • packages/wherefore/MANUAL_TESTING.md covers what automated tests can't: running the packaged tarball as a user would, and confirming a real agent discovers an installed skill.

Manual testing checklist

Mirrors packages/wherefore/MANUAL_TESTING.md. Tick as you go. (These are a task list rather than a table because GitHub only makes list checkboxes clickable.)

Setup

  • npm pack in packages/wherefore, install the tarball, run via wherefore (or node bin/prepare-package.js once, then node bin/wherefore.js)

Help and dispatch

  • wherefore / wherefore --help -> usage, exit 0
  • wherefore bogus -> unknown command, exit 1

Default init (no skills)

  • wherefore init -> scaffolds wherefore/, AGENTS.md, CLAUDE.md, a dist/ line in .gitignore, a wherefore devDependency; NO .agents/.claude/.codex skill dirs; prints "Skipping agent skill install"
  • Run init twice -> "already exists" messages, exactly one ## Wherefore block, package.json not rewritten

Opt-in skills

  • init --skills -> .agents/skills/{capture,ask,resolve,supersede}/SKILL.md
  • init --skills --agent claude,codex -> .claude/skills and .codex/skills only (no .agents/skills)
  • init --skills --agent all -> all three roots
  • mkdir .codex && init --skills --agent auto -> only .codex/skills
  • init --skills --agent bogus -> exit 1, lists valid names
  • re-run --agent claude, then again with --force -> skip, then overwrite
  • HOME=$(mktemp -d) init --global --agent claude -> skill under the temp HOME's .claude/skills

Robustness

  • Invalid JSON in package.json -> warning, rest of scaffold still created, exit 1

Dashboard launcher

  • WHEREFORE_DASHBOARD_BIN=<stub> wherefore dashboard build --src x -> forwards args, propagates the child exit code
  • Real wherefore dashboard dev in a dir with wherefore/ -> serves and stops on Ctrl-C; dashboard --help shows the dashboard's own help

Real cross-agent verification

  • Claude Code discovers the four skills from .claude/skills/
  • Codex discovers skills from .codex/skills/, and reads AGENTS.md with no skills installed
  • Copilot / Cursor / Gemini / Antigravity discover skills from .agents/skills/

End to end

  • init -> capture a decision -> wherefore dashboard build -> the entry and questions render in dist/

Decisions logged

  • wherefore/log/2026-07-03-wherefore-cli-and-multi-agent-skills.md
  • wherefore/log/2026-07-03-plan-directory.md
  • wherefore/questions/Q-008.md

🤖 Generated with Claude Code

DustinVK and others added 13 commits July 3, 2026 17:38
@DustinVK
Implement init command for workspace setup and skill installation
13022bd
@DustinVK
Support --force flag to overwrite existing files and skills in init
edbbab6
@DustinVK
Remove duplicated skills/templates from Git; generate them dynamicall…
37b0b62 
…y at build/package time
@DustinVK @claude
init: write consumer files precisely, not verbatim
8c72103 
The init command wrote several project files in ways that leaked internal
detail or clobbered consumer formatting:

- CLAUDE.md received the entire CLAUDE.snippet.md template, including the
  human-facing "paste the block below" instructions and marker comments.
  Extract and install only the block between the markers.
- The CLAUDE.md idempotency guard also matched the loose phrase
  "wherefore plugin"; drop it and key only on the "## Wherefore" heading we
  actually write.
- The .gitignore de-dupe used substring matching, so an existing
  `frontend/dist/` (or the internal `.test-dist/`) masked a missing
  top-level `dist/`. Match whole lines instead.
- `.test-dist/` is this package's own test-output dir and meaningless to a
  consumer; stop adding it to their .gitignore.
- Adding the devDependency reformatted the consumer's package.json to
  2-space with no trailing newline. Detect and preserve the existing
  indentation and trailing newline.

Adds targeted regression tests for the gitignore line-match, the CLAUDE.md
paste-instruction exclusion, and package.json format preservation.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
init: report partial failures and swap skills atomically
bc5fe31 
Two robustness gaps in the init command:

- The topics.md / package.json / AGENTS.md / CLAUDE.md steps swallowed
  errors as warnings, so init printed "Initialization complete!" and exited
  0 even when a write genuinely failed. Track a hadError flag across those
  steps (and the skill install) and exit 1 at the end if anything errored;
  "already exists / skipped" is not an error.
- On --force, the skill install ran `rm(dest)` before `cp`, so a failed
  copy left the skill deleted with no replacement. Copy into a temp dir and
  rename it into place, so dest is only removed once the new copy exists.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
dashboard: guard and cache package-asset generation
2605ffd 
prepare-package.js unconditionally rm+recopied skills/ and templates/ on
every dev/build/test invocation, and would hard-fail if the monorepo sources
were absent.

- Guard: when the plugin sources are missing (e.g. an installed package),
  no-op if the assets are already present rather than crashing; warn if both
  are missing.
- Cache: skip the rebuild when the generated assets are already newer than
  every source. Any error in the freshness check falls through to a full,
  correct rebuild, so a stale skip is not possible.

Also add a prepublishOnly script alongside prepack so publish reliably
regenerates the shipped assets.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
init: dedup skill install and drop dead flag checks
5543fdd 
- The global and local skill-install branches were ~20 lines of identical
  logic differing only in target dir and "global"/"local" wording. Collapse
  to one loop parameterized by a scope label and skillsDir.
- parseArgs never stores the string 'true' for the boolean --global/--force
  flags, so the `flags.global === 'true'` / `flags.force === 'true'`
  disjuncts were dead; the rawArgs.includes checks already do the work.

No behavior change; global and local installs verified.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
docs: document wherefore/plan/ in AGENTS.md layout
861784c 
init scaffolds a wherefore/plan/ directory that the documented layout did not
list. Keep it as a home for forward-looking plans and add it to the directory
layout so the scaffolding matches the docs. AGENTS.md is also the template init
installs, so consuming projects get the updated layout too.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
feat: add lean wherefore CLI package with multi-agent skill install
a4a5828 
Introduce packages/wherefore, a dependency-light CLI published as `wherefore`
(npx wherefore init). Separating it from the astro-heavy dashboard keeps init
fast and fixes the "dashboard" positioning of the old init command.

- `init` scaffolds wherefore/, writes the AGENTS.md cross-tool floor + a
  CLAUDE.md snippet, and pins a `wherefore` devDependency. Skills are now
  OPT-IN (--skills / --agent / --global), not installed by default, keeping
  AGENTS.md as the always-on cross-tool surface.
- Multi-agent skill targeting via --agent <list|all|auto>: claude ->
  .claude/skills, codex -> .codex/skills, copilot/cursor/gemini/antigravity ->
  the shared .agents/skills path; --global maps to the ~/ equivalents. Unknown
  agents error. Reuses the atomic temp-swap install and aggregate exit-1.
- `dashboard` is a thin launcher that spawns @dustinvk/wherefore-dashboard on
  demand (overridable via WHEREFORE_DASHBOARD_BIN), so `wherefore` needs no
  astro dependency.
- prepare-package.js (moved) generates skills/ + templates/ from the single
  plugins/wherefore source at build/pack time.

13 tests cover default-off skills, per-agent/all/auto/unknown/global/force
paths, the launcher, and the CLAUDE.md/gitignore/package.json regressions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
refactor: move init out of the dashboard package into wherefore
48ba0be 
The dashboard package is a static-site build tool; scaffolding a project and
installing agent skills now live in the standalone `wherefore` CLI. Revert the
dashboard to build/dev only:

- Remove the init command (a redirect points users to `npx wherefore init`).
- Delete bin/prepare-package.js and drop skills/templates from `files`, the
  `.gitignore`, and the dev/build/test/prepack/prepublishOnly scripts.
- Remove the init tests (they moved to packages/wherefore); keep build/dev.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
docs: document the wherefore CLI and capture the decision
ef6a09f 
- README: add the `wherefore` CLI to the ways-to-work list, a "Setting up a
  project" section covering `npx wherefore init` and the opt-in --skills/--agent
  flags, and the new package in the repo layout.
- dashboard README: note that project setup / skill install lives in the
  `wherefore` CLI.
- Capture the decision in the log: 2026-07-03-wherefore-cli-and-multi-agent-skills
  (lean CLI split, opt-in multi-agent skills, AGENTS.md-floor-stays-default) plus
  open question Q-008 on whether to ship per-agent skills at all.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
docs: add manual testing plan for the wherefore CLI
d34e13c 
Covers what npm test can't: running the packaged tarball as a user would, the
robustness/idempotency paths, the real dashboard launcher, and per-agent
verification that an installed SKILL.md is actually discovered by Claude Code,
Codex, Cursor, Copilot, Gemini, and Antigravity.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK @claude
wherefore: log the decision to keep wherefore/plan/
eadca52 
Capture the grilling decision to keep the init-scaffolded wherefore/plan/
directory (rather than remove the orphaned dir) and document it as the home
for forward-looking plans, the counterpart to log/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DustinVK DustinVK changed the title Implement unified multi-agent init command without file drift Add the wherefore CLI: init scaffolding + opt-in multi-agent skills Jul 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@DustinVK