@haus-tech/haus-workflow 7.2.1 → 7.3.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@haus-tech/haus-workflow",
3
- "version": "7.2.1",
3
+ "version": "7.3.0",
4
4
  "description": "Haus AI workflow CLI for Claude Code.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -74,7 +74,7 @@ haus decisions next-number # next NNNN
74
74
  haus decisions validate path # structure check
75
75
  ```
76
76
 
77
- Index lives at `docs/decisions/README.md` — keep it `@import`ed from `CLAUDE.md`.
77
+ Index lives at `docs/decisions/README.md`. It is not `@import`ed (it grows with every ADR): before choosing a library, data or security model or API contract, `grep -i <topic> docs/decisions/README.md` and read the matching records.
78
78
 
79
79
  ## When another skill offers an ADR, or the decision has no diff
80
80
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: fixing-weak-tests
3
- description: Use when tests may pass for wrong values, when asked to audit test quality, tear apart or harden tests, review AI-written tests, or fix the findings of a test audit across a repo. Triggers on "riv isär testerna", "granska testkvaliteten", "fixa svaga tester", "laga testerna från auditen", "tear apart tests", "fix weak tests", "audit the tests", "are these tests any good".
3
+ description: 'Audit and harden weak tests (pass for wrong values, AI-written tests), or fix audit findings. Triggers: "riv isär testerna", "fixa svaga tester", "granska testkvaliteten", "tear apart tests", "fix weak tests", "audit the tests".'
4
4
  argument-hint: '[audit report path or area]'
5
5
  ---
6
6
 
@@ -222,4 +222,4 @@ anything in the current project.
222
222
  ## Do not use when
223
223
 
224
224
  - User needs a security, code, or test review — use the dedicated reviewer agents instead.
225
- - User asks about workflow concepts or wants to understand the WORKFLOW.md standard — answer directly from the loaded context.
225
+ - User asks about workflow concepts or wants to understand the WORKFLOW.md standard: answer from the loaded core, and read `references/workflow-reference.md` (the on-demand half: merging, interviews, release branches, hooks, where facts live) for the section the core names.
@@ -45,8 +45,9 @@ Do this in order:
45
45
 
46
46
  6. **Check the imports.** Verify the root `CLAUDE.md` imports `@AGENTS.md` inside its
47
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.
48
+ `@.haus-workflow/WORKFLOW.md` and `@.haus-workflow/workflow-config.md` (the decisions
49
+ index is grepped on demand, never imported). If not, run `haus apply --write`, never a
50
+ hand edit.
50
51
 
51
52
  7. **Confirm.** End with one plain-language line, for example:
52
53
  "✅ Your project is configured: I wrote your project docs and installed the
@@ -0,0 +1,87 @@
1
+ # Workflow reference
2
+
3
+ On-demand part of the workflow standard. `.haus-workflow/WORKFLOW.md` is the always-loaded core and names the section to read here before the step it covers. Where the two disagree, the core wins.
4
+
5
+ ## Doc paths
6
+
7
+ | Workflow term | Default path |
8
+ | ------------- | --------------------------------------------------------------------- |
9
+ | Spec | `docs/SPEC.md` |
10
+ | Design | `docs/DESIGN.md` |
11
+ | UX flows | `docs/UX.md` |
12
+ | Mockups | `docs/design/` (gitignore binaries, commit README.txt) |
13
+ | Plans | `docs/plans/<feature-slug>.md` (one per feature, persist after merge) |
14
+ | Decision log | `docs/decisions/` (index `docs/decisions/README.md`) |
15
+ | Glossary | `GLOSSARY.md` at the repo root (domain terms; no open questions) |
16
+ | Research | `docs/research/YYYY-MM-DD-<slug>.md` (dated; evidence, never a rule) |
17
+ | Failure modes | `docs/runbook.md` |
18
+ | Issue tracker | `.claude/skills/issue-authoring/references/issue-tracker.md` |
19
+
20
+ `workflow-config.md` overrides a row. When the user or a skill says "spec", "design", "ux", "plan", "mockup", "ADR", "decision" or "issue tracker", resolve it here.
21
+
22
+ ## Interviews
23
+
24
+ When Align intent runs as an interview (any skill), ask one question per message and wait for the answer, even when the skill says to ask a round at once. Number the question, give options and a recommended answer, and look facts up instead of asking. Write each term to the glossary as it settles, and every other settled answer to the spec or plan it changes or, when neither exists yet, to an interview record under `docs/research/`. In the record, quote the human's answer as given; label reasoning the human did not state as the assistant's. Draft ADRs only at the closing confirmation, for the decisions that meet the ADR bar. That confirmation is Align intent's OK and approves nothing further.
25
+
26
+ Skills that survey or interview (an architecture review, a retro, a grilling) only propose: what the human picks enters the 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.
27
+
28
+ ## Merging
29
+
30
+ Once the human has said go for a production or customer-visible merge, send it 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. `&&` 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. On a full-suite branch the green full-suite status stands in for the local run. Without a standing authorization in the user's own `~/.claude/CLAUDE.md`, present merge / PR / cleanup options instead.
31
+
32
+ ## Retro and lessons
33
+
34
+ After a major milestone, capture lessons as issues through 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; project-local lessons stay in this repo's issues.
35
+
36
+ ## Closing keywords
37
+
38
+ One keyword per issue, one per line in the PR body (`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.
39
+
40
+ ## Release branches
41
+
42
+ Customer projects ship through release branches (Haus's own repos keep `main` plus tags unless they opt in):
43
+
44
+ 1. Branches are `main`, `release/<n>` (the test environment, no merge gate; numbered on from the highest `release/<n>`, a dated `release/YYYY-MM-DD` with `--date`), `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.
45
+ 2. A ticket reaches the release branch with `haus release merge --verification <file>`, which opens the PR and squash-merges it in one step, with no CI wait and no human go. Never merge it by hand; the guard denies a hand merge.
46
+ 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.
47
+ 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.
48
+ 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.
49
+
50
+ Testing on 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`).
51
+
52
+ ## Pre-commit hooks
53
+
54
+ 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.
55
+
56
+ ## Where facts live
57
+
58
+ Each fact has exactly one home. Never duplicate across layers.
59
+
60
+ | Layer | What goes here |
61
+ | ---------------------------------- | ------------------------------------------------------------------------------------ |
62
+ | Hook, lint rule or CI check | A rule a machine can enforce. Build the check before writing prose. |
63
+ | `AGENTS.md` / `CLAUDE.md` | Stable rules, commands, conventions. Loaded every session, so keep it small. |
64
+ | `.claude/rules/*.md` with `paths:` | Rules that only matter in one part of the tree. Loaded when a matching file is read. |
65
+ | Auto memory (`MEMORY.md`) | Learnings the agent discovers (build quirks, debug insights, patterns). |
66
+ | ADR (`docs/decisions/`) | Architectural decisions, library choices, policy. Permanent, write-once. |
67
+ | Runbook (`docs/runbook.md`) | Failure modes + exact fix. Permanent, append-only. |
68
+ | `workflow-config.md` | Doc paths, test commands, highest-stakes, tool choices. Project-owned. |
69
+
70
+ 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 the workflow standard), proposed by any skill or audit, becomes an upstream issue, never a local edit.
71
+
72
+ ## ADR details
73
+
74
+ ADRs capture why a significant choice was made. The machine drafts; the human approves.
75
+
76
+ - Location: `docs/decisions/NNNN-kebab-case-title.md`. Index: `docs/decisions/README.md`, one line per ADR with its why. The index is not loaded every session: grep it before a decision-worthy choice.
77
+ - Statuses: `Proposed`, `Accepted`, `Deprecated`, `Superseded by ADR-XXXX`. To change one, add a new ADR that supersedes it.
78
+ - `haus decisions suggest` drafts from the diff, `haus decisions guard` stops a PR without one, `haus decisions check` gates CI.
79
+ - One writer: `adr-decisions`. When another skill tells you to record, offer or edit an ADR (`domain-modeling` and the skills that call it), use that skill only to judge whether the decision deserves a record, then write it through `adr-decisions`: house template, `docs/decisions/`, next number, README row, status Proposed. That skill's own ADR format, directory and numbering do not apply.
80
+
81
+ ## Out-of-scope capture
82
+
83
+ 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.
84
+
85
+ - Findings and deferred scope: file automatically, labelled `needs-triage`. Ideas: only when a human asks.
86
+ - Findings about haus-shipped content route upstream to `WeAreHausTech/haus-workflow` through the issue-authoring skill's routing rule. Never put client code or client-identifying detail in an upstream issue.
87
+ - 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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: optimizing-test-suites
3
- description: Use when a test suite is too slow, the iteration loop is painful, tests look duplicated or redundant, or someone asks to run tests in parallel, run only affected tests, cut test time or clean up the test suite. Triggers on "testerna tar för lång tid", "kör testeffektivitet", "snabba upp testerna", "hitta dubbletter i testerna", "kör testerna parallellt", "make the tests faster", "find duplicate tests", "only run affected tests".
3
+ description: 'Speed up a slow test suite, find duplicate/redundant tests, run in parallel or only affected tests. Triggers: "testerna tar för lång tid", "snabba upp testerna", "hitta dubbletter i testerna", "make the tests faster", "only run affected tests".'
4
4
  argument-hint: '[suite or area]'
