@haus-tech/haus-workflow 6.8.0 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +41 -85
  3. package/dist/cli.js +25445 -34158
  4. package/docs/before-you-start.md +17 -22
  5. package/docs/glossary.md +10 -8
  6. package/package.json +1 -6
  7. package/packages/agents/issue-creator.md +3 -5
  8. package/packages/skills/adr-decisions/SKILL.md +8 -9
  9. package/packages/skills/bullmq-patterns/SKILL.md +1 -11
  10. package/packages/skills/haus-workflow/SKILL.md +28 -41
  11. package/packages/skills/haus-workflow/references/init.md +38 -69
  12. package/packages/skills/haus-workflow/references/new.md +15 -20
  13. package/packages/skills/i18next-patterns/SKILL.md +1 -11
  14. package/packages/skills/issue-authoring/SKILL.md +18 -25
  15. package/packages/skills/laravel-nova-patterns/SKILL.md +1 -11
  16. package/packages/skills/strapi-patterns/SKILL.md +1 -11
  17. package/packages/skills/vendure-app-patterns/SKILL.md +1 -11
  18. package/packages/skills/vendure-plugin-patterns/SKILL.md +1 -11
  19. package/packages/skills/whats-installed/SKILL.md +10 -8
  20. package/packages/skills/writing-documentation/SKILL.md +2 -10
  21. package/packages/templates/agentic-workflow-standard.md +15 -5
  22. package/packages/templates/decisions-ci-gate.yml +1 -1
  23. package/packages/templates/lefthook-lighthouse.yml +2 -2
  24. package/library/catalog/decisions-triggers.json +0 -26
  25. package/library/catalog/haus-lock.schema.json +0 -4
  26. package/library/catalog/manifest.json +0 -5941
  27. package/library/catalog/validation-rules.json +0 -169
  28. package/library/global/settings-fragments/hooks.json +0 -53
  29. package/scripts/postinstall.mjs +0 -62
@@ -13,36 +13,31 @@ missing. Run it first; come back here only for the detail.
13
13
 
14
14
  ## What haus needs
15
15
 
16
- | You need | What haus uses it for | If it is missing |
17
- | --------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
18
- | **Node 22 or newer** | running haus itself | `nvm install 22` (or install Node 22 from nodejs.org) |
19
- | **git** | reading the project, and every worktree command | macOS: `xcode-select --install`, or `brew install git` |
20
- | **GitHub CLI (`gh`)** | signing in to the catalog haus installs from | `brew install gh`, then `gh auth login` |
21
- | **A GitHub sign-in** | the catalog repository is private | `gh auth login` — see below |
22
- | **Claude Code** | the editor haus configures, and the `claude` CLI | install from <https://claude.com/claude-code>, then reopen your terminal |
23
- | **Network access** | fetching the catalog | connect, or use an offline bundle (`docs/cli.md` → offline) |
16
+ | You need | What haus uses it for | If it is missing |
17
+ | --------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ |
18
+ | **Node 22 or newer** | running haus itself | `nvm install 22` (or install Node 22 from nodejs.org) |
19
+ | **git** | reading the project, `haus sync`, every worktree command | macOS: `xcode-select --install`, or `brew install git` |
20
+ | **GitHub CLI (`gh`)** | signing git in to the repository haus syncs from | `brew install gh`, then `gh auth login` |
21
+ | **A GitHub sign-in** | the `haus-workflow` repository is private | `gh auth login`, see below |
22
+ | **Claude Code** | the editor haus configures, and the `claude` CLI | install from <https://claude.com/claude-code>, then reopen your terminal |
23
+ | **Network access** | the first `haus sync` of a release | connect once; later runs of the same release work offline |
24
24
 
25
25
  ## The one that catches everybody: signing in to GitHub
26
26
 
27
- haus installs its skills and agents from a **private** catalog repository. GitHub
28
- answers a signed-out read of a private repository with **404**, not "please sign in" —
29
- so if you are not signed in, the first command reports that a file could not be
30
- fetched, and it looks like the network or the tool is broken. It is neither.
27
+ `haus sync` pulls each project's skills and agents with git from the **private**
28
+ `WeAreHausTech/haus-workflow` repository, using git's own credentials. GitHub answers a
29
+ signed-out read of a private repository with "repository not found", not "please sign
30
+ in", so if git is not signed in the first sync looks like a typo or a broken network. It
31
+ is neither.
31
32
 
32
33
  ```bash
33
- gh auth login # sign in once
34
+ gh auth login # sign in once; answer yes to "Authenticate Git with your GitHub credentials?"
35
+ gh auth setup-git # if you signed in earlier without that answer
34
36
  haus doctor --prereqs # confirm
35
37
  ```
36
38
 
37
- If you use a token instead of the GitHub CLI:
38
-
39
- ```bash
40
- export GITHUB_TOKEN=$(gh auth token) # or: export HAUS_GITHUB_TOKEN=<your token>
41
- ```
42
-
43
- If you are signed in and the catalog still refuses, your account does not have access
44
- to the catalog repository yet — ask a maintainer to add you, rather than signing in
45
- again.
39
+ If you are signed in and the repository still refuses, your account does not have access
40
+ to it yet. Ask a maintainer to add you, rather than signing in again.
46
41
 
47
42
  ## Then what
48
43
 
package/docs/glossary.md CHANGED
@@ -17,21 +17,23 @@ security reviewer. Installed into `.claude/agents/`.
17
17
  `.claude/rules/`. Shorter than a skill and always in effect.
