@haus-tech/haus-workflow 6.8.0 → 7.1.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 +27 -0
  2. package/README.md +41 -85
  3. package/dist/cli.js +25386 -33982
  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
@@ -42,14 +42,4 @@ description: Laravel Nova router. Use for admin resources, actions, fields, filt
42
42
 
43
43
  ## Reference Documentation
44
44
 
45
- Up-to-date API docs are cached locally by haus.
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
- 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.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
- Up-to-date API docs are cached locally by haus.
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
- Up-to-date API docs are cached locally by haus.
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. `.haus-workflow/haus.lock.json` — the authoritative list of installed
18
- catalog items: id, type, version, and installed paths. Prefer this.
19
- 2. If the lock file is missing, list what is on disk instead:
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
- 3. `.claude/templates/start-here.md` — a plain-language onboarding page. If
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 lock file, or directory listings into the
41
- conversation — that is the inventory, not the answer.
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 apply`,
49
- `haus update`), run by a developer.
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 as a default haus catalog skill. When run inside a haus-managed repo:
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
- - **Emit enrichment for asset selection.** After the deep scan, if `.haus-workflow/` exists, write `.haus-workflow/deep-context.json` (best-effort) so haus can recommend skills the shallow scan missed:
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 (catalog content to `WeAreHausTech/haus-workflow-catalog`, the haus program and the skills and agents it ships itself to `WeAreHausTech/haus-workflow`), project-local lessons stay in this repo's issues.
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 `haus.lefthook-security` and `haus.lefthook-quality` templates hold the house baseline (typecheck, lint, format and secret scan on pre-commit, unit tests on pre-push). A web front end adds the `haus.lefthook-lighthouse` 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.
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, catalog rule, template or this standard), proposed by any skill or audit, becomes an upstream issue, never a local edit.
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: catalog content to `WeAreHausTech/haus-workflow-catalog`, the haus program and the skills and agents it ships itself to `WeAreHausTech/haus-workflow`. Never put client code or client-identifying detail in an upstream issue.
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, catalog sync) live in the
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 (`haus configs haus.lighthouserc` writes a
7
- # starter).
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
- }
@@ -1,4 +0,0 @@
1
- {
2
- "$comment": "Canonical schema lives in haus-workflow-catalog. Do not edit this file directly.",
3
- "$ref": "https://raw.githubusercontent.com/WeAreHausTech/haus-workflow-catalog/main/schema/haus-lock.schema.json"
4
- }