feat: add HAX CLI Claude Code plugin + marketplace

.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "haxtheweb",
+  "description": "Official Claude Code plugins for the HAX ecosystem — install and drive the HAX CLI for building web components and HAXsites.",
+  "owner": {
+    "name": "HAXTheWeb core team",
+    "url": "https://hax.psu.edu/"
+  },
+  "plugins": [
+    {
+      "name": "hax",
+      "source": "./plugins/hax",
+      "description": "Install and drive the HAX CLI (@haxtheweb/create): scaffold HAX-capable web components and HAXsites, audit DDD compliance, serve locally, and publish.",
+      "version": "1.0.0",
+      "author": {
+        "name": "HAXTheWeb core team",
+        "url": "https://hax.psu.edu/"
+      },
+      "homepage": "https://haxtheweb.org/",
+      "repository": "https://github.com/haxtheweb/create",
+      "license": "Apache-2.0",
+      "keywords": ["hax", "haxcms", "webcomponents", "lit", "ddd", "cli"]
+    }
+  ]
+}

docs/brainstorms/2026-06-29-hax-onboarding-plugins-requirements.md

@@ -0,0 +1,154 @@
+# HAX onboarding plugins (Claude + Codex) — v1 requirements
+
+- **Date:** 2026-06-29
+- **Status:** Ready for planning
+- **Owner:** HAXTheWeb core team
+- **Type:** Standard (product onboarding surface across two AI coding tools)
+
+## Summary
+
+Ship a thin onboarding layer around the HAX CLI (`@haxtheweb/create`, the `hax`
+command) for two AI coding tools — Claude Code and OpenAI Codex — that takes a
+brand-new user from in-context discovery, through setup that mostly vanishes, to a
+**live HAXsite open in the browser** within their first session. Each tool gets the
+surface idiomatic to its own extension model rather than a forced mirror.
+
+## Problem
+
+New HAX users bounce at three points in the first 15 minutes, in order of impact:
+
+1. **Discovery** — they don't know the CLI exists.
+2. **Install / setup** — getting `hax` onto their machine and runnable.
+3. **First value** — not knowing the one command that produces something they can
+   see and feel proud of.
+
+These plugins attack stages 1–3 *inside the AI tools developers already use*, where
+an assistant can carry the user across each gap automatically.
+
+## Who it's for
+
+Brand-new HAX users — and their AI agents — working inside Claude Code or Codex.
+The HAX core audience skews toward educators and content authors as well as
+component developers, which is why the v1 "first value" moment is a **site you can
+see**, not a component dev loop.
+
+## Goals
+
+- A new user reaches a live site (`hax serve` in the browser) on their first run
+  with minimal manual steps.
+- Setup is automatic (Claude) or one instruction the agent runs unprompted (Codex);
+  the user should rarely hand-type the install.
+- Both tools ship a credible, *idiomatic* surface — not a lowest-common-denominator
+  mirror.
+- The assistant has accurate, onboarding-scoped knowledge of the CLI so it
+  recommends the right next command.
+
+## Non-goals (v1)
+
+- **Shared MCP server** for true cross-tool parity — deferred to v2.
+- **Full command mirroring on Codex** (porting all five Claude workflows to Codex
+  prompts).
+- **Power-user breadth as guided commands** — node/content ops, imports/migration,
+  skeletons, theming, publishing. These remain *reference knowledge* the assistant
+  can use, not part of the golden path.
+- **Cold-start / top-of-funnel marketing** (blog posts, awesome-lists, marketplace
+  directories). v1 improves *in-context* discovery only; awareness for someone who
+  has never heard of HAX is out of scope for these artifacts.
+- **Auto-update / version pinning** beyond surfacing `hax update`.
+
+## The golden path (the v1 "hello world")
+
+One guided quickstart, identical in intent on both tools:
+
+1. Ensure `hax` is installed (auto on Claude; agent-run on Codex).
+2. `hax site <name> --y` — scaffold a HAXsite with sensible defaults.
+3. `hax serve` — started in the background (it is long-running).
+4. Surface the local URL and tell the user what they're looking at and how to edit
+   a page.
+
+Success of this path = the user sees their site in a browser and knows the one next
+edit to make.
+
+## Scope by platform
+
+### Claude Code — full plugin (largely built this session)
+
+Lives in this repo as a marketplace + plugin:
+
+- `.claude-plugin/marketplace.json` — in-tool discovery (`/plugin marketplace add
+  haxtheweb/create`).
+- `plugins/hax/.claude-plugin/plugin.json` — manifest.
+- `plugins/hax/hooks/` — SessionStart hook that auto-installs `@haxtheweb/create`
+  if `hax` is missing (opt-out via `HAX_PLUGIN_NO_AUTOINSTALL=1`). This *is* the
+  "setup vanishes" mechanism.
+- `plugins/hax/skills/hax/SKILL.md` — onboarding-scoped CLI knowledge.
+- `plugins/hax/commands/` — slash commands for the top workflows.
+
+**v1 delta to apply during build:** tighten emphasis toward the golden path — make
+the quickstart (`hax site` → `hax serve` → live URL) the obvious first move, with a
+dedicated quickstart entry point, rather than presenting all commands as equals.
+
+### Codex — native + minimal
+
+Codex has no plugin/marketplace/hook system; it extends via `AGENTS.md` (read
+natively), user-level custom prompts (its slash commands), MCP servers, and config
+profiles. v1 therefore:
+
+- **Strengthen `AGENTS.md`** with a concise, prominent "Quickstart for new users"
+  section: ensure `hax` is installed (`npm install --global @haxtheweb/create`),
+  then `hax site` → `hax serve` → open the URL. This doubles as the
+  instruction-driven install (no SessionStart hook exists in Codex).
+- **Add one Codex custom prompt** (e.g. `hax-quickstart`) that walks the golden
+  path, plus documented setup for where it lives.
+
+## Funnel → deliverable mapping
+
+| Funnel stage | Claude | Codex |
+|---|---|---|
+| Discovery (in-context) | Marketplace listing + plugin README | `AGENTS.md` + repo/README pointers |
+| Setup | SessionStart auto-install hook | `AGENTS.md` "ensure installed" instruction |
+| First value | Quickstart-emphasized commands + skill | `hax-quickstart` prompt + AGENTS.md section |
+
+## Success criteria
+
+- A first-time user in either tool reaches a served site in the browser without
+  hand-typing the install command.
+- On Claude, the plugin installs and the quickstart is discoverable with no manual
+  CLI knowledge.
+- On Codex, the agent installs `hax` and runs the golden path from the AGENTS.md
+  guidance without the user naming the command.
+- Both manifests/structures validate (Claude: `claude plugin validate`; Codex:
+  AGENTS.md guidance is accurate and current).
+
+## Dependencies & assumptions
+
+- **Node.js ≥ 18.20.3 and npm** on PATH (so the CLI can install). Stated as a
+  prereq on both tools.
+- **Codex mechanics are assumptions to verify in planning:** custom prompt location
+  (believed `~/.codex/prompts/`), absence of session hooks, and native AGENTS.md
+  reading. Confirm against current Codex before finalizing the Codex surface.
+- **Codex prompt distribution is user-level**, so v1 "distribution" for Codex is a
+  documented setup/copy step, not an installable package. v1 accepts this limitation.
+- `hax serve` is long-running — the quickstart must background it and report the URL,
+  not block the session.
+- This work currently lives on worktree branch `worktree-claude-hax-plugin`,
+  uncommitted; it needs to land on `main` to be installable.
+
+## Open questions
+
+- Exact Codex custom-prompt distribution story — copy/paste, a `hax` CLI helper that
+  writes the prompt, or just rely on AGENTS.md? (Lean: AGENTS.md + documented prompt
+  for v1.)
+- Should the Claude quickstart be a new dedicated command (e.g. `/hax:start`) or a
+  reframing of the existing `/hax:site` + `/hax:serve`? (Lean: a thin
+  quickstart entry that chains the two.)
+- Default site name / theme for the golden path to remove one more decision from the
+  newcomer.
+
+## Handoff / next steps
+
+- Run `/ce-plan` against this doc to define the build: the Claude v1 delta
+  (quickstart emphasis), the Codex AGENTS.md section + custom prompt, and the
+  verify-Codex-mechanics task.
+- Land the existing Claude plugin (`plugins/hax/` + `.claude-plugin/marketplace.json`)
+  from the worktree branch onto `main`.

