@haus-tech/haus-workflow 6.7.1 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +41 -85
  3. package/dist/cli.js +17629 -23486
  4. package/docs/before-you-start.md +17 -22
  5. package/docs/glossary.md +10 -8
  6. package/package.json +3 -6
  7. package/packages/agents/issue-creator.md +59 -0
  8. package/packages/configs/eslint/eslint.config.mjs +90 -0
  9. package/packages/configs/lighthouse/lighthouserc.yml +35 -0
  10. package/packages/configs/prettier/.prettierignore +28 -0
  11. package/packages/configs/prettier/prettier.config.cjs +12 -0
  12. package/packages/packages.yaml +81 -0
  13. package/packages/skills/adr-decisions/SKILL.md +113 -0
  14. package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
  15. package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
  16. package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
  17. package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
  18. package/packages/skills/bullmq-patterns/SKILL.md +53 -0
  19. package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
  20. package/packages/skills/bullmq-patterns/references/scope.md +30 -0
  21. package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
  22. package/{library/global → packages}/skills/haus-workflow/SKILL.md +28 -41
  23. package/packages/skills/haus-workflow/references/init.md +57 -0
  24. package/{library/global → packages}/skills/haus-workflow/references/new.md +15 -20
  25. package/packages/skills/i18next-patterns/SKILL.md +52 -0
  26. package/packages/skills/i18next-patterns/references/conventions.md +32 -0
  27. package/packages/skills/i18next-patterns/references/scope.md +29 -0
  28. package/packages/skills/i18next-patterns/references/workflow.md +39 -0
  29. package/packages/skills/issue-authoring/SKILL.md +184 -0
  30. package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
  31. package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
  32. package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
  33. package/packages/skills/laravel-nova-patterns/SKILL.md +45 -0
  34. package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
  35. package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
  36. package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
  37. package/packages/skills/nextauth-patterns/SKILL.md +48 -0
  38. package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
  39. package/packages/skills/nextauth-patterns/references/scope.md +33 -0
  40. package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
  41. package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
  42. package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
  43. package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
  44. package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
  45. package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
  46. package/packages/skills/qliro-patterns/SKILL.md +48 -0
  47. package/packages/skills/qliro-patterns/references/conventions.md +28 -0
  48. package/packages/skills/qliro-patterns/references/scope.md +30 -0
  49. package/packages/skills/qliro-patterns/references/workflow.md +46 -0
  50. package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
  51. package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
  52. package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
  53. package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
  54. package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
  55. package/packages/skills/strapi-patterns/SKILL.md +53 -0
  56. package/packages/skills/strapi-patterns/references/conventions.md +33 -0
  57. package/packages/skills/strapi-patterns/references/scope.md +29 -0
  58. package/packages/skills/strapi-patterns/references/workflow.md +47 -0
  59. package/packages/skills/vendure-app-patterns/SKILL.md +34 -0
  60. package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
  61. package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
  62. package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
  63. package/packages/skills/vendure-plugin-patterns/SKILL.md +45 -0
  64. package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
  65. package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
  66. package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
  67. package/packages/skills/whats-installed/SKILL.md +55 -0
  68. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
  69. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
  70. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
  71. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
  72. package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
  73. package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
  74. package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
  75. package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
  76. package/packages/skills/writing-documentation/SKILL.md +153 -0
  77. package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
  78. package/packages/skills/writing-documentation/references/claude-template.md +43 -0
  79. package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
  80. package/packages/skills/writing-documentation/references/summary-template.md +81 -0
  81. package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
  82. package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
  83. package/packages/templates/agentic-workflow-poc.md +180 -0
  84. package/packages/templates/agentic-workflow-standard.md +170 -0
  85. package/packages/templates/decision-template.md +27 -0
  86. package/packages/templates/decisions-ci-gate.yml +32 -0
  87. package/packages/templates/lefthook-branch-guard.yml +27 -0
  88. package/packages/templates/lefthook-lighthouse.yml +28 -0
  89. package/packages/templates/lefthook-quality.yml +34 -0
  90. package/packages/templates/lefthook-security.yml +27 -0
  91. package/packages/templates/start-here.md +72 -0
  92. package/library/catalog/decisions-triggers.json +0 -26
  93. package/library/catalog/haus-lock.schema.json +0 -4
  94. package/library/catalog/manifest.json +0 -5941
  95. package/library/catalog/validation-rules.json +0 -169
  96. package/library/global/settings-fragments/hooks.json +0 -53
  97. package/library/global/skills/haus-workflow/references/init.md +0 -88
  98. package/scripts/postinstall.mjs +0 -62
  99. /package/{library/global → packages}/agents/request-assessor.md +0 -0
  100. /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
  101. /package/{library/global → packages}/agents/request-designer.md +0 -0
  102. /package/{library/global → packages}/agents/request-scorer.md +0 -0
  103. /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
  104. /package/{library/global → packages}/agents/request-specifier.md +0 -0
  105. /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
  106. /package/{library/global → packages}/skills/request/SKILL.md +0 -0
  107. /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
  108. /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
  109. /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
  110. /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
  111. /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
  112. /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
  113. /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
  114. /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
  115. /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
  116. /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
  117. /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
  118. /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
  119. /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
  120. /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
  121. /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
  122. /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
  123. /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
  124. /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
  125. /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
  126. /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
  127. /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
