@haus-tech/haus-workflow 0.11.1 → 0.12.0

package/library/global/skills/haus-workflow/SKILL.md

@@ -1,63 +1,103 @@
-## <!-- HAUS-MANAGED id=skill.haus-workflow v=1 source=@haus-tech/haus-workflow@0.1.0 -->
+## <!-- HAUS-MANAGED id=skill.haus-workflow v=2 source=@haus-tech/haus-workflow@0.1.0 -->
 
 name: haus-workflow
-description: Haus all-in-one workflow skill. Handles project setup, update, catalog refresh, and CLAUDE.md regeneration.
+description: Haus all-in-one workflow skill. Handles project setup, update, catalog refresh, and CLAUDE.md regeneration. Invoke with a task name or without to get a menu.
 
 ---
 
 # haus-workflow
 
-All-in-one entry point for the Haus AI workflow. Covers setup, update, sync, catalog refresh, and root `CLAUDE.md` regeneration.
+All-in-one entry point for the Haus AI workflow.
 
-## Use when
+## Invocation
 
-- Setting up a project for the first time (`haus init`).
-- Updating an existing project setup (`.claude/` + `.haus-workflow/`).
-- Checking for a newer `@haus-tech/haus-workflow` package and refreshing `~/.claude/` accordingly.
-- Fetching catalog updates (`haus update`).
-- Regenerating the root `CLAUDE.md` import block.
+`/haus-workflow [task]`
 
-## Do not use when
+`task` is optional. If omitted, present a task menu (see below). If provided, map it to a command and run immediately.
 
-- User needs a security, code, or test review — use the dedicated reviewer agents instead.
+## Task aliases → commands
+
+| Alias(es)                            | Command              | What it does                                   |
+| ------------------------------------ | -------------------- | ---------------------------------------------- |
+| `init`, `setup`                      | `haus init`          | First-time project setup                       |
+| `apply`, `refresh`, `update-project` | `haus apply --write` | Re-run setup / refresh `.claude/` context      |
+| `update`, `upgrade`                  | `haus update`        | Update npm package + catalog + `~/.claude/`    |
+| `catalog`                            | `haus update`        | Fetch latest catalog (same command as update)  |
+| `doctor`, `check`                    | `haus doctor`        | Check for install drift                        |
+| `install`, `global`                  | `haus install`       | Seed `~/.claude/` with haus-owned files        |
+| `uninstall`                          | `haus uninstall`     | Remove all haus global files from `~/.claude/` |
+| `claude-md`, `regenerate`            | `haus apply --write` | Regenerate root `CLAUDE.md` import block       |
+
+## Step 1 — Determine the task
+
+**If a task argument was passed:** look it up in the alias table above. If no match, tell the user and list valid options. If matched, skip to Step 2.
+
+**If no task was passed:** use `AskUserQuestion` to present this menu:
+
+```
+Question: "What would you like to do?"
+Options:
+  1. Set up this project for the first time
+     (haus init — scans repo, writes .haus-workflow/, updates CLAUDE.md)
+  2. Refresh project setup
+     (haus apply --write — re-runs setup, regenerates CLAUDE.md imports)
+  3. Update haus package + catalog + global files
+     (haus update — checks npm for new version, fetches catalog, refreshes ~/.claude/)
+  4. Fetch catalog updates only
+     (haus update — same command; pulls latest workflow templates and lockfile)
+  5. Regenerate CLAUDE.md import block
+     (haus apply --write — rewrites the @-import block at the root CLAUDE.md)
+```
+
+Map the user's selection to the command from the alias table, then continue to Step 2.
+
+## Step 2 — Run the command
 
-## How to invoke
+Run the mapped command via Bash. Quote the exact command you are running before executing it.
 
-Run the relevant CLI command for the task:
+## Step 3 — Post-run steps
 
-| Goal                                        | Command              |
-| ------------------------------------------- | -------------------- |
-| First-time project setup                    | `haus init`          |
-| Re-run setup / refresh context              | `haus apply --write` |
-| Update package + catalog + `~/.claude/`     | `haus update`        |
-| Check install drift                         | `haus doctor`        |
-| Install global haus files into `~/.claude/` | `haus install`       |
-| Remove all haus global files                | `haus uninstall`     |
+After the command completes, follow the relevant post-run steps below.
 
