@haus-tech/haus-workflow 6.7.1 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/README.md +41 -85
- package/dist/cli.js +17629 -23486
- package/docs/before-you-start.md +17 -22
- package/docs/glossary.md +10 -8
- package/package.json +3 -6
- package/packages/agents/issue-creator.md +59 -0
- package/packages/configs/eslint/eslint.config.mjs +90 -0
- package/packages/configs/lighthouse/lighthouserc.yml +35 -0
- package/packages/configs/prettier/.prettierignore +28 -0
- package/packages/configs/prettier/prettier.config.cjs +12 -0
- package/packages/packages.yaml +81 -0
- package/packages/skills/adr-decisions/SKILL.md +113 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
- package/packages/skills/bullmq-patterns/SKILL.md +53 -0
- package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
- package/packages/skills/bullmq-patterns/references/scope.md +30 -0
- package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
- package/{library/global → packages}/skills/haus-workflow/SKILL.md +28 -41
- package/packages/skills/haus-workflow/references/init.md +57 -0
- package/{library/global → packages}/skills/haus-workflow/references/new.md +15 -20
- package/packages/skills/i18next-patterns/SKILL.md +52 -0
- package/packages/skills/i18next-patterns/references/conventions.md +32 -0
- package/packages/skills/i18next-patterns/references/scope.md +29 -0
- package/packages/skills/i18next-patterns/references/workflow.md +39 -0
- package/packages/skills/issue-authoring/SKILL.md +184 -0
- package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
- package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
- package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
- package/packages/skills/laravel-nova-patterns/SKILL.md +45 -0
- package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
- package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
- package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
- package/packages/skills/nextauth-patterns/SKILL.md +48 -0
- package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
- package/packages/skills/nextauth-patterns/references/scope.md +33 -0
- package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
- package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
- package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
- package/packages/skills/qliro-patterns/SKILL.md +48 -0
- package/packages/skills/qliro-patterns/references/conventions.md +28 -0
- package/packages/skills/qliro-patterns/references/scope.md +30 -0
- package/packages/skills/qliro-patterns/references/workflow.md +46 -0
- package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
- package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
- package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
- package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
- package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
- package/packages/skills/strapi-patterns/SKILL.md +53 -0
- package/packages/skills/strapi-patterns/references/conventions.md +33 -0
- package/packages/skills/strapi-patterns/references/scope.md +29 -0
- package/packages/skills/strapi-patterns/references/workflow.md +47 -0
- package/packages/skills/vendure-app-patterns/SKILL.md +34 -0
- package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
- package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
- package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
- package/packages/skills/vendure-plugin-patterns/SKILL.md +45 -0
- package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
- package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
- package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
- package/packages/skills/whats-installed/SKILL.md +55 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
- package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
- package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
- package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
- package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
- package/packages/skills/writing-documentation/SKILL.md +153 -0
- package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
- package/packages/skills/writing-documentation/references/claude-template.md +43 -0
- package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
- package/packages/skills/writing-documentation/references/summary-template.md +81 -0
- package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
- package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
- package/packages/templates/agentic-workflow-poc.md +180 -0
- package/packages/templates/agentic-workflow-standard.md +170 -0
- package/packages/templates/decision-template.md +27 -0
- package/packages/templates/decisions-ci-gate.yml +32 -0
- package/packages/templates/lefthook-branch-guard.yml +27 -0
- package/packages/templates/lefthook-lighthouse.yml +28 -0
- package/packages/templates/lefthook-quality.yml +34 -0
- package/packages/templates/lefthook-security.yml +27 -0
- package/packages/templates/start-here.md +72 -0
- package/library/catalog/decisions-triggers.json +0 -26
- package/library/catalog/haus-lock.schema.json +0 -4
- package/library/catalog/manifest.json +0 -5941
- package/library/catalog/validation-rules.json +0 -169
- package/library/global/settings-fragments/hooks.json +0 -53
- package/library/global/skills/haus-workflow/references/init.md +0 -88
- package/scripts/postinstall.mjs +0 -62
- /package/{library/global → packages}/agents/request-assessor.md +0 -0
- /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
- /package/{library/global → packages}/agents/request-designer.md +0 -0
- /package/{library/global → packages}/agents/request-scorer.md +0 -0
- /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
- /package/{library/global → packages}/agents/request-specifier.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
- /package/{library/global → packages}/skills/request/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
- /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
- /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# PoC Workflow Standard
|
|
2
|
+
|
|
3
|
+
> For throwaway proofs of concept and customer demos. The code is never published and is
|
|
4
|
+
> discarded after the demo. The goal is a demo script that runs in the meeting, nothing else.
|
|
5
|
+
|
|
6
|
+
This is not the production standard with exceptions. It is a separate, shorter standard
|
|
7
|
+
for a repo whose only deliverable is a working demo. `haus init --profile poc` installs
|
|
8
|
+
it, and the profile keeps the testing, review and security content out of this repo on
|
|
9
|
+
purpose: a rule that is not here cannot steer the work.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Source-of-truth documents
|
|
14
|
+
|
|
15
|
+
| Workflow term | Path | Owner |
|
|
16
|
+
| ---------------- | ----------------------- | --------------- |
|
|
17
|
+
| Manus (script) | `docs/MANUS.md` | `brainstorming` |
|
|
18
|
+
| Executable manus | `demo/manus.spec.ts` | the build |
|
|
19
|
+
| Plans | `docs/plans/<round>.md` | `writing-plans` |
|
|
20
|
+
| Start command | `README.md` | the build |
|
|
21
|
+
|
|
22
|
+
There is no spec, design, UX, ADR or runbook in a PoC. `docs/MANUS.md` IS the spec.
|
|
23
|
+
When the user says "spec" or "manus", resolve to `docs/MANUS.md`.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Superpowers in a PoC
|
|
28
|
+
|
|
29
|
+
`using-superpowers` defers to this file. These skills apply, each with one adjustment:
|
|
30
|
+
|
|
31
|
+
| Skill | Adjustment |
|
|
32
|
+
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| `brainstorming` | Every round starts here. The spec location is `docs/MANUS.md` (this preference overrides the skill's default). |
|
|
34
|
+
| `writing-plans` | Only when brainstorming classifies the round as architectural. The first round always is. |
|
|
35
|
+
| `executing-plans` / `subagent-driven-development` | Unchanged. |
|
|
36
|
+
| `dispatching-parallel-agents` + `using-git-worktrees` | One worktree per manus point when points are independent. |
|
|
37
|
+
| `verification-before-completion` | "Verify" means "run the manus". |
|
|
38
|
+
| `systematic-debugging` | When the manus is red. |
|
|
39
|
+
|
|
40
|
+
These skills do NOT apply here. The reason is stated so nobody re-derives them:
|
|
41
|
+
|
|
42
|
+
| Skill | Why not |
|
|
43
|
+
| ------------------------------------------------- | ---------------------------------------------------- |
|
|
44
|
+
| `test-driven-development` | The manus is the only executable check in this repo. |
|
|
45
|
+
| `requesting-code-review`, `receiving-code-review` | The code is discarded; nobody reviews it. |
|
|
46
|
+
| `finishing-a-development-branch` | Replaced by the merge rule under Git below. |
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Three ways a session starts
|
|
51
|
+
|
|
52
|
+
1. **"Extend the demo with X."** Brainstorm (the skill classifies the round), update
|
|
53
|
+
`docs/MANUS.md`, build, manus green.
|
|
54
|
+
2. **"Fix point 3" / "make the button blue".** Escape hatch: if the whole diff fits in one
|
|
55
|
+
sentence, skip the brainstorm. Build, manus green.
|
|
56
|
+
3. **"Where are we?"** Read `docs/MANUS.md`, run the manus, report per point and the
|
|
57
|
+
days left until the demo date. No code.
|
|
58
|
+
|
|
59
|
+
Never assume the PoC is built in one session. Everything the next session needs lives in
|
|
60
|
+
the repo, never in the conversation.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## The manus
|
|
65
|
+
|
|
66
|
+
`docs/MANUS.md` is the customer story. Its header carries the demo date (`Demo: YYYY-MM-DD`,
|
|
67
|
+
from the "when is the meeting" answer): that is the timebox, and it is visible in the
|
|
68
|
+
repo. Then the numbered points in the order they are shown. Each point has one line for
|
|
69
|
+
what the customer sees and one line for what proves it. A **Parked** section at the
|
|
70
|
+
bottom holds ideas that come up in the meeting. This repo files no GitHub issues and does
|
|
71
|
+
not use `issue-creator`; the repo is thrown away.
|
|
72
|
+
|
|
73
|
+
```markdown
|
|
74
|
+
# Manus
|
|
75
|
+
|
|
76
|
+
Demo: 2026-09-25
|
|
77
|
+
|
|
78
|
+
1. **Pick the B2B channel.** The customer sees the channel switch and the B2B price list.
|
|
79
|
+
Proof: the price of product X changes when the channel changes.
|
|
80
|
+
2. **Order as a company customer.** ...
|
|
81
|
+
|
|
82
|
+
## Parked
|
|
83
|
+
|
|
84
|
+
- Idea from the meeting, not decided.
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`demo/manus.spec.ts` is the same list, executable: one Playwright `test()` per point, same
|
|
88
|
+
title, same order, using `getByRole`/`getByText`. Points decided but not yet built are
|
|
89
|
+
`test.fixme()`. `playwright test --list`, run through the project's package manager (the
|
|
90
|
+
exact command lives in `workflow-config.md`), prints the manus; a run shows green, pending
|
|
91
|
+
and broken per point. The dev server takes its port from `PORT`, so two worktrees can run
|
|
92
|
+
at once.
|
|
93
|
+
|
|
94
|
+
**IMPORTANT: exactly one executable file, and it is the manus. No unit tests, no
|
|
95
|
+
coverage, no TDD.** A second test file is the production standard creeping back in.
|
|
96
|
+
|
|
97
|
+
A vendor scaffold sometimes ships with its own test script, test directories, and a
|
|
98
|
+
second Playwright config already in place. That suite is not this repo's gate: it is
|
|
99
|
+
never run, never extended, and its presence is not permission to add tests of your own.
|
|
100
|
+
|
|
101
|
+
Why Playwright and not clicking through the browser: one run costs one command and gives
|
|
102
|
+
a pass/fail per point; a manual click-through costs a screenshot per step and is not
|
|
103
|
+
repeatable. Use the browser tool for eyes only: a visual pass at the end of a round, and
|
|
104
|
+
when the manus is red and you need to see why. On demo day the manus is the rehearsal
|
|
105
|
+
(`--headed`) and the fallback (video) if the live demo dies.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Build rules
|
|
110
|
+
|
|
111
|
+
Thin is correct. Hard-coded data and mock data are the right choice, not a shortcut. No
|
|
112
|
+
auth, error handling or edge case that is not in the manus. One rule survives from the
|
|
113
|
+
coding-style rules: organize by feature, so the next session can find things. Add
|
|
114
|
+
`.env.example` if any env is needed.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Git
|
|
119
|
+
|
|
120
|
+
- `main` is always green on the manus. Work on a branch per round; use a worktree when
|
|
121
|
+
the `main` checkout must stay untouched before a meeting, or when several manus points
|
|
122
|
+
are built in parallel.
|
|
123
|
+
- Manus green on the branch, then `git merge --ff-only` (or squash) into `main`, then
|
|
124
|
+
remove the worktree. No PR, no review.
|
|
125
|
+
- A red manus is never committed. `fixme` is allowed.
|
|
126
|
+
- Until the first manus point goes green, commit on `main` directly. There is no green
|
|
127
|
+
`main` to protect yet. That changes at the first point's green run: every round after
|
|
128
|
+
it follows the branch-and-merge rule above.
|
|
129
|
+
- Conventional Commits, scoped to the manus: `feat(manus): point 4 price list per channel`.
|
|
130
|
+
"Where are we?" reads this log.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## NEVER rules
|
|
135
|
+
|
|
136
|
+
- **NEVER commit a red manus.** The next session inherits a broken demo.
|
|
137
|
+
- **NEVER use real customer data.** Mock only: the demo is shown to a customer, and GDPR
|
|
138
|
+
applies to throwaway code too.
|
|
139
|
+
- **NEVER deploy or make the repo public.** A PoC never goes online.
|
|
140
|
+
- **NEVER commit secrets.** Permanent in history, even in a throwaway repo that gets
|
|
141
|
+
forgotten.
|
|
142
|
+
- **NEVER `git push --force` on `main`.** `main` is the demo.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Stop conditions (unattended mode)
|
|
147
|
+
|
|
148
|
+
Stop and ask when:
|
|
149
|
+
|
|
150
|
+
- Verification fails 3+ times on the same manus point.
|
|
151
|
+
- A round wants to add manus points that were not decided in a brainstorm. The manus is
|
|
152
|
+
the scope ceiling.
|
|
153
|
+
- A point needs something outside the repo: a real integration, credentials, real data.
|
|
154
|
+
- A product decision is needed that only the customer can make.
|
|
155
|
+
|
|
156
|
+
The ratchet in a PoC repo always goes to "stop, is this still a PoC?", never to "add
|
|
157
|
+
tests".
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Context management
|
|
162
|
+
|
|
163
|
+
Clear between unrelated rounds. Delegate reading to subagents. Checkpoint before risky
|
|
164
|
+
changes. The repo holds the state; the conversation does not.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## After the demo
|
|
169
|
+
|
|
170
|
+
The meeting ends a PoC; it does not extend it. Decide, actively, one of two outcomes:
|
|
171
|
+
|
|
172
|
+
- **Archive.** Archive the repo on GitHub. The Parked section is the only thing that may
|
|
173
|
+
travel on, as issues in another repo.
|
|
174
|
+
- **Build it for real.** Start a production project from zero with `project:new` in
|
|
175
|
+
production mode. `docs/MANUS.md` and Parked are the _input_ to its first brainstorm.
|
|
176
|
+
The code never travels with it, whatever the customer said in the meeting.
|
|
177
|
+
|
|
178
|
+
This is the reclassification gate: keeping the code is a new task, and it is answered by
|
|
179
|
+
starting over, never by hardening this repo. `haus init` refuses to switch a PoC repo to
|
|
180
|
+
the production profile for the same reason.
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# Agentic Development Workflow Standard
|
|
2
|
+
|
|
3
|
+
> Tech-agnostic methodology for AI-assisted software projects.
|
|
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
|
+
---
|
|
25
|
+
|
|
26
|
+
## Feature workflow
|
|
27
|
+
|
|
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.
|
|
31
|
+
|
|
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 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
|
+
|
|
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
|
+
---
|
|
42
|
+
|
|
43
|
+
## NEVER rules
|
|
44
|
+
|
|
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.
|
|
46
|
+
|
|
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.
|
|
50
|
+
- 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
|
+
---
|
|
55
|
+
|
|
56
|
+
## Git
|
|
57
|
+
|
|
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/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
|
+
|
|
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
|
+
---
|
|
94
|
+
|
|
95
|
+
## Pre-commit hooks
|
|
96
|
+
|
|
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
|
+
---
|
|
100
|
+
|
|
101
|
+
## Security defaults
|
|
102
|
+
|
|
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
|
+
---
|
|
156
|
+
|
|
157
|
+
## Out-of-scope capture
|
|
158
|
+
|
|
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.
|
|
160
|
+
|
|
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.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Stop conditions (unattended mode)
|
|
169
|
+
|
|
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.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# ADR-NNNN: [Short title]
|
|
2
|
+
|
|
3
|
+
- **Status:** Proposed | Accepted | Superseded by ADR-XXXX | Deprecated
|
|
4
|
+
- **Date:** YYYY-MM-DD
|
|
5
|
+
- **Decided by:** [person who approved] (draft by [AI agent])
|
|
6
|
+
- **Affects:** [components/paths/packages]
|
|
7
|
+
- **Related:** [PR link, issue, related ADR numbers]
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
What problem or situation triggered the decision? What constraints applied?
|
|
12
|
+
|
|
13
|
+
## Decision
|
|
14
|
+
|
|
15
|
+
What we chose, in plain language — ideally one sentence.
|
|
16
|
+
|
|
17
|
+
## Motivation (why)
|
|
18
|
+
|
|
19
|
+
Why this over the alternatives. **This is the line agents read to answer "why".**
|
|
20
|
+
|
|
21
|
+
## Alternatives considered
|
|
22
|
+
|
|
23
|
+
- [Alternative] — rejected because [reason].
|
|
24
|
+
|
|
25
|
+
## Consequences
|
|
26
|
+
|
|
27
|
+
Positive and negative follow-ons. What becomes harder? What do we lock in?
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Paste under `jobs:` in `.github/workflows/ci.yml` (sibling to `build:` / `test:`).
|
|
2
|
+
# Prerequisite: `haus` on PATH — e.g. `npm install -g @haus-tech/haus-workflow@latest`.
|
|
3
|
+
#
|
|
4
|
+
# Trivial-change carve-outs (dep bumps, lockfile-only) live in the
|
|
5
|
+
# CLI `haus decisions check` algorithm — not in this job fragment.
|
|
6
|
+
#
|
|
7
|
+
# Optional lefthook pre-commit — merge under `pre-commit.commands` in lefthook.yml:
|
|
8
|
+
#
|
|
9
|
+
# decisions-check:
|
|
10
|
+
# run: haus decisions check --staged
|
|
11
|
+
# fail_text: 'Staged change needs an ADR. Run `haus decisions suggest`.'
|
|
12
|
+
|
|
13
|
+
decisions-gate:
|
|
14
|
+
if: github.event_name == 'pull_request'
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
with:
|
|
19
|
+
fetch-depth: 0
|
|
20
|
+
- uses: actions/setup-node@v4
|
|
21
|
+
with:
|
|
22
|
+
node-version: '22'
|
|
23
|
+
- name: Install haus CLI
|
|
24
|
+
run: npm install -g @haus-tech/haus-workflow@latest
|
|
25
|
+
- name: Require ADR for decision-worthy changes
|
|
26
|
+
env:
|
|
27
|
+
PR_BODY: ${{ github.event.pull_request.body }}
|
|
28
|
+
BASE_REF: ${{ github.event.pull_request.base.ref }}
|
|
29
|
+
run: |
|
|
30
|
+
set -euo pipefail
|
|
31
|
+
git fetch --no-tags origin "$BASE_REF"
|
|
32
|
+
haus decisions check --range "origin/$BASE_REF..HEAD"
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Lefthook branch guard — deterministic backing for the workflow standard's
|
|
2
|
+
# "NEVER work directly on `main`" rule (agentic-workflow-standard.md, NEVER rules).
|
|
3
|
+
#
|
|
4
|
+
# `permissions.deny` in `.claude/settings.json` can only match tool-call patterns;
|
|
5
|
+
# it cannot express "which branch is checked out". This hook can: it fails any
|
|
6
|
+
# commit made while a protected branch is checked out. Copy to the repo root as
|
|
7
|
+
# `lefthook.yml` (or merge into an existing one), then run `lefthook install`.
|
|
8
|
+
#
|
|
9
|
+
# Escape hatches — for repos that intentionally commit straight to main:
|
|
10
|
+
# - opt out per repo: git config haus.allowProtectedCommits true
|
|
11
|
+
# - change the guard list: export HAUS_PROTECTED_BRANCHES="main master release"
|
|
12
|
+
# Detached HEAD (e.g. mid-rebase) is always allowed: those commits are not made
|
|
13
|
+
# "on" any branch, and blocking them would break rebase itself.
|
|
14
|
+
pre-commit:
|
|
15
|
+
commands:
|
|
16
|
+
branch-guard:
|
|
17
|
+
run: |
|
|
18
|
+
if [ "$(git config --get haus.allowProtectedCommits)" = "true" ]; then exit 0; fi
|
|
19
|
+
branch="$(git branch --show-current)"
|
|
20
|
+
[ -z "$branch" ] && exit 0
|
|
21
|
+
for protected in ${HAUS_PROTECTED_BRANCHES:-main master}; do
|
|
22
|
+
if [ "$branch" = "$protected" ]; then
|
|
23
|
+
echo "Refusing to commit directly on protected branch '$branch'."
|
|
24
|
+
exit 1
|
|
25
|
+
fi
|
|
26
|
+
done
|
|
27
|
+
fail_text: 'Direct commits on this branch are blocked (NEVER work directly on main). Create a branch first: `git checkout -b feat/<slug>`. If this repo intentionally commits to main, opt out once with `git config haus.allowProtectedCommits true`.'
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Lefthook Lighthouse pre-push: a performance gate for web front ends.
|
|
2
|
+
#
|
|
3
|
+
# Builds the production front end and runs Lighthouse CI (`lhci autorun`) against it
|
|
4
|
+
# before a push that touches front-end files, so a change that slows a page down stops
|
|
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 (copy the starter from haus-workflow's
|
|
7
|
+
# `packages/configs/lighthouse/lighthouserc.yml`).
|
|
8
|
+
#
|
|
9
|
+
# Setup:
|
|
10
|
+
# 1. Add the runner as a dev dependency: `npm install -D @lhci/cli` (or pnpm/yarn add -D).
|
|
11
|
+
# 2. Merge the `lighthouse` command below into the project's `lefthook.yml`.
|
|
12
|
+
# 3. REPLACE `glob` with the front end's source paths and `run` with its build command.
|
|
13
|
+
# Keep `/**` at the end of a folder glob: in Lefthook's default matcher `src/**/*`
|
|
14
|
+
# skips files directly under `src/`. With pnpm use `pnpm exec lhci autorun`, with Yarn
|
|
15
|
+
# `yarn lhci autorun`. In a monorepo, set `root:` to the app folder that holds
|
|
16
|
+
# `lighthouserc.yml`.
|
|
17
|
+
# 4. Add `.lighthouseci/` (the local reports) to `.gitignore`.
|
|
18
|
+
#
|
|
19
|
+
# The numbers are lab numbers from this machine. PageSpeed Insights runs the same lab test
|
|
20
|
+
# from Google's servers, so its score differs, and its field data (28 days of real
|
|
21
|
+
# visitors) no local run can see. The limits catch a regression; they do not promise a
|
|
22
|
+
# public score. Lighthouse needs Chrome installed, or CHROME_PATH set.
|
|
23
|
+
pre-push:
|
|
24
|
+
commands:
|
|
25
|
+
lighthouse:
|
|
26
|
+
glob: 'src/**'
|
|
27
|
+
run: npm run build && npm exec -- lhci autorun
|
|
28
|
+
fail_text: 'The Lighthouse gate failed. A build or server error (a port in use, a missing Chrome) is named in the lines above: fix it and push again. A broken limit is listed with its audit, value and limit: open the HTML report in .lighthouseci/ to see what got slower, fix it and push again. A limit that is wrong for this project changes in lighthouserc.yml in the same PR, with the reason in the PR body.'
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Lefthook quality pre-commit — lint, typecheck, and format gates for haus projects.
|
|
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,
|
|
5
|
+
# gate unit tests on pre-push. Copy to the repo root as `lefthook.yml` (or merge
|
|
6
|
+
# into an existing one), then run `lefthook install`.
|
|
7
|
+
#
|
|
8
|
+
# The `run:` commands below are Node-flavoured defaults. REPLACE each one with this
|
|
9
|
+
# project's real command (e.g. `composer lint`, `ruff check .`, `go vet ./...`,
|
|
10
|
+
# `dotnet format --verify-no-changes`) and delete any gate the project cannot back
|
|
11
|
+
# with a real command — a hook that runs the wrong command either blocks every
|
|
12
|
+
# commit or passes without checking anything.
|
|
13
|
+
#
|
|
14
|
+
# Write `fail_text` for the agent that reads it: name the exact fix command.
|
|
15
|
+
pre-commit:
|
|
16
|
+
parallel: true
|
|
17
|
+
commands:
|
|
18
|
+
lint:
|
|
19
|
+
run: npm run lint
|
|
20
|
+
fail_text: 'Lint failed. Run the lint fixer (e.g. `npm run lint -- --fix`), re-stage, then commit.'
|
|
21
|
+
typecheck:
|
|
22
|
+
run: npm run typecheck
|
|
23
|
+
fail_text: 'Type errors found. Fix all type errors before committing.'
|
|
24
|
+
format:
|
|
25
|
+
run: npm run format:check
|
|
26
|
+
fail_text: 'Formatting drift found. Run the formatter (e.g. `npm run format`), re-stage, then commit.'
|
|
27
|
+
|
|
28
|
+
# Unit tests are gated on pre-push, not pre-commit (too slow per-commit).
|
|
29
|
+
# Never gate E2E suites in hooks.
|
|
30
|
+
pre-push:
|
|
31
|
+
commands:
|
|
32
|
+
test:
|
|
33
|
+
run: npm test
|
|
34
|
+
fail_text: 'Unit tests failed. Fix the failures before pushing.'
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Lefthook security pre-commit — commit-time secret scanning for haus projects.
|
|
2
|
+
#
|
|
3
|
+
# Complements haus's runtime PreToolUse guards + settings.json permissions.deny
|
|
4
|
+
# (which gate the agent in real time) with a commit-time net. Copy to the repo
|
|
5
|
+
# root as `lefthook.yml` (or merge into an existing one), then run `lefthook install`.
|
|
6
|
+
#
|
|
7
|
+
# gitleaks is optional but recommended (https://github.com/gitleaks/gitleaks#installing):
|
|
8
|
+
# when present it does the heavy lifting; the grep baseline below always runs.
|
|
9
|
+
pre-commit:
|
|
10
|
+
parallel: true
|
|
11
|
+
commands:
|
|
12
|
+
gitleaks:
|
|
13
|
+
# Runs only when gitleaks is installed — a missing binary never fails the commit.
|
|
14
|
+
run: |
|
|
15
|
+
if command -v gitleaks >/dev/null 2>&1; then
|
|
16
|
+
gitleaks protect --staged --redact --no-banner
|
|
17
|
+
fi
|
|
18
|
+
fail_text: 'gitleaks found a likely secret in staged changes. Remove it, re-stage, and commit. Install gitleaks: https://github.com/gitleaks/gitleaks#installing'
|
|
19
|
+
secret-grep:
|
|
20
|
+
# Always-on baseline. Scans ADDED lines only (ignores removed lines, so
|
|
21
|
+
# deleting a leaked secret is never blocked) for inline credential assignments.
|
|
22
|
+
run: |
|
|
23
|
+
added="$(git diff --cached --no-color -U0 | grep -E '^\+' | grep -vE '^\+\+\+')"
|
|
24
|
+
if printf '%s\n' "$added" | grep -iqE "(password|secret|token|api_key)[[:space:]]*[:=][[:space:]]*['\"]"; then
|
|
25
|
+
exit 1
|
|
26
|
+
fi
|
|
27
|
+
fail_text: 'A staged line looks like an inline credential (password/secret/token/api_key). Move it to an environment variable or secret manager, then re-stage.'
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Start here — a guide for everyone on this project
|
|
2
|
+
|
|
3
|
+
> You do not need to be a developer to use this page. If words like
|
|
4
|
+
> "repository" or "pull request" are new to you, the glossary at the bottom
|
|
5
|
+
> is written for you.
|
|
6
|
+
|
|
7
|
+
## What is this?
|
|
8
|
+
|
|
9
|
+
This project is set up with **haus**, an internal Haus tool. haus gives the
|
|
10
|
+
project's AI assistant (Claude Code) a set of ready-made instructions: how
|
|
11
|
+
this codebase works, what good work looks like here, and which rules the team
|
|
12
|
+
follows. Think of it as an employee handbook written for the AI — so everyone
|
|
13
|
+
who works with the assistant gets consistent, correct help, whatever their
|
|
14
|
+
role.
|
|
15
|
+
|
|
16
|
+
## What can I do with it?
|
|
17
|
+
|
|
18
|
+
Open Claude Code in this project and ask for what you need in plain language
|
|
19
|
+
— your own words, in any language. You cannot break anything by asking
|
|
20
|
+
questions: reading and explaining change nothing, and changes to the project
|
|
21
|
+
itself only take effect after a person on the team has reviewed and accepted
|
|
22
|
+
them.
|
|
23
|
+
|
|
24
|
+
Good first things to ask:
|
|
25
|
+
|
|
26
|
+
- **"What is installed here, and what can I ask for?"** — you get a menu of
|
|
27
|
+
what the assistant knows how to help with in this project.
|
|
28
|
+
- **"Explain what this project does, in plain language."**
|
|
29
|
+
- **"What has changed in the project recently?"**
|
|
30
|
+
- **"Help me turn this idea into a description the developers can act on."**
|
|
31
|
+
- **"Walk me through this error message"** — or this page, or this file.
|
|
32
|
+
|
|
33
|
+
You do not need to know the correct technical term for anything. Describe
|
|
34
|
+
what you want in your own words; finding the right tool is the assistant's
|
|
35
|
+
job, not yours.
|
|
36
|
+
|
|
37
|
+
## What did haus actually set up?
|
|
38
|
+
|
|
39
|
+
A few folders inside the project. All of them are safe to ignore in daily
|
|
40
|
+
work — this list exists so none of it looks mysterious:
|
|
41
|
+
|
|
42
|
+
| Where | What it is |
|
|
43
|
+
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `.claude/skills/` | Step-by-step guides the assistant follows for specific kinds of work (testing, reviewing, writing docs, …) |
|
|
45
|
+
| `.claude/agents/` | Specialist helpers the assistant can hand a task to — they work on their own and report back |
|
|
46
|
+
| `.claude/rules/` | House rules the assistant applies automatically while it works |
|
|
47
|
+
| `.claude/templates/` | Ready-made document skeletons — this guide is one of them |
|
|
48
|
+
| `.haus-workflow/WORKFLOW.md` | The engineering rulebook: how code is planned, tested, and reviewed. Written for developers and the AI — you never need to read it |
|
|
49
|
+
|
|
50
|
+
## Glossary
|
|
51
|
+
|
|
52
|
+
| Word | What it means |
|
|
53
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
54
|
+
| **Repository** (repo) | The project's shared folder: every file, plus the full history of every change ever made |
|
|
55
|
+
| **Commit** | One saved change, with a note saying what changed and why |
|
|
56
|
+
| **Branch** | A working copy inside the repository where changes are prepared without touching the live version |
|
|
57
|
+
| **Pull request** (PR) | A proposed set of changes, presented for review before it is accepted |
|
|
58
|
+
| **Merge** | Accepting a pull request into the main version of the project |
|
|
59
|
+
| **CI** | Automatic checks that run on every proposed change — tests, style, safety — before a person reviews it |
|
|
60
|
+
| **Issue** | A tracked to-do on the project's GitHub page: a bug report, an idea, or a task |
|
|
61
|
+
| **Skill** | A step-by-step guide the AI assistant follows for a certain kind of task |
|
|
62
|
+
| **Agent** | A helper the assistant can delegate a task to; it works independently and reports back |
|
|
63
|
+
| **Claude Code** | The AI assistant tool this project uses |
|
|
64
|
+
| **haus** | The internal Haus tool that installed — and keeps updated — everything described on this page |
|
|
65
|
+
|
|
66
|
+
## Where to learn more
|
|
67
|
+
|
|
68
|
+
- Ask the assistant. "What can I ask for?" is always a good start.
|
|
69
|
+
- The Haus Workflow documentation site:
|
|
70
|
+
<https://wearehaustech.github.io/docs/haus-workflow/>
|
|
71
|
+
- Any developer on the team — this setup is shared across Haus projects, so
|
|
72
|
+
everyone works with the same pieces.
|
|
@@ -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
|
-
}
|