plugins/hax/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "hax",
+  "displayName": "HAX CLI",
+  "version": "1.0.0",
+  "description": "Install and drive the HAX CLI (@haxtheweb/create). Scaffold HAX-capable web components and HAXsites, audit DDD design-system compliance, run a dev server, and publish. Ships a knowledge skill plus slash commands for the top workflows, and auto-installs the CLI on session start if it's missing.",
+  "author": {
+    "name": "HAXTheWeb core team",
+    "url": "https://hax.psu.edu/"
+  },
+  "homepage": "https://haxtheweb.org/",
+  "repository": "https://github.com/haxtheweb/create",
+  "license": "Apache-2.0",
+  "keywords": ["hax", "haxcms", "webcomponents", "lit", "cli", "ddd", "scaffolding", "static-site"]
+}

plugins/hax/README.md

@@ -0,0 +1,63 @@
+# HAX CLI — Claude Code plugin
+
+Install and drive the [HAX CLI](https://www.npmjs.com/package/@haxtheweb/create)
+(`@haxtheweb/create`, the `hax` command) from inside Claude Code. Scaffold
+HAX-capable web components and HAXsites, audit DDD compliance, serve locally, and
+publish — without leaving the assistant.
+
+## What's inside
+
+- **Auto-install hook** — a `SessionStart` hook checks whether `hax` is on your
+  `PATH`. If it's missing, it installs `@haxtheweb/create` globally (one time).
+  Opt out with `export HAX_PLUGIN_NO_AUTOINSTALL=1`.
+- **`hax` skill** — full command-surface knowledge (web components, sites,
+  content/node ops, imports, skeletons, publishing) plus HAX conventions
+  (JavaScript-only, DDD design tokens, `haxProperties`). Claude loads it
+  automatically when you talk about HAX.
+- **Slash commands** for the top workflows:
+  - `/hax:quickstart` — **start here**: scaffold a HAXsite and open it live in the browser
+  - `/hax:site` — create or administer a HAXsite
+  - `/hax:webcomponent` — scaffold a Lit/DDD web component
+  - `/hax:audit` — audit components for DDD compliance
+  - `/hax:serve` — run a HAXsite dev server
+  - `/hax:publish` — deploy to surge / Netlify / Vercel or set up CI
+
+## Install
+
+This repo is also a Claude Code plugin **marketplace**. Add it and install the
+plugin:
+
+```text
+/plugin marketplace add haxtheweb/create
+/plugin install hax@haxtheweb
+```
+
+To develop against a local checkout instead:
+
+```text
+/plugin marketplace add /path/to/create
+/plugin install hax@haxtheweb
+```
+
+## Quickstart (the golden path)
+
+New to HAX? Once the plugin is installed, just run:
+
+```text
+/hax:quickstart
+```
+
+It checks the CLI is ready (the auto-install hook handles that on session start),
+scaffolds a HAXsite with sensible defaults, serves it locally, and hands you the
+live URL with the one next edit to make. From nothing to a site you can see, in a
+single step. Everything else (`/hax:webcomponent`, `/hax:audit`, `/hax:publish`,
+content/import operations) builds out from there.
+
+## Requirements
+
+- Node.js `>=18.20.3` and `npm` on your `PATH` (so the CLI can be installed).
+
+## Links
+
+- HAX CLI source & docs: <https://github.com/haxtheweb/create>
+- HAX: <https://haxtheweb.org/> · <https://hax.psu.edu/>

plugins/hax/commands/audit.md

@@ -0,0 +1,19 @@
+---
+description: Audit HAX web components for DDD design-system compliance (hax audit).
+argument-hint: "[path]  (defaults to the current component root)"
+allowed-tools: Bash(hax:*), Bash(cd:*), Read, Edit
+---
+
+Run `hax audit` to check web components against the **DDD** (HAX design system) standards.
+It reads `.dddignore` to skip files and suggests CSS/token fixes.
+
+User input: `$ARGUMENTS`
+
+Guidance:
+- Run from the component's root directory. If the input names a path, `cd` into it first.
+- Use `hax --debug audit` to also print the gathered `.dddignore` contents (troubleshooting).
+- Audit is expected before submitting theme components or PRs.
+
+Run the audit, summarize the findings, then apply or recommend the suggested DDD token
+changes (use CSS custom properties instead of hardcoded values). Do **not** edit
+auto-generated files like `custom-elements.json` — rebuild the project to regenerate them.

plugins/hax/commands/publish.md

@@ -0,0 +1,26 @@
+---
+description: Publish a HAXsite (surge / Netlify / Vercel) or set up CI deploy with the HAX CLI.
+argument-hint: "[surge|netlify|vercel|github-actions|gitlab-ci] [--domain <name>] [--y]"
+allowed-tools: Bash(hax:*), Bash(cd:*), Read
+---
+
+Publish or set up deployment for a HAXsite with the HAX CLI. Run from the site root (or pass
+`--root ./<site>`).
+
+User input: `$ARGUMENTS`
+
+Targets:
+- surge.sh: `hax site site:surge` (or `--domain my-site.surge.sh`)
+- Netlify: `hax site site:netlify --y` (or `--domain <site-id>`)
+- Vercel: `hax site site:vercel --y` (or `--domain <project-name>`)
+- GitHub Actions (deploy on push): `hax site setup:github-actions`
+- GitLab CI (deploy on push): `hax site setup:gitlab-ci`
+- Sync the site's git remote: `hax site site:sync`
+
+Guidance:
+- Pick the target from the input; if it's ambiguous, ask which host.
+- Publishing to a third-party host is **outward-facing** — confirm the target and domain
+  with the user before deploying, unless they already specified it and asked you to proceed.
+- Add `--y` for automated deploys once the target is confirmed.
+
+Run the appropriate command and report the resulting URL or next steps.

plugins/hax/commands/quickstart.md

@@ -0,0 +1,44 @@
+---
+description: Guided HAX quickstart for new users — scaffold a HAXsite and open it live in the browser (hax site → hax serve).
+argument-hint: "[site-name]  (optional; defaults to my-hax-site)"
+allowed-tools: Bash(hax:*), Bash(cd:*)
+---
+
+Walk a brand-new user along the HAX golden path: from nothing to a **live HAXsite
+in the browser** in a single pass. Keep it fast and encouraging, and remove
+decisions rather than adding them.
+
+User input: `$ARGUMENTS`
+
+Run these steps in order:
+
+1. **Confirm the CLI is ready.** Run `hax --version`. If `hax` is missing, the
+   plugin's SessionStart hook normally installs it automatically; if it still is
+   not available, tell the user to install Node.js `>=18.20.3` and run
+   `npm install --global @haxtheweb/create`, then stop here.
+
+2. **Pick a site name.** Use the name from the input if one was given; otherwise
+   default to `my-hax-site`. Do not make the user decide. Mention they can rename
+   it or spin up more sites later.
+
+3. **Scaffold the site.** From the current directory (or a directory the user
+   names), run:
+   `hax site <name> --y --no-i`
+   This creates a HAXsite with sensible defaults.
+
+4. **Serve it.** `cd` into the new site folder and start the dev server in the
+   **background** (it is long-running and will not return):
+   `cd <name> && hax serve`
+   Read the startup output for the local URL (usually http://localhost, sometimes
+   a different port).
+
+5. **Hand it off.** Tell the user, briefly and warmly:
+   - the URL their site is now running at,
+   - that this is a real, portable HAXcms site they can edit and publish,
+   - one concrete next move — add a page with
+     `hax site node:add --title "..." --content "<p>...</p>" --y` (or via
+     `/hax:site`), or open the URL and edit content in the HAX authoring UI.
+
+Do not run `hax start` (the interactive Clack menu); this quickstart is the
+non-interactive path. The goal is the user seeing their own site live on the first
+try, so keep the wrap-up short and celebratory and point clearly at the next edit.

plugins/hax/commands/serve.md

@@ -0,0 +1,15 @@
+---
+description: Launch a HAXsite in local development mode (hax serve).
+argument-hint: "[path-to-site]  (defaults to the current directory)"
+allowed-tools: Bash(hax:*), Bash(cd:*)
+---
+
+Start a HAXsite dev server with `hax serve` (serves at http://localhost).
+
+User input: `$ARGUMENTS`
+
+Guidance:
+- Run from the root of a HAXsite. If the input names a site folder, `cd` into it first.
+- `hax serve` is **long-running** — start it in the background so the session stays
+  responsive, then report the local URL to the user.
+- If the current directory is not a HAXsite, say so and offer to create one with `/hax:site`.

plugins/hax/commands/site.md

@@ -0,0 +1,29 @@
+---
+description: Create a new HAXsite or run a site operation with the HAX CLI (hax site).
+argument-hint: "[site-name] [--theme <name>] [--y]  |  [op e.g. node:add --title ...]"
+allowed-tools: Bash(hax:*), Bash(cd:*), Read
+---
+
+Create or administer a HAXsite using `hax site` from `@haxtheweb/create`.
+
+User input: `$ARGUMENTS`
+
+Decide between creating a new site and operating on an existing one:
+
+**New site** — when the input is a name (optionally with flags):
+- `hax site <name> --y` (add `--theme "<theme>"`, e.g. `clean-two`, `polaris-flex-theme`).
+- From a template: `--skeleton-machine-name <installed>` or `--skeleton-file ./template.json`.
+- Run from the directory where the site folder should be created, or pass `--root <path>`.
+- If no name is given, ask for one.
+
+**Existing-site operations** — run from inside the site folder (or `--root ./<site>`):
+- Add a page: `hax site node:add --title "<title>" --content "<html>" --y`
+- Edit a node: `hax site node:edit --item-id <id> --node-op <title|content|slug|parent|order|...> ...`
+- Delete a node: `hax site node:delete --item-id <id> --y`
+- Stats / export: `hax site site:stats`, `hax site site:items --to-file items.json`
+- Change theme: `hax site site:theme --theme "<theme>" --y`
+- Search: `hax site site:search --search "<query>"` (add `--search-selector` for HTML selectors)
+
+Use `--y --no-i` for non-interactive runs; add `--quiet` to reduce noise. Construct the
+appropriate `hax site …` command from the input, run it, then summarize what was created
+or changed. After scaffolding a new site, mention it can be previewed with `/hax:serve`.