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