5
5
  ---
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: qa-genomklickning
3
- description: Use when everything built on a branch (a release branch, a feature branch, a PR) must be clicked through and probed in as many combinations as possible before release, with the bugs found fixed test-first and re-verified. Triggers on "/qa-genomklickning", "klicka igenom allt", "QA:a releasebranchen", "testa allt som gjorts på branchen", "genomklickning", "full QA pass", "click through everything on this branch".
3
+ description: 'Click through and probe everything built on a branch/PR before release, fix bugs test-first, re-verify. Triggers: "/qa-genomklickning", "klicka igenom allt", "QA:a releasebranchen", "genomklickning", "full QA pass", "click through everything".'
4
4
  argument-hint: '[branch] [scope-base]'
5
5
  ---
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: request
3
- description: The single entry point to Haus's request flow. Use when the user says "/request", "kör requestflödet", "speca och bedöm", "prisa den här posten", "ta önskemålet hela vägen", "vad ligger i kön", "detaljer <post>", or when several request skills are to be chained in sequence. Individual request skills (request-write-spec, request-score and others) still work standalone; this skill owns the chain, the archive and the dispatch to subagents.
3
+ description: 'Entry point to Haus request flow and chain of request-* skills, archive and subagent dispatch. Triggers: "/request", "kör requestflödet", "speca och bedöm", "prisa den här posten", "vad ligger i kön", "detaljer <post>".'
4
4
  ---