18
18
 
19
19
  **Command** (or slash command) — something you can invoke by name in Claude Code, like
20
- `/docs`. haus installs a few, and the catalog can add more.
20
+ `/docs`. A package can add some.
21
21
 
22
22
  **Hook** — a check that runs automatically at a specific moment: before a command runs,
23
23
  when a session starts. haus installs hooks that block dangerous commands and stop the
24
24
  assistant reading files that hold secrets. You do not invoke a hook; it fires on its own.
25
25
 
26
- **Catalog** — the shared library of skills, agents, and rules that haus installs from.
27
- It lives in a private repository, which is why haus needs you signed in to GitHub.
26
+ **Package**: a named group of skills and agents haus ships, such as
27
+ `software-engineering` for every project or `web-react` for a React app. The packages live
28
+ in haus's own private repository, which is why haus needs you signed in to GitHub.
28
29
 
29
- **Recommendation** — haus's answer to "which of those items does this project need",
30
- based on what it finds in the project. Stored in `.haus-workflow/recommendation.json`,
31
- which is deliberately not committed: it is a local answer, recomputed whenever you ask.
30
+ **`haus.json`**: the one file a project commits to say which haus release and which
31
+ packages it uses. `haus init` writes it from what it finds in the project; the team edits
32
+ it to add or drop a package.
32
33
 
33
- **Lockfile** (`.haus-workflow/haus.lock.json`) — the record of what haus installed and
34
- which version. This one **is** committed, so everyone on the team gets the same set.
34
+ **Sync** (`haus sync`): pulling the packages `haus.json` names into `.claude/`. The
35
+ synced folders are not committed: every clone gets them from its own sync, which runs by
36
+ itself after a checkout or a pull.
35
37
 
36
38
  **ADR** (Architecture Decision Record) — a short note recording a decision and why it
37
39
  was made, kept in `docs/decisions/`. Written once; superseded by a later ADR rather
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@haus-tech/haus-workflow",
3
- "version": "6.8.0",
3
+ "version": "7.0.0",
4
4
  "description": "Haus AI workflow CLI for Claude Code.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -13,10 +13,7 @@
13
13
  "homepage": "https://github.com/WeAreHausTech/haus-workflow",
14
14
  "files": [
15
15
  "dist",
16
- "scripts/postinstall.mjs",
17
- "library/global",
18
16
  "packages",
19
- "library/catalog",
20
17
  "library/schemas",
21
18
  "README.md",
22
19
  "CHANGELOG.md",
@@ -44,10 +41,8 @@
44
41
  "verify": "node scripts/verify.mjs",
45
42
  "verify:full": "node scripts/verify.mjs --coverage",
46
43
  "ci:local": "node scripts/ci-local.mjs --force",
47
- "check:contract-behavior": "node --import tsx scripts/contract-behavior-check.mjs",
48
44
  "check:mutation-table": "node scripts/check-mutation-table.mjs",
49
45
  "check:docs-site": "node scripts/check-docs-site.mjs",
50
- "postinstall": "node ./scripts/postinstall.mjs || true",
51
46
  "prepare": "lefthook install || true",
52
47
  "security:audit": "yarn npm audit -A -R --severity high --environment production"
53
48
  },
@@ -18,11 +18,9 @@ Modes: `finding` | `deferred` | `idea`.
18
18
  Before creating anything:
19
19
 
20
20
  1. Route each item per the skill's Routing section: findings about
21
- haus-shipped content (a skill, agent, rule, template, or the workflow
22
- standard) file against `WeAreHausTech/haus-workflow-catalog`; findings about
23
- the haus CLI itself (a command, a gate, a guard hook, a file the CLI
24
- writes, or a skill or agent it ships itself) file against
25
- `WeAreHausTech/haus-workflow`; everything else files locally. Then confirm
21
+ the haus CLI or the content it ships (a command, a gate, a guard hook, a
22
+ file the CLI writes, a skill or agent `haus sync` wrote, or a template haus ships)
23
+ file against `WeAreHausTech/haus-workflow`; everything else files locally. Then confirm
26
24
  GitHub issues are available on that destination:
27
25
  `gh repo view [<owner>/<repo>] --json nameWithOwner,hasIssuesEnabled`.
28
26
  If this fails for the local repo or reports `hasIssuesEnabled: false`,
@@ -20,15 +20,14 @@ Captures **why** significant choices were made under `docs/decisions/`.
20
20
 
21
21
  Gate carve-outs live in the haus CLI algorithm (not `decisions-triggers.json`). Use this table:
22
22
 
23
- | Change | ADR needed? |
24
- | --------------------------------------------------------------------- | ------------------------------------------ |
25
- | Dependency version bump, no dep added/removed | No |
26
- | New or removed dependency | Yes |
27
- | Lockfile-only regen (no package.json change) | No |
28
- | Catalog sync (`chore/sync-catalog-*` branch, or `library/catalog/**`) | No |
29
- | Schema/migration/CI/infra/API-contract/auth path | Yes (security paths: `[adr-skip]` ignored) |
30
- | 8+ files across 2+ top-level dirs (not a dep bump) | Yes |
31
- | Docs/tests-only | No (already exempt) |
23
+ | Change | ADR needed? |
24
+ | -------------------------------------------------- | ------------------------------------------ |
25
+ | Dependency version bump, no dep added/removed | No |
26
+ | New or removed dependency | Yes |
27
+ | Lockfile-only regen (no package.json change) | No |
28
+ | Schema/migration/CI/infra/API-contract/auth path | Yes (security paths: `[adr-skip]` ignored) |
29
+ | 8+ files across 2+ top-level dirs (not a dep bump) | Yes |
30
+ | Docs/tests-only | No (already exempt) |
32
31
 
