@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.
- package/CHANGELOG.md +21 -0
- package/README.md +41 -85
- package/dist/cli.js +25445 -34158
- package/docs/before-you-start.md +17 -22
- package/docs/glossary.md +10 -8
- package/package.json +1 -6
- package/packages/agents/issue-creator.md +3 -5
- package/packages/skills/adr-decisions/SKILL.md +8 -9
- package/packages/skills/bullmq-patterns/SKILL.md +1 -11
- package/packages/skills/haus-workflow/SKILL.md +28 -41
- package/packages/skills/haus-workflow/references/init.md +38 -69
- package/packages/skills/haus-workflow/references/new.md +15 -20
- package/packages/skills/i18next-patterns/SKILL.md +1 -11
- package/packages/skills/issue-authoring/SKILL.md +18 -25
- package/packages/skills/laravel-nova-patterns/SKILL.md +1 -11
- package/packages/skills/strapi-patterns/SKILL.md +1 -11
- package/packages/skills/vendure-app-patterns/SKILL.md +1 -11
- package/packages/skills/vendure-plugin-patterns/SKILL.md +1 -11
- package/packages/skills/whats-installed/SKILL.md +10 -8
- package/packages/skills/writing-documentation/SKILL.md +2 -10
- package/packages/templates/agentic-workflow-standard.md +15 -5
- package/packages/templates/decisions-ci-gate.yml +1 -1
- package/packages/templates/lefthook-lighthouse.yml +2 -2
- package/library/catalog/decisions-triggers.json +0 -26
- package/library/catalog/haus-lock.schema.json +0 -4
- package/library/catalog/manifest.json +0 -5941
- package/library/catalog/validation-rules.json +0 -169
- package/library/global/settings-fragments/hooks.json +0 -53
- package/scripts/postinstall.mjs +0 -62
package/docs/before-you-start.md
CHANGED
|
@@ -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
|
|
17
|
-
| --------------------- |
|
|
18
|
-
| **Node 22 or newer** | running haus itself
|
|
19
|
-
| **git** | reading the project,
|
|
20
|
-
| **GitHub CLI (`gh`)** | signing in to the
|
|
21
|
-
| **A GitHub sign-in** | the
|
|
22
|
-
| **Claude Code** | the editor haus configures, and the `claude` CLI
|
|
23
|
-
| **Network access** |
|
|
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
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
|
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`.
|
|
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
|
-
**
|
|
27
|
-
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
**
|
|
34
|
-
|
|
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": "
|
|
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
|
|
22
|
-
|
|
23
|
-
|
|
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
|
|
24
|
-
|
|
|
25
|
-
| Dependency version bump, no dep added/removed
|
|
26
|
-
| New or removed dependency
|
|
27
|
-
| Lockfile-only regen (no package.json change)
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
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
|
-
|
|
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
|
|
35
|
-
| `uninstall` | `haus uninstall` | Remove all haus global files from `~/.claude/`. Machine scope only
|
|
36
|
-
| `help` (`?`) | _Answer directly_ | Explain what haus-workflow is, list tasks, point to deeper docs
|
|
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
|
|
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.
|
|
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
|
|
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,
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
`
|
|
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.**
|
|
151
|
-
|
|
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
|
|
155
|
-
|
|
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
|
|
161
|
-
(re-scan, deep docs read,
|
|
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
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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/`,
|
|
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,
|
|
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. **
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
|
82
|
-
|
|
83
|
-
|
|
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
|
|
190
|
-
|
|
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
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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
|
|
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"`).
|
|
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
|
|
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,
|
|
333
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
- **
|
|
35
|
-
|
|
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.
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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.
|
|
54
|
-
|
|
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
|
-
|
|
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
|
|
59
|
-
|
|
60
|
-
|
|
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:**
|
|
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.
|