5
5
 
6
6
  # /request: the entry point to the request flow
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: request-assess-impact
3
- description: Write an impact analysis for an approved spec, covering what the change touches in the system and what follows from it. Always use when a spec has passed review and is to be scored, when the user says "kör påverkansanalys", "vad rör det här", "kolla vad som påverkas", or when `request-score` needs source material and none exists. Reads the codebase, settles technical decisions itself and reports them; never asks questions back. Output is a document, never a score and never a price.
3
+ description: 'Impact analysis for an approved spec: what the change touches. Triggers: "kör påverkansanalys", "vad rör det här", "kolla vad som påverkas", or when request-score lacks source material. Output is a document, never a score or price.'
4
4
  ---
5
5
 
6
6
  # request-assess-impact
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: request-score
3
- description: Scores a spec plus impact analysis by comparing the assignment against a scale of seventeen reference assignments. Always use when the user wants "sätt poäng", "poängsätt", "kör poängen", "vad landar det här på", "var på skalan ligger det", or when a spec has an impact analysis and is to be priced. Also used as a gate on a complete implementation plan before the first line of code: "kör guarden", "stämmer poängen fortfarande". Use it even when scoring is only implied, e.g. when someone pastes a spec with source material and asks how big it is. Output is JSON with a score and evidence, never a price.
3
+ description: 'Score a spec plus impact analysis against 17 reference assignments. Triggers: "sätt poäng", "poängsätt", "kör poängen", "var på skalan ligger det", "kör guarden", "stämmer poängen fortfarande". Output is JSON, never a price.'
4
4
  ---
