From 762873593c1bc655a1a4f87123d429df9e1f3a8f Mon Sep 17 00:00:00 2001 From: "Rick Manelius, PhD" Date: Mon, 29 Jun 2026 20:06:43 -0500 Subject: [PATCH 1/2] feat: add HAX CLI Claude Code plugin + marketplace Make this repo a Claude Code plugin marketplace and ship the `hax` plugin so new users can discover, install, and drive the HAX CLI from inside Claude Code, reaching a live HAXsite in the browser on their first run. - .claude-plugin/marketplace.json: in-tool discovery (`/plugin marketplace add haxtheweb/create`) - plugins/hax/.claude-plugin/plugin.json: manifest - plugins/hax/hooks/: SessionStart hook auto-installs @haxtheweb/create when `hax` is missing (opt out with HAX_PLUGIN_NO_AUTOINSTALL=1) - plugins/hax/skills/hax/SKILL.md: onboarding-scoped CLI knowledge - plugins/hax/commands/: /hax:quickstart (golden path) plus site, webcomponent, serve, audit, publish Validated with `claude plugin validate` (plugin + marketplace). Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/marketplace.json | 24 +++ plugins/hax/.claude-plugin/plugin.json | 14 ++ plugins/hax/README.md | 63 ++++++ plugins/hax/commands/audit.md | 19 ++ plugins/hax/commands/publish.md | 26 +++ plugins/hax/commands/quickstart.md | 44 +++++ plugins/hax/commands/serve.md | 15 ++ plugins/hax/commands/site.md | 29 +++ plugins/hax/commands/webcomponent.md | 22 +++ plugins/hax/hooks/hooks.json | 17 ++ plugins/hax/hooks/scripts/ensure-hax.sh | 48 +++++ plugins/hax/skills/hax/SKILL.md | 249 ++++++++++++++++++++++++ 12 files changed, 570 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 plugins/hax/.claude-plugin/plugin.json create mode 100644 plugins/hax/README.md create mode 100644 plugins/hax/commands/audit.md create mode 100644 plugins/hax/commands/publish.md create mode 100644 plugins/hax/commands/quickstart.md create mode 100644 plugins/hax/commands/serve.md create mode 100644 plugins/hax/commands/site.md create mode 100644 plugins/hax/commands/webcomponent.md create mode 100644 plugins/hax/hooks/hooks.json create mode 100755 plugins/hax/hooks/scripts/ensure-hax.sh create mode 100644 plugins/hax/skills/hax/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..f455d98 --- /dev/null +++ b/.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"] + } + ] +} diff --git a/plugins/hax/.claude-plugin/plugin.json b/plugins/hax/.claude-plugin/plugin.json new file mode 100644 index 0000000..5085085 --- /dev/null +++ b/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"] +} diff --git a/plugins/hax/README.md b/plugins/hax/README.md new file mode 100644 index 0000000..a10d98a --- /dev/null +++ b/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: +- HAX: · diff --git a/plugins/hax/commands/audit.md b/plugins/hax/commands/audit.md new file mode 100644 index 0000000..181e745 --- /dev/null +++ b/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. diff --git a/plugins/hax/commands/publish.md b/plugins/hax/commands/publish.md new file mode 100644 index 0000000..748b201 --- /dev/null +++ b/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 ] [--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 ./`). + +User input: `$ARGUMENTS` + +Targets: +- surge.sh: `hax site site:surge` (or `--domain my-site.surge.sh`) +- Netlify: `hax site site:netlify --y` (or `--domain `) +- Vercel: `hax site site:vercel --y` (or `--domain `) +- 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. diff --git a/plugins/hax/commands/quickstart.md b/plugins/hax/commands/quickstart.md new file mode 100644 index 0000000..b590e65 --- /dev/null +++ b/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 --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 && 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 "

...

" --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. diff --git a/plugins/hax/commands/serve.md b/plugins/hax/commands/serve.md new file mode 100644 index 0000000..34437f7 --- /dev/null +++ b/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`. diff --git a/plugins/hax/commands/site.md b/plugins/hax/commands/site.md new file mode 100644 index 0000000..cdc6249 --- /dev/null +++ b/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 ] [--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 --y` (add `--theme ""`, e.g. `clean-two`, `polaris-flex-theme`). +- From a template: `--skeleton-machine-name ` or `--skeleton-file ./template.json`. +- Run from the directory where the site folder should be created, or pass `--root `. +- If no name is given, ask for one. + +**Existing-site operations** — run from inside the site folder (or `--root ./`): +- Add a page: `hax site node:add --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`. diff --git a/plugins/hax/commands/webcomponent.md b/plugins/hax/commands/webcomponent.md new file mode 100644 index 0000000..6c8065b --- /dev/null +++ b/plugins/hax/commands/webcomponent.md @@ -0,0 +1,22 @@ +--- +description: Scaffold a new HAX-capable Lit/DDD web component with the HAX CLI (hax webcomponent). +argument-hint: "[component-name] [--writeHaxProperties] [--y]" +allowed-tools: Bash(hax:*), Bash(cd:*), Read +--- + +Create a new web component with `hax webcomponent` from `@haxtheweb/create`. Components are +LitElement-based, extend `DDDSuper` (the DDD design system), and are i18n-wired. + +User input: `$ARGUMENTS` + +Guidance: +- New component: `hax webcomponent <my-element> --y`. The name **must be hyphenated** + (e.g. `my-card`, not `myCard`). If no name is given, ask for a hyphenated one. +- Add `--writeHaxProperties` to generate the schema for HAX authoring integration. +- In a **monorepo root**, the CLI places the component correctly and inherits settings — + run from the repo root in that case. +- Set metadata with `--org <org>` / `--author <name>`; use `--y --no-i` for scripting. + +Build and run the `hax webcomponent …` command, then summarize the created component and +next steps (`cd <name>`, `npm install`, `npm start`). Remember HAX is **JavaScript only — +no TypeScript**; import prebuilt JS dists of any TS-authored libraries. diff --git a/plugins/hax/hooks/hooks.json b/plugins/hax/hooks/hooks.json new file mode 100644 index 0000000..788d5e0 --- /dev/null +++ b/plugins/hax/hooks/hooks.json @@ -0,0 +1,17 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup|resume", + "hooks": [ + { + "type": "command", + "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/ensure-hax.sh\"", + "timeout": 120, + "statusMessage": "Checking HAX CLI…" + } + ] + } + ] + } +} diff --git a/plugins/hax/hooks/scripts/ensure-hax.sh b/plugins/hax/hooks/scripts/ensure-hax.sh new file mode 100755 index 0000000..5377dcf --- /dev/null +++ b/plugins/hax/hooks/scripts/ensure-hax.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +# +# ensure-hax.sh — SessionStart hook for the HAX Claude Code plugin. +# +# Makes sure the HAX CLI (`hax`, shipped by @haxtheweb/create) is available. +# - If `hax` is already on PATH, reports its version and exits. +# - If it is missing, installs @haxtheweb/create globally with npm. +# +# Opt out of auto-install: export HAX_PLUGIN_NO_AUTOINSTALL=1 +# +# This hook never blocks the session: it always exits 0. Anything it prints on +# stdout is surfaced to Claude as session context so the assistant knows whether +# the CLI is ready. + +set -uo pipefail + +MANUAL_INSTALL="npm install --global @haxtheweb/create" + +# --- Already installed? Report and bail. ------------------------------------ +if command -v hax >/dev/null 2>&1; then + ver="$(hax --version 2>/dev/null | head -n1 | tr -d '\r')" + echo "HAX CLI is available (hax ${ver:-installed}). Use \`hax help\` or the /hax:* slash commands." + exit 0 +fi + +# --- Respect opt-out. ------------------------------------------------------- +if [ "${HAX_PLUGIN_NO_AUTOINSTALL:-0}" = "1" ]; then + echo "HAX CLI not found; auto-install disabled (HAX_PLUGIN_NO_AUTOINSTALL=1). Install with: ${MANUAL_INSTALL}" + exit 0 +fi + +# --- Need npm to install. --------------------------------------------------- +if ! command -v npm >/dev/null 2>&1; then + echo "HAX CLI not found and npm is unavailable. Install Node.js (>=18.20.3), then run: ${MANUAL_INSTALL}" + exit 0 +fi + +# --- Install globally (one-time). ------------------------------------------- +# Human-facing progress goes to stderr; the result line goes to stdout/context. +echo "HAX CLI not found — installing @haxtheweb/create globally (one-time setup)…" 1>&2 +if npm install --global @haxtheweb/create >/dev/null 2>&1; then + ver="$(hax --version 2>/dev/null | head -n1 | tr -d '\r')" + echo "Installed HAX CLI (hax ${ver:-latest}). Use \`hax help\` or the /hax:* slash commands." +else + echo "Could not auto-install the HAX CLI (global npm install failed — it may need elevated permissions). Install manually: ${MANUAL_INSTALL}" +fi + +exit 0 diff --git a/plugins/hax/skills/hax/SKILL.md b/plugins/hax/skills/hax/SKILL.md new file mode 100644 index 0000000..7b3b03e --- /dev/null +++ b/plugins/hax/skills/hax/SKILL.md @@ -0,0 +1,249 @@ +--- +name: hax +description: >- + Build and manage HAX projects with the `hax` CLI (@haxtheweb/create). Use when + the user wants to create a HAX web component or HAXsite, scaffold a Lit/DDD + component, audit DDD design-system compliance, run a HAXsite dev server, + add/edit/delete pages or content, import or migrate content into a HAXsite, + publish to surge/netlify/vercel/gh-pages, or otherwise run `hax` commands. + Triggers include: hax, haxcms, haxsite, haxtheweb, web component, Lit element, + DDD audit, "hax site", "hax webcomponent". +allowed-tools: Bash, Read, Edit, Write, Glob, Grep +--- + +# HAX CLI (`@haxtheweb/create`) + +The `hax` command rapidly scaffolds and manages **HAX-capable web components** and +**HAXsites** (HAXcms single sites). It is the primary interface for the HAX +ecosystem. This skill gives you the command surface and the conventions that make +HAX work correctly. + +## Installation & updates + +```bash +npm install --global @haxtheweb/create # installs `hax` and `create-haxtheweb` +hax update # self-update the CLI +hax --version # check installed version +``` + +This plugin's SessionStart hook installs the CLI automatically if `hax` is +missing. If it isn't on PATH, fall back to the global install above (or `npx +@haxtheweb/create` / `npm init @haxtheweb` for a one-off run). Requires Node +`>=18.20.3`. + +## Quickstart (golden path for a new user) + +When someone is new to HAX or just wants to see something work, lead with the +shortest path to a **live site in the browser** — do not dump the full command +surface on them: + +```bash +hax site my-hax-site --y --no-i # 1. scaffold a HAXsite with defaults +cd my-hax-site && hax serve # 2. serve it (background; long-running) + # 3. surface the local URL + one next edit +``` + +The `/hax:quickstart` command runs exactly this. Default the site name if they +don't supply one, background `hax serve`, report the URL, and point at a single +concrete next step. Save web components, audits, imports, theming, and publishing +for after they've seen their first site. + +## Command groups + +```bash +hax start # interactive menu (ascii art + Clack prompts) +hax serve # run a HAXsite in dev mode at http://localhost +hax site # create / administer a HAXsite +hax webcomponent # create / work with a Lit + DDD web component (alias: hax wc) +hax audit # audit web components for DDD compliance +hax party # community / get-involved options +hax update # CLI self-update +hax help [command] # authoritative, up-to-date help; also `hax site --help` +``` + +Always trust `hax help`, `hax site --help`, and `hax webcomponent --help` for the +current flag list — they reflect the installed version. + +## Global flags (apply across commands) + +| Flag | Meaning | +|------|---------| +| `--y` / `--auto` | Yes to all prompts (scripting) | +| `--no-i` | No interactions / sub-processes (best for scripting) | +| `--quiet` | Suppress console logging | +| `--skip` | Skip frills/animations (faster) | +| `--v` | Verbose; `--debug` developer output | +| `--format <json\|yaml>` | Output format (default json) | +| `--path <dir>` | Where to perform the operation | +| `--root <dir>` | Run the command as if from this directory | +| `--to-file <file>` | Redirect command output to a file | +| `--no-extras` | Skip automatic extra processing | +| `--npm-client <npm\|yarn\|pnpm>` | Package manager (default npm) | +| `--org <org>` / `--author <name>` | package.json / site metadata | + +**For automation, prefer `--y --no-i` (optionally `--quiet`).** Without them, the +CLI may open interactive Clack prompts that stall a non-interactive session. + +## Create a web component + +```bash +hax webcomponent my-element --y # Lit + DDDSuper + i18n, defaults +hax webcomponent my-card --writeHaxProperties --y # also emit haxProperties +``` + +- The name **must be hyphenated** (`my-element`, never `myElement`). +- LitElement-based, extends `DDDSuper` (the DDD design system), i18n-wired. +- In a **monorepo root**, the component is placed in the correct location and + inherits settings — run from the repo root in that case. +- After creation: `cd my-element && npm install && npm start` to develop. +- `--writeHaxProperties` generates the schema that lets the component plug into + the HAX authoring UI. + +## Create a HAXsite + +```bash +hax site mysite --y # default theme +hax site mysite --theme "polaris-flex-theme" --y # pick a theme +hax site mysite --skeleton-machine-name clean-one --y # from an installed skeleton +hax site mysite --skeleton-file ./template.json --y # from a local skeleton file +``` + +Custom theme starting point: + +```bash +hax site mysite --theme "custom-theme" \ + --custom-theme-name "my-theme" \ + --custom-theme-template "base" --y # templates: base | polaris-flex | polaris-sidebar +``` + +A HAXsite is a portable HAXcms site: `site.json` (JSON Outline Schema), `pages/` +content, `files/` assets, optional `theme/`. Preview with `hax serve` from the +site root. + +## Work with an existing HAXsite + +Run site sub-commands from inside the site folder, or target it with +`--root ./mysite`. + +### Content / node operations + +```bash +# Add a page +hax site node:add --title "My summer vacation" \ + --content "<p>An awesome blog post.</p>" --y + +# Edit a node by id (node-op: title | content | slug | parent | order | published | tags | theme | hide-in-menu) +hax site node:edit --item-id item-<uuid> --node-op title --title "New title" +hax site node:edit --item-id item-<uuid> --node-op content --content "<p>New content</p>" +hax site node:edit --item-id item-<uuid> --node-op parent # interactive picker + +# Inspect / delete +hax site node:stats # interactive node inspector +hax site node:delete --item-id item-<uuid> --y +``` + +Page-creation flags: `--title`, `--content`, `--slug`, `--published`, `--tags`, +`--parent`, `--order`, `--theme`, `--hide-in-menu`. + +### Site operations + +```bash +hax site site:stats # site stats +hax site site:items --to-file export-items.json # list nodes -> file +hax site site:items-import --items-import items.json # import nodes from file +hax site site:list-files # uploaded files +hax site site:search --search "lesson" # full-text search +hax site site:search --search "video-player[src]" --search-selector # HTML selector search +hax site site:theme --theme "clean-two" --y # change theme +hax site site:html --to-file output.html # export site as HTML +hax site site:md --to-file output.md # export site as Markdown +hax site site:schema --to-file schema.json # export HAXSchema (vdom) +hax site site:sync # git sync (if remote configured) +``` + +### Skeleton templates (reusable site blueprints) + +```bash +hax site site:skeleton-export --to-file ./template.json # export current site +hax site site:skeleton-install # install current site as skeleton +hax site site:skeleton-install --skeleton-file ./template.json \ + --skeleton-machine-name course-template # install from file, rename +``` + +### Recipes + +```bash +hax site recipe:read # print the recipe used to build the site +hax site recipe:play --recipe my.recipe --y # replay a recipe (scripted) +``` + +## Import & migrate content + +```bash +hax site --import-site https://example.com --import-structure htmlToSite +``` + +`--import-structure` options: `pressbooksToSite`, `elmslnToSite`, `haxcmsToSite`, +`notionToSite`, `gitbookToSite`, `evolutionToSite`, `ploneToSite`, +`wordpressPagesToSite`, `drupalBookToSite`, `htmlToSite`, `docxToSite`. Tune +scraping with `--title-scrape` / `--content-scrape` (CSS selectors). Validate +source URLs before importing untrusted content. + +## Serve locally + +```bash +hax serve # serves the HAXsite in the current dir at http://localhost +``` + +`hax serve` is **long-running** — start it in the background so the session stays +responsive, then report the local URL. + +## Publish / deploy a HAXsite + +Run from the site root (or pass `--root ./mysite`). Deploying is outward-facing — +confirm the target/domain before pushing unless the user already specified it. + +```bash +hax site site:surge --domain my-blog.surge.sh # surge.sh +hax site site:netlify --y # Netlify (or --domain <site-id>) +hax site site:vercel --y # Vercel (or --domain <project>) +hax site setup:github-actions # CI: deploy on git push (GH Pages) +hax site setup:gitlab-ci # CI: deploy on git push (GitLab) +``` + +## Audit components for DDD compliance + +```bash +hax audit # run from a component's root +hax --debug audit # also print gathered .dddignore contents +``` + +- Audits CSS/structure against the **DDD** design system and suggests token-based + fixes. Honors a `.dddignore` file (each generated component ships with one). +- **Required** before submitting theme components or PRs. +- Do **not** hand-edit auto-generated files like `custom-elements.json` — run the + project build (`npm run build` / `yarn run build`) to regenerate them. + +## HAX conventions (important when editing generated code) + +- **JavaScript only — no TypeScript.** HAX ships unbundled JS/HTML/CSS with no + compile step. If you use a TS-authored library, import its prebuilt JS dist + (e.g. `@vaadin/<c>/<c>.js`, `@shoelace-style/shoelace/dist/components/...`). +- Use `globalThis`, single quotes, ES modules; prefer functional patterns. +- Components extend `DDDSuper`; HAXcms **themes** extend `HAXCMSLitElement`. After + editing a theme, rebuild to regenerate `custom-elements.json`. +- Use DDD design tokens (CSS custom properties) for color/spacing/typography + instead of hardcoded values. +- Web component & package names are hyphenated and should match. + +## Typical workflows + +- **New component:** `hax webcomponent my-thing --writeHaxProperties --y` → `cd` → + `npm install` → `npm start` → edit → `hax audit`. +- **New site:** `hax site mysite --y` → `cd mysite` → `hax serve` → add pages with + `hax site node:add ...` → publish with `hax site site:vercel --y`. +- **Migrate a site:** `hax site newsite --import-site <url> --import-structure + <method> --y` → review → `hax serve`. + +When unsure of an exact flag for the installed version, run the relevant +`hax <command> --help` first and adapt. From d02457a666ff2bf214e4ea751674af2fbcee9876 Mon Sep 17 00:00:00 2001 From: "Rick Manelius, PhD" <rickmanelius@gmail.com> Date: Mon, 29 Jun 2026 20:06:56 -0500 Subject: [PATCH 2/2] docs: add HAX onboarding plugins v1 requirements Brainstorm/requirements for the cross-tool (Claude Code + Codex) HAX onboarding layer. Documents the golden path, scope by platform, and the remaining Codex surface (AGENTS.md quickstart + custom prompt) deferred beyond the Claude plugin. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --- ...-29-hax-onboarding-plugins-requirements.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/brainstorms/2026-06-29-hax-onboarding-plugins-requirements.md diff --git a/docs/brainstorms/2026-06-29-hax-onboarding-plugins-requirements.md b/docs/brainstorms/2026-06-29-hax-onboarding-plugins-requirements.md new file mode 100644 index 0000000..02ac7fd --- /dev/null +++ b/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`.