@haus-tech/haus-workflow 6.7.0 → 6.8.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 +18 -0
- package/dist/cli.js +4764 -1767
- package/package.json +3 -1
- package/packages/agents/issue-creator.md +61 -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 +114 -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 +63 -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/packages/skills/i18next-patterns/SKILL.md +62 -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 +191 -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 +55 -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 +63 -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 +44 -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 +55 -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 +53 -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 +161 -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 +160 -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/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/SKILL.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/init.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/new.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,26 @@
|
|
|
1
|
+
# Completeness criteria
|
|
2
|
+
|
|
3
|
+
Use with `validation-checklist.md` before finishing a docs update. Every item must be **answered in docs**, marked **N/A**, or **`> CONFIRM-WITH-TEAM: confirm with team.`** — never guessed.
|
|
4
|
+
|
|
5
|
+
## App mode
|
|
6
|
+
|
|
7
|
+
1. **Install and run** — prerequisites, install command, how to start locally, how to verify success.
|
|
8
|
+
2. **Runtime** — processes/services (API, worker, CLI, etc.) and how they interact, or N/A for single-process apps.
|
|
9
|
+
3. **Wiring** — path(s) to bootstrap entry points and central configuration.
|
|
10
|
+
4. **Change routing** — where typical changes go (table or bullets): feature logic, config, schema, tests, CI.
|
|
11
|
+
5. **Pre-PR checks** — commands for test/lint/build and repo-specific steps (migrations, codegen, etc.).
|
|
12
|
+
6. **Deploy** — how releases run, ordered steps, post-deploy checks, rollback — or explicit CONFIRM-WITH-TEAM.
|
|
13
|
+
7. **Environment** — key vars from `.env.example` with purpose and consumer (subsystem or config path).
|
|
14
|
+
8. **Regeneration** — migrations, codegen, or other generated artifacts: commands and “do not hand-edit” paths, or N/A.
|
|
15
|
+
9. **Agent guardrails** — generated/vendor/secret paths agents must not edit; docs are an index, not a code copy.
|
|
16
|
+
10. **Unknowns** — gaps use team CONFIRM-WITH-TEAM, not invented URLs, hosts, or ops steps.
|
|
17
|
+
|
|
18
|
+
## Workspace mode
|
|
19
|
+
|
|
20
|
+
1. **Repo map** — every manifest repo with pointer to its `CLAUDE.md` / README / config.
|
|
21
|
+
2. **Layout** — clone/path overrides and local directory layout.
|
|
22
|
+
3. **Startup order** — which repos/services start in what order, or CONFIRM-WITH-TEAM.
|
|
23
|
+
4. **Cross-repo env** — shared env alignment documented or CONFIRM-WITH-TEAM in `docs/environments.md`.
|
|
24
|
+
5. **Release order** — coordinated release across repos documented or CONFIRM-WITH-TEAM in `docs/release-flow.md`.
|
|
25
|
+
6. **No duplication** — install/deploy/env tables live in app repos only; workspace uses `{folder}/path` pointers.
|
|
26
|
+
7. **Unknowns** — gaps use team CONFIRM-WITH-TEAM, not invented URLs, hosts, or ops steps.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# SUMMARY.md template
|
|
2
|
+
|
|
3
|
+
Use when creating or regenerating `docs/SUMMARY.md`. Remove sections with zero files on disk.
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
# [Project Name]
|
|
7
|
+
|
|
8
|
+
[One paragraph: what this repo is, its role in the wider system if applicable, core capability. Factual only.]
|
|
9
|
+
|
|
10
|
+
## Agent Context Guide
|
|
11
|
+
|
|
12
|
+
- Use this file as the documentation index; open detail docs from the tables below only when needed.
|
|
13
|
+
- Start with **CLAUDE.md** for setup, commands, conventions, and pre-PR checks.
|
|
14
|
+
- Route by task (load one primary topic, not every file):
|
|
15
|
+
- **Run / debug locally** → Setup (app: `setup.md`; workspace: `local-development.md`)
|
|
16
|
+
- **Code change** → Codebase; add Conventions and Architecture if the change is cross-cutting or touches integrations
|
|
17
|
+
- **Ship / release** → Development workflow + Deployment (app) or Release flow (workspace)
|
|
18
|
+
- **Multi-repo** (workspace only) → Repositories + Environments + System overview as needed
|
|
19
|
+
- Prefer path references in docs over duplicating source; read code for implementation detail.
|
|
20
|
+
- If docs conflict with code or user intent, ask before making broad changes.
|
|
21
|
+
|
|
22
|
+
## Architecture
|
|
23
|
+
|
|
24
|
+
| File | Description |
|
|
25
|
+
| ---------------------------------- | ----------- |
|
|
26
|
+
| [architecture.md](architecture.md) | … |
|
|
27
|
+
|
|
28
|
+
## Codebase
|
|
29
|
+
|
|
30
|
+
| File | Description |
|
|
31
|
+
| -------------------------- | ----------- |
|
|
32
|
+
| [codebase.md](codebase.md) | … |
|
|
33
|
+
|
|
34
|
+
## Conventions
|
|
35
|
+
|
|
36
|
+
Omit if `docs/conventions.md` does not exist.
|
|
37
|
+
|
|
38
|
+
| File | Description |
|
|
39
|
+
| -------------------------------- | -------------------------------------------------- |
|
|
40
|
+
| [conventions.md](conventions.md) | Extension patterns, schema/codegen, change recipes |
|
|
41
|
+
|
|
42
|
+
## Setup
|
|
43
|
+
|
|
44
|
+
| File | Description |
|
|
45
|
+
| -------------------- | ----------- |
|
|
46
|
+
| [setup.md](setup.md) | … |
|
|
47
|
+
|
|
48
|
+
## Development workflow
|
|
49
|
+
|
|
50
|
+
Omit if `docs/development-workflow.md` does not exist.
|
|
51
|
+
|
|
52
|
+
| File | Description |
|
|
53
|
+
| -------------------------------------------------- | --------------------------------------------- |
|
|
54
|
+
| [development-workflow.md](development-workflow.md) | Common changes, where to edit, quality checks |
|
|
55
|
+
|
|
56
|
+
## Deployment
|
|
57
|
+
|
|
58
|
+
Omit if no deployment docs exist.
|
|
59
|
+
|
|
60
|
+
| File | Description |
|
|
61
|
+
| ------------------------------ | ----------- |
|
|
62
|
+
| [deployment.md](deployment.md) | … |
|
|
63
|
+
|
|
64
|
+
## Other
|
|
65
|
+
|
|
66
|
+
Optional. Non-standard docs only (integrations, testing, data-model, security, etc.).
|
|
67
|
+
|
|
68
|
+
| File | Description |
|
|
69
|
+
| ----------------------------- | --------------------------------------------- |
|
|
70
|
+
| [path.md](path.md) | … |
|
|
71
|
+
| [GLOSSARY.md](../GLOSSARY.md) | Domain terms, written by the interview skills |
|
|
72
|
+
| [research/](research/) | Dated research notes; evidence, never a rule |
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Regeneration rules
|
|
76
|
+
|
|
77
|
+
- List every file that exists on disk; no phantom rows.
|
|
78
|
+
- Omit empty sections.
|
|
79
|
+
- Links relative to `docs/`.
|
|
80
|
+
- One-line descriptions in tables; detail in linked files.
|
|
81
|
+
- **Workspace repos:** SUMMARY describes glue docs only; link app-repo paths from `repositories.md`, do not duplicate app `setup.md` / `deployment.md` content here.
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Topic file formats
|
|
2
|
+
|
|
3
|
+
Use this file for detailed formatting guidance. Keep SKILL.md high-level.
|
|
4
|
+
|
|
5
|
+
## Inventory rule (app mode)
|
|
6
|
+
|
|
7
|
+
When scanning central config/wiring, **every registered module, plugin, package, or top-level source area** must appear in `docs/codebase.md` (at least name, path, one-line purpose). Do not document only a “major” subset.
|
|
8
|
+
|
|
9
|
+
## `docs/setup.md`
|
|
10
|
+
|
|
11
|
+
**Create when:** multiple services, external dependencies, non-obvious env vars, or troubleshooting needs.
|
|
12
|
+
|
|
13
|
+
**Required sections:**
|
|
14
|
+
|
|
15
|
+
- Prerequisites
|
|
16
|
+
- Related systems (what must run locally: DB, queue, search, etc.)
|
|
17
|
+
- Install
|
|
18
|
+
- Environment — table from `.env.example` with columns: **Variable | Purpose | Used by** (subsystem name or config file path; grep config if needed)
|
|
19
|
+
- Run locally
|
|
20
|
+
- Verify — concrete checks (URLs, health endpoints, log lines) from README/scripts, or CONFIRM-WITH-TEAM
|
|
21
|
+
- Troubleshooting
|
|
22
|
+
|
|
23
|
+
## `docs/development-workflow.md`
|
|
24
|
+
|
|
25
|
+
**Create when:** split runtime, missing test script, hooks, i18n, external CMS/API, or non-obvious change paths.
|
|
26
|
+
|
|
27
|
+
**Required sections:**
|
|
28
|
+
|
|
29
|
+
- Scope of this repo
|
|
30
|
+
- Common changes
|
|
31
|
+
- Where to change what (table: change type → primary path(s))
|
|
32
|
+
- Quality checks (test/lint/build commands; note if lint/hooks absent)
|
|
33
|
+
- Link to deployment docs when they exist
|
|
34
|
+
|
|
35
|
+
**Include when discovered:**
|
|
36
|
+
|
|
37
|
+
- Generated artifact dirs and regen commands (`codegen`, OpenAPI, etc.)
|
|
38
|
+
- Schema/migration workflow order
|
|
39
|
+
- If multiple extension patterns exist (e.g. central registry vs module config), point to `docs/conventions.md` or document briefly here
|
|
40
|
+
|
|
41
|
+
## `docs/deployment.md`
|
|
42
|
+
|
|
43
|
+
**Create when:** CI/CD, multiple environments, remote deploy, or post-deploy tasks.
|
|
44
|
+
|
|
45
|
+
**Required sections:**
|
|
46
|
+
|
|
47
|
+
- Hosting/runtime overview
|
|
48
|
+
- Deploy triggers (branch, tag, manual dispatch — from workflows)
|
|
49
|
+
- Environment differences
|
|
50
|
+
- Release checklist (numbered, from CI/scripts)
|
|
51
|
+
- Artifacts — what is built and where it lands (if inferable)
|
|
52
|
+
- Post-deploy verification — smoke checks from workflows/scripts, or CONFIRM-WITH-TEAM
|
|
53
|
+
- Rollback notes — only if inferable from workflows/docs; else CONFIRM-WITH-TEAM
|
|
54
|
+
|
|
55
|
+
## `docs/architecture.md`
|
|
56
|
+
|
|
57
|
+
**Create when:** app has two or more of: database, queue/cache, search index, external APIs, multiple processes.
|
|
58
|
+
|
|
59
|
+
**Required sections:**
|
|
60
|
+
|
|
61
|
+
- Runtime model — processes and roles
|
|
62
|
+
- Core components — names from config (DB, cache, queue, search, etc.)
|
|
63
|
+
- Extension model — how domain logic is organized (plugins, modules, packages) and registration location
|
|
64
|
+
- Request/job flow — short numbered flow (e.g. API → logic → async job)
|
|
65
|
+
- Integration boundaries — external systems and env vars that configure them (not full API specs)
|
|
66
|
+
- Schema evolution — migrations/versioning if present, or N/A
|
|
67
|
+
|
|
68
|
+
## `docs/codebase.md`
|
|
69
|
+
|
|
70
|
+
**Create when:** application source exists (`src/`, `app/`, `lib/`, etc.).
|
|
71
|
+
|
|
72
|
+
**Required sections:**
|
|
73
|
+
|
|
74
|
+
- Top-level directories (table: path → purpose)
|
|
75
|
+
- Entry points and wiring — bootstrap files + central config path(s)
|
|
76
|
+
- **Complete inventory** — all top-level modules/plugins/packages under main source root and wired external packages (from central config)
|
|
77
|
+
- Where to change what (table: task → path(s))
|
|
78
|
+
- Tests — where unit/e2e/integration tests live, or N/A
|
|
79
|
+
|
|
80
|
+
## `docs/conventions.md`
|
|
81
|
+
|
|
82
|
+
**Create when:** framework extensions, plugins/modules, custom metadata/fields, workers, or codegen — and patterns are not obvious from layout alone.
|
|
83
|
+
|
|
84
|
+
**Suggested sections:**
|
|
85
|
+
|
|
86
|
+
- Extension patterns — how the app extends the framework; where registration happens (paths only)
|
|
87
|
+
- Configuration vs code — env vs config files vs database
|
|
88
|
+
- Schema/data changes — tool and order of operations
|
|
89
|
+
- Generated artifacts — paths and regen commands; do not hand-edit
|
|
90
|
+
- Common change recipes (table filled from scan):
|
|
91
|
+
|
|
92
|
+
| Task | Start here | Also touch |
|
|
93
|
+
| ---- | ---------- | ---------- |
|
|
94
|
+
|
|
95
|
+
- Multiple ways to add the same kind of metadata (e.g. central file vs module config): document both and when to use each, if the repo has both
|
|
96
|
+
|
|
97
|
+
## Optional topic files
|
|
98
|
+
|
|
99
|
+
Create only when triggered; link from `docs/SUMMARY.md` **Other** section.
|
|
100
|
+
|
|
101
|
+
| File | Trigger |
|
|
102
|
+
| ---------------------- | ------------------------------------------------------------------------- |
|
|
103
|
+
| `docs/integrations.md` | Three or more external systems, or non-obvious sync/webhooks |
|
|
104
|
+
| `docs/testing.md` | Multiple test types, custom fixtures, or heavy e2e setup |
|
|
105
|
+
| `docs/data-model.md` | Frequent schema/migration pain; complex custom persistence |
|
|
106
|
+
| `docs/security.md` | Non-obvious auth boundaries or PII handling (high-level only; no secrets) |
|
|
107
|
+
|
|
108
|
+
## Workspace glue docs
|
|
109
|
+
|
|
110
|
+
See `claude-template-workspace.md`. Do not copy app-repo install/deploy tables.
|
|
111
|
+
|
|
112
|
+
| File | Owns |
|
|
113
|
+
| --------------------------- | ------------------------------------------------ |
|
|
114
|
+
| `docs/system-overview.md` | Integration boundaries, data flow between repos |
|
|
115
|
+
| `docs/repositories.md` | Repo map, links to each app README and config |
|
|
116
|
+
| `docs/local-development.md` | Layout, clone/path overrides, startup order only |
|
|
117
|
+
| `docs/environments.md` | Cross-repo env alignment |
|
|
118
|
+
| `docs/release-flow.md` | Coordinated release order across manifest repos |
|
|
119
|
+
|
|
120
|
+
## Topic file rules
|
|
121
|
+
|
|
122
|
+
- Use content-based names (e.g. `api-design.md`, not `overview.md`).
|
|
123
|
+
- Prefer flat files unless there are two or more distinct documents in that area.
|
|
124
|
+
- Avoid copied content from other docs; reference source paths.
|
|
125
|
+
- One home per fact; link elsewhere.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Validation checklist
|
|
2
|
+
|
|
3
|
+
Run this before finishing a docs update. Also run `completeness-criteria.md`.
|
|
4
|
+
|
|
5
|
+
## Required checks
|
|
6
|
+
|
|
7
|
+
- Path from setup → develop → verify → deploy is documented or explicitly CONFIRM-WITH-TEAM.
|
|
8
|
+
- `CLAUDE.md` includes setup, commands, conventions, PR checklist, and guidance to update docs when setup/commands/env/deploy/integration changes.
|
|
9
|
+
- `docs/SUMMARY.md` matches files on disk (no phantom links).
|
|
10
|
+
- README links to `docs/SUMMARY.md` and relevant setup/workflow docs.
|
|
11
|
+
- No invented requirements, URLs, hosts, or release steps.
|
|
12
|
+
- `.env.example` or `.env.sample` is referenced when environment is discussed.
|
|
13
|
+
- All items in `completeness-criteria.md` for the detected mode are satisfied or CONFIRM-WITH-TEAM.
|
|
14
|
+
|
|
15
|
+
## App-mode checks
|
|
16
|
+
|
|
17
|
+
- Codebase map lists **all** top-level source areas and wired modules found in central config (not a partial sample).
|
|
18
|
+
- Env table includes **Used by** (consumer/subsystem or config path) or explicit CONFIRM-WITH-TEAM to add.
|
|
19
|
+
- Generated-code directories are named with regen command, or marked N/A.
|
|
20
|
+
- Multi-process runtime is documented in architecture, or explicitly single-process / N/A.
|
|
21
|
+
- External/wired packages are distinguished from in-repo modules.
|
|
22
|
+
- Agent Context Guide in SUMMARY includes task → doc routing.
|
|
23
|
+
|
|
24
|
+
## Workspace-mode checks
|
|
25
|
+
|
|
26
|
+
- Manifest/repo map is complete with pointers to each app’s docs.
|
|
27
|
+
- Startup order and cross-repo env/release are documented or CONFIRM-WITH-TEAM.
|
|
28
|
+
- Workspace docs do not duplicate app install/deploy/env tables.
|
|
29
|
+
|
|
30
|
+
## Single-source checks
|
|
31
|
+
|
|
32
|
+
- App repo docs own implementation detail; workspace docs point to app file paths.
|
|
33
|
+
- Workspace docs do not duplicate app repo setup/deploy internals.
|
|
34
|
+
- References in workspace docs use real repo folder names or manifest folder names.
|
|
35
|
+
- Commands and conventions are not duplicated at length in both `CLAUDE.md` and topic files (one primary home, link elsewhere).
|
|
36
|
+
|
|
37
|
+
## Quality checks
|
|
38
|
+
|
|
39
|
+
- Unknowns are marked with `> CONFIRM-WITH-TEAM: confirm with team.`
|
|
40
|
+
- Terminology is consistent across docs.
|
|
41
|
+
- Changes are concise and aligned with current code/config.
|
|
42
|
+
- Docs prefer path references over copying implementation detail.
|
|
@@ -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,160 @@
|
|
|
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 and the human's explicit go. Once the human has said go, send the merge right after `gh pr create` as one background command, `gh pr checks <n> --watch --interval 20 && gh pr merge <n> --squash --delete-branch --match-head-commit <sha>` with the head you verified: the guard's approval prompt then shows while the human is still there, not minutes later. `&&` keeps a red check from merging, and the head match keeps a later push from landing unapproved. If the watch stops on "no checks reported", send it again. Otherwise present merge / PR / cleanup options, unless the user's own `~/.claude/CLAUDE.md` grants a standing authorization. Docs ship with the change: if setup, commands, env, deploy or integrations changed, run the writing-documentation skill (`/docs`) in the same PR, or state that docs are N/A. After a major milestone, capture lessons as issues via the out-of-scope rule (`/retro`, where installed, proposes them; file only the ones the human picks); lessons about haus-shipped content go upstream as `needs-triage` issues through the issue-authoring skill's routing rule (catalog content to `WeAreHausTech/haus-workflow-catalog`, the haus program and the skills and agents it ships itself to `WeAreHausTech/haus-workflow`), project-local lessons stay in this repo's issues.
|
|
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`.
|
|
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
|
+
---
|
|
63
|
+
|
|
64
|
+
## Testing rules (non-negotiable)
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
| Layer | Minimum bar |
|
|
69
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------- |
|
|
70
|
+
| Pure logic / domain functions | TDD. Test first, code second. Cover happy path + edge cases + invariants. |
|
|
71
|
+
| UI components | One render-and-interact test per public component. Query by role/label, not class names. |
|
|
72
|
+
| Backend / data layer | One integration test per repository function, against a local emulator/test DB, never prod. |
|
|
73
|
+
| Critical user flows | One happy-path E2E per critical journey. |
|
|
74
|
+
|
|
75
|
+
**Verification gate:** run the suite for every touched layer and record the passing output in the task's verification block. Untested = unfinished.
|
|
76
|
+
|
|
77
|
+
**Highest-stakes logic** (financial, auth, medical, pedagogical, and whatever `workflow-config.md` names) is TDD-only: write the test from the spec before any implementation. No exceptions.
|
|
78
|
+
|
|
79
|
+
**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.
|
|
80
|
+
|
|
81
|
+
See `workflow-config.md` for this project's test commands.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Pre-commit hooks
|
|
86
|
+
|
|
87
|
+
Lefthook. `lefthook.yml` holds this project's stages; the `haus.lefthook-security` and `haus.lefthook-quality` templates hold the house baseline (typecheck, lint, format and secret scan on pre-commit, unit tests on pre-push). A web front end adds the `haus.lefthook-lighthouse` pre-push stage: Lighthouse CI against the production build, with its limits in `lighthouserc.yml`, so a slower page stops before the PR; a limit changes only in the same PR, with the reason. Never gate E2E in hooks. Write `fail_text` as instructions the agent can act on. Add CI when a second developer joins, a broken commit reaches main, or before the first public release.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Security defaults
|
|
92
|
+
|
|
93
|
+
- **Default deny.** Access-control layers (DB rules, RLS, middleware) start denied, opened explicitly.
|
|
94
|
+
- **Security rules are implementation.** Write them in the same task as the feature they protect.
|
|
95
|
+
- **Validate at boundaries.** Parse and validate user input, API responses, env vars with a schema library. Trust internal types downstream.
|
|
96
|
+
- **OWASP Top 10 check** before any new public route: injection, broken auth, IDOR, SSRF, misconfiguration.
|
|
97
|
+
- **Dependency audit** on a regular cadence. Block critical findings before release.
|
|
98
|
+
- **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.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Architecture Decision Records (ADR)
|
|
103
|
+
|
|
104
|
+
ADRs capture why a significant choice was made. The machine drafts; the human approves.
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
- Location: `docs/decisions/NNNN-kebab-case-title.md`. Index: `docs/decisions/README.md`, one line per ADR with its why, imported from `CLAUDE.md`.
|
|
109
|
+
- Write-once. To change one, add a new ADR that supersedes it. Statuses: `Proposed`, `Accepted`, `Deprecated`, `Superseded by ADR-XXXX`.
|
|
110
|
+
- Template and procedure: the `adr-decisions` skill. `haus decisions suggest` drafts from the diff; `haus decisions check` gates CI.
|
|
111
|
+
- **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.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Runbook
|
|
116
|
+
|
|
117
|
+
Maintain `docs/runbook.md`: one entry per non-obvious failure resolved, with the exact symptom, the root cause and the exact fix command.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Where facts live
|
|
122
|
+
|
|
123
|
+
Each fact has exactly one home. Never duplicate across layers.
|
|
124
|
+
|
|
125
|
+
| Layer | What goes here |
|
|
126
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------ |
|
|
127
|
+
| Hook, lint rule or CI check | A rule a machine can enforce. Build the check before writing prose. |
|
|
128
|
+
| `AGENTS.md` / `CLAUDE.md` | Stable rules, commands, conventions. Loaded every session, so keep it small. |
|
|
129
|
+
| `.claude/rules/*.md` with `paths:` | Rules that only matter in one part of the tree. Loaded when a matching file is read. |
|
|
130
|
+
| Auto memory (`MEMORY.md`) | Learnings the agent discovers (build quirks, debug insights, patterns). |
|
|
131
|
+
| ADR (`docs/decisions/`) | Architectural decisions, library choices, policy. Permanent, write-once. |
|
|
132
|
+
| Runbook (`docs/runbook.md`) | Failure modes + exact fix. Permanent, append-only. |
|
|
133
|
+
| `workflow-config.md` | Doc paths, test commands, highest-stakes, tool choices. Project-owned. |
|
|
134
|
+
|
|
135
|
+
This table outranks any skill's advice about what `CLAUDE.md`, `AGENTS.md` or a standards file should hold. A project's own path-scoped rules go in `.claude/rules/project/`. A change to haus-shipped content (a skill, agent, catalog rule, template or this standard), proposed by any skill or audit, becomes an upstream issue, never a local edit.
|
|
136
|
+
|
|
137
|
+
Rule of thumb: ADR for WHY, runbook for HOW TO FIX, memory for what was LEARNED, `CLAUDE.md` for the stable RULES, `workflow-config.md` for the project-specific VALUES.
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Subagents
|
|
142
|
+
|
|
143
|
+
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.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Out-of-scope capture
|
|
148
|
+
|
|
149
|
+
When you notice out-of-scope work worth keeping (a bug found mid-task, scope deferred from a plan, an idea a human explicitly asks you to record), spawn the `issue-creator` agent instead of a background-task chip. Chips die with the session; issues persist and reach the whole team.
|
|
150
|
+
|
|
151
|
+
- Findings and deferred scope: file automatically, labelled `needs-triage`. Ideas: only when a human asks; auto-filed ideas bury real bugs.
|
|
152
|
+
- Findings about haus-shipped content (a skill, agent, template, or this standard) route upstream through the issue-authoring skill's routing rule: catalog content to `WeAreHausTech/haus-workflow-catalog`, the haus program and the skills and agents it ships itself to `WeAreHausTech/haus-workflow`. Never put client code or client-identifying detail in an upstream issue.
|
|
153
|
+
- No GitHub issues available (no remote, `gh` missing or unauthenticated, issues disabled): create a background-task chip instead and say so in your final message.
|
|
154
|
+
- Nothing in a filed issue is implemented before human sign-off.
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Stop conditions (unattended mode)
|
|
159
|
+
|
|
160
|
+
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?
|