5
5
 
6
6
  # request-score
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: request-sync
3
- description: Reads and writes requests against the ticket system (Asana today), and sets up the binding between a repo and the right customer board. Always use when the user wants "sätt upp", "koppla repot mot Asana", "kör uppsättningen", "hämta requests", "vad ligger för granskning", "lägg in poängen i Asana", "skriv tillbaka", "flytta ärendet", "skapa en request", or when output from `request-write-spec` or `request-score` is to land on the board. This is the only skill that knows field names, status values and boards; every other skill in the request family works against domain JSON.
3
+ description: 'Read/write requests against the ticket system (Asana) and bind a repo to its customer board. Triggers: "koppla repot mot Asana", "hämta requests", "lägg in poängen i Asana", "skriv tillbaka", "flytta ärendet", "skapa en request".'
4
4
  ---
5
5
 
6
6
  # request-sync
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: request-write-spec
3
- description: Write a spec in the Haus spec format from a raw customer request, without asking questions back. Always use when the user wants to "speca", "skriv en spec", "gör en spec av det här", pastes a customer request or ticket that should become a spec, or runs requests through the maintenance model's flow. Also for rewriting an existing spec into the format. Output is finished specs plus a reviewer block for human validation, never follow-up questions.
3
+ description: 'Write a Haus-format spec from a raw customer request, never asking questions back. Triggers: "speca", "skriv en spec", "gör en spec av det här", a pasted customer request or ticket. Output is specs plus a reviewer block.'
4
4
  ---
5
5
 
6
6
  # request-write-spec
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: slack-cowork
3
- description: Speglar en Slack-kanals canvases till en lokal projektmapp, håller dem synkade och skapar nya. Använd den här skillen när användaren vill koppla upp sessionen mot en Slack-kanal, hämta ner eller "suga ner" canvases, arbeta med utkast lokalt innan de publiceras, pusha ändringar tillbaka till Slack, eller skapa en ny canvas i en kanal. Använd den också i början av en session som gäller ett projekt med en kopplad Slack-kanal — då behöver du synka och läsa av vad som ändrats sedan sist innan något annat arbete påbörjas. Utlöses av fraser som "koppla upp mot #kanal", "synka kanalen", "läs in canvasarna", "pusha till Slack", "publicera utkastet", "vad har hänt i kanalen", "slack-cowork".
3
+ description: 'Speglar en Slack-kanals canvases till lokal mapp, synkar och skapar nya. Triggers: "koppla upp mot #kanal", "synka kanalen", "läs in canvasarna", "pusha till Slack", "publicera utkastet", "slack-cowork". Synka vid sessionsstart i kopplat projekt.'
4
4
  ---
5
5
 
6
6
  # slack-cowork
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: testsammanfattning
3
- description: Sätter upp och uppdaterar en testsammanfattning i ett repo, alltså ett genererat dokument där varje rad är ett testat beteende med utfallet från senaste körningen och en länk till exakt rad i testloggen. Använd när användaren säger "testsammanfattning", "sammanfatta testerna", "vad har testerna bekräftat", "skriv en sammanfattning av testerna", "sätt upp testloggar", "uppdatera testsammanfattningen", "kör test:log", eller när ett repo med tester ska få en läsbar redovisning av vad som är testat. Använd också efter en testkörning i ett repo som redan har `test-summary.config.json`.
3
+ description: 'Sätter upp/uppdaterar testsammanfattning i ett repo (testat beteende, utfall, länk till testloggen). Triggers: "testsammanfattning", "sammanfatta testerna", "vad har testerna bekräftat", "sätt upp testloggar", "kör test:log".'
4
4
  ---
5
5
 
6
6
  # Testsammanfattning
@@ -1,170 +1,56 @@
1
1
  # Agentic Development Workflow Standard
2
2
 