@@ -0,0 +1,38 @@
1
+ # Workflow
2
+
3
+ ## Implementation steps
4
+
5
+ 1. Identify provider: OIDC generic, Azure AD (v1/v2 endpoint), or BankID — check existing config files
6
+ 2. Locate auth middleware/guard chain — map which routes/resolvers it protects
7
+ 3. Check callback handler: verify state/nonce validation, PKCE verifier, token endpoint call
8
+ 4. Trace claim extraction: from `id_token` or `userinfo` endpoint to application user object
9
+ 5. Validate role/permission mapping: confirm downstream authorization checks match new claims
10
+ 6. Verify redirect URI alignment: env vars, provider app registration, and middleware matcher all consistent
11
+ 7. Check token storage: httpOnly cookie vs session store — confirm expiry and refresh logic
12
+ 8. For BankID: verify personal number assertion is validated before trust, check auth level (`loa`)
13
+ 9. Run auth flow end-to-end in dev environment: login → callback → session → protected route
14
+
15
+ ## Commands
16
+
17
+ ```bash
18
+ # NestJS/Node
19
+ yarn tsc --noEmit # type check token/claims types
20
+ jest --testPathPattern auth # run auth unit tests
21
+
22
+ # Laravel (Socialite / Laravel Passport)
23
+ php artisan test --filter=Auth # run auth feature tests
24
+ php artisan route:list | grep callback # inspect registered callback routes
25
+
26
+ # .NET
27
+ dotnet test --filter Category=Auth
28
+ ```
29
+
30
+ ## Validation checklist
31
+
32
+ - [ ] Token signature verified against provider JWKS endpoint — never skip
33
+ - [ ] `state` and `nonce` parameters validated on callback to prevent CSRF/replay
34
+ - [ ] Redirect URIs match exactly (no trailing slash drift) in env and provider config
35
+ - [ ] Session expiry and refresh token rotation implemented for long-lived sessions
36
+ - [ ] Role/claim mapping tested with both positive and negative claim values
37
+ - [ ] BankID `loa` level meets application minimum assurance requirement
38
+ - [ ] Auth guard applied to all protected routes — no accidental public exposure
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: bullmq-patterns
3
+ description: BullMQ router. Use for queue definitions, workers, schedulers, repeatable jobs, and graceful shutdown.
4
+ ---
5
+
6
+ # BullMQ Patterns
7
+
8
+ ## Use when
9
+
10
+ - task adds, modifies, or removes a BullMQ queue, worker, scheduler, or flow
11
+ - task touches Redis connection wiring for BullMQ (`new Queue("name", { connection })`)
12
+ - task adds repeatable jobs (cron, every-N-ms) or delayed jobs
13
+ - task wires graceful shutdown (worker drain, queue close) into app lifecycle
14
+
15
+ ## Do not use when
16
+
17
+ - project uses a different job system (Bull v3, Agenda, custom in-process scheduler)
18
+ - task is in-process scheduling without Redis (use a different skill)
19
+ - task is Redis general usage with no BullMQ surface (use `haus.ecc-redis-patterns`)
20
+
21
+ ## Inspect first
22
+
23
+ - Queue definitions: `queues/*.ts` or `src/queues/*.ts`
24
+ - Worker definitions: `workers/*.ts` — `new Worker(name, processor, { connection })`
25
+ - Shared Redis connection module: typically `lib/redis.ts` (must be `IORedis` instance for BullMQ)
26
+ - App lifecycle: where workers start, where they're closed on `SIGTERM` / `SIGINT`
27
+ - `package.json` BullMQ version — 5.x has breaking changes vs 4.x
28
+
29
+ ## Avoid mistakes
30
+
31
+ - creating multiple `IORedis` connections — BullMQ requires a separate connection per Queue/Worker
32
+ - using `Redis` from `redis` package (node-redis) — BullMQ requires `IORedis`
33
+ - mixing `bull` v3 and `bullmq` packages — different APIs, can't share queues
34
+ - forgetting `concurrency` on `Worker` — defaults to 1, blocks throughput
35
+ - not closing workers on shutdown — jobs marked failed when worker disappears
36
+ - swallowing job errors in the processor — failed jobs disappear silently
37
+
38
+ ## Router
39
+
40
+ 1. Load `references/conventions.md` for queue, worker, and connection patterns.
41
+ 2. Load `references/scope.md` for in-scope files and stack boundaries.
42
+ 3. Load `references/workflow.md` only for graceful shutdown and job retry diagnosis.
43
+ 4. Keep one queue per concern; share `IORedis` instances per role (Queue vs Worker).
44
+
45
+ ## References
46
+
47
+ - references/conventions.md
48
+ - references/scope.md
49
+ - references/workflow.md
50
+
51
+ ## Reference Documentation
52
+
53
+ For the current API reference, fetch https://docs.bullmq.io/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
@@ -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
@@ -31,9 +31,9 @@ that branch of the merged task.
31
31
  | `clone [name]` (`project:clone`, `cloneandsetup`, `project:cloneandsetup`) | _Clone procedure below_ | Clone one repo by name, or a whole workspace from `repos.manifest.json`. Afterwards asks "set up for local dev too?" (deps, databases, links, env via `localdev.yml`). `cloneandsetup` aliases pre-answer that question with yes. |
