@haus-tech/haus-workflow 7.2.0 → 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/CHANGELOG.md +12 -0
- package/dist/cli.js +9782 -9717
- package/package.json +1 -1
- package/packages/skills/adr-decisions/SKILL.md +1 -1
- package/packages/skills/fixing-weak-tests/SKILL.md +1 -1
- package/packages/skills/haus-workflow/SKILL.md +1 -1
- package/packages/skills/haus-workflow/references/init.md +3 -2
- package/packages/skills/haus-workflow/references/workflow-reference.md +87 -0
- package/packages/skills/optimizing-test-suites/SKILL.md +1 -1
- package/packages/skills/qa-genomklickning/SKILL.md +1 -1
- package/packages/skills/request/SKILL.md +1 -1
- package/packages/skills/request-assess-impact/SKILL.md +1 -1
- package/packages/skills/request-score/SKILL.md +1 -1
- package/packages/skills/request-sync/SKILL.md +1 -1
- package/packages/skills/request-write-spec/SKILL.md +1 -1
- package/packages/skills/slack-cowork/SKILL.md +1 -1
- package/packages/skills/testsammanfattning/SKILL.md +1 -1
- package/packages/templates/agentic-workflow-standard.md +29 -143
- package/packages/templates/lefthook-quality.yml +2 -2
package/package.json
CHANGED
|
@@ -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
|
|
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:
|
|
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
|
|
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
|
|
49
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
-
>
|
|
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.
|
|
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,
|
|
33
|
-
2. **Align intent.** State
|
|
34
|
-
3. **Plan.**
|
|
35
|
-
4. **Isolate.** Never edit on `main`: a
|
|
36
|
-
5. **Code.** Sequential unless tasks are independent
|
|
37
|
-
6. **Commit.** Adversarial
|
|
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
|
-
|
|
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
|
|
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
|
|
48
|
-
- Never work directly on `main`.
|
|
49
|
-
- Never rewrite published history (amend, rebase then force).
|
|
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.
|
|
52
|
-
- **NEVER encode ambiguity silently.**
|
|
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
|
-
|
|
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.
|
|
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
|
-
##
|
|
35
|
+
## Testing (non-negotiable)
|
|
96
36
|
|
|
97
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
43
|
+
## ADRs
|
|
158
44
|
|
|
159
|
-
|
|
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
|
-
|
|
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
|
|
54
|
+
## Stop conditions (unattended)
|
|
169
55
|
|
|
170
|
-
Stop and ask
|
|
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
|
|
4
|
-
# (
|
|
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
|
#
|