3
- > Tech-agnostic methodology for AI-assisted software projects.
3
+ > The always-loaded core. Procedures, recipes and the reasons behind them are in `.claude/skills/haus-workflow/references/workflow-reference.md` (WR below): read the section named before the step it covers. If that file is missing, `haus.json` pins a release older than this file: set `release` to the haus version in this file's header, run `haus sync`, and until then follow the core alone.
4
4
 
5
- ---
6
-
7
- ## Source-of-truth documents
8
-
9
- | Workflow term | Default path |
10
- | ------------- | --------------------------------------------------------------------- |
11
- | Spec | `docs/SPEC.md` |
12
- | Design | `docs/DESIGN.md` |
13
- | UX flows | `docs/UX.md` |
14
- | Mockups | `docs/design/` (gitignore binaries, commit README.txt) |
15
- | Plans | `docs/plans/<feature-slug>.md` (one per feature, persist after merge) |
16
- | Decision log | `docs/decisions/` |
17
- | Glossary | `GLOSSARY.md` at the repo root (domain terms; no open questions) |
18
- | Research | `docs/research/YYYY-MM-DD-<slug>.md` (dated; evidence, never a rule) |
19
- | Failure modes | `docs/runbook.md` |
20
- | Issue tracker | `.claude/skills/issue-authoring/references/issue-tracker.md` |
21
-
22
- When the user or an installed skill says "spec", "design", "ux", "plan", "mockup", "ADR", "decision" or "issue tracker": resolve to the rows above. These paths override the defaults inside any installed skill (`docs/superpowers/specs/`, `docs/superpowers/plans/`, `docs/adr/`).
23
-
24
- ---
5
+ Doc paths (spec, design, UX, plans, decisions, runbook, glossary, research) come from `workflow-config.md`; where it names none, plans are `docs/plans/<slug>.md`, decisions `docs/decisions/`, the glossary `GLOSSARY.md`, research `docs/research/YYYY-MM-DD-<slug>.md`, failure modes `docs/runbook.md`. These paths override any installed skill's defaults (`docs/superpowers/specs/`, `docs/superpowers/plans/`, `docs/adr/`).
25
6
 
26
7
  ## Feature workflow
27
8
 
28
- The loop is explore, plan, code, commit. The superpowers plugin carries the how (brainstorming, writing-plans, using-git-worktrees, test-driven-development, verification-before-completion, requesting-code-review, finishing-a-development-branch). This section sets the gates.
29
-
30
- **Escape hatch:** if you can describe the whole diff in one sentence (typo, copy tweak, one-line fix), go straight to code. Planning is for changes that touch multiple files, are architecturally uncertain, or live in unfamiliar code.
9
+ The loop is explore, plan, code, commit. Superpowers carries the how; this section sets the gates. A diff you can describe in one sentence goes straight to code.
31
10
 
