@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.
Files changed (117) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/cli.js +4764 -1767
  3. package/package.json +3 -1
  4. package/packages/agents/issue-creator.md +61 -0
  5. package/packages/configs/eslint/eslint.config.mjs +90 -0
  6. package/packages/configs/lighthouse/lighthouserc.yml +35 -0
  7. package/packages/configs/prettier/.prettierignore +28 -0
  8. package/packages/configs/prettier/prettier.config.cjs +12 -0
  9. package/packages/packages.yaml +81 -0
  10. package/packages/skills/adr-decisions/SKILL.md +114 -0
  11. package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
  12. package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
  13. package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
  14. package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
  15. package/packages/skills/bullmq-patterns/SKILL.md +63 -0
  16. package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
  17. package/packages/skills/bullmq-patterns/references/scope.md +30 -0
  18. package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
  19. package/packages/skills/i18next-patterns/SKILL.md +62 -0
  20. package/packages/skills/i18next-patterns/references/conventions.md +32 -0
  21. package/packages/skills/i18next-patterns/references/scope.md +29 -0
  22. package/packages/skills/i18next-patterns/references/workflow.md +39 -0
  23. package/packages/skills/issue-authoring/SKILL.md +191 -0
  24. package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
  25. package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
  26. package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
  27. package/packages/skills/laravel-nova-patterns/SKILL.md +55 -0
  28. package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
  29. package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
  30. package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
  31. package/packages/skills/nextauth-patterns/SKILL.md +48 -0
  32. package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
  33. package/packages/skills/nextauth-patterns/references/scope.md +33 -0
  34. package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
  35. package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
  36. package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
  37. package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
  38. package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
  39. package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
  40. package/packages/skills/qliro-patterns/SKILL.md +48 -0
  41. package/packages/skills/qliro-patterns/references/conventions.md +28 -0
  42. package/packages/skills/qliro-patterns/references/scope.md +30 -0
  43. package/packages/skills/qliro-patterns/references/workflow.md +46 -0
  44. package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
  45. package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
  46. package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
  47. package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
  48. package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
  49. package/packages/skills/strapi-patterns/SKILL.md +63 -0
  50. package/packages/skills/strapi-patterns/references/conventions.md +33 -0
  51. package/packages/skills/strapi-patterns/references/scope.md +29 -0
  52. package/packages/skills/strapi-patterns/references/workflow.md +47 -0
  53. package/packages/skills/vendure-app-patterns/SKILL.md +44 -0
  54. package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
  55. package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
  56. package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
  57. package/packages/skills/vendure-plugin-patterns/SKILL.md +55 -0
  58. package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
  59. package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
  60. package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
  61. package/packages/skills/whats-installed/SKILL.md +53 -0
  62. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
  63. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
  64. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
  65. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
  66. package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
  67. package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
  68. package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
  69. package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
  70. package/packages/skills/writing-documentation/SKILL.md +161 -0
  71. package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
  72. package/packages/skills/writing-documentation/references/claude-template.md +43 -0
  73. package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
  74. package/packages/skills/writing-documentation/references/summary-template.md +81 -0
  75. package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
  76. package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
  77. package/packages/templates/agentic-workflow-poc.md +180 -0
  78. package/packages/templates/agentic-workflow-standard.md +160 -0
  79. package/packages/templates/decision-template.md +27 -0
  80. package/packages/templates/decisions-ci-gate.yml +32 -0
  81. package/packages/templates/lefthook-branch-guard.yml +27 -0
  82. package/packages/templates/lefthook-lighthouse.yml +28 -0
  83. package/packages/templates/lefthook-quality.yml +34 -0
  84. package/packages/templates/lefthook-security.yml +27 -0
  85. package/packages/templates/start-here.md +72 -0
  86. /package/{library/global → packages}/agents/request-assessor.md +0 -0
  87. /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
  88. /package/{library/global → packages}/agents/request-designer.md +0 -0
  89. /package/{library/global → packages}/agents/request-scorer.md +0 -0
  90. /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
  91. /package/{library/global → packages}/agents/request-specifier.md +0 -0
  92. /package/{library/global → packages}/skills/haus-workflow/SKILL.md +0 -0
  93. /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
  94. /package/{library/global → packages}/skills/haus-workflow/references/init.md +0 -0
  95. /package/{library/global → packages}/skills/haus-workflow/references/new.md +0 -0
  96. /package/{library/global → packages}/skills/request/SKILL.md +0 -0
  97. /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
  98. /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
  99. /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
  100. /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
  101. /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
  102. /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
  103. /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
  104. /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
  105. /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
  106. /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
  107. /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
  108. /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
  109. /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
  110. /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
  111. /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
  112. /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
  113. /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
  114. /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
  115. /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
  116. /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
  117. /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