33
32
  To waive the trigger rules, put `[adr-skip] <reason>` on its own line in the PR body or in a commit body, not the subject. A mention mid-line or in backticks does not count (CLI 5.11.0 and later). It never waives a misplaced or invalid record.
34
33
 
@@ -50,14 +50,4 @@ description: BullMQ router. Use for queue definitions, workers, schedulers, repe
50
50
 
51
51
  ## Reference Documentation
52
52
 
53
- Up-to-date API docs are cached locally by haus.
54
-
55
- To refresh (uses etag — fast if unchanged):
56
-
57
- ```bash
58
- haus fetch-refs --id haus.bullmq-patterns
59
- ```
60
-
61
- Then read `.haus-workflow/llms-cache/docs-bullmq-io-llms-txt.md` for current API reference.
62
-
63
- Source: https://docs.bullmq.io/llms.txt
53
+ For the current API reference, fetch https://docs.bullmq.io/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
@@ -31,9 +31,9 @@ that branch of the merged task.
31
31
  | `clone [name]` (`project:clone`, `cloneandsetup`, `project:cloneandsetup`) | _Clone procedure below_ | Clone one repo by name, or a whole workspace from `repos.manifest.json`. Afterwards asks "set up for local dev too?" (deps, databases, links, env via `localdev.yml`). `cloneandsetup` aliases pre-answer that question with yes. |
32
32
  | `new [description]` (`create`, `project:new`, `poc`, `kunddemo`) | _New-project procedure below_ | Create a brand-new project from a plain-language request, unchanged seven-phase flow. The `poc`/`kunddemo` aliases (and phrases like "ny poc", "customer demo") run the same flow in PoC mode: a throwaway demo repo under the `poc` profile (`--profile poc`), see `references/new.md` → PoC mode. |
33
33
  | `doctor` (`check`, `fix`, `project:doctor`, `project:fix`) | _Doctor procedure below_ | Health check for the detected scope; relays the verdict, then offers to apply the doctor's own suggested fixes and re-checks until green. `fix` aliases pre-answer "fix now?" with yes. |