32
- 1. **Explore.** Read spec, design, UX, mockups, the glossary and the code you will touch. No edits, no plan, no questions before this.
33
- 2. **Align intent.** State all assumptions, flag every gap and conflict between inputs, list what is ambiguous. Stop and wait for explicit user OK before writing a plan. A user-level `CLAUDE.md` that delegates this gate replaces the stop with a recorded assumption in the plan. When this step runs as an interview (any skill), ask one question per message and wait for the answer, even when the skill tells you to ask several questions or a whole round at once. Number the question, give options and a recommended answer, and look facts up instead of asking. Write each term to the glossary as it settles, and every other settled answer to the spec or plan it changes or, when neither exists yet, to an interview record under `docs/research/`. In the record, quote the human's answer as given; label any reasoning the human did not state as the assistant's. Draft ADRs only at the closing confirmation, for the decisions that meet the ADR bar. That confirmation is this step's OK and approves nothing further.
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
- 4. **Isolate.** Never edit on `main`: a feature branch or a worktree under `.claude/worktrees/<slug>` (gitignored).
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 ticket into the open `release/*` branch skips the merge text of this step: run `haus release merge --verification <file>`, with no CI wait and no human go. 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.
11
+ 1. **Explore.** Read the spec, design, UX flows, mockups, glossary and the code you will touch before any edit, plan or question.
12
+ 2. **Align intent.** State assumptions, flag gaps and conflicts, then stop for the user's OK before the plan. Interviews: WR "Interviews".
13
+ 3. **Plan.** Tasks with testable acceptance criteria, exact verification commands, dependencies and a source-doc reference, saved to the plan path above. Stop for the user's OK before executing.
14
+ 4. **Isolate.** Never edit on `main`: a branch or a worktree under `.claude/worktrees/<slug>`.
15
+ 5. **Code.** Sequential unless tasks are independent, then parallel subagents, each in its own worktree. Each task gets a pass/fail signal: implement, run the check, read it, fix. Diagnose a bug's root cause before any fix.
16
+ 6. **Commit.** Adversarial review in fresh context, then check what the target branch deploys (`.haus-workflow/deploy.json`). A merge into a production or customer-visible branch is a production deploy: a recorded local run and the human's explicit go. Before any merge read WR "Merging" (the recipe, and the options to present without a standing authorization). A ticket into the open `release/*` goes through `haus release merge` (WR "Release branches"). Docs ship in the same PR when setup, commands, env, deploy or integrations change (`/docs`), else state N/A.
38
17
 
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
-
41
- ---
18
+ A user-level `CLAUDE.md` that delegates a stop replaces it with a recorded assumption in the plan. Questions: decisions in one batch at the start of a task; inside an interview, one question per message.
42
19
 
43
20
  ## NEVER rules
44
21
 
45
- Apply even in unattended mode. `.claude/settings.json` already denies force pushes, `--no-verify`, `gh pr merge --admin`, publishing and secret-file reads; the rules below are the ones only you can keep.
22
+ Apply even unattended; `.claude/settings.json` denies force pushes, `--no-verify`, `gh pr merge --admin`, publishing and secret-file reads.
46
23
 
