@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
|
@@ -42,14 +42,4 @@ description: Laravel Nova router. Use for admin resources, actions, fields, filt
|
|
|
42
42
|
|
|
43
43
|
## Reference Documentation
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
To refresh (uses etag — fast if unchanged):
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
haus fetch-refs --id haus.laravel-nova-patterns
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
Then read `.haus-workflow/llms-cache/nova-laravel-com-docs-llms-txt.md` for current API reference.
|
|
54
|
-
|
|
55
|
-
Source: https://nova.laravel.com/docs/llms.txt
|
|
45
|
+
For the current API reference, fetch https://nova.laravel.com/docs/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
|
|
@@ -50,14 +50,4 @@ description: Strapi v5 router. Use for content type schemas, controllers, servic
|
|
|
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.strapi-patterns
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
Then read `.haus-workflow/llms-cache/docs-strapi-io-llms-txt.md` for current API reference.
|
|
62
|
-
|
|
63
|
-
Source: https://docs.strapi.io/llms.txt
|
|
53
|
+
For the current API reference, fetch https://docs.strapi.io/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
|
|
@@ -31,14 +31,4 @@ description: Vendure app router. Use for app-level config, workers, jobs, and AP
|
|
|
31
31
|
|
|
32
32
|
## Reference Documentation
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
To refresh (uses etag — fast if unchanged):
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
|
-
haus fetch-refs --id haus.vendure-app-patterns
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
Then read `.haus-workflow/llms-cache/docs-vendure-io-llms-txt.md` for current API reference.
|
|
43
|
-
|
|
44
|
-
Source: https://docs.vendure.io/llms.txt
|
|
34
|
+
For the current API reference, fetch https://docs.vendure.io/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
|
|
@@ -42,14 +42,4 @@ description: Vendure 3 plugin router. Use for plugin modules, resolvers, service
|
|
|
42
42
|
|
|
43
43
|
## Reference Documentation
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
To refresh (uses etag — fast if unchanged):
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
haus fetch-refs --id haus.vendure-plugin-patterns
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
Then read `.haus-workflow/llms-cache/docs-vendure-io-llms-txt.md` for current API reference.
|
|
54
|
-
|
|
55
|
-
Source: https://docs.vendure.io/llms.txt
|
|
45
|
+
For the current API reference, fetch https://docs.vendure.io/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
|
|
@@ -14,12 +14,14 @@ file tree, or what a "skill" is.
|
|
|
14
14
|
|
|
15
15
|
Read, in this order:
|
|
16
16
|
|
|
17
|
-
1.
|
|
18
|
-
|
|
19
|
-
2.
|
|
17
|
+
1. `haus.json` at the project root: the haus release and the packages this
|
|
18
|
+
project gets (`software-engineering`, a stack package such as `web-react`).
|
|
19
|
+
2. `.haus-workflow/synced.json`: what `haus sync` installed from those packages,
|
|
20
|
+
one entry per skill or agent folder with its path. Prefer this for the list.
|
|
21
|
+
3. If it is missing, list what is on disk instead:
|
|
20
22
|
`.claude/skills/`, `.claude/agents/`, `.claude/commands/`,
|
|
21
23
|
`.claude/rules/`, `.claude/templates/`.
|
|
22
|
-
|
|
24
|
+
4. `.claude/templates/start-here.md`: a plain-language onboarding page. If
|
|
23
25
|
it exists and the reader is non-technical, mention it as the standing
|
|
24
26
|
reference they can come back to without you.
|
|
25
27
|
|
|
@@ -37,16 +39,16 @@ Read, in this order:
|
|
|
37
39
|
- **Match depth to the reader.** A developer can get ids, versions, and
|
|
38
40
|
paths on request; a non-technical reader gets the menu and example
|
|
39
41
|
requests only.
|
|
40
|
-
- **Never dump raw JSON**, the
|
|
41
|
-
conversation
|
|
42
|
+
- **Never dump raw JSON**, the record files, or directory listings into the
|
|
43
|
+
conversation: that is the inventory, not the answer.
|
|
42
44
|
- **End with two or three example requests** tailored to this specific
|
|
43
45
|
project, so the reader can copy one and go.
|
|
44
46
|
|
|
45
47
|
## Do not
|
|
46
48
|
|
|
47
49
|
- Do not install, remove, or update anything — this skill is read-only.
|
|
48
|
-
Changing what is installed is the haus CLI's job (`haus
|
|
49
|
-
`haus
|
|
50
|
+
Changing what is installed is the haus CLI's job (`haus.json`, then
|
|
51
|
+
`haus sync`), run by a developer.
|
|
50
52
|
- Do not list items that are not actually present in this project.
|
|
51
53
|
- Do not recite `.haus-workflow/WORKFLOW.md` at a non-technical reader.
|
|
52
54
|
If they ask about the team's working rules, summarize only the part they
|
|
@@ -24,19 +24,11 @@ Produces **agent-operable** docs: `CLAUDE.md` and `docs/SUMMARY.md` as primary e
|
|
|
24
24
|
|
|
25
25
|
## Integration with haus
|
|
26
26
|
|
|
27
|
-
This skill ships
|
|
27
|
+
This skill ships in haus's `software-engineering` package. When run inside a haus-managed repo:
|
|
28
28
|
|
|
29
29
|
- **Seed from the scanner, don't re-derive.** If `.haus-workflow/context-map.json` exists, read it for roles, stacks, dependencies, and package manager and treat those as given. Spend effort on the deep inventory the shallow scanner cannot produce (wired modules, env→consumer mapping, runtime topology, deploy pipeline).
|
|
30
30
|
- **Preserve the haus import block.** Never alter or drop the `<!-- HAUS:BEGIN haus-imports v=1 -->` … `<!-- HAUS:END haus-imports -->` block in `CLAUDE.md`; write your body around it.
|
|
31
|
-
- **
|
|
32
|
-
|
|
33
|
-
```json
|
|
34
|
-
{ "source": "writing-documentation", "roles": [], "stacks": {}, "patterns": [] }
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
**Never add fields beyond this shape** — in particular, never include the repo's absolute path, the user's home directory, or any other machine-specific string (e.g. as a `root`/`scanRoot`/`cwd` field, or embedded inside a `patterns` entry). This file is machine-local and gitignored, but if it ever leaks into git anyway it must never carry another developer's local filesystem path. `source` identifies the writer; `roles`/`stacks`/`patterns` are the signal the recommender actually consumes — no fifth field, and no machine-specific value inside any of these four.
|
|
38
|
-
|
|
39
|
-
Then hint the user: run `haus recommend && haus apply` to pick up newly-discovered skills.
|
|
31
|
+
- **Name a package the scan missed.** If the deep read finds a stack the shallow scan did not (for example Vendure in a nested folder) and `haus.json` does not list its package, tell the user which package fits; they add it with `haus init --packages <list>`, then `haus sync`.
|
|
40
32
|
|
|
41
33
|
- **App mode only under haus.** haus drives single-repo (app mode). Workspace mode is for manual multi-repo use; haus does not orchestrate it.
|
|
42
34
|
|
|
@@ -34,7 +34,7 @@ The loop is explore, plan, code, commit. The superpowers plugin carries the how
|
|
|
34
34
|
3. **Plan.** Discrete tasks, each with testable acceptance criteria, exact verification commands, dependencies on other tasks and a source-doc reference. Save to `docs/plans/<slug>.md`. Stop and wait for explicit user OK before executing. A user-level `CLAUDE.md` that delegates this gate replaces the stop with a recorded assumption in the plan.
|
|
35
35
|
4. **Isolate.** Never edit on `main`: a feature branch or a worktree under `.claude/worktrees/<slug>` (gitignored).
|
|
36
36
|
5. **Code.** Sequential unless tasks are independent (no shared state, no ordering), then parallel subagents, each in its own worktree. Every task gets a pass/fail signal (test, build, lint, screenshot vs mockup): implement, run the check, read the result, fix, repeat. When a bug surfaces, diagnose the root cause before writing any fix.
|
|
37
|
-
6. **Commit.** Adversarial code review in fresh context before merging, then check what the target branch deploys (`.haus-workflow/deploy.json`). A merge into a production or customer-visible branch is a production deploy: it needs a recorded local run and the human's explicit go. Once the human has said go, send the merge right after `gh pr create` as one background command, `gh pr checks <n> --watch --interval 20 && gh pr merge <n> --squash --delete-branch --match-head-commit <sha>` with the head you verified: the guard's approval prompt then shows while the human is still there, not minutes later. `&&` keeps a red check from merging, and the head match keeps a later push from landing unapproved. If the watch stops on "no checks reported", send it again. Otherwise present merge / PR / cleanup options, unless the user's own `~/.claude/CLAUDE.md` grants a standing authorization. Docs ship with the change: if setup, commands, env, deploy or integrations changed, run the writing-documentation skill (`/docs`) in the same PR, or state that docs are N/A. After a major milestone, capture lessons as issues via the out-of-scope rule (`/retro`, where installed, proposes them; file only the ones the human picks); lessons about haus-shipped content go upstream as `needs-triage` issues through the issue-authoring skill's routing rule (
|
|
37
|
+
6. **Commit.** Adversarial code review in fresh context before merging, then check what the target branch deploys (`.haus-workflow/deploy.json`). A merge into a production or customer-visible branch is a production deploy: it needs a recorded local run (on a full-suite branch, the green full-suite status instead) and the human's explicit go. Once the human has said go, send the merge right after `gh pr create` as one background command, `gh pr checks <n> --watch --interval 20 && gh pr merge <n> --squash --delete-branch --match-head-commit <sha>` with the head you verified: the guard's approval prompt then shows while the human is still there, not minutes later. `&&` keeps a red check from merging, and the head match keeps a later push from landing unapproved. If the watch stops on "no checks reported", send it again. Otherwise present merge / PR / cleanup options, unless the user's own `~/.claude/CLAUDE.md` grants a standing authorization. Docs ship with the change: if setup, commands, env, deploy or integrations changed, run the writing-documentation skill (`/docs`) in the same PR, or state that docs are N/A. After a major milestone, capture lessons as issues via the out-of-scope rule (`/retro`, where installed, proposes them; file only the ones the human picks); lessons about haus-shipped content go upstream as `needs-triage` issues through the issue-authoring skill's routing rule (the haus program and every skill, agent, rule and template it ships to `WeAreHausTech/haus-workflow`), project-local lessons stay in this repo's issues.
|
|
38
38
|
|
|
39
39
|
**Skills that survey or interview** (an architecture review, a retro, a grilling) only propose: what the human picks enters this loop at Align intent. Start one on a branch (a worktree only from a clean, committed state) if it may edit docs. After a compaction or resume, load the skill you were running again before you continue.
|
|
40
40
|
|
|
@@ -55,10 +55,18 @@ Apply even in unattended mode. `.claude/settings.json` already denies force push
|
|
|
55
55
|
|
|
56
56
|
## Git
|
|
57
57
|
|
|
58
|
-
- Squash-merge: `gh pr merge <n> --squash --delete-branch`. Never plain `--merge
|
|
58
|
+
- Squash-merge: `gh pr merge <n> --squash --delete-branch`. Never plain `--merge`, except the release PR below.
|
|
59
59
|
- Conventional Commits: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`, `ci`, `perf`. Scope by domain: `feat(auth):`.
|
|
60
60
|
- Closing keywords in a PR body: one keyword per issue, one per line (`Closes #1`, then `Closes #2` on its own line). `Closes #1, #2` closes only #1. They work only when the PR targets the default branch, and another repo's issue needs `owner/repo#123`. Close only what the PR actually finishes.
|
|
61
61
|
|
|
62
|
+
**Customer projects ship through release branches** (Haus's own repos keep `main` plus tags unless they opt in):
|
|
63
|
+
|
|
64
|
+
1. Branches are `main`, `release/YYYY-MM-DD` (the test environment, no merge gate), `ticket/<id>-<slug>` and `hotfix/<slug>`. `haus release init` writes the rows into `deploy.json` (the human confirms), `haus release start` cuts the release branch.
|
|
65
|
+
2. A ticket reaches the release branch with `haus release merge`, which opens the PR and squash-merges it in one step.
|
|
66
|
+
3. `haus release ship` opens the release PR into `main`, the one exception to squash: `gh pr merge <n> --merge --match-head-commit <sha>`. It needs a green full-suite status and the human's go.
|
|
67
|
+
4. A merge into `main` deploys nothing. Then `haus release tag`, and production is `haus release deploy <tag>`, run only with the human's go.
|
|
68
|
+
5. A hotfix goes `hotfix/<slug>` from `main`, `haus release suite` for its green status, PR into `main` (squash) with the human's go, `haus release tag`, `haus release deploy`, then `main` is merged into the open release branch.
|
|
69
|
+
|
|
62
70
|
---
|
|
63
71
|
|
|
64
72
|
## Testing rules (non-negotiable)
|
|
@@ -74,6 +82,8 @@ No task is done until tests pass locally and the changed flow has been run in th
|
|
|
74
82
|
|
|
75
83
|
**Verification gate:** run the suite for every touched layer and record the passing output in the task's verification block. Untested = unfinished.
|
|
76
84
|
|
|
85
|
+
**Release branches:** verify the changed flow while building the ticket and record it in the ticket PR; a merge into `release/*` needs no receipt. The full suite runs in the background after each merge and must use parallelism (runner workers, and parallel per-commit reruns to find a breaking ticket). A suite that cannot run in parallel says why (`serialReason`).
|
|
86
|
+
|
|
77
87
|
**Highest-stakes logic** (financial, auth, medical, pedagogical, and whatever `workflow-config.md` names) is TDD-only: write the test from the spec before any implementation. No exceptions.
|
|
78
88
|
|
|
79
89
|
**Precedence:** this table is the house testing bar. A rule file installed under `.claude/rules/` (for example `common/testing.md`) adds stack-specific technique on top; where it states a different general bar (a flat coverage percentage, "all test types required", blanket-mandatory TDD), this table wins.
|
|
@@ -84,7 +94,7 @@ See `workflow-config.md` for this project's test commands.
|
|
|
84
94
|
|
|
85
95
|
## Pre-commit hooks
|
|
86
96
|
|
|
87
|
-
Lefthook. `lefthook.yml` holds this project's stages; the `
|
|
97
|
+
Lefthook. `lefthook.yml` holds this project's stages; the house baseline is in two templates haus ships, `packages/templates/lefthook-security.yml` and `packages/templates/lefthook-quality.yml` in the haus-workflow repo, which a project copies and adapts (typecheck, lint, format and secret scan on pre-commit, unit tests on pre-push). A web front end copies `packages/templates/lefthook-lighthouse.yml` as its pre-push stage: Lighthouse CI against the production build, with its limits in `lighthouserc.yml`, so a slower page stops before the PR; a limit changes only in the same PR, with the reason. Never gate E2E in hooks. Write `fail_text` as instructions the agent can act on. Add CI when a second developer joins, a broken commit reaches main, or before the first public release.
|
|
88
98
|
|
|
89
99
|
---
|
|
90
100
|
|
|
@@ -132,7 +142,7 @@ Each fact has exactly one home. Never duplicate across layers.
|
|
|
132
142
|
| Runbook (`docs/runbook.md`) | Failure modes + exact fix. Permanent, append-only. |
|
|
133
143
|
| `workflow-config.md` | Doc paths, test commands, highest-stakes, tool choices. Project-owned. |
|
|
134
144
|
|
|
135
|
-
This table outranks any skill's advice about what `CLAUDE.md`, `AGENTS.md` or a standards file should hold. A project's own path-scoped rules go in `.claude/rules/project/`. A change to haus-shipped content (a skill, agent,
|
|
145
|
+
This table outranks any skill's advice about what `CLAUDE.md`, `AGENTS.md` or a standards file should hold. A project's own path-scoped rules go in `.claude/rules/project/`. A change to haus-shipped content (a skill, agent, rule, template or this standard), proposed by any skill or audit, becomes an upstream issue, never a local edit.
|
|
136
146
|
|
|
137
147
|
Rule of thumb: ADR for WHY, runbook for HOW TO FIX, memory for what was LEARNED, `CLAUDE.md` for the stable RULES, `workflow-config.md` for the project-specific VALUES.
|
|
138
148
|
|
|
@@ -149,7 +159,7 @@ Every spawned agent needs a self-contained prompt: file paths, relevant decision
|
|
|
149
159
|
When you notice out-of-scope work worth keeping (a bug found mid-task, scope deferred from a plan, an idea a human explicitly asks you to record), spawn the `issue-creator` agent instead of a background-task chip. Chips die with the session; issues persist and reach the whole team.
|
|
150
160
|
|
|
151
161
|
- Findings and deferred scope: file automatically, labelled `needs-triage`. Ideas: only when a human asks; auto-filed ideas bury real bugs.
|
|
152
|
-
- Findings about haus-shipped content (a skill, agent, template, or this standard) route upstream through the issue-authoring skill's routing rule:
|
|
162
|
+
- Findings about haus-shipped content (a skill, agent, template, or this standard) route upstream through the issue-authoring skill's routing rule: the haus program and every skill, agent, rule and template it ships go to `WeAreHausTech/haus-workflow`. Never put client code or client-identifying detail in an upstream issue.
|
|
153
163
|
- No GitHub issues available (no remote, `gh` missing or unauthenticated, issues disabled): create a background-task chip instead and say so in your final message.
|
|
154
164
|
- Nothing in a filed issue is implemented before human sign-off.
|
|
155
165
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Paste under `jobs:` in `.github/workflows/ci.yml` (sibling to `build:` / `test:`).
|
|
2
2
|
# Prerequisite: `haus` on PATH — e.g. `npm install -g @haus-tech/haus-workflow@latest`.
|
|
3
3
|
#
|
|
4
|
-
# Trivial-change carve-outs (dep bumps, lockfile-only
|
|
4
|
+
# Trivial-change carve-outs (dep bumps, lockfile-only) live in the
|
|
5
5
|
# CLI `haus decisions check` algorithm — not in this job fragment.
|
|
6
6
|
#
|
|
7
7
|
# Optional lefthook pre-commit — merge under `pre-commit.commands` in lefthook.yml:
|
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
# Builds the production front end and runs Lighthouse CI (`lhci autorun`) against it
|
|
4
4
|
# before a push that touches front-end files, so a change that slows a page down stops
|
|
5
5
|
# before the PR, not after the deploy. The limits, the URLs and the server command live
|
|
6
|
-
# in `lighthouserc.yml` at the project root (
|
|
7
|
-
#
|
|
6
|
+
# in `lighthouserc.yml` at the project root (copy the starter from haus-workflow's
|
|
7
|
+
# `packages/configs/lighthouse/lighthouserc.yml`).
|
|
8
8
|
#
|
|
9
9
|
# Setup:
|
|
10
10
|
# 1. Add the runner as a dev dependency: `npm install -D @lhci/cli` (or pnpm/yarn add -D).
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"decisionsDir": "docs/decisions",
|
|
3
|
-
"legacyDecisionsDir": "docs/adr",
|
|
4
|
-
"pathGlobs": [
|
|
5
|
-
"**/package.json",
|
|
6
|
-
"**/pnpm-lock.yaml",
|
|
7
|
-
"**/yarn.lock",
|
|
8
|
-
"**/package-lock.json",
|
|
9
|
-
"**/migrations/**",
|
|
10
|
-
"**/prisma/schema.prisma",
|
|
11
|
-
"**/.github/workflows/**",
|
|
12
|
-
"**/Dockerfile*",
|
|
13
|
-
"**/docker-compose*.yml",
|
|
14
|
-
"**/terraform/**",
|
|
15
|
-
"**/openapi*.yaml",
|
|
16
|
-
"**/schema.graphql"
|
|
17
|
-
],
|
|
18
|
-
"securityPathGlobs": ["**/.env.example", "**/auth/**", "**/middleware/**"],
|
|
19
|
-
"pathRegex": ["(^|/)src/.*/auth/", "(^|/)middleware/", "\\.env\\.example$"],
|
|
20
|
-
"minFilesChanged": 8,
|
|
21
|
-
"minLinesChanged": 200,
|
|
22
|
-
"exemptGlobs": ["docs/**", "tests/**", "**/*.md", ".haus-workflow/**"],
|
|
23
|
-
"requiredSections": ["## Context", "## Decision", "## Consequences"],
|
|
24
|
-
"recommendedSections": ["## Motivation (why)", "## Alternatives considered"],
|
|
25
|
-
"decisionFilePattern": "^\\d{4}-.+\\.md$"
|
|
26
|
-
}
|