34
- | `refresh` (`update`, `upgrade`, `apply`, `regenerate`, `claude-md`, `project:refresh`, `add-skills`, `opt-in`, `project:add-skills`, `install`, `global`) | _Refresh procedure below_ | Bring haus current. Always: update npm package + catalog + `~/.claude` (seeding it first if never installed). Inside a set-up project/workspace, asks: **Full sync** (re-run the whole setup pipeline in place) or **Just add helpers** (offer opt-in skills/agents + configs only). `add-skills`/`opt-in` aliases jump to the helpers branch; outside any project it stops after the global update. |
35
- | `uninstall` | `haus uninstall` | Remove all haus global files from `~/.claude/`. Machine scope only — confirm gate states this does NOT touch the current project (that's `init` → clean slate). |
36
- | `help` (`?`) | _Answer directly_ | Explain what haus-workflow is, list tasks, point to deeper docs — touches no files. |
34
+ | `refresh` (`update`, `upgrade`, `apply`, `regenerate`, `claude-md`, `project:refresh`, `add-skills`, `opt-in`, `project:add-skills`, `install`, `global`) | _Refresh procedure below_ | Bring haus current. Always: `haus update` (npm package and core files; haus seeds nothing in `~/.claude`). Inside a set-up project/workspace, asks: **Full sync** (re-run the whole setup pipeline in place) or **Just add helpers** (offer packages `haus.json` does not list yet). `add-skills`/`opt-in` aliases jump to the helpers branch; outside any project it stops after the global update. |
35
+ | `uninstall` | `haus uninstall` | Remove all haus global files from `~/.claude/`. Machine scope only: the confirm gate states this does NOT touch the current project (that's `init` → clean slate). |
36
+ | `help` (`?`) | _Answer directly_ | Explain what haus-workflow is, list tasks, point to deeper docs. Touches no files. |
37
37
 
38
38
  ## Step 1 — Determine the task
39
39
 
@@ -76,7 +76,7 @@ Before running anything, determine what the current directory is. Check in order
76
76
  a repo) AND a parent directory holds `haus.workspace.yaml`/`repos.manifest.json`.
77
77
  Ambiguous — ask via `AskUserQuestion`: "Run this for this repo only, or the whole
78
78
  workspace?" (options: This repo / Whole workspace). Never guess.
79
- 3. **Project** — the git root has `.haus-workflow/` and `haus.lock.json`.
79
+ 3. **Project**: the git root has `.haus-workflow/` and `haus.json`.
80
80
  4. **Not set up** — none of the above. `init`, `new`, and `clone` proceed in project
81
81
  scope; `doctor` says the project isn't set up yet and suggests `init`; `refresh`
82
82
  runs its global half only.
@@ -108,14 +108,14 @@ After the command completes, follow the relevant post-run steps below.
108
108
 
109
109
  ### Init (`init`)
110
110
 
111
- 0. **State check.** Scope was detected in Step 1.5. If `haus.lock.json` already
111
+ 0. **State check.** Scope was detected in Step 1.5. If `haus.json` already
112
112
  exists (or, workspace scope, `.haus-workflow/workspace.manifest.json` records a
113
113
  prior setup), this project is already set up — ask via `AskUserQuestion`:
114
114
  - **Refresh instead** (recommended) — non-destructive; jump to the Refresh
115
115
  procedure's full-sync branch.
116
116
  - **Clean slate**: explain plainly that it removes the haus-managed files haus owns (backed up
117
117
  first; user content preserved), then re-runs setup from scratch. Say what it keeps:
118
- an item the user edited and its lock row, and a `.claude/rules/haus.md` haus did not
118
+ an item the user edited, and a `.claude/rules/haus.md` haus did not
119
119
  write. `haus undo --force` removes those too, after a backup, except a
120
120
  `.claude/rules/haus.md` that is a link or a folder, which stays either way. In workspace
121
121
  scope it also keeps a linked copy edited at the workspace root and a
@@ -134,10 +134,10 @@ After the command completes, follow the relevant post-run steps below.
134
134
  `haus workspace setup --write`, run the chosen per-member documentation pass,
135
135
  and stop. Do not follow `references/init.md`; it contains project commands.
136
136
  2. **Project scope.** Open and follow `references/init.md` in this skill's directory.
137
- Run every step in order. It detects the stack, runs `haus apply --write`
138
- (scaffolding, skills, commands, rules, docs skill), writes the **project docs**
139
- (`CLAUDE.md` body + `docs/`) and `.haus-workflow/deep-context.json`, runs
140
- `haus recommend`, applies the newly-matched helpers, and confirms. Then fill
137
+ Run every step in order. It detects the stack, picks the packages for
138
+ `haus.json`, runs `haus init` and `haus sync` (core files, then the packages'
139
+ skills and agents, the docs skill among them), writes the **project docs**
140
+ (`CLAUDE.md` body + `docs/`), offers a package the deep read found, and confirms. Then fill
141
141
  `.haus-workflow/workflow-config.md` — replace every placeholder (`TODO`, `n/a`,
142
142
  empty): test/lint/typecheck/build commands (check `package.json`), docs paths,
143
143
  validation library, pre-commit tool, highest-stakes logic (ask if unclear).
@@ -147,43 +147,30 @@ After the command completes, follow the relevant post-run steps below.
147
147
 
148
148
  Bring haus current. Global half always runs; the project half depends on scope.
149
149
 
150
- 1. **Global half.** If `~/.claude` was never seeded by haus (`haus install --check`
151
- reports it missing), run `haus install` first. Then run `haus update`. React to
150
+ 1. **Global half.** Run `haus update` (haus writes nothing to `~/.claude` unless the user
151
+ turned on session labels with `haus install --session-labels`). React to
152
152
  its output: if a new version is available run `npm i -g @haus-tech/haus-workflow`
153
153
  and confirm the bump; if `WORKFLOW.md` changed, remind the user to review
154
- `workflow-config.md` for new sections; if the catalog changed, summarise which
155
- templates changed.
154
+ `workflow-config.md` for new sections. If it names a newer release, offer to move
155
+ `release` in `haus.json` to it and run `haus sync`.
156
156
  2. **No project/workspace detected** (scope step said "not set up") → report the
157
157
  global result and stop.
158
158
  3. **Project or workspace detected** → ask via `AskUserQuestion` (skip the question
159
159
  when an alias pre-answered it):
160
- - **Full sync** — re-run the Init procedure's pipeline in place, end to end
161
- (re-scan, deep docs read, re-recommend, apply; workspace scope:
160
+ - **Full sync**: re-run the Init procedure's pipeline in place, end to end
161
+ (re-scan, deep docs read, package check, `haus sync`; workspace scope:
162
162
  `haus workspace setup --write`, asking the deep-docs question first). Nothing
163
- is removed up front; anything removed upstream is pruned by `apply`'s existing
164
- orphan-pruning.
165
- - **Just add helpers** — no package pipeline re-run, no docs regeneration:
166
- run `haus rescan` — does the same scan + recommend as `haus scan --json` then
167
- `haus recommend`, in one call, and additionally ensures the catalog-pinned
168
- global plugin(s), which a manual scan+recommend pair would skip; read
169
- `.haus-workflow/recommendation.json` and `.haus-workflow/haus.lock.json`
170
- yourself; offer items not already installed — `optInEligible[]` grouped by
171
- `optInGroup` (purpose + tokenEstimate as plain language) and `recommended[]`
172
- config entries with `install: false` whose files aren't present. One
173
- multi-select `AskUserQuestion`, all unchecked. Then one single
174
- `haus recommend --declare-role <role> <role> …` with the common role of each
175
- chosen group that has one, passed as the name after `role=` (every entry's
176
- `requires` names only roles, `role=<name>`, and the same role first; a
177
- declared role also admits the shared helpers listed under other groups),
178
- then one single
179
- `haus recommend --include <id> <id> …` with the ids of the chosen groups that
180
- have none (skip a command with nothing to pass), followed by
181
- `haus apply --write`; configs via `haus configs <id>` (`--force` only if the
182
- user chose to replace an existing file). Nothing eligible → say so and stop.
183
- Reached directly by the `add-skills`/`opt-in` aliases. In workspace scope, ask
184
- which member repo(s) first and run the branch per chosen repo.
185
- 4. Report what changed in plain language — package/catalog bumps, docs refreshed,
186
- helpers added/updated/removed.
163
+ is removed up front: `haus sync` removes only what a package no longer ships.
164
+ - **Just add helpers**: no docs regeneration. Read `haus.json` yourself and offer
165
+ the packages it does not list yet, one `AskUserQuestion` option per package in
166
+ plain language (`client-requests`: the request flow; `communication`: Slack
167
+ canvases; the stack packages by their stack), all unchecked. On confirm run
168
+ `printf 'y\n' | haus init --packages <the whole new list>`, then `haus sync`.
169
+ Nothing to add → say so and stop. Reached directly by the `add-skills`/`opt-in`
170
+ aliases. In workspace scope, ask which member repo(s) first and run the branch
171
+ per chosen repo.
172
+ 4. Report what changed in plain language: haus and release bumps, docs refreshed,
173
+ packages added.
187
174
 
188
175
  ### Doctor (`doctor`)
189
176
 
@@ -224,7 +211,7 @@ Bring haus current. Global half always runs; the project half depends on scope.
224
211
  it must ask the workspace-membership question there before eliciting anything
225
212
  else. Otherwise (Project or Not-set-up scope) open it knowing that question is
226
213
  skipped.
227
- 2. Open and follow `references/new.md` in this skill's directory. It is a seven-phase AI-driven flow: elicit the request and propose features, gate on user intent, scaffold (registry stacks via `haus new --json --yes` with a `--dry-run` preview; any other stack via a user-confirmed official scaffolder plus manual rails), install context via `haus init`, seed `docs/SPEC.md` + `docs/plans/walking-skeleton.md`, build the walking skeleton with one subagent per feature (against a structure recorded in `docs/DESIGN.md`), verify (build + lint + tests + smoke boot), then write the project docs by following `references/init.md` from step 3 (deep read, `CLAUDE.md` body + `docs/`, recommend re-check, opt-ins). Repos are only ever created private. Failure `detail` is relayed verbatim and nothing is ever auto-deleted. Never run bare interactive `haus new`. The same reference carries a **PoC mode** (entered by the `poc`/`kunddemo` aliases, or by the "Production project or throwaway PoC?" question when no phrase was given): the repo gets the `poc` profile before the first design question (`haus new --profile poc` on the fast path; a hand-written `haus.config.json` plus `haus init --json --dry-run --profile poc` and `haus apply --write` on the manual path), the first brainstorm writes `docs/MANUS.md` instead of `docs/SPEC.md`, the only check is the Playwright manus, and Phase 6 skips the docs pass.
214
+ 2. Open and follow `references/new.md` in this skill's directory. It is a seven-phase AI-driven flow: elicit the request and propose features, gate on user intent, scaffold (registry stacks via `haus new --json --yes` with a `--dry-run` preview; any other stack via a user-confirmed official scaffolder plus manual rails), install context via `haus init`, seed `docs/SPEC.md` + `docs/plans/walking-skeleton.md`, build the walking skeleton with one subagent per feature (against a structure recorded in `docs/DESIGN.md`), verify (build + lint + tests + smoke boot), then write the project docs by following `references/init.md` from step 3 (deep read, `CLAUDE.md` body + `docs/`, package check). Repos are only ever created private. Failure `detail` is relayed verbatim and nothing is ever auto-deleted. Never run bare interactive `haus new`. The same reference carries a **PoC mode** (entered by the `poc`/`kunddemo` aliases, or by the "Production project or throwaway PoC?" question when no phrase was given): the repo gets the `poc` profile before the first design question (`haus new --profile poc` on the fast path; a hand-written `haus.config.json` plus `haus init --json --dry-run --profile poc` and `haus apply --write` on the manual path), the first brainstorm writes `docs/MANUS.md` instead of `docs/SPEC.md`, the only check is the Playwright manus, and Phase 6 skips the docs pass.
228
215
 
229
216
  ### After `haus uninstall`
230
217
 
@@ -6,83 +6,52 @@ commands; they read plain language and approve.
6
6
 
7
7
  Do this in order:
8
8
 
9
- 1. **Detect.** Run `haus init --json --dry-run`. Read the JSON yourself —
9
+ 1. **Detect.** Run `haus init --json --dry-run`. Read the JSON yourself:
10
10
  do not show it. Stdout is one envelope:
11
- `{ scan, recommendation, hooks, repoName, warnings, items, records }`. `items` and
12
- `records` are `null` here: a dry run never reaches the apply step.
11
+ `{ scan, hooks, repoName, warnings, items, records }`. `items` and
12
+ `records` are `null` here: a dry run never reaches the apply step. Stderr names the
13
+ `haus.json` it would write (`[dry-run] would write haus.json (release ..., packages ...)`).
13
14
  Translate `scan` into one or two plain sentences, e.g. "This looks like a Next.js
14
15
  website using Yarn. I found unit tests but no end-to-end tests." If
15
16
  `scan.detectionStatus` is `unknown` or `partial`, say so honestly ("I couldn't fully
16
17
  recognise this stack, so I'll apply the general workflow and security guidance").
17
18
 
18
- 2. **Apply the basics.** Run `haus apply --write`. Read the result. This installs
19
- the core guardrails and helpers — including the documentation skill haus uses
20
- in the next step.
21
-
22
- 3. **Write the project docs.** Open and follow the instructions in
23
- `.claude/skills/writing-documentation/SKILL.md`, which step 2 just installed.
24
- Following it, do a deep read of the project and:
25
- - write the project documentation (the `CLAUDE.md` body and `docs/` files).
26
- NEVER alter the `<!-- HAUS:BEGIN haus-imports … -->` … `<!-- HAUS:END … -->`
27
- block in `CLAUDE.md`; write around it.
28
- - write `.haus-workflow/deep-context.json` describing what the deep read found
29
- (roles, stacks, patterns the quick scan in step 1 could not see).
30
- If this step can't be completed for any reason, say so plainly and skip to
31
- step 6 — setup still finishes correctly with the basics from step 2.
32
-
33
- 4. **Re-check recommendations with the new understanding.** Run `haus recommend`.
34
- It re-reads `deep-context.json` and may surface extra helpers matching what the
35
- deep read discovered. You MUST run this before the next apply — `haus apply`
36
- does not re-calculate recommendations on its own.
37
-
38
- 5. **Offer optional helpers.** Read `.haus-workflow/recommendation.json` yourself
39
- (never show the JSON). Two kinds of optional extras may be listed; offer only
40
- the ones present, all **unchecked** by default — these are opt-in:
41
- - **Optional skills & agents** (`optInEligible[]`): workflow/ops/review/design
42
- helpers that don't auto-install for this stack. Group them by their
43
- `optInGroup` label and present one `AskUserQuestion` option per group
44
- (use each item's `purpose` and `tokenEstimate` to describe it in plain
45
- language, e.g. "Code review workflow — request/receive structured reviews").
46
- Opt the user in by role wherever a group has one. A chosen group has a
47
- common role when every entry's `requires` names only roles (`role=<name>`,
48
- several joined by `|` when a helper serves more than one group) and all
49
- its entries name the same role first. Collect each common role as the name
50
- after `role=` (`interview-workflow`, not `role=interview-workflow`) and run a
51
- **single** `haus recommend --declare-role <role> <role> …` with all of them:
52
- haus records them in `.haus-workflow/haus.config.json`, and a declared role
53
- also admits the shared helpers listed under other groups, which the group's
54
- own ids would miss. Then, only for chosen groups with no common role (a
55
- `requires` that names a stack or a dependency, or entries whose first roles
56
- differ), run a **single** `haus recommend --include <id> <id> …` with all of
57
- their ids. Skip a command that has nothing to pass, and never run either
58
- once per group: each run re-scores the whole catalog.
59
- - **Project config** (entries in `recommended[]` with `install: false`, e.g.
60
- Haus ESLint / Prettier baselines): offer each as a plain choice ("Add the
61
- Haus ESLint baseline"). On confirm, run `haus configs <id>`. `haus configs`
62
- **preserves existing config files by default**: it refuses a config file
63
- that differs (`refused (not owned)`). Only re-run with
64
- `haus configs <id> --force` if the user explicitly chooses to **replace**
65
- their current config; it backs the file up before replacing it.
66
-
67
- If neither list has anything, skip this step silently — don't ask an empty
68
- question.
69
-
70
- 6. **Apply the rest.** Run `haus apply --write` again. It only writes what changed,
71
- so this adds the newly-matched helpers from step 4 plus any opt-ins from step 5.
72
- Then verify the root `CLAUDE.md` imports all three haus files — add any missing:
73
-
74
- ```
75
- @.haus-workflow/WORKFLOW.md
76
- @.haus-workflow/workflow-config.md
77
- @docs/decisions/README.md
78
- ```
19
+ 2. **Pick the packages.** `haus.json` lists the packages this project gets:
20
+ `software-engineering` always, plus one per stack the scan found (`web-react`,
21
+ `commerce-vendure`, `wordpress`, `laravel`, `dotnet`, `strapi`, `nx`). Name the
22
+ suggested ones in plain language. `client-requests` (the request flow) and
23
+ `communication` (Slack canvases) are never suggested: offer them in one
24
+ `AskUserQuestion`, unchecked. An existing `haus.json` keeps its list unless the user
25
+ changes it.
26
+
27
+ 3. **Apply the basics.** Run `printf 'y\n' | haus init`, adding
28
+ `--packages <a>,<b>` when step 2 changed the list. It writes `haus.json` and the core
29
+ guardrails. Then run `haus sync`: it installs the packages `haus.json` names into
30
+ `.claude/`, including the documentation skill haus uses in the next step.
31
+
32
+ 4. **Write the project docs.** Open and follow the instructions in
33
+ `.claude/skills/writing-documentation/SKILL.md`, which step 3 just installed.
34
+ Following it, do a deep read of the project and write the project documentation
35
+ (the `CLAUDE.md` body and `docs/` files).
36
+ NEVER alter the `<!-- HAUS:BEGIN haus-imports … -->` … `<!-- HAUS:END … -->`
37
+ block in `CLAUDE.md`; write around it.
38
+ If this step can't be completed for any reason, say so plainly and skip to
39
+ step 6: setup still finishes correctly with the basics from step 3.
40
+
41
+ 5. **Check the packages against the deep read.** If the deep read found a stack the
42
+ quick scan missed (for example Vendure behind a monorepo folder), offer its package.
43
+ On confirm, run `printf 'y\n' | haus init --packages <the whole list>`, then
44
+ `haus sync`. Nothing new → skip this step silently.
45
+
46
+ 6. **Check the imports.** Verify the root `CLAUDE.md` imports `@AGENTS.md` inside its
47
+ haus block, and that `AGENTS.md` holds the haus block with
48
+ `@.haus-workflow/WORKFLOW.md`, `@.haus-workflow/workflow-config.md` and
49
+ `@docs/decisions/README.md`. If not, run `haus apply --write`, never a hand edit.
79
50
 
80
51
  7. **Confirm.** End with one plain-language line, for example:
81
- "✅ Your project is configured — I wrote your project docs, added N guardrails
82
- and M coding helpers (K matched after reading your code in depth), plus the J
83
- optional helpers you chose: <name them>. Run `/haus-workflow doctor` any time to
84
- re-check." Fill the numbers from the apply output, and name the opt-ins the
85
- user picked in step 5 (omit that clause if they chose none).
52
+ "✅ Your project is configured: I wrote your project docs and installed the
53
+ <packages> packages. Run `/haus-workflow doctor` any time to re-check." Name the
54
+ packages from `haus.json`.
86
55
 
87
56
  If anything fails, explain what happened in plain language and what you'll try
88
57
  next — don't dump raw errors.
@@ -186,21 +186,18 @@ add tests.
186
186
  Everything from here on runs inside the new project directory — `cd` into it first and
187
187
  stay there.
188
188
 
189
- - Fast path: the chained `haus init` inside `haus new` already ran — go to seeding.
190
- (That chained init is the CLI pipeline only: it installs skills and guardrails but
189
+ - Fast path: the chained `haus init` inside `haus new` already ran. Run `haus sync` so the
190
+ packages `haus.json` names land in `.claude/`, then go to seeding.
191
+ (That chained init is the CLI pipeline only: it writes `haus.json` and the guardrails but
191
192
  does not write project docs — those are written in Phase 6, where the deep read
192
193
  sees the real code instead of an empty scaffold.)
193
194
  - Manual path:
194
195
  - Read: run `haus init --json --dry-run` and read the envelope yourself.
195
- - If it refuses with the zero-signal message — literally zero catalog items matched,
196
- not merely an unknown stack (catalog defaults normally still match, so most tier-3
197
- projects write fine without `--force`) — tell the user plainly: "no stack-specific
198
- assets in the catalog; installing workflow defaults." Confirm with the user, then
199
- re-run `haus init --json --dry-run --force`.
200
- - Write: run `haus apply --write`.
201
- - Guard: NEVER run write-mode `haus init` (i.e. `haus init` without `--json
202
- --dry-run`) — it prompts for confirmation, and an agent's non-answer means nothing
203
- is written despite exit 0.
196
+ - If `scan.detectionStatus` is `unknown`, tell the user plainly: "no stack-specific
197
+ packages for this stack; installing the workflow defaults."
198
+ - Write: run `printf 'y\n' | haus init`, then `haus sync`. `haus init` asks before it
199
+ writes, and an agent's non-answer means nothing is written despite exit 0, so the
200
+ answer is piped in.
204
201
  - Seeding: write the elicited requirements into the project as `docs/SPEC.md`
205
202
  (purpose, features, auth/data choices, what is mocked) and
206
203
  `docs/plans/walking-skeleton.md` (one task per selected feature with acceptance
@@ -212,16 +209,15 @@ stay there.
212
209
 
213
210
  1. Write `.haus-workflow/haus.config.json` with exactly `{ "profile": "poc" }` (create the
214
211
  directory).
215
- 2. Read: `haus init --json --dry-run --profile poc`; on the zero-signal refusal, confirm
216
- and re-run with `--force` as above.
212
+ 2. Read: `haus init --json --dry-run --profile poc`.
217
213
  3. Add a `"manus"` key to package.json scripts now, before the write step, even as a
218
- placeholder (`"manus": "playwright test"`). `haus apply --write` derives the PoC's
214
+ placeholder (`"manus": "playwright test"`). The write derives the PoC's
219
215
  only gate command in `.haus-workflow/workflow-config.md` from whether that key
220
216
  exists, not from its final body, and with no key at all it falls back to a Playwright
221
217
  invocation that resolves against whatever default config the scaffold shipped and
222
218
  finds no tests at all. The skeleton below fills in the real body once the runner
223
219
  config is decided; what matters here is that the key exists first.
224
- 4. Write: `haus apply --write`. It reads the profile: `.haus-workflow/WORKFLOW.md` now
220
+ 4. Write: `printf 'y\n' | haus init --profile poc`, then `haus sync`. It reads the profile: `.haus-workflow/WORKFLOW.md` now
225
221
  starts with `# PoC Workflow Standard`, and there is no haus gate (`lefthook.yml`).
226
222
 
227
223
  Fast path: the chained init already ran `haus apply --write` inside Phase 3, before this
@@ -329,12 +325,11 @@ why.
329
325
  and the layout matches the structure conventions recorded in `docs/DESIGN.md`.
330
326
  Record the results in `docs/plans/walking-skeleton.md`'s verification blocks.
331
327
  2. Write the project docs: follow `references/init.md` from step 3 to the end —
332
- deep read, `CLAUDE.md` body + `docs/` files, `.haus-workflow/deep-context.json`,
333
- the `haus recommend` re-check, the opt-in helpers offer, and the final
334
- `haus apply --write`. This runs HERE, after the build, on purpose: the chained
328
+ deep read, `CLAUDE.md` body + `docs/` files, the package check and the import
329
+ check. This runs HERE, after the build, on purpose: the chained
335
330
  CLI init installs the writing-documentation skill but never executes it, and a
336
331
  deep read now sees the real features instead of an empty scaffold — so the docs
337
- describe reality and `haus recommend` can match what was actually built.
332
+ describe reality and the package check sees what was actually built.
338
333
  (init.md steps 1–2 are already covered by Phase 4; do not redo them.)
339
334
  Commit the docs output as its own conventional commit.
340
335
  3. Push to the remote (if a repo was created).
@@ -357,7 +352,7 @@ still flags here is real: read it and act on it, or, for a machine-level finding
357
352
  a disabled global plugin, check it with the tool that owns it (`claude plugin list`)
358
353
  before telling the user doctor is wrong. Then push if a remote exists (never for
359
354
  local-only). Then stop: do NOT follow `references/init.md`
360
- from step 3, because a PoC has no docs pass, no deep read and no recommend re-check. Hand off in
355
+ from step 3, because a PoC has no docs pass, no deep read and no package check. Hand off in
361
356
  the user's language, naming the demo date, the two re-entry phrases and the decision the
362
357
  meeting ends with: next session, open this repo and say "where are we" / "var är vi",
363
358
  or "extend the demo with ..."; after the demo, decide
@@ -49,14 +49,4 @@ description: i18next router. Use for translation namespace structure, key conven
49
49
 
50
50
  ## Reference Documentation
51
51
 
52
- Up-to-date API docs are cached locally by haus.
53
-
54
- To refresh (uses etag — fast if unchanged):
55
-
56
- ```bash
57
- haus fetch-refs --id haus.i18next-patterns
58
- ```
59
-
60
- Then read `.haus-workflow/llms-cache/www-i18next-com-llms-txt.md` for current API reference.
61
-
62
- Source: https://www.i18next.com/llms.txt
52
+ For the current API reference, fetch https://www.i18next.com/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
@@ -31,39 +31,32 @@ dedupe, and create all run against it.
31
31
 
32
32
  - **Project-local** (default): the finding concerns this repository's own
33
33
  code, config, or process. File into the current repo, unchanged.
34
- - **Catalog-content**: the finding concerns content haus shipped — a skill,
35
- agent, rule, template, or the workflow standard itself (files haus
36
- installed under `.claude/skills/`, `.claude/agents/`, `.claude/templates/`,
37
- the catalog rule folders under `.claude/rules/`, or
38
- `.haus-workflow/WORKFLOW.md`). A local issue about shipped content is
39
- invisible upstream and the defect ships to every other consumer, so file it
40
- where it is fixed once for everyone:
41
- `gh issue create -R WeAreHausTech/haus-workflow-catalog …`. Already in that
42
- repo, routing is a no-op — file locally.
43
- - **Haus CLI**: the finding concerns the haus program rather than catalog
44
- content it installs: a command's behaviour, output or exit code, a wrong or
34
+ - **Haus-shipped**: the finding concerns the haus program or content it
35
+ ships. That is a command's behaviour, output or exit code, a wrong or
45
36
  missing finding from doctor, the decision gate or the CI gate, a guard hook,
46
37
  a file the CLI writes and owns (`.claude/settings.json`,
47
- `.claude/rules/haus.md`, the managed blocks in `CLAUDE.md`,
48
- `.haus-workflow/haus.lock.json`), or a skill or agent the CLI ships itself
49
- (in `~/.claude/skills/` or `~/.claude/agents/` by default, with
50
- `source=@haus-tech/haus-workflow@<version>` in its `haus_managed`
51
- frontmatter). File it where the CLI is fixed:
38
+ `.claude/rules/haus.md`, the managed blocks in `CLAUDE.md` and `AGENTS.md`,
39
+ `.haus-workflow/WORKFLOW.md`, `.haus-workflow/synced.json`), a skill or
40
+ agent `haus sync` wrote from a package (the folders
41
+ `.haus-workflow/synced.json` lists under `.claude/`), or a template or config
42
+ haus ships under `packages/`. A local issue about
43
+ shipped content is invisible upstream and the defect ships to every other
44
+ consumer, so file it where it is fixed once for everyone:
52
45
  `gh issue create -R WeAreHausTech/haus-workflow …`. Already in that repo,
53
- routing is a no-op: file locally. When it is unclear whether the CLI or the
54
- catalog owns a finding, route it to the catalog.
46
+ routing is a no-op: file locally. A skill or agent haus pulls from a pinned
47
+ upstream (superpowers and the other upstream entries of `packages.yaml`) goes
48
+ there too: haus owns the pin and the selection.
55
49
 
56
- Catalog- and CLI-routed issues cross a repo boundary. NEVER include client code,
50
+ Upstream-routed issues cross a repo boundary. NEVER include client code,
57
51
  secrets, internal URLs, or client-identifying paths: name the shipped item and
58
- its path as shipped in the catalog (for a Haus CLI finding, the command, skill
59
- or agent and the haus version), describe the defect against the shipped
60
- content, and call the discovering project only "a consumer repo".
52
+ its path as shipped in `packages/` (for a CLI finding, the command and the
53
+ haus version), describe the defect against the shipped content, and call the
54
+ discovering project only "a consumer repo".
61
55
 
62
56
  If upstream filing is unavailable (no access, unauthenticated, issues
63
57
  disabled), do not drop the finding: file it project-local with one extra
64
- header line, and say so in your report —
65
- `> **Routing:** catalog-content — upstream filing failed (<reason>); re-file to WeAreHausTech/haus-workflow-catalog`
66
- For a Haus CLI finding the line reads `> **Routing:** haus-cli, upstream filing failed (<reason>); re-file to WeAreHausTech/haus-workflow`.
58
+ header line, and say so in your report:
59
+ `> **Routing:** haus-shipped, upstream filing failed (<reason>); re-file to WeAreHausTech/haus-workflow`
67
60
 
68
61
  A retro candidate is a finding like any other: route it by what it is about.
69
62
  File one issue per candidate the human picks, and none for the rest.