-## Setup flow (init)
+### After `haus init`
 
-1. Run `haus init` in the project root.
-2. Haus scans the repo, generates `.haus-workflow/context-map.json` and `.haus-workflow/recommendation.json`.
-3. Writes `.haus-workflow/WORKFLOW.md` (managed, from catalog template) and `.haus-workflow/project.md`.
-4. Writes `.haus-workflow/workflow-config.md` if it does not exist (project-owned). The CLI seeds what the scan knows (package manager → inferred test/audit commands). After the CLI step, open `workflow-config.md` and complete it using project context:
-   - `package.json` scripts → exact test, lint, typecheck, build commands
-   - `docs/` directory → presence of SPEC.md, DESIGN.md, UX.md
-   - Dependencies → validation library (zod, yup, joi…), pre-commit tool
-   - Project domain → highest-stakes logic (payment, auth, medical…)
-5. Ensures root `CLAUDE.md` imports `@.haus-workflow/WORKFLOW.md`, `@.haus-workflow/workflow-config.md`, and `@.haus-workflow/project.md`.
-6. Prints a summary; user confirms before writes.
+1. Open `.haus-workflow/workflow-config.md`.
+2. Check for unfilled placeholders (`TODO`, `n/a`, empty values) in:
+   - Test, lint, typecheck, build commands — confirm against `package.json` scripts.
+   - Docs paths — check whether `docs/SPEC.md`, `docs/DESIGN.md`, `docs/UX.md` exist.
+   - Validation library — check `package.json` dependencies for `zod`, `yup`, `joi`, `valibot`.
+   - Pre-commit tool — check for `.husky/`, `lefthook.yml`, `.pre-commit-config.yaml`.
+   - Highest-stakes logic — ask the user if unclear.
+3. Fill in every unfilled field. Do not leave placeholders.
+4. Confirm with the user that `workflow-config.md` is complete before proceeding.
 
-## Update flow
+### After `haus apply --write`
 
-`haus update` runs in order:
+Verify that the root `CLAUDE.md` imports all three haus files:
 
-1. Checks installed npm package version vs. latest on registry. If newer: prints `npm i -g @haus-tech/haus-workflow` instruction.
-2. After any version change, re-runs `haus install` to refresh `~/.claude/` haus files.
-3. Fetches latest catalog from `haus-workflow-catalog`, writes cache, updates lockfile.
-4. Re-renders `.haus-workflow/project.md`. Re-applies `.haus-workflow/WORKFLOW.md` if catalog template version changed (hash-based; skips if user-modified). If `.haus-workflow/workflow-config.md` does not exist, writes and completes it (same as init step 4). If WORKFLOW.md was updated, prompt the user: "WORKFLOW.md has been updated. Review workflow-config.md to check if any new configuration sections need project-specific values."
+```
+@.haus-workflow/WORKFLOW.md
+@.haus-workflow/workflow-config.md
+@.haus-workflow/project.md
+```
 
-## Global install
+If any import is missing, add it.
 
-`haus install` seeds `~/.claude/` with haus-owned files. Each file carries a `<!-- HAUS-MANAGED ... -->` header so the CLI can update or remove it safely without touching user content.
+### After `haus update`
 