32
32
  | `new [description]` (`create`, `project:new`, `poc`, `kunddemo`) | _New-project procedure below_ | Create a brand-new project from a plain-language request, unchanged seven-phase flow. The `poc`/`kunddemo` aliases (and phrases like "ny poc", "customer demo") run the same flow in PoC mode: a throwaway demo repo under the `poc` profile (`--profile poc`), see `references/new.md` → PoC mode. |
33
33
  | `doctor` (`check`, `fix`, `project:doctor`, `project:fix`) | _Doctor procedure below_ | Health check for the detected scope; relays the verdict, then offers to apply the doctor's own suggested fixes and re-checks until green. `fix` aliases pre-answer "fix now?" with yes. |
34
- | `refresh` (`update`, `upgrade`, `apply`, `regenerate`, `claude-md`, `project:refresh`, `add-skills`, `opt-in`, `project:add-skills`, `install`, `global`) | _Refresh procedure below_ | Bring haus current. Always: update npm package + catalog + `~/.claude` (seeding it first if never installed). Inside a set-up project/workspace, asks: **Full sync** (re-run the whole setup pipeline in place) or **Just add helpers** (offer opt-in skills/agents + configs only). `add-skills`/`opt-in` aliases jump to the helpers branch; outside any project it stops after the global update. |
35
- | `uninstall` | `haus uninstall` | Remove all haus global files from `~/.claude/`. Machine scope only — confirm gate states this does NOT touch the current project (that's `init` → clean slate). |
36
- | `help` (`?`) | _Answer directly_ | Explain what haus-workflow is, list tasks, point to deeper docs — touches no files. |
34
+ | `refresh` (`update`, `upgrade`, `apply`, `regenerate`, `claude-md`, `project:refresh`, `add-skills`, `opt-in`, `project:add-skills`, `install`, `global`) | _Refresh procedure below_ | Bring haus current. Always: `haus update` (npm package and core files; haus seeds nothing in `~/.claude`). Inside a set-up project/workspace, asks: **Full sync** (re-run the whole setup pipeline in place) or **Just add helpers** (offer packages `haus.json` does not list yet). `add-skills`/`opt-in` aliases jump to the helpers branch; outside any project it stops after the global update. |
35
+ | `uninstall` | `haus uninstall` | Remove all haus global files from `~/.claude/`. Machine scope only: the confirm gate states this does NOT touch the current project (that's `init` → clean slate). |
36
+ | `help` (`?`) | _Answer directly_ | Explain what haus-workflow is, list tasks, point to deeper docs. Touches no files. |
37
37
 
38
38
  ## Step 1 — Determine the task
39
39
 
@@ -76,7 +76,7 @@ Before running anything, determine what the current directory is. Check in order
76
76
  a repo) AND a parent directory holds `haus.workspace.yaml`/`repos.manifest.json`.
77
77
  Ambiguous — ask via `AskUserQuestion`: "Run this for this repo only, or the whole
78
78
  workspace?" (options: This repo / Whole workspace). Never guess.
79
- 3. **Project** — the git root has `.haus-workflow/` and `haus.lock.json`.
79
+ 3. **Project**: the git root has `.haus-workflow/` and `haus.json`.
80
80
  4. **Not set up** — none of the above. `init`, `new`, and `clone` proceed in project
81
81
  scope; `doctor` says the project isn't set up yet and suggests `init`; `refresh`
82
82
  runs its global half only.
@@ -108,14 +108,14 @@ After the command completes, follow the relevant post-run steps below.
108
108
 
109
109
  ### Init (`init`)
110
110
 
111
- 0. **State check.** Scope was detected in Step 1.5. If `haus.lock.json` already
111
+ 0. **State check.** Scope was detected in Step 1.5. If `haus.json` already
112
112
  exists (or, workspace scope, `.haus-workflow/workspace.manifest.json` records a
113
113
  prior setup), this project is already set up — ask via `AskUserQuestion`:
114
114
  - **Refresh instead** (recommended) — non-destructive; jump to the Refresh
115
115
  procedure's full-sync branch.
116
116
  - **Clean slate**: explain plainly that it removes the haus-managed files haus owns (backed up
117
117
  first; user content preserved), then re-runs setup from scratch. Say what it keeps:
118
- an item the user edited and its lock row, and a `.claude/rules/haus.md` haus did not
118
+ an item the user edited, and a `.claude/rules/haus.md` haus did not
119
119
  write. `haus undo --force` removes those too, after a backup, except a
120
120
  `.claude/rules/haus.md` that is a link or a folder, which stays either way. In workspace
121
121
  scope it also keeps a linked copy edited at the workspace root and a
@@ -134,10 +134,10 @@ After the command completes, follow the relevant post-run steps below.
134
134
  `haus workspace setup --write`, run the chosen per-member documentation pass,
135
135
  and stop. Do not follow `references/init.md`; it contains project commands.
136
136
  2. **Project scope.** Open and follow `references/init.md` in this skill's directory.
137
- Run every step in order. It detects the stack, runs `haus apply --write`
138
- (scaffolding, skills, commands, rules, docs skill), writes the **project docs**
139
- (`CLAUDE.md` body + `docs/`) and `.haus-workflow/deep-context.json`, runs
140
- `haus recommend`, applies the newly-matched helpers, and confirms. Then fill
137
+ Run every step in order. It detects the stack, picks the packages for
138
+ `haus.json`, runs `haus init` and `haus sync` (core files, then the packages'
139
+ skills and agents, the docs skill among them), writes the **project docs**
140
+ (`CLAUDE.md` body + `docs/`), offers a package the deep read found, and confirms. Then fill
141
141
  `.haus-workflow/workflow-config.md` — replace every placeholder (`TODO`, `n/a`,
142
142
  empty): test/lint/typecheck/build commands (check `package.json`), docs paths,
143
143
  validation library, pre-commit tool, highest-stakes logic (ask if unclear).
@@ -147,43 +147,30 @@ After the command completes, follow the relevant post-run steps below.
147
147
 
148
148
  Bring haus current. Global half always runs; the project half depends on scope.
149
149
 
150
- 1. **Global half.** If `~/.claude` was never seeded by haus (`haus install --check`
151
- reports it missing), run `haus install` first. Then run `haus update`. React to
150
+ 1. **Global half.** Run `haus update` (haus writes nothing to `~/.claude` unless the user
151
+ turned on session labels with `haus install --session-labels`). React to
152
152
  its output: if a new version is available run `npm i -g @haus-tech/haus-workflow`
153
153
  and confirm the bump; if `WORKFLOW.md` changed, remind the user to review
154
- `workflow-config.md` for new sections; if the catalog changed, summarise which
155
- templates changed.
154
+ `workflow-config.md` for new sections. If it names a newer release, offer to move
155
+ `release` in `haus.json` to it and run `haus sync`.
156
156
  2. **No project/workspace detected** (scope step said "not set up") → report the
157
157
  global result and stop.
158
158
  3. **Project or workspace detected** → ask via `AskUserQuestion` (skip the question
159
159
  when an alias pre-answered it):
160
- - **Full sync** — re-run the Init procedure's pipeline in place, end to end
161
- (re-scan, deep docs read, re-recommend, apply; workspace scope:
160
+ - **Full sync**: re-run the Init procedure's pipeline in place, end to end
161
+ (re-scan, deep docs read, package check, `haus sync`; workspace scope:
162
162
  `haus workspace setup --write`, asking the deep-docs question first). Nothing
163
- is removed up front; anything removed upstream is pruned by `apply`'s existing
164
- orphan-pruning.
165
- - **Just add helpers** — no package pipeline re-run, no docs regeneration:
166
- run `haus rescan` — does the same scan + recommend as `haus scan --json` then
167
- `haus recommend`, in one call, and additionally ensures the catalog-pinned
168
- global plugin(s), which a manual scan+recommend pair would skip; read
169
- `.haus-workflow/recommendation.json` and `.haus-workflow/haus.lock.json`
170
- yourself; offer items not already installed — `optInEligible[]` grouped by
171
- `optInGroup` (purpose + tokenEstimate as plain language) and `recommended[]`
172
- config entries with `install: false` whose files aren't present. One
173
- multi-select `AskUserQuestion`, all unchecked. Then one single
174
- `haus recommend --declare-role <role> <role> …` with the common role of each
175
- chosen group that has one, passed as the name after `role=` (every entry's
176
- `requires` names only roles, `role=<name>`, and the same role first; a
177
- declared role also admits the shared helpers listed under other groups),
178
- then one single
179
- `haus recommend --include <id> <id> …` with the ids of the chosen groups that
180
- have none (skip a command with nothing to pass), followed by
181
- `haus apply --write`; configs via `haus configs <id>` (`--force` only if the
182
- user chose to replace an existing file). Nothing eligible → say so and stop.
183
- Reached directly by the `add-skills`/`opt-in` aliases. In workspace scope, ask
184
- which member repo(s) first and run the branch per chosen repo.
185
- 4. Report what changed in plain language — package/catalog bumps, docs refreshed,
186
- helpers added/updated/removed.
163
+ is removed up front: `haus sync` removes only what a package no longer ships.
164
+ - **Just add helpers**: no docs regeneration. Read `haus.json` yourself and offer
165
+ the packages it does not list yet, one `AskUserQuestion` option per package in
166
+ plain language (`client-requests`: the request flow; `communication`: Slack
167
+ canvases; the stack packages by their stack), all unchecked. On confirm run
168
+ `printf 'y\n' | haus init --packages <the whole new list>`, then `haus sync`.
169
+ Nothing to add → say so and stop. Reached directly by the `add-skills`/`opt-in`
170
+ aliases. In workspace scope, ask which member repo(s) first and run the branch
171
+ per chosen repo.
172
+ 4. Report what changed in plain language: haus and release bumps, docs refreshed,
173
+ packages added.
187
174
 
188
175
  ### Doctor (`doctor`)
189
176
 
@@ -224,7 +211,7 @@ Bring haus current. Global half always runs; the project half depends on scope.
224
211
  it must ask the workspace-membership question there before eliciting anything
225
212
  else. Otherwise (Project or Not-set-up scope) open it knowing that question is
226
213
  skipped.
227
- 2. Open and follow `references/new.md` in this skill's directory. It is a seven-phase AI-driven flow: elicit the request and propose features, gate on user intent, scaffold (registry stacks via `haus new --json --yes` with a `--dry-run` preview; any other stack via a user-confirmed official scaffolder plus manual rails), install context via `haus init`, seed `docs/SPEC.md` + `docs/plans/walking-skeleton.md`, build the walking skeleton with one subagent per feature (against a structure recorded in `docs/DESIGN.md`), verify (build + lint + tests + smoke boot), then write the project docs by following `references/init.md` from step 3 (deep read, `CLAUDE.md` body + `docs/`, recommend re-check, opt-ins). Repos are only ever created private. Failure `detail` is relayed verbatim and nothing is ever auto-deleted. Never run bare interactive `haus new`. The same reference carries a **PoC mode** (entered by the `poc`/`kunddemo` aliases, or by the "Production project or throwaway PoC?" question when no phrase was given): the repo gets the `poc` profile before the first design question (`haus new --profile poc` on the fast path; a hand-written `haus.config.json` plus `haus init --json --dry-run --profile poc` and `haus apply --write` on the manual path), the first brainstorm writes `docs/MANUS.md` instead of `docs/SPEC.md`, the only check is the Playwright manus, and Phase 6 skips the docs pass.
214
+ 2. Open and follow `references/new.md` in this skill's directory. It is a seven-phase AI-driven flow: elicit the request and propose features, gate on user intent, scaffold (registry stacks via `haus new --json --yes` with a `--dry-run` preview; any other stack via a user-confirmed official scaffolder plus manual rails), install context via `haus init`, seed `docs/SPEC.md` + `docs/plans/walking-skeleton.md`, build the walking skeleton with one subagent per feature (against a structure recorded in `docs/DESIGN.md`), verify (build + lint + tests + smoke boot), then write the project docs by following `references/init.md` from step 3 (deep read, `CLAUDE.md` body + `docs/`, package check). Repos are only ever created private. Failure `detail` is relayed verbatim and nothing is ever auto-deleted. Never run bare interactive `haus new`. The same reference carries a **PoC mode** (entered by the `poc`/`kunddemo` aliases, or by the "Production project or throwaway PoC?" question when no phrase was given): the repo gets the `poc` profile before the first design question (`haus new --profile poc` on the fast path; a hand-written `haus.config.json` plus `haus init --json --dry-run --profile poc` and `haus apply --write` on the manual path), the first brainstorm writes `docs/MANUS.md` instead of `docs/SPEC.md`, the only check is the Playwright manus, and Phase 6 skips the docs pass.
228
215
 
229
216
  ### After `haus uninstall`
230
217
 
@@ -0,0 +1,57 @@
1
+ # project:init procedure
2
+
3
+ Set up this project with haus, conversationally. The person you're helping may
4
+ not be a developer — never make them open a terminal or read JSON. You run the
5
+ commands; they read plain language and approve.
6
+
7
+ Do this in order:
8
+
9
+ 1. **Detect.** Run `haus init --json --dry-run`. Read the JSON yourself:
10
+ do not show it. Stdout is one envelope:
11
+ `{ scan, hooks, repoName, warnings, items, records }`. `items` and
12
+ `records` are `null` here: a dry run never reaches the apply step. Stderr names the
13
+ `haus.json` it would write (`[dry-run] would write haus.json (release ..., packages ...)`).
14
+ Translate `scan` into one or two plain sentences, e.g. "This looks like a Next.js
15
+ website using Yarn. I found unit tests but no end-to-end tests." If
16
+ `scan.detectionStatus` is `unknown` or `partial`, say so honestly ("I couldn't fully
17
+ recognise this stack, so I'll apply the general workflow and security guidance").
18
+
19
+ 2. **Pick the packages.** `haus.json` lists the packages this project gets:
20
+ `software-engineering` always, plus one per stack the scan found (`web-react`,
21
+ `commerce-vendure`, `wordpress`, `laravel`, `dotnet`, `strapi`, `nx`). Name the
22
+ suggested ones in plain language. `client-requests` (the request flow) and
23
+ `communication` (Slack canvases) are never suggested: offer them in one
24
+ `AskUserQuestion`, unchecked. An existing `haus.json` keeps its list unless the user
25
+ changes it.
26
+
27
+ 3. **Apply the basics.** Run `printf 'y\n' | haus init`, adding
28
+ `--packages <a>,<b>` when step 2 changed the list. It writes `haus.json` and the core
29
+ guardrails. Then run `haus sync`: it installs the packages `haus.json` names into
30
+ `.claude/`, including the documentation skill haus uses in the next step.
31
+
32
+ 4. **Write the project docs.** Open and follow the instructions in
33
+ `.claude/skills/writing-documentation/SKILL.md`, which step 3 just installed.
34
+ Following it, do a deep read of the project and write the project documentation
35
+ (the `CLAUDE.md` body and `docs/` files).
36
+ NEVER alter the `<!-- HAUS:BEGIN haus-imports … -->` … `<!-- HAUS:END … -->`
37
+ block in `CLAUDE.md`; write around it.
38
+ If this step can't be completed for any reason, say so plainly and skip to
39
+ step 6: setup still finishes correctly with the basics from step 3.
40
+
41
+ 5. **Check the packages against the deep read.** If the deep read found a stack the
42
+ quick scan missed (for example Vendure behind a monorepo folder), offer its package.
43
+ On confirm, run `printf 'y\n' | haus init --packages <the whole list>`, then
44
+ `haus sync`. Nothing new → skip this step silently.
45
+
46
+ 6. **Check the imports.** Verify the root `CLAUDE.md` imports `@AGENTS.md` inside its
47
+ haus block, and that `AGENTS.md` holds the haus block with
48
+ `@.haus-workflow/WORKFLOW.md`, `@.haus-workflow/workflow-config.md` and
49
+ `@docs/decisions/README.md`. If not, run `haus apply --write`, never a hand edit.
50
+
51
+ 7. **Confirm.** End with one plain-language line, for example:
52
+ "✅ Your project is configured: I wrote your project docs and installed the
53
+ <packages> packages. Run `/haus-workflow doctor` any time to re-check." Name the
54
+ packages from `haus.json`.
55
+
56
+ If anything fails, explain what happened in plain language and what you'll try
57
+ next — don't dump raw errors.
@@ -186,21 +186,18 @@ add tests.
186
186
  Everything from here on runs inside the new project directory — `cd` into it first and
187
187
  stay there.
188
188
 
189
- - Fast path: the chained `haus init` inside `haus new` already ran — go to seeding.
190
- (That chained init is the CLI pipeline only: it installs skills and guardrails but
189
+ - Fast path: the chained `haus init` inside `haus new` already ran. Run `haus sync` so the
190
+ packages `haus.json` names land in `.claude/`, then go to seeding.
191
+ (That chained init is the CLI pipeline only: it writes `haus.json` and the guardrails but
191
192
  does not write project docs — those are written in Phase 6, where the deep read
192
193
  sees the real code instead of an empty scaffold.)
193
194
  - Manual path:
194
195
  - Read: run `haus init --json --dry-run` and read the envelope yourself.
195
- - If it refuses with the zero-signal message — literally zero catalog items matched,
196
- not merely an unknown stack (catalog defaults normally still match, so most tier-3
197
- projects write fine without `--force`) — tell the user plainly: "no stack-specific
198
- assets in the catalog; installing workflow defaults." Confirm with the user, then
199
- re-run `haus init --json --dry-run --force`.
200
- - Write: run `haus apply --write`.
201
- - Guard: NEVER run write-mode `haus init` (i.e. `haus init` without `--json
202
- --dry-run`) — it prompts for confirmation, and an agent's non-answer means nothing
203
- is written despite exit 0.
196
+ - If `scan.detectionStatus` is `unknown`, tell the user plainly: "no stack-specific
197
+ packages for this stack; installing the workflow defaults."
198
+ - Write: run `printf 'y\n' | haus init`, then `haus sync`. `haus init` asks before it
199
+ writes, and an agent's non-answer means nothing is written despite exit 0, so the
200
+ answer is piped in.
204
201
  - Seeding: write the elicited requirements into the project as `docs/SPEC.md`
205
202
  (purpose, features, auth/data choices, what is mocked) and
206
203
  `docs/plans/walking-skeleton.md` (one task per selected feature with acceptance
@@ -212,16 +209,15 @@ stay there.
212
209
 
213
210
  1. Write `.haus-workflow/haus.config.json` with exactly `{ "profile": "poc" }` (create the
214
211
  directory).
215
- 2. Read: `haus init --json --dry-run --profile poc`; on the zero-signal refusal, confirm
216
- and re-run with `--force` as above.
212
+ 2. Read: `haus init --json --dry-run --profile poc`.
217
213
  3. Add a `"manus"` key to package.json scripts now, before the write step, even as a
218
- placeholder (`"manus": "playwright test"`). `haus apply --write` derives the PoC's
214
+ placeholder (`"manus": "playwright test"`). The write derives the PoC's
219
215
  only gate command in `.haus-workflow/workflow-config.md` from whether that key
220
216
  exists, not from its final body, and with no key at all it falls back to a Playwright
221
217
  invocation that resolves against whatever default config the scaffold shipped and
222
218
  finds no tests at all. The skeleton below fills in the real body once the runner
223
219
  config is decided; what matters here is that the key exists first.
224
- 4. Write: `haus apply --write`. It reads the profile: `.haus-workflow/WORKFLOW.md` now
220
+ 4. Write: `printf 'y\n' | haus init --profile poc`, then `haus sync`. It reads the profile: `.haus-workflow/WORKFLOW.md` now
225
221
  starts with `# PoC Workflow Standard`, and there is no haus gate (`lefthook.yml`).
226
222
 
227
223
  Fast path: the chained init already ran `haus apply --write` inside Phase 3, before this
@@ -329,12 +325,11 @@ why.
329
325
  and the layout matches the structure conventions recorded in `docs/DESIGN.md`.
330
326
  Record the results in `docs/plans/walking-skeleton.md`'s verification blocks.
331
327
  2. Write the project docs: follow `references/init.md` from step 3 to the end —
332
- deep read, `CLAUDE.md` body + `docs/` files, `.haus-workflow/deep-context.json`,
333
- the `haus recommend` re-check, the opt-in helpers offer, and the final
334
- `haus apply --write`. This runs HERE, after the build, on purpose: the chained
328
+ deep read, `CLAUDE.md` body + `docs/` files, the package check and the import
329
+ check. This runs HERE, after the build, on purpose: the chained
335
330
  CLI init installs the writing-documentation skill but never executes it, and a
336
331
  deep read now sees the real features instead of an empty scaffold — so the docs
337
- describe reality and `haus recommend` can match what was actually built.
332
+ describe reality and the package check sees what was actually built.
338
333
  (init.md steps 1–2 are already covered by Phase 4; do not redo them.)
339
334
  Commit the docs output as its own conventional commit.
340
335
  3. Push to the remote (if a repo was created).
@@ -357,7 +352,7 @@ still flags here is real: read it and act on it, or, for a machine-level finding
357
352
  a disabled global plugin, check it with the tool that owns it (`claude plugin list`)
358
353
  before telling the user doctor is wrong. Then push if a remote exists (never for
359
354
  local-only). Then stop: do NOT follow `references/init.md`
360
- from step 3, because a PoC has no docs pass, no deep read and no recommend re-check. Hand off in
355
+ from step 3, because a PoC has no docs pass, no deep read and no package check. Hand off in
361
356
  the user's language, naming the demo date, the two re-entry phrases and the decision the
362
357
  meeting ends with: next session, open this repo and say "where are we" / "var är vi",
363
358
  or "extend the demo with ..."; after the demo, decide
@@ -0,0 +1,52 @@
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
+ For the current API reference, fetch https://www.i18next.com/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
@@ -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)