@haus-tech/haus-workflow 6.7.1 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/README.md +41 -85
- package/dist/cli.js +17629 -23486
- package/docs/before-you-start.md +17 -22
- package/docs/glossary.md +10 -8
- package/package.json +3 -6
- package/packages/agents/issue-creator.md +59 -0
- package/packages/configs/eslint/eslint.config.mjs +90 -0
- package/packages/configs/lighthouse/lighthouserc.yml +35 -0
- package/packages/configs/prettier/.prettierignore +28 -0
- package/packages/configs/prettier/prettier.config.cjs +12 -0
- package/packages/packages.yaml +81 -0
- package/packages/skills/adr-decisions/SKILL.md +113 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
- package/packages/skills/bullmq-patterns/SKILL.md +53 -0
- package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
- package/packages/skills/bullmq-patterns/references/scope.md +30 -0
- package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
- package/{library/global → packages}/skills/haus-workflow/SKILL.md +28 -41
- package/packages/skills/haus-workflow/references/init.md +57 -0
- package/{library/global → packages}/skills/haus-workflow/references/new.md +15 -20
- package/packages/skills/i18next-patterns/SKILL.md +52 -0
- package/packages/skills/i18next-patterns/references/conventions.md +32 -0
- package/packages/skills/i18next-patterns/references/scope.md +29 -0
- package/packages/skills/i18next-patterns/references/workflow.md +39 -0
- package/packages/skills/issue-authoring/SKILL.md +184 -0
- package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
- package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
- package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
- package/packages/skills/laravel-nova-patterns/SKILL.md +45 -0
- package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
- package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
- package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
- package/packages/skills/nextauth-patterns/SKILL.md +48 -0
- package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
- package/packages/skills/nextauth-patterns/references/scope.md +33 -0
- package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
- package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
- package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
- package/packages/skills/qliro-patterns/SKILL.md +48 -0
- package/packages/skills/qliro-patterns/references/conventions.md +28 -0
- package/packages/skills/qliro-patterns/references/scope.md +30 -0
- package/packages/skills/qliro-patterns/references/workflow.md +46 -0
- package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
- package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
- package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
- package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
- package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
- package/packages/skills/strapi-patterns/SKILL.md +53 -0
- package/packages/skills/strapi-patterns/references/conventions.md +33 -0
- package/packages/skills/strapi-patterns/references/scope.md +29 -0
- package/packages/skills/strapi-patterns/references/workflow.md +47 -0
- package/packages/skills/vendure-app-patterns/SKILL.md +34 -0
- package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
- package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
- package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
- package/packages/skills/vendure-plugin-patterns/SKILL.md +45 -0
- package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
- package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
- package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
- package/packages/skills/whats-installed/SKILL.md +55 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
- package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
- package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
- package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
- package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
- package/packages/skills/writing-documentation/SKILL.md +153 -0
- package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
- package/packages/skills/writing-documentation/references/claude-template.md +43 -0
- package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
- package/packages/skills/writing-documentation/references/summary-template.md +81 -0
- package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
- package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
- package/packages/templates/agentic-workflow-poc.md +180 -0
- package/packages/templates/agentic-workflow-standard.md +170 -0
- package/packages/templates/decision-template.md +27 -0
- package/packages/templates/decisions-ci-gate.yml +32 -0
- package/packages/templates/lefthook-branch-guard.yml +27 -0
- package/packages/templates/lefthook-lighthouse.yml +28 -0
- package/packages/templates/lefthook-quality.yml +34 -0
- package/packages/templates/lefthook-security.yml +27 -0
- package/packages/templates/start-here.md +72 -0
- package/library/catalog/decisions-triggers.json +0 -26
- package/library/catalog/haus-lock.schema.json +0 -4
- package/library/catalog/manifest.json +0 -5941
- package/library/catalog/validation-rules.json +0 -169
- package/library/global/settings-fragments/hooks.json +0 -53
- package/library/global/skills/haus-workflow/references/init.md +0 -88
- package/scripts/postinstall.mjs +0 -62
- /package/{library/global → packages}/agents/request-assessor.md +0 -0
- /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
- /package/{library/global → packages}/agents/request-designer.md +0 -0
- /package/{library/global → packages}/agents/request-scorer.md +0 -0
- /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
- /package/{library/global → packages}/agents/request-specifier.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
- /package/{library/global → packages}/skills/request/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
- /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
- /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
|
@@ -0,0 +1,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
|
|
35
|
-
| `uninstall` | `haus uninstall` | Remove all haus global files from `~/.claude/`. Machine scope only
|
|
36
|
-
| `help` (`?`) | _Answer directly_ | Explain what haus-workflow is, list tasks, point to deeper docs
|
|
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
|
|
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.
|
|
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
|
|
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,
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
`
|
|
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.**
|
|
151
|
-
|
|
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
|
|
155
|
-
|
|
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
|
|
161
|
-
(re-scan, deep docs read,
|
|
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
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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/`,
|
|
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
|
|
190
|
-
|
|
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
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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
|
|
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"`).
|
|
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
|
|
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,
|
|
333
|
-
|
|
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
|
|
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
|
|
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)
|