-`haus uninstall` reverses this: removes every HAUS-MANAGED file and strips haus hook entries from `~/.claude/settings.json`. User-owned files are never deleted.
+1. If CLI output says a new version is available, run `npm i -g @haus-tech/haus-workflow` and confirm the version bump.
+2. If `WORKFLOW.md` was updated, remind the user: "WORKFLOW.md updated — review `workflow-config.md` for any new sections that need project-specific values."
+3. If CLI output shows catalog changes, summarise which templates changed.
+
+### After `haus doctor`
+
+Report findings clearly. For each drift item, suggest the exact fix command.
+
+### After `haus install` / `haus uninstall`
+
+Confirm which files were written to or removed from `~/.claude/`. No further steps.
+
+## Do not use when
+
+- User needs a security, code, or test review — use the dedicated reviewer agents instead.
+- User asks about workflow concepts or wants to understand the WORKFLOW.md standard — answer directly from the loaded context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haus-tech/haus-workflow",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
   "homepage": "https://github.com/WeAreHausTech/haus-workflow",
   "files": [
     "dist",
+    "scripts/postinstall.mjs",
     "library/global",
     "library/catalog",
     "tests/fixtures/catalog",
@@ -24,7 +25,7 @@
   "scripts": {
     "build": "tsup src/cli.ts --format esm --dts --clean --out-dir dist --external @inquirer/checkbox",
     "dev": "tsx src/cli.ts",
-    "test": "node --test tests/**/*.test.js",
+    "test": "node --import tsx --test tests/**/*.test.js",
     "lint": "eslint src scripts",
     "format:check": "prettier --check .",
     "format": "prettier --write .",
@@ -37,7 +38,8 @@
     "release:dry": "GITHUB_TOKEN=$(gh auth token) release-it --dry-run",
     "prepack": "yarn build",
     "verify": "yarn typecheck && yarn typecheck:scripts && yarn lint && yarn build && yarn test",
-    "prepare": "husky",
+    "postinstall": "node ./scripts/postinstall.mjs || true",
+    "prepare": "lefthook install || true",
     "security:audit": "yarn npm audit -A -R --severity high --environment production"
   },
   "dependencies": {
@@ -62,8 +64,7 @@
     "@typescript-eslint/parser": "8.59.3",
     "eslint": "9.39.4",
     "eslint-plugin-import": "2.32.0",
-    "husky": "9.1.7",
-    "lint-staged": "17.0.4",
+    "lefthook": "1.13.6",
     "prettier": "3.8.3",
     "release-it": "20.0.1",
     "tsup": "8.5.1",
@@ -77,10 +78,9 @@
     "access": "public"
   },
   "packageManager": "yarn@4.15.0",
-  "lint-staged": {
-    "**/*.ts": [
-      "eslint",
-      "prettier --write"
-    ]
+  "dependenciesMeta": {
+    "lefthook": {
+      "built": true
+    }
   }
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * npm postinstall hook. On a GLOBAL install of @haus-tech/haus-workflow, runs
+ * `haus install --postinstall` automatically so a non-developer gets a working
+ * Claude Code setup with zero manual steps — then the CLI prints exactly what it
+ * changed in ~/.claude and how to undo it.
+ *
+ * Fail-open by design: this must NEVER break `npm install`. Every gate that isn't
+ * satisfied is a silent no-op, and the whole body is wrapped so any error still
+ * exits 0. Plain Node ESM (no tsx) because consumers don't have the dev toolchain.
+ */
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Pure gate: decides whether the postinstall should run. Kept side-effect-free and
+ * exported so it can be unit-tested across the full env/fs matrix without spawning npm.
+ *
+ * @param {{ env: Record<string, string | undefined>, distExists: boolean, srcExists: boolean }} input
+ * @returns {{ run: boolean, reason: string }}
+ */
+export function shouldRunPostinstall({ env, distExists, srcExists }) {
+  if (env.npm_config_global !== 'true') return { run: false, reason: 'not a global install' }
+  if (env.CI) return { run: false, reason: 'CI environment' }
+  if (env.HAUS_NO_POSTINSTALL === '1') return { run: false, reason: 'HAUS_NO_POSTINSTALL=1' }
+  if (!distExists) return { run: false, reason: 'dist/cli.js missing' }
+  // Published tarballs omit src/; its presence means we're in the package's own
+  // dev checkout, where a local `yarn install` must not self-trigger.
+  if (srcExists) return { run: false, reason: 'running inside the package dev checkout' }
+  return { run: true, reason: 'global install' }
+}
+
+/** Entry point: runs only when this file is invoked directly (not when imported by a test). */
+function main() {
+  try {
+    const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+    const cliPath = path.join(pkgRoot, 'dist', 'cli.js')
+    const decision = shouldRunPostinstall({
+      env: process.env,
+      distExists: fs.existsSync(cliPath),
+      srcExists: fs.existsSync(path.join(pkgRoot, 'src')),
+    })
+
+    if (!decision.run) {
+      if (process.env.HAUS_DEBUG) console.error(`[haus postinstall] skipped: ${decision.reason}`)
+      process.exit(0)
+    }
+
+    // Non-fatal: a nonzero CLI exit must not fail `npm install`.
+    spawnSync(process.execPath, [cliPath, 'install', '--postinstall'], { stdio: 'inherit' })
+  } catch (err) {
+    if (process.env.HAUS_DEBUG) console.error(`[haus postinstall] error (ignored): ${err}`)
+  }
+  process.exit(0)
+}
+
+// Run only as a script, never when imported.
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main()
+}

package/tests/README.md

@@ -8,12 +8,11 @@ yarn test
 
 ## Structure
 
-| Path              | Contents                                           |
-| ----------------- | -------------------------------------------------- |
-| `tests/*.test.js` | Unit and integration tests                         |
-| `tests/helpers/`  | Shared test utilities                              |
-| `tests/fixtures/` | Static fixture repos used by tests                 |
-| `tests/golden/`   | Golden output snapshots for scan/recommend/context |
+| Path              | Contents                            |
+| ----------------- | ----------------------------------- |
+| `tests/*.test.js` | Unit and integration tests          |
+| `tests/helpers/`  | Shared test utilities               |
+| `tests/fixtures/` | Static fixture repos used by tests  |
 
 ## helpers/fixture-runner.js
 
@@ -22,8 +21,6 @@ Utilities for running the compiled CLI against fixture repos in a temp directory
 - `cloneFixtureToTemp(fixtureName)` — copies `tests/fixtures/repos/<name>` to a temp dir, returns the path
 - `runHaus(cwd, command)` — runs `node dist/cli.js <command>` in `cwd`, returns stdout
 - `readHausJson(cwd, fileName)` — reads `.haus-workflow/<fileName>` as parsed JSON
-- `normalizeRecommendationForGolden(rec)` — stable sort for golden snapshot comparison
-- `normalizeContextForGolden(ctx)` — stable sort for golden snapshot comparison
 
 Tests that use `fixture-runner.js` require a built `dist/` — run `yarn build && yarn test`, or use `yarn verify` which builds before running tests.
 
@@ -47,10 +44,6 @@ Full fixture repos scanned by integration tests and golden tests. Each subdirect
 | `wordpress-bedrock-site`         | WordPress Bedrock (Composer)          |
 | `wordpress-with-node-tooling`    | WordPress + Node tooling (pnpm)       |
 
-### fixtures/findings/
-
-QA findings records (see `fixtures/findings/README.md`). Observational only — not gated by any test.
-
 ### Other fixture dirs
 
 - `fixtures/dotnet-service/` — unsupported stack (C#/.NET), used to verify unsupported-stack handling
@@ -59,12 +52,3 @@ QA findings records (see `fixtures/findings/README.md`). Observational only —
 - `fixtures/vendure-plugin/` — minimal Vendure plugin package
 - `fixtures/laravel-app/`, `fixtures/next-react-app/`, `fixtures/wordpress-bedrock/` — legacy shallow fixtures; prefer `fixtures/repos/` equivalents for new tests
 
-## golden/
-
-Snapshot files for `context-goldens.test.js` and `recommender.test.js`. Keyed by fixture name.
-
-- `golden/scans/` — `scanProject` output
-- `golden/recommendations/` — `runRecommend` output (normalized)
-- `golden/context/` — `runContext` output (normalized)
-
-To regenerate goldens after intentional recommender changes, delete the relevant `.json` file and re-run `yarn test` — the test will write the new snapshot and pass on the next run.

package/tests/fixtures/catalog/manifest.json

@@ -2,25 +2,6 @@
   "version": "0.1.0",
   "_note": "Stable fixture for CLI tests. Decoupled from production catalog repo. Update manually when catalog schema changes.",
   "items": [
-    {
-      "id": "haus.global-engineering-rules",
-      "source": "haus",
-      "type": "skill",
-      "path": "skills/global-engineering-rules",
-      "title": "Haus global engineering rules",
-      "purpose": "Provide baseline deterministic engineering, validation, and security guardrails.",
-      "whenToUse": "Use as default baseline in supported Haus workflows.",
-      "whenNotToUse": "Do not use for unsupported stacks or non-development workflows.",
-      "references": [],
-      "safetyNotes": ["Never read secrets or customer exports."],
-      "tokenBudget": 1800,
-      "tags": ["haus", "quality", "security"],
-      "repoRoles": [],
-      "requiresAny": [],
-      "tokenEstimate": 1800,
-      "installMode": "copy-selected",
-      "default": true
-    },
     {
       "id": "haus.nextjs-patterns",
       "source": "haus",