Haus Workflow

Internal Haus tool. Open-source but unsupported for external use. No external issues, PRs, or roadmap commitments accepted.

Install

Requires Node 22+.

Terminal:

npm install -g @haus-tech/haus-workflow

Or paste this into Claude Code:

Install the haus-workflow CLI globally by running `npm install -g @haus-tech/haus-workflow`.

A global install auto-runs haus install via a postinstall hook — it seeds ~/.claude/ with Haus-managed skills, global slash commands, and hooks, merges security rules into ~/.claude/settings.json, and prints a notice of what changed. It is non-fatal, idempotent, and global-only. Skip it with HAUS_NO_POSTINSTALL=1; re-run or repair any time with haus install. Undo with haus uninstall.

haus-workflow skill

Once installed, Claude Code gains a /haus-workflow slash command.

Task names are plain verbs; each detects its own scope (a single haus-set-up repo, a multi-repo workspace, or neither) before acting. refresh also updates this machine's haus install (~/.claude, npm) first; uninstall acts ONLY on the machine, never on a repo. Every old project:-prefixed name (and other legacy aliases like setup, fix, add-skills) still works as an alias into the task it merged into.

/haus-workflow                 # interactive menu — pick a task
/haus-workflow init            # set up this project (or workspace) with haus; offers refresh/clean-slate when already set up
/haus-workflow clone [name]    # clone one repo by name, or a whole workspace (repos.manifest.json); offers local-dev setup after
/haus-workflow new [description] # create a brand-new project from a plain-language request
/haus-workflow doctor          # health check for this project or workspace; offers to apply suggested fixes
/haus-workflow refresh         # update haus itself (package + catalog + ~/.claude), then fully sync this project or just add optional helpers
/haus-workflow uninstall       # remove haus global files from ~/.claude — never touches this project

Without an argument, the skill presents a menu so you can pick the task. With an argument, it runs immediately.

Commands

haus init              # full setup: scan → recommend → apply (safe to re-run)
haus init --dry-run    # preview the .claude/ write only; scan artifacts are still written
haus clone <url> [dir] # clone a single git repo by URL (the primitive the clone/cloneandsetup tasks loop over)
haus scan              # scan repo and write context-map
haus recommend         # recommend catalog items (binary eligibility)
haus apply --dry-run   # preview what would be written
haus apply --write     # write .claude/ files (skills, agents, commands, templates)
haus apply --select    # interactively choose which recommended items to install
haus apply --refill-config    # fill still-blank workflow-config.md fields, keep edits
haus update                   # check npm for new CLI + sync catalog + refresh ~/.claude/ and this project
haus update --check           # check for updates without applying
haus undo                     # remove haus-managed project files (lock-tracked paths)
haus doctor                   # health check: hooks, CLAUDE.md, imports, catalog cache
haus guard bash|file-access   # security guard hook; invoked by PreToolUse
haus workspace                # multi-repo ops: discover, scan, setup, doctor across a workspace
haus uninstall                # remove Haus-managed files from ~/.claude/

Cross-session learnings use Claude Code's native memory (MEMORY.md); haus ships no memory store.

Catalog

Content lives in haus-workflow-catalog (version pinned in library/catalog/manifest.json). Fetched at runtime from the latest release tag. Ref precedence: HAUS_CATALOG_REF env → a project's .haus-workflow/haus.config.json#catalogRef pin → latest release tag → bundled snapshot → main. The bundled snapshot is metadata only — it has no item content to install (see "Offline and air-gapped use" below); it exists so the CLI still has a manifest to read with no network access, not as a usable install source. Validation rules sync from catalog → library/catalog/validation-rules.json (ADR-0001).

Items install by flattening (skill, agent, template, command — basename only) or by mirroring their upstream path under sources/<slug>/ (rule, asset — so .claude/rules/react/hooks.md lands where the curated prose that references it expects). See ADR-0046.

On haus apply / haus update, items removed from the catalog or marked deprecated are pruned from the project when their on-disk copy still matches the lock hash; user-edited copies are kept, lock entry and all. Every lock-tracked catalog item haus deletes is snapshotted under .haus-workflow/backups/ first and can be put back with haus backups restore (haus undo also removes other project files such as .claude/settings.json and the root CLAUDE.md, which are not lock-tracked and not snapshotted — see docs/cli.md → haus backups). Approved items deselected via --select are not pruned.

Upgrading from a pre-0.30.0 CLI: deprecated-skill pruning shipped in 0.30.0. If an older CLI left deprecated skills on disk, upgrade first (npm i -g @haus-tech/haus-workflow) then run haus update to prune them.

Upgrading to 2.0.0: see docs/upgrading-2.0.md. It carries the rollout order (CLI first, catalog second), the two renamed skill directories, what .claude/rules/ now contains, and how to pin to a format-1 catalog to defer.

Offline and air-gapped use

The npm package ships catalog metadata only — the manifest, validation rules, ADR triggers and the lock schema. It does not contain any catalog item content. A machine with no populated cache can write core files (CLAUDE.md, settings.json, WORKFLOW.md) but cannot install skills, agents, or rules until it has real content — from a network sync or an imported bundle (see ADR-0060).

To set up a disconnected machine:

# On a machine with network access:
haus update
haus catalog bundle export --out catalog.tgz

# Move catalog.tgz across, then on the disconnected machine:
haus catalog bundle import catalog.tgz
haus apply --write --offline

Pass --offline (or set HAUS_OFFLINE=1) to skip the network legs up front rather than waiting on timeouts (catalog sync, npm version check, workflow-template fetch, llms.txt reference fetch, global-plugin install; the read-only local plugin probe still runs — see docs/cli.md → --offline for why). It never changes what gets installed.

The honest-shortfall reporting covers haus apply, haus init, haus new, and haus workspace setup (issue #325 extended apply's original ADR-0060 gate to init and workspace setup; issue #329 threaded the same --allow-empty-cache flag through haus new): a run that cannot install everything it wanted reports K of N catalog items installed and exits 1 if it installed none, unless --allow-empty-cache opts into writing core files anyway (still exits 1 having installed nothing). workspace setup reports this per member repo — a repo that installed zero catalog items, hit the zero-signal guard, or was refused for an unsupported catalog format is recorded failed, not ok (issue #330). See docs/cli.md for each command's exact flags and behaviour.

Internal docs

docs/SUMMARY.md — full documentation index

• Architecture
• Codebase
• CLI reference
• Developer scripts & release
• Security
• Runbook