@@ -0,0 +1,33 @@
1
+ ## Naming conventions
2
+
3
+ - Queue names: kebab-case, descriptive of the work (`email-send`, `order-fulfillment`, `image-resize`)
4
+ - Queue module files: `queues/<name>.queue.ts` exporting the `Queue` instance
5
+ - Worker module files: `workers/<name>.worker.ts` exporting the `Worker` instance
6
+ - Job names within a queue: kebab-case (`send-welcome-email`, `retry-failed-payment`)
7
+ - Job data type: explicit TypeScript interface — `interface SendWelcomeEmailJob { userId: string }`
8
+ - Connection module: `lib/redis.ts` exporting `IORedis` factory (`createBullMqConnection()`)
9
+ - Scheduler / repeatable job IDs: stable keys so re-deploy doesn't duplicate (`repeat: { jobId: "daily-cleanup" }`)
10
+
11
+ ## Do / don't
12
+
13
+ DO: Use one `IORedis` instance per `Queue` and one per `Worker` (BullMQ requirement) — DON'T: share a single instance across both
14
+ DO: Set `Worker` `concurrency` explicitly (e.g. `{ concurrency: 5 }`) — DON'T: rely on the default of 1
15
+ DO: Set `removeOnComplete` / `removeOnFail` retention to bounded values — DON'T: keep all jobs forever (Redis memory bloat)
16
+ DO: Pass connection as a shared factory result, not a literal options object — DON'T: instantiate `new IORedis({...})` inline per queue
17
+ DO: Use `attempts` + `backoff` for retry policy — DON'T: implement retry by re-adding jobs manually
18
+ DO: For repeatable jobs use `jobId` to dedupe across deploys — DON'T: rely on `repeat.cron` alone (creates new entries each deploy)
19
+ DO: Type job data via `Queue<TData, TResult>` generics — DON'T: cast `as any` in processor
20
+ DO: Throw inside the processor to mark the job failed — DON'T: catch and return silently
21
+ DO: Close workers + queues in a `SIGTERM` handler — DON'T: rely on process exit alone
22
+
23
+ ## Forbidden patterns
24
+
25
+ NEVER: use `Redis` from the `redis` (node-redis) package — BullMQ requires `IORedis` from `ioredis`
26
+ NEVER: mix `bull` (v3) and `bullmq` packages in the same project — different APIs, queue shapes differ
27
+ NEVER: store secrets or PII in job data without server-side encryption — Redis backups may leak
28
+ NEVER: log full job data containing user input verbatim — PII leakage
29
+ NEVER: ignore `Worker` error events (`worker.on("error", ...)`) — silent failure
30
+ NEVER: skip the `connection` option when constructing `Queue` / `Worker` — BullMQ refuses to start
31
+ NEVER: run worker concurrency higher than Redis connection pool can support
32
+ NEVER: deploy without graceful shutdown — in-flight jobs marked failed mid-execution
33
+ NEVER: rely on `jobId` collision detection to dedupe long-running schedules without TTL — old jobs linger
@@ -0,0 +1,30 @@
1
+ # Scope
2
+
3
+ ## In-scope files and dirs
4
+
5
+ - `queues/**/*.ts` — `Queue` definitions
6
+ - `workers/**/*.ts` — `Worker` definitions and processors
7
+ - `lib/redis.ts` / `src/lib/redis.ts` — `IORedis` factory for BullMQ connections
8
+ - `src/main.ts` / `src/server.ts` / `app.ts` — lifecycle wiring (worker start, graceful shutdown)
9
+ - `package.json` — `bullmq`, `ioredis` versions
10
+ - `docker-compose.*` — Redis service when running locally
11
+ - `.env` / `.env.example` — `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_TLS`
12
+
13
+ ## Stack boundaries
14
+
15
+ - BullMQ 4.x and 5.x: 5.x has breaking changes — verify version before applying patterns
16
+ - `IORedis` is required — `redis` (node-redis) is not compatible
17
+ - Vendure backends use BullMQ via `@vendure/job-queue-plugin/package/bullmq` — wrap conventions apply
18
+ - NestJS apps use `@nestjs/bullmq` adapter — provider patterns differ but underlying queue semantics match
19
+ - Not in scope: Bull v3 (`bull` package), Agenda, in-process schedulers, Sidekiq, RabbitMQ
20
+
21
+ ## Triggers
22
+
23
+ - Adding a new queue or worker
24
+ - Changing job data shape (breaking change for in-flight jobs)
25
+ - Switching connection options (TLS, sentinel, cluster)
26
+ - Adding a repeatable / cron job
27
+ - Adding `attempts` / `backoff` retry policy
28
+ - Wiring graceful shutdown
29
+ - Migrating from Bull v3 to BullMQ
30
+ - Upgrading BullMQ major version (4 → 5)
@@ -0,0 +1,50 @@
1
+ # Workflow
2
+
3
+ ## Implementation steps
4
+
5
+ 1. For a new queue: create `queues/<name>.queue.ts` exporting `new Queue<TData>("<name>", { connection: createBullMqConnection() })`.
6
+ 2. Create the matching `workers/<name>.worker.ts` with a typed processor function and a fresh connection.
7
+ 3. Set explicit `concurrency` on the `Worker` based on workload and Redis capacity.
8
+ 4. Set retention via `defaultJobOptions: { removeOnComplete: 1000, removeOnFail: 5000 }`.
9
+ 5. Add retry policy via `attempts: 3, backoff: { type: "exponential", delay: 1000 }` on job options.
10
+ 6. For repeatable jobs, set a stable `jobId` in `repeat` options so redeploys don't duplicate.
11
+ 7. Wire graceful shutdown: on `SIGTERM` call `await worker.close()` and `await queue.close()` before exiting.
12
+ 8. Type the queue with generics: `new Queue<JobData, JobResult>("...", ...)`.
13
+ 9. Add a regression test that enqueues a job and asserts the worker processes it (use a test Redis or `ioredis-mock`).
14
+
15
+ ## Commands
16
+
17
+ ```bash
18
+ # Local Redis (Docker)
19
+ docker-compose up redis
20
+
21
+ # BullMQ Board (admin UI) — only run in dev/staging, never expose to prod
22
+ yarn bullmq-board # or @bull-board/* if integrated
23
+
24
+ # Inspect queue state via redis-cli
25
+ redis-cli KEYS "bull:<queue-name>:*"
26
+ redis-cli LLEN "bull:<queue-name>:waiting"
27
+ redis-cli LLEN "bull:<queue-name>:active"
28
+
29
+ # Drain a stuck queue (DESTRUCTIVE — confirm before running in prod)
30
+ redis-cli DEL "bull:<queue-name>:waiting"
31
+
32
+ # Tests
33
+ yarn vitest run workers/__tests__/<name>.test.ts
34
+ yarn jest workers/<name>.test.ts
35
+ ```
36
+
37
+ ## Validation checklist
38
+
39
+ - [ ] Queue + Worker each use a fresh `IORedis` instance (not shared)
40
+ - [ ] `concurrency` set explicitly on every `Worker`
41
+ - [ ] `removeOnComplete` / `removeOnFail` retention bounded
42
+ - [ ] Retry policy (`attempts` + `backoff`) declared on jobs that need it
43
+ - [ ] Repeatable jobs carry stable `jobId` to dedupe across deploys
44
+ - [ ] Graceful shutdown on `SIGTERM` closes workers + queues
45
+ - [ ] Job data shape typed via generics; no `as any` casts
46
+ - [ ] No PII logged from job data
47
+ - [ ] `Worker` `error` event handler logs to observability (Sentry / pino)
48
+ - [ ] Connection uses `IORedis` from `ioredis` package, not `redis` (node-redis)
49
+ - [ ] Bull (v3) and BullMQ not mixed in the same project
50
+ - [ ] Regression test added before fixing a queue/worker bug
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: i18next-patterns
3
+ description: i18next router. Use for translation namespace structure, key conventions, SSR-safe loading, and locale switching.
4
+ ---
5
+
6
+ # i18next Patterns
7
+
8
+ ## Use when
9
+
10
+ - task adds, modifies, or restructures translation keys / namespaces
11
+ - task touches i18next config (`i18n.ts`, `i18next.config.ts`, language detector)
12
+ - task wires `react-i18next`, `next-i18next`, or App Router server-side translations
13
+ - task adds locale routing or locale-aware redirects
14
+
15
+ ## Do not use when
16
+
17
+ - project uses a non-i18next translation system (FormatJS, Lingui)
18
+ - task is static content with no locale dimension
19
+ - task is purely backend with no user-facing copy
20
+
21
+ ## Inspect first
22
+
23
+ - `i18n.ts` / `lib/i18n.ts` — init config, namespaces, fallback, detection
24
+ - `public/locales/<lang>/<ns>.json` (next-i18next pattern) or `locales/<lang>/<ns>.json`
25
+ - React/Vue consumer: `useTranslation(ns)` call sites and current key shape
26
+ - SSR / App Router setup if applicable (`getServerSideTranslations`, custom loader)
27
+ - language detector config: query > cookie > localStorage > navigator
28
+
29
+ ## Avoid mistakes
30
+
31
+ - duplicating keys across namespaces — pick one and reference via cross-ns reference
32
+ - hard-coding strings instead of translating — breaks locale completeness checks
33
+ - loading every namespace on every page — set `ns` list per route
34
+ - mixing `t(key)` calls with template literals — disables key extraction
35
+ - relying on `react-i18next` `Suspense` without a Suspense boundary — blank UI
36
+
37
+ ## Router
38
+
39
+ 1. Load `references/conventions.md` for namespace, key, and interpolation patterns.
40
+ 2. Load `references/scope.md` for in-scope files and SSR-vs-client boundaries.
41
+ 3. Load `references/workflow.md` only for locale add/remove or missing-key diagnosis flow.
42
+ 4. Keep keys flat, namespaces small, server translations explicit per route.
43
+
44
+ ## References
45
+
46
+ - references/conventions.md
47
+ - references/scope.md
48
+ - references/workflow.md
49
+
50
+ ## Reference Documentation
51
+
52
+ Up-to-date API docs are cached locally by haus.
53
+
54
+ To refresh (uses etag — fast if unchanged):
55
+
56
+ ```bash
57
+ haus fetch-refs --id haus.i18next-patterns
58
+ ```
59
+
60
+ Then read `.haus-workflow/llms-cache/www-i18next-com-llms-txt.md` for current API reference.
61
+
62
+ Source: https://www.i18next.com/llms.txt
@@ -0,0 +1,32 @@
1
+ ## Naming conventions
2
+
3
+ - Namespace files: `locales/<lang>/<ns>.json` (e.g. `locales/sv/common.json`, `locales/en/product.json`)
4
+ - Namespace names: lowercase, singular, kebab-case (`common`, `product`, `checkout`, `account-settings`)
5
+ - Translation keys: dot-separated camelCase (`button.signIn`, `error.network.timeout`)
6
+ - Interpolation: `{{variable}}` double-curly — never `${var}` template literals
7
+ - Plurals: i18next standard suffixes — `_one`, `_other`, `_zero` (per CLDR rules)
8
+ - Context: `_<context>` suffix (`order.status_pending`, `order.status_shipped`)
9
+ - Component-scoped namespaces: match component name kebab-cased (`ProductCard` → `product-card`)
10
+ - React hook usage: `const { t } = useTranslation(["common", "product"])` — declare needed namespaces
11
+
12
+ ## Do / don't
13
+
14
+ DO: Declare all `ns` used by a route up front in `useTranslation([...])` — DON'T: pull in `defaultNS` for one key
15
+ DO: Use `Trans` component for inline JSX in strings — DON'T: build HTML strings via concatenation
16
+ DO: Add `i18next-parser` to extract keys automatically — DON'T: maintain key lists by hand
17
+ DO: Set `fallbackLng` to the project's source locale (e.g. `sv`) — DON'T: leave `en` as fallback when source is Swedish
18
+ DO: Use `returnNull: false` and explicit fallback `t(key, "default text")` for missing keys — DON'T: render `null`
19
+ DO: For Next.js App Router, use server-side translations via `getServerTranslations(lng, ns)` — DON'T: rely on client-side hydration alone for SEO content
20
+ DO: Pluralize via `t(key, { count })` — DON'T: write `if (count === 1) t("x_one") else t("x_other")`
21
+ DO: Lazy-load namespaces per-route — DON'T: load all namespaces on app boot
22
+
23
+ ## Forbidden patterns
24
+
25
+ NEVER: hardcoded UI strings in components after i18next is wired — broken locale completeness
26
+ NEVER: template literal interpolation inside `t(key)` — extractors can't parse it
27
+ NEVER: dynamic key construction without an enum/registry (`t(\`error.\${type}\`)`) — extraction misses keys
28
+ NEVER: change a translation key without updating every locale file — silent fallback to source locale
29
+ NEVER: ship locale files with unresolved markers or untranslated source strings — production leak
30
+ NEVER: rely on `localStorage` for locale persistence in SSR routes — server can't read it; hydration mismatch
31
+ NEVER: load remote translations synchronously in critical render path — UI blocks on network
32
+ NEVER: write keys with spaces or special chars — breaks dot-path lookups
@@ -0,0 +1,29 @@
1
+ # Scope
2
+
3
+ ## In-scope files and dirs
4
+
5
+ - `i18n.ts` / `lib/i18n.ts` — init config, namespaces, fallback
6
+ - `i18next.config.ts` (next-i18next legacy)
7
+ - `locales/**/*.json` or `public/locales/**/*.json` — translation files
8
+ - `app/i18n/**` (App Router) — server-side translation setup
9
+ - `next.config.js` `i18n` config (Pages Router only)
10
+ - React/Vue consumer files calling `useTranslation` / `<Trans>` / `$t`
11
+ - `i18next-parser.config.js` — key extraction config
12
+
13
+ ## Stack boundaries
14
+
15
+ - i18next + react-i18next: standard React integration, client + SSR
16
+ - next-i18next: Pages Router specific; deprecated for App Router projects
17
+ - App Router SSR: custom `getServerTranslations` pattern, no next-i18next
18
+ - Vue: `vue-i18n` (different API surface, not in scope for this skill)
19
+ - FormatJS / Lingui: out of scope; different mental model
20
+
21
+ ## Triggers
22
+
23
+ - Adding a new locale
24
+ - Adding or renaming a translation namespace
25
+ - Migrating Pages Router next-i18next to App Router server translations
26
+ - Adding key extraction (`i18next-parser`)
27
+ - Adding context-aware or plural-aware keys
28
+ - Switching locale detector strategy
29
+ - Adding language-aware routing (locale prefix in URL)
@@ -0,0 +1,39 @@
1
+ # Workflow
2
+
3
+ ## Implementation steps
4
+
5
+ 1. For a new translation key: add it to the source locale file first, then to every other locale (use parser to scaffold).
6
+ 2. For a new namespace: create `locales/<lang>/<ns>.json` per locale; add `<ns>` to `useTranslation([...])` calls.
7
+ 3. For a new locale: copy the source locale folder, translate, add to `supportedLngs` in i18n config.
8
+ 4. For App Router (Next.js 13+), use a server-side `getServerTranslations` helper; never rely on client-side hydration for above-the-fold copy.
9
+ 5. Configure `i18next-parser` (`i18next-parser.config.js`) and run `yarn i18n:extract` to scaffold missing keys.
10
+ 6. Verify locale completeness with the parser's `--fail-on-update` mode in CI.
11
+ 7. When changing key shape (rename, restructure), update all locale files atomically — don't ship a partial migration.
12
+ 8. For pluralization, use `t(key, { count })` and rely on i18next's CLDR-driven suffix selection.
13
+
14
+ ## Commands
15
+
16
+ ```bash
17
+ yarn dev # local dev with i18next debug logs (set debug: true in dev only)
18
+ yarn i18n:extract # run i18next-parser to find missing keys
19
+ yarn i18n:check # CI mode — fail if locale files drift from source
20
+ yarn build # production build (locale files bundled or fetched lazily)
21
+
22
+ # Key inspection
23
+ grep -r "t(\"<key>\"" src/ # find usage of a specific key
24
+ grep -rL "\"<key>\"" locales/ # find locales missing a key
25
+ ```
26
+
27
+ ## Validation checklist
28
+
29
+ - [ ] Every key present in source locale also present in every other supported locale
30
+ - [ ] No hard-coded user-facing strings in components touched by the change
31
+ - [ ] All `useTranslation([...])` calls declare every namespace they consume
32
+ - [ ] No template-literal interpolation inside `t(key)` calls
33
+ - [ ] Pluralization handled via `t(key, { count })`, not manual `if/else`
34
+ - [ ] App Router routes use server-side translations for SEO-critical content
35
+ - [ ] No `defaultNS` fallback being used implicitly for new code
36
+ - [ ] `i18next-parser` ran clean — no untracked keys, no orphans
37
+ - [ ] Fallback locale set explicitly (`fallbackLng`)
38
+ - [ ] Locale completeness check passes in CI
39
+ - [ ] Regression test added before fixing an i18n bug
@@ -0,0 +1,191 @@
1
+ ---
2
+ name: issue-authoring
3
+ description: Use when filing bugs or review findings, capturing scope deferred out of a plan, or recording ideas as GitHub issues in the two-audience house format — a short human section for approval first, then a technical section deep enough to implement from.
4
+ ---
5
+
6
+ # Issue Authoring
7
+
8
+ Every issue has two audiences in one body: a human section readable in under a
9
+ minute (no file paths, no jargon, no code) that a decision-maker can say yes or
10
+ no to, then a technical section, arbitrarily deep, for whoever picks it up after
11
+ approval.
12
+
13
+ **Every issue is a proposal, not a work order. Nothing filed may be implemented
14
+ before a human signs off.**
15
+
16
+ Exception to the format, not to the rule above: issues labelled `wayfinder:` are planning artifacts a human asked for
17
+ by typing `/wayfinder`. They skip the two-audience format and `needs-triage`;
18
+ file them as `references/issue-tracker.md` ("Wayfinding operations") says.
19
+
20
+ ## Automation asymmetry
21
+
22
+ - `finding` / `deferred`: may be filed automatically — bounded by real work.
23
+ Label everything auto-filed `needs-triage`.
24
+ - `idea`: file ONLY on explicit human request. Idea volume is unbounded —
25
+ auto-filed ideas bury real bugs within weeks.
26
+
27
+ ## Routing: which repo gets the issue
28
+
29
+ Decide the destination per item BEFORE anything else — availability, labels,
30
+ dedupe, and create all run against it.
31
+
32
+ - **Project-local** (default): the finding concerns this repository's own
33
+ code, config, or process. File into the current repo, unchanged.
34
+ - **Catalog-content**: the finding concerns content haus shipped — a skill,
35
+ agent, rule, template, or the workflow standard itself (files haus
36
+ installed under `.claude/skills/`, `.claude/agents/`, `.claude/templates/`,
37
+ the catalog rule folders under `.claude/rules/`, or
38
+ `.haus-workflow/WORKFLOW.md`). A local issue about shipped content is
39
+ invisible upstream and the defect ships to every other consumer, so file it
40
+ where it is fixed once for everyone:
41
+ `gh issue create -R WeAreHausTech/haus-workflow-catalog …`. Already in that
42
+ repo, routing is a no-op — file locally.
43
+ - **Haus CLI**: the finding concerns the haus program rather than catalog
44
+ content it installs: a command's behaviour, output or exit code, a wrong or
45
+ missing finding from doctor, the decision gate or the CI gate, a guard hook,
46
+ a file the CLI writes and owns (`.claude/settings.json`,
47
+ `.claude/rules/haus.md`, the managed blocks in `CLAUDE.md`,
48
+ `.haus-workflow/haus.lock.json`), or a skill or agent the CLI ships itself
49
+ (in `~/.claude/skills/` or `~/.claude/agents/` by default, with
50
+ `source=@haus-tech/haus-workflow@<version>` in its `haus_managed`
51
+ frontmatter). File it where the CLI is fixed:
52
+ `gh issue create -R WeAreHausTech/haus-workflow …`. Already in that repo,
53
+ routing is a no-op: file locally. When it is unclear whether the CLI or the
54
+ catalog owns a finding, route it to the catalog.
55
+
56
+ Catalog- and CLI-routed issues cross a repo boundary. NEVER include client code,
57
+ secrets, internal URLs, or client-identifying paths: name the shipped item and
58
+ its path as shipped in the catalog (for a Haus CLI finding, the command, skill
59
+ or agent and the haus version), describe the defect against the shipped
60
+ content, and call the discovering project only "a consumer repo".
61
+
62
+ If upstream filing is unavailable (no access, unauthenticated, issues
63
+ disabled), do not drop the finding: file it project-local with one extra
64
+ header line, and say so in your report —
65
+ `> **Routing:** catalog-content — upstream filing failed (<reason>); re-file to WeAreHausTech/haus-workflow-catalog`
66
+ For a Haus CLI finding the line reads `> **Routing:** haus-cli, upstream filing failed (<reason>); re-file to WeAreHausTech/haus-workflow`.
67
+
68
+ A retro candidate is a finding like any other: route it by what it is about.
69
+ File one issue per candidate the human picks, and none for the rest.
70
+
71
+ ## Common header (every issue)
72
+
73
+ ```markdown
74
+ > **Type:** finding | deferred | idea · **Severity/Size:** <value> · **Source:** <where + date>
75
+ > **Status:** Awaiting human approval — do not implement before sign-off.
76
+ > **Failing test exists:** Yes — `<path>` / No / n/a
77
+ ```
78
+
79
+ Keep the header even with native fields set — the approval gate and failing-test
80
+ flag have no native equivalent.
81
+
82
+ ### Recording approval
83
+
84
+ **Read `references/recording-approval.md` before touching a `Status` line** — it holds
85
+ the named-evidence bar (without that evidence you edit nothing and start nothing), the
86
+ exact approved-status format, and the read-modify-write recipe that keeps `gh issue edit`
87
+ from wiping the technical section.
88
+
89
+ ## Templates
90
+
91
+ ### finding — a bug or review finding
92
+
93
+ Sections, in order: `Summary` · `Consequences` · `What's affected` · `Risks` ·
94
+ `Is it visible in the application?` · `---` · `Technical description`
95
+ containing `Reproduction`, `Root cause`, `Suggested fix`, `Verification`,
96
+ `Related`.
97
+
98
+ Rules:
99
+
100
+ - Never claim a reproduction that was not performed — write "code-read, not
101
+ reproduced" explicitly.
102
+ - When a pattern repeats, note every occurrence.
103
+ - Record environment traps (e.g. reproduces only in a bundled build, not via
104
+ raw imports — omitting that sends a fixer down the wrong path).
105
+ - If the finding implies an architecture decision, draft or reference an ADR
106
+ via the `adr-decisions` skill and link it under `Related`.
107
+
108
+ ### deferred — scope pushed out of a plan
109
+
110
+ Sections: `What was deferred` · `Why it was deferred` (the decision and who
111
+ made it) · `What we are doing instead` · `What would make this worth doing`
112
+ (the trigger — the critical field: it lets the item be re-evaluated
113
+ later) · `Rough size` · `---` · `Technical notes` ·
114
+ `Related plan/ADR`.
115
+
116
+ No root cause or reproduction — there is no defect.
117
+
118
+ ### idea — the lightest template
119
+
120
+ Sections: `What` (one sentence) · `Why / what problem it solves` ·
121
+ `Rough size` (a guess is fine) · `What would make this worth doing` ·
122
+ `Context when the idea came up` (where in the code, what task was in
123
+ progress — what makes the idea recoverable six months later).
124
+
125
+ ## Operating rules
126
+
127
+ - Titles in plain language a non-developer understands — no jargon, finding IDs,
128
+ or file paths.
129
+ - One issue per item; merge only on explicit request.
130
+ - Never invent detail. Unverified reproductions or root causes must be
131
+ labelled as such. An issue with honest gaps beats a confident guess.
132
+ - `has-failing-test` label wherever a red test exists.
133
+ - Dedupe search scope: open and closed issues, titles and bodies, in English
134
+ and Swedish (`gh issue list --search`, `gh search issues`).
135
+ - **Keep dedupe queries to 2–3 distinctive words, and run several narrow ones
136
+ rather than one long one.** GitHub free-text terms are ANDed within a single
137
+ indexed field, so a query mixing title-only and body-only words matches
138
+ nothing and silently reports "no duplicate". Verified: an issue whose title
139
+ matched `placeholder bug report` and whose body matched `skill verification`
140
+ was returned by each query alone and by neither combined. A long query is the
141
+ failure mode that manufactures duplicates.
142
+ - Run both engines: `gh issue list --search` and `gh search issues` disagree on
143
+ the same query; treat a hit from either as a duplicate.
144
+
145
+ ## Procedure
146
+
147
+ 1. Route each item (Routing section above), then confirm GitHub issues are
148
+ available on its destination:
149
+ `gh repo view [<owner>/<repo>] --json nameWithOwner,hasIssuesEnabled`.
150
+ If this fails for the local repo (no GitHub remote, `gh` missing or
151
+ unauthenticated) or reports `hasIssuesEnabled: false`, abort immediately —
152
+ file nothing — and tell whoever invoked you to create a background-task
153
+ chip instead. If it fails only for the upstream repo, fall back to
154
+ project-local filing with the routing marker line instead of aborting.
155
+ 2. **Read `references/native-metadata.md` before running the detection query** — it
156
+ holds the detection query itself, the union inline-fragment gotcha, the truncation
157
+ and permission cases, the native-vs-fallback table, and the mutations. Do not
158
+ improvise the query from memory — the issue-fields schema is still rolling out,
159
+ and a guessed field name errors in a way that reads as "this repo has no issue
160
+ fields". Run the detection query; pick native or fallback per row of that table.
161
+ Confirm every label you intend to pass exists on the destination repo
162
+ (`gh label list [-R <owner>/<repo>]`) — a missing
163
+ label makes `gh issue create` fail outright. Do NOT create the missing ones:
164
+ labels are shared repo taxonomy, creating them unattended is exactly the kind
165
+ of unapproved change this skill exists to avoid. Drop the missing ones, keep
166
+ the rest, and list every label you skipped so a human can add them
167
+ deliberately. If `needs-triage` itself is missing, still file — then say so
168
+ prominently, because the issue is now untriaged with nothing marking it.
169
+ 3. Draft the body to a temp file using the matching template. **YOU MUST write
170
+ EVERY issue body through a QUOTED heredoc — `cat > "$f" <<'EOF'` — never
171
+ unquoted:** this draft, the approval-record edit, the step-7 cross-reference
172
+ pass, any body write at all. Unquoted, it expands `$VAR`, `${...}`,
173
+ `` ` ` `` and `$(...)` inside the code snippets the technical section quotes,
174
+ silently corrupting the issue and potentially executing repo-derived commands.
175
+ 4. Dedupe search — IMMEDIATELY before `gh issue create`, not at batch start
176
+ (a batch-start check goes stale and produces duplicates, as it did in
177
+ the pilot). Search the destination repo: `gh issue list -R <owner>/<repo> --search`,
178
+ `gh search issues --repo <owner>/<repo>`.
179
+ 5. `gh issue create [-R <owner>/<repo>] --title '<plain title>' --body-file <tmp> --label needs-triage [--label …]`
180
+ 6. Query the created issue's `viewerCanType`/`viewerCanSetFields`/`viewerCanLabel`;
181
+ set native type/priority/effort only where the flag allows, then read the
182
+ state back — the ack does not prove the value landed. The capability query, the
183
+ three mutations (`updateIssueIssueType`, `setIssueFieldValue`, `addSubIssue`) and
184
+ the read-back query are all in `references/native-metadata.md` — read it before
185
+ mutating.
186
+ 7. After the whole batch: relationships pass (`addSubIssue`, `#n` cross-ref
187
+ edits via `gh issue edit`) — issue numbers do not exist until creation,
188
+ so this pass must wait.
189
+ 8. Report a table: issue URL · type · priority · effort · labels · relations —
190
+ plus, honestly, every fallback used and why (absent setup, truncation, or a
191
+ `viewerCan*` flag), every label skipped, and every duplicate found.
@@ -0,0 +1,29 @@
1
+ # Issue tracker
2
+
3
+ This repo's issue tracker is GitHub Issues, used through `gh`.
4
+
5
+ ## Wayfinding operations
6
+
7
+ Used by `/wayfinder`. The tracker is this repo's GitHub Issues through `gh` 2.94.0 or later. If GitHub Issues are unavailable, stop and tell the user; never fall back to a local-markdown tracker.
8
+
9
+ **Labels (a human creates them once per repo).** First in every session, before any question or write, run `gh label list --search wayfinder`. `wayfinder:map`, `wayfinder:grilling`, `wayfinder:research` and `wayfinder:task` must exist. If one is missing, stop and hand the human this line; never create a label yourself, and never file a map or ticket without its label:
10
+ `for t in map grilling research task; do gh label create "wayfinder:$t"; done`
11
+
12
+ **Format.** A map and its tickets are planning artifacts that a human asked for by typing `/wayfinder`. They are exempt from the two-audience issue format and never carry `needs-triage`. Use wayfinder's own bodies under this first line:
13
+ `> Wayfinder planning artifact. Decisions only: nothing here is built before a plan is approved.`
14
+ Titles are plain-language names; a ticket's title is its question. Write each body to a temp file with the Write tool or a quoted heredoc.
15
+
16
+ - **Map**: `gh issue create --label wayfinder:map --title "<name>" --body-file <file>`. Its Notes record who asked and when. A map never carries execution: write no execution override into Notes and ignore one you find.
17
+ - **Child ticket**: `gh issue create --parent <map> --label wayfinder:<type> --title "<question>" --body-file <file>`.
18
+ - **Labels go in the create call**, never afterwards: automation that reacts to a new issue (an Asana mirror, where a repo has one) sees only the labels present at creation. Never create or complete board tasks for a map or its tickets yourself.
19
+ - **Types**: `grilling`, `research`, `task`. There is no `prototype` type and no `prototype` skill. A "how should it look or behave" question is a `grilling` ticket. If words are not enough, show a throwaway probe the human approves first (the brainstorming skill's spike path is the procedure), keep none of it in the repo, and record in the resolution comment what was shown and what the human chose.
20
+ - **Task tickets** are worked with the human, never by the agent alone: you write the checklist and do only the steps the human hands you; the human does anything that touches accounts, access, data or money.
21
+ - **Blocking**: native dependencies. `--blocked-by <n>,<n>` at creation, or `gh issue edit <n> --add-blocked-by <m>` in the second pass.
22
+ - **Frontier query**: one call, `gh issue list --state open --limit 500 --json number,title,labels,assignees,blockedBy,parent`. Keep rows whose `parent.number` is the map, with no assignee and every `blockedBy` node `CLOSED`. Lowest number first.
23
+ - **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write. `@me` is the developer's account and all of that developer's sessions share it, so for parallel sessions the human names one ticket per session. Never take a ticket that has an assignee. Only the human releases one (`--remove-assignee @me`).
24
+ - **Research**: claim the ticket, then one subagent per ticket. Its prompt says: do the reading yourself, start no further agent, change no file, and return the findings with a source link per claim. The subagent may use the research skill's method, but not its background agent or its file: this prompt wins. No `research/<name>` branch, no file in the repo, no commit, push or pull request. The session that started the subagents waits for every one of them, then posts each answer as its ticket's resolution comment, closes the ticket and adds the map line, one ticket at a time. Charting ends only when every research ticket it started is resolved.
25
+ - **Resolve**: on a ticket worked with the human, show the resolution and post it once the human confirms. `gh issue comment <n> --body-file <file>`, then `gh issue close <n>`, then add the pointer line to the map: read the body fresh (`gh issue view <map> --json body --jq .body`), add the line unless another session already added it, `gh issue edit <map> --body-file <file>`, and read it back to check that your line is there. A session that writes the map at the same moment can still drop a line, so as your last step, after every other map edit, list the map's closed children (`gh issue list --state closed --limit 500 --json number,title,stateReason,parent`, keeping rows whose `parent.number` is the map): every child closed as completed needs a line in Decisions so far. Add each missing line the same way, from that ticket's resolution comment when it is not yours.
26
+ - **Out of scope or invalidated**: `gh issue close <n> --reason "not planned" --comment "<why>"`. An out-of-scope ticket also gets a line in the map's Out of scope section; an invalidated one gets no map line, and its comment names the ticket whose decision retired it. Never `gh issue delete`. Work worth keeping for a later effort goes through the house out-of-scope rule (`issue-creator`), not the map.
27
+ - **Repo edits**: the only files a wayfinder session changes are the glossary and decision records. Make those on a branch or worktree, never on `main`, and commit only when the human says so. A ticket's resolution comment is the record of its interview, so a wayfinder session writes no interview record under `docs/research/`, even where the standard or the grilling skill says to write settled answers to the repo.
28
+ - **Lasting decisions**: record a hard-to-reverse answer with the `adr-decisions` skill in `docs/decisions/` and link it from the resolution comment. Never write `docs/adr/`.
29
+ - **Map clear**: stop. Tell the human the map is ready for brainstorming or writing-plans and give its URL. The human closes the map, or asks a session to, once the plan in `docs/plans/<slug>.md` names it as its source.
@@ -0,0 +1,122 @@
1
+ # Native metadata
2
+
3
+ Loaded on demand from `SKILL.md` (procedure steps 2 and 6): the detection query, the
4
+ per-issue capability query, the three mutations, the native-vs-fallback table, and the
5
+ read-back that confirms a value actually landed.
6
+
7
+ Detect support first — many repos have neither issue types nor fields enabled:
8
+
9
+ ```bash
10
+ gh api graphql -f owner='<owner>' -f repo='<repo>' -f query='
11
+ query($owner:String!,$repo:String!){
12
+ repository(owner:$owner,name:$repo){
13
+ issueTypes(first:20){ pageInfo { hasNextPage } nodes { id name } }
14
+ issueFields(first:20){ pageInfo { hasNextPage } nodes {
15
+ __typename
16
+ ... on IssueFieldSingleSelect { id name options { id name } }
17
+ } }
18
+ }
19
+ }'
20
+ ```
21
+
22
+ The inline fragment is required: `issueFields` is a union, so `__typename` alone
23
+ returns type names with no ids. Field and option ids are per-repo — read them
24
+ from this query, never carry them between repos.
25
+
26
+ If this query errors or returns empty nodes, use the fallback column — the
27
+ issue-fields schema is still rolling out, so introspect and adjust, never guess.
28
+
29
+ Truncation is a third case: if either `pageInfo.hasNextPage` is `true` and what
30
+ you need is not on the page you got, page through with `after:` — the ids are
31
+ missing to page size, not to missing setup. If you still fall back, report it as
32
+ truncation, not as "this repo has no issue fields".
33
+
34
+ Permission is a fourth case the detection query cannot answer: the write flags
35
+ live on `Issue`, not on the repository or the field, so they exist only once an
36
+ issue does (`Repository.viewerCanSeeIssueFields` is visibility, not write
37
+ access). So between `gh issue create` and setting native metadata, ask the
38
+ created issue what this token may do:
39
+
40
+ ```bash
41
+ gh api graphql -f owner='<owner>' -f repo='<repo>' -F number=<n> -f query='
42
+ query($owner:String!,$repo:String!,$number:Int!){
43
+ repository(owner:$owner,name:$repo){
44
+ issue(number:$number){ viewerCanType viewerCanSetFields viewerCanLabel }
45
+ }
46
+ }'
47
+ ```
48
+
49
+ Degrade per capability instead of attempting and failing — a mutation that 403s
50
+ fails _after_ earlier steps have already landed:
51
+
52
+ - `viewerCanType: false` → skip `updateIssueIssueType`; use the type label fallback.
53
+ - `viewerCanSetFields: false` → skip `setIssueFieldValue`; use the `severity:`
54
+ label fallback for Priority and leave Effort in the `Rough size` section.
55
+ - `viewerCanLabel: false` → no labels can be applied at all (a `--label` on
56
+ `gh issue create` will have failed for the same reason — re-create without
57
+ them). The issue then carries no `needs-triage`: say so prominently in your
58
+ report, because nothing marks it as untriaged.
59
+
60
+ These flags are per-issue, not per-field: one `viewerCanSetFields` answers for
61
+ every issue field, so it can never say Priority is writable but Effort is not.
62
+
63
+ | Metadata | Native (primary) | Fallback — and its cause |
64
+ | ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
65
+ | Type | `updateIssueIssueType`: finding→Bug, idea→Feature, deferred→Task | label `finding`/`idea`/`deferred` — no types, or `viewerCanType: false` |
66
+ | Priority | `setIssueFieldValue` on the Priority field (from severity) | label `severity: high\|medium\|low` — no fields, or `viewerCanSetFields: false` |
67
+ | Effort | `setIssueFieldValue` on the Effort/Size field (from Rough size) | `Rough size` section — same causes (one flag covers both) |
68
+ | Relationships | `addSubIssue` + `#n` cross-refs, second pass after the batch | `Related` body section |
69
+ | Triage | label `needs-triage` on everything auto-filed | none — `viewerCanLabel: false` leaves no triage marker |
70
+
71
+ Mutation shapes:
72
+
73
+ ```bash
74
+ # Set issue type (issue node id + type node id from detection)
75
+ gh api graphql -f issue='<issueNodeId>' -f type='<issueTypeId>' -f query='
76
+ mutation($issue:ID!,$type:ID!){
77
+ updateIssueIssueType(input:{issueId:$issue,issueTypeId:$type}){ issue { number } }
78
+ }'
79
+
80
+ # Parent/child relationship
81
+ gh api graphql -f parent='<parentNodeId>' -f child='<childNodeId>' -f query='
82
+ mutation($parent:ID!,$child:ID!){
83
+ addSubIssue(input:{issueId:$parent,subIssueId:$child}){ issue { number } }
84
+ }'
85
+
86
+ # Priority + Effort in one call. Element shape: fieldId + one typed value key.
87
+ gh api graphql -f issue='<issueNodeId>' -f query='
88
+ mutation($issue:ID!){
89
+ setIssueFieldValue(input:{issueId:$issue, issueFields:[
90
+ {fieldId:"<priorityFieldId>", singleSelectOptionId:"<optionId>"},
91
+ {fieldId:"<effortFieldId>", singleSelectOptionId:"<optionId>"}
92
+ ]}){ issue { number } }
93
+ }'
94
+ ```
95
+
96
+ ### Read back the result
97
+
98
+ The mutations return a bare `issue { number }` — an ack, not state. Confirm with:
99
+
100
+ ```bash
101
+ gh api graphql -f owner='<owner>' -f repo='<repo>' -f query='
102
+ query($owner:String!,$repo:String!){
103
+ repository(owner:$owner,name:$repo){
104
+ issue(number:<n>){
105
+ issueType { name }
106
+ labels(first:20){ nodes { name } }
107
+ parent { number }
108
+ subIssues(first:10){ nodes { number } }
109
+ issueFieldValues(first:20){ nodes {
110
+ ... on IssueFieldSingleSelectValue {
111
+ value
112
+ field { ... on IssueFieldSingleSelect { name } }
113
+ }
114
+ } }
115
+ }
116
+ }
117
+ }'
118
+ ```
119
+
120
+ Select `field { name }` or the read-back is ambiguous: on
121
+ `IssueFieldSingleSelectValue`, `name` is the _option_ name, so Priority=Low and
122
+ Effort=Low read as two indistinguishable `Low` entries.