wherefore CLAUDE.md

CLAUDE.md

@AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A Claude Code plugin marketplace. It hosts the wherefore plugin, which ships five skills and a command for capturing technical decisions into a repo-committed wherefore log, querying them later, closing out open questions, retiring superseded or obsolete decisions, and tracking forward-looking plan items. The marketplace itself has no build system, tests, or runtime -- the only "code" is JSON manifests, Markdown skill/command definitions, and a GitHub Actions CI workflow.

Validation

# Validate a single plugin
claude plugin validate ./plugins/wherefore

# Validate the whole marketplace
claude plugin validate .

# Check JSON syntax (what CI does first)
python3 -m json.tool .claude-plugin/marketplace.json
python3 -m json.tool plugins/wherefore/.claude-plugin/plugin.json

CI (.github/workflows/validate-plugins.yml) runs both JSON checks and claude plugin validate on every push and PR.

Publishing / setup

Marketplace and plugin names must be kebab-case -- the Claude.ai sync rejects anything else.

To test locally before pushing:

# From this repo's root
/plugin marketplace add ./
/plugin install wherefore@dustinvk

Repo structure and how pieces fit together

.claude-plugin/marketplace.json       # registry: lists plugins by name + source path
plugins/wherefore/
  .claude-plugin/plugin.json          # plugin manifest (name, version, author, license)
  CLAUDE.snippet.md                   # pasted into a consuming project's CLAUDE.md to
                                      # make Claude offer to capture decisions automatically
  commands/seed.md                    # /wherefore:seed: inspects a codebase and proposes
                                      # wherefore/topics.md vocabulary (ask-before-write)
  skills/capture/
    SKILL.md                          # captures a discussion into wherefore/ as one or
                                      # more tagged Markdown entries; registers any open
                                      # questions as questions/Q-NNN-short-slug.md files
    topics.seed.md                    # starter vocabulary copied on first use if no
                                      # topics.md exists yet
  skills/ask/
    SKILL.md                          # answers "why did we build X?" by shortlisting from
                                      # entry frontmatter, then opening matching files;
                                      # also surfaces open questions in the same area
  skills/resolve/
    SKILL.md                          # closes an open question by editing its
                                      # questions/Q-NNN-short-slug.md file (answer, rationale, back-link)
  skills/supersede/
    SKILL.md                          # marks an entry superseded (with pointer to
                                      # replacement) or obsolete via its frontmatter
  skills/slate/
    SKILL.md                          # manages wherefore/plan/ items (open, advance,
                                      # drop, read): one verb, four intents; never
                                      # writes log/ or questions/, hands off instead