47
- - **NEVER commit or push without explicit user OK**, unless inside an approved plan (plan approval = blanket exec authority for that plan's scope only) or the user's own `~/.claude/CLAUDE.md` grants a standing authorization that covers it. A standing authorization never covers a merge that deploys production or publishes to a customer.
48
- - Never work directly on `main`. Always a branch or worktree (the Lefthook `branch-guard` stage enforces this where installed).
49
- - Never rewrite published history (amend, rebase then force). Breaks anyone who pulled.
24
+ - **NEVER commit or push without explicit user OK**, unless inside an approved plan's scope or the user's own `~/.claude/CLAUDE.md` grants a standing authorization. None covers a merge that deploys production or publishes to a customer.
25
+ - Never work directly on `main`.
26
+ - Never rewrite published history (amend, rebase then force).
50
27
  - Never delete a branch with unmerged work without explicit OK.
51
- - Never commit secrets, credentials, tokens or API keys. They are permanent in git history.
52
- - **NEVER encode ambiguity silently.** Ambiguity means stop and ask. Record the resolution in its home: an ADR when it meets the ADR bar, otherwise the spec or plan it changes.
53
-
54
- ---
28
+ - Never commit secrets, credentials, tokens or API keys.
29
+ - **NEVER encode ambiguity silently.** Stop and ask; record the answer in an ADR when it meets the bar, else in the spec or plan.
55
30
 
56
31
  ## Git
57
32
 
58
- - Squash-merge: `gh pr merge <n> --squash --delete-branch`. Never plain `--merge`, except the release PR below.
59
- - Conventional Commits: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`, `ci`, `perf`. Scope by domain: `feat(auth):`.
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
-
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/<n>` (the test environment, no merge gate; numbered on from the highest `release/<n>`, a dated `release/YYYY-MM-DD` with `--date`), `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. Never wait for CI or merge it by hand; the guard denies a hand merge.
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
-
70
- ---
71
-
72
- ## Testing rules (non-negotiable)
73
-
74
- No task is done until tests pass locally and the changed flow has been run in the app (dev server, local build or docs preview) with data that triggers it. CI green is not verification. All new code ships with tests.
75
-
76
- | Layer | Minimum bar |
77
- | ----------------------------- | ------------------------------------------------------------------------------------------- |
78
- | Pure logic / domain functions | TDD. Test first, code second. Cover happy path + edge cases + invariants. |
79
- | UI components | One render-and-interact test per public component. Query by role/label, not class names. |
80
- | Backend / data layer | One integration test per repository function, against a local emulator/test DB, never prod. |
81
- | Critical user flows | One happy-path E2E per critical journey. |
82
-
83
- **Verification gate:** run the suite for every touched layer and record the passing output in the task's verification block. Untested = unfinished.
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
-
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.
88
-
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.
90
-
91
- See `workflow-config.md` for this project's test commands.
92
-
93
- ---
33
+ Squash-merge (`gh pr merge <n> --squash --delete-branch`), never plain `--merge` except a release PR. Conventional Commits scoped by domain (`feat(auth):`). Closing keywords: WR "Closing keywords".
94
34
 
95
- ## Pre-commit hooks
35
+ ## Testing (non-negotiable)
96
36
 
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.
98
-
99
- ---
37
+ No task is done until tests pass locally and the changed flow has run in the app with data that triggers it. CI green is not verification. New code ships with tests: pure logic TDD (happy path, edge cases, invariants); one render-and-interact test per public UI component (query by role or label); one integration test per repository function against a local test DB, never prod; one happy-path E2E per critical journey. Run the suite for every touched layer and record the passing output in the task's verification block. Highest-stakes logic (financial, auth, medical, pedagogical, and what `workflow-config.md` names) is TDD-only. This bar wins over a general bar in any `.claude/rules/` file. Test commands: `workflow-config.md`.
100
38
 
101
39
  ## Security defaults
102
40
 
103
- - **Default deny.** Access-control layers (DB rules, RLS, middleware) start denied, opened explicitly.
104
- - **Security rules are implementation.** Write them in the same task as the feature they protect.
105
- - **Validate at boundaries.** Parse and validate user input, API responses, env vars with a schema library. Trust internal types downstream.
106
- - **OWASP Top 10 check** before any new public route: injection, broken auth, IDOR, SSRF, misconfiguration.
107
- - **Dependency audit** on a regular cadence. Block critical findings before release.
108
- - **No remote scripts in generated reports.** A report or prototype an agent generates about this codebase inlines its assets and loads nothing from a CDN, even when a skill's scaffold does.
109
-
110
- ---
111
-
112
- ## Architecture Decision Records (ADR)
113
-
114
- ADRs capture why a significant choice was made. The machine drafts; the human approves.
115
-
116
- Write one when choosing a library or framework, defining a data or security model, picking a merge or deploy strategy, setting an API contract, or resolving a spec conflict. For any other decision, offer one only when it is hard to reverse, would surprise a reader who lacks the context, and came from a real trade-off. These two sentences are the ADR bar.
117
-
118
- - Location: `docs/decisions/NNNN-kebab-case-title.md`. Index: `docs/decisions/README.md`, one line per ADR with its why, imported from `CLAUDE.md`.
119
- - Write-once. To change one, add a new ADR that supersedes it. Statuses: `Proposed`, `Accepted`, `Deprecated`, `Superseded by ADR-XXXX`.
120
- - Template and procedure: the `adr-decisions` skill. `haus decisions suggest` drafts from the diff; `haus decisions check` gates CI.
121
- - **One writer: `adr-decisions`.** When another skill tells you to record, offer or edit an ADR (`domain-modeling` and the skills that call it), use that skill only to judge whether the decision deserves a record, then write the record through `adr-decisions`: house template, `docs/decisions/`, next number, README row, status Proposed until a human approves. That skill's own ADR format, directory and numbering do not apply here.
122
-
123
- ---
124
-
125
- ## Runbook
126
-
127
- Maintain `docs/runbook.md`: one entry per non-obvious failure resolved, with the exact symptom, the root cause and the exact fix command.
128
-
129
- ---
130
-
131
- ## Where facts live
132
-
133
- Each fact has exactly one home. Never duplicate across layers.
134
-
135
- | Layer | What goes here |
136
- | ---------------------------------- | ------------------------------------------------------------------------------------ |
137
- | Hook, lint rule or CI check | A rule a machine can enforce. Build the check before writing prose. |
138
- | `AGENTS.md` / `CLAUDE.md` | Stable rules, commands, conventions. Loaded every session, so keep it small. |
139
- | `.claude/rules/*.md` with `paths:` | Rules that only matter in one part of the tree. Loaded when a matching file is read. |
140
- | Auto memory (`MEMORY.md`) | Learnings the agent discovers (build quirks, debug insights, patterns). |
141
- | ADR (`docs/decisions/`) | Architectural decisions, library choices, policy. Permanent, write-once. |
142
- | Runbook (`docs/runbook.md`) | Failure modes + exact fix. Permanent, append-only. |
143
- | `workflow-config.md` | Doc paths, test commands, highest-stakes, tool choices. Project-owned. |
144
-
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.
146
-
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.
148
-
149
- ---
150
-
151
- ## Subagents
152
-
153
- Every spawned agent needs a self-contained prompt: file paths, relevant decisions, expected output format. No implicit context from the parent session. Independent investigations or feature modules run in parallel, each in its own worktree; a state-dependent pipeline runs sequentially; a specific failure gets one agent with full context.
154
-
155
- ---
41
+ Default deny on access-control layers. Security rules ship in the same task as the feature. Validate input, API responses and env vars at the boundary with a schema library. OWASP Top 10 check before a new public route. Regular dependency audit; critical findings block a release. A generated report or prototype inlines its assets, no CDN scripts.
156
42
 
157
- ## Out-of-scope capture
43
+ ## ADRs
158
44
 
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.
45
+ Write one when choosing a library or framework, a data or security model, a merge or deploy strategy, an API contract, or resolving a spec conflict; for other decisions only when hard to reverse, surprising without context, and a real trade-off. Before any of those choices, `grep -i <topic> docs/decisions/README.md` and read the matching records. Write-once, drafted through the `adr-decisions` skill (also when another skill asks for an ADR), status Proposed until a human approves.
160
46
 
161
- - Findings and deferred scope: file automatically, labelled `needs-triage`. Ideas: only when a human asks; auto-filed ideas bury real bugs.
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.
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.
164
- - Nothing in a filed issue is implemented before human sign-off.
47
+ ## Elsewhere, on demand
165
48
 
166
- ---
49
+ - Editing `lefthook.yml`, `lighthouserc.yml` or `.github/workflows/`: WR "Pre-commit hooks".
50
+ - Deciding where a fact or rule belongs (CLAUDE.md, a rule, memory, ADR, runbook): WR "Where facts live". A change to haus-shipped content becomes an upstream issue, never a local edit.
51
+ - A non-obvious failure resolved: one `docs/runbook.md` entry (symptom, root cause, exact fix).
52
+ - Out-of-scope work found mid-task: the `issue-creator` agent, labelled `needs-triage` (WR "Out-of-scope capture"). Nothing in a filed issue is built before human sign-off.
167
53
 
168
- ## Stop conditions (unattended mode)
54
+ ## Stop conditions (unattended)
169
55
 
170
- Stop and ask the user when verification fails 3+ times on the same task, a spec/design/UX conflict needs a product decision, a security hole cannot be closed without new requirements, or build or tests are red after rebase.
56
+ Stop and ask when verification fails 3+ times on one task, a spec or design conflict needs a product decision, a security hole needs new requirements, or build or tests are red after a rebase.
@@ -1,7 +1,7 @@
1
1
  # Lefthook quality pre-commit — lint, typecheck, and format gates for haus projects.
2
2
  #
3
- # Installable counterpart of the workflow standard's "Pre-commit hooks" section
4
- # (agentic-workflow-standard.md): gate every commit on typecheck + lint + format,
3
+ # Installable counterpart of the workflow reference's "Pre-commit hooks" section
4
+ # (haus-workflow skill, references/workflow-reference.md): gate every commit on typecheck + lint + format,
5
5
  # gate unit tests on pre-push. Copy to the repo root as `lefthook.yml` (or merge
6
6
  # into an existing one), then run `lefthook install`.
7
7
  #