@haus-tech/haus-workflow 6.7.0 → 6.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/cli.js +4764 -1767
  3. package/package.json +3 -1
  4. package/packages/agents/issue-creator.md +61 -0
  5. package/packages/configs/eslint/eslint.config.mjs +90 -0
  6. package/packages/configs/lighthouse/lighthouserc.yml +35 -0
  7. package/packages/configs/prettier/.prettierignore +28 -0
  8. package/packages/configs/prettier/prettier.config.cjs +12 -0
  9. package/packages/packages.yaml +81 -0
  10. package/packages/skills/adr-decisions/SKILL.md +114 -0
  11. package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
  12. package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
  13. package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
  14. package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
  15. package/packages/skills/bullmq-patterns/SKILL.md +63 -0
  16. package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
  17. package/packages/skills/bullmq-patterns/references/scope.md +30 -0
  18. package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
  19. package/packages/skills/i18next-patterns/SKILL.md +62 -0
  20. package/packages/skills/i18next-patterns/references/conventions.md +32 -0
  21. package/packages/skills/i18next-patterns/references/scope.md +29 -0
  22. package/packages/skills/i18next-patterns/references/workflow.md +39 -0
  23. package/packages/skills/issue-authoring/SKILL.md +191 -0
  24. package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
  25. package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
  26. package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
  27. package/packages/skills/laravel-nova-patterns/SKILL.md +55 -0
  28. package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
  29. package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
  30. package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
  31. package/packages/skills/nextauth-patterns/SKILL.md +48 -0
  32. package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
  33. package/packages/skills/nextauth-patterns/references/scope.md +33 -0
  34. package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
  35. package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
  36. package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
  37. package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
  38. package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
  39. package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
  40. package/packages/skills/qliro-patterns/SKILL.md +48 -0
  41. package/packages/skills/qliro-patterns/references/conventions.md +28 -0
  42. package/packages/skills/qliro-patterns/references/scope.md +30 -0
  43. package/packages/skills/qliro-patterns/references/workflow.md +46 -0
  44. package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
  45. package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
  46. package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
  47. package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
  48. package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
  49. package/packages/skills/strapi-patterns/SKILL.md +63 -0
  50. package/packages/skills/strapi-patterns/references/conventions.md +33 -0
  51. package/packages/skills/strapi-patterns/references/scope.md +29 -0
  52. package/packages/skills/strapi-patterns/references/workflow.md +47 -0
  53. package/packages/skills/vendure-app-patterns/SKILL.md +44 -0
  54. package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
  55. package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
  56. package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
  57. package/packages/skills/vendure-plugin-patterns/SKILL.md +55 -0
  58. package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
  59. package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
  60. package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
  61. package/packages/skills/whats-installed/SKILL.md +53 -0
  62. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
  63. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
  64. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
  65. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
  66. package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
  67. package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
  68. package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
  69. package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
  70. package/packages/skills/writing-documentation/SKILL.md +161 -0
  71. package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
  72. package/packages/skills/writing-documentation/references/claude-template.md +43 -0
  73. package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
  74. package/packages/skills/writing-documentation/references/summary-template.md +81 -0
  75. package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
  76. package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
  77. package/packages/templates/agentic-workflow-poc.md +180 -0
  78. package/packages/templates/agentic-workflow-standard.md +160 -0
  79. package/packages/templates/decision-template.md +27 -0
  80. package/packages/templates/decisions-ci-gate.yml +32 -0
  81. package/packages/templates/lefthook-branch-guard.yml +27 -0
  82. package/packages/templates/lefthook-lighthouse.yml +28 -0
  83. package/packages/templates/lefthook-quality.yml +34 -0
  84. package/packages/templates/lefthook-security.yml +27 -0
  85. package/packages/templates/start-here.md +72 -0
  86. /package/{library/global → packages}/agents/request-assessor.md +0 -0
  87. /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
  88. /package/{library/global → packages}/agents/request-designer.md +0 -0
  89. /package/{library/global → packages}/agents/request-scorer.md +0 -0
  90. /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
  91. /package/{library/global → packages}/agents/request-specifier.md +0 -0
  92. /package/{library/global → packages}/skills/haus-workflow/SKILL.md +0 -0
  93. /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
  94. /package/{library/global → packages}/skills/haus-workflow/references/init.md +0 -0
  95. /package/{library/global → packages}/skills/haus-workflow/references/new.md +0 -0
  96. /package/{library/global → packages}/skills/request/SKILL.md +0 -0
  97. /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
  98. /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
  99. /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
  100. /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
  101. /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
  102. /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
  103. /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
  104. /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
  105. /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
  106. /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
  107. /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
  108. /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
  109. /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
  110. /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
  111. /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
  112. /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
  113. /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
  114. /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
  115. /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
  116. /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
  117. /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
@@ -0,0 +1,29 @@
1
+ # Recording approval
2
+
3
+ Loaded on demand from `SKILL.md`: the evidence a `Status` line edit requires, the exact
4
+ approved-status format, and the read-modify-write recipe that keeps the edit from wiping
5
+ the technical section.
6
+
7
+ The header edit is a _record of_ approval, never an assertion of it. NEVER edit
8
+ the `Status` line without named evidence that a human approved: an approving
9
+ comment on the issue, an approval label a human applied, or a human instruction
10
+ that names this issue number. Record the evidence in the line itself:
11
+ `> **Status:** Approved by @<human> <YYYY-MM-DD> (<comment link / label / instruction>).`
12
+
13
+ **If no such evidence exists, do NOT edit the header and do NOT start work.**
14
+ Being handed "work on #157" counts only when the human saying it is the approver;
15
+ an agent that approves its own proposal deletes the gate this skill exists for.
16
+
17
+ `gh issue edit` has no partial-body edit — `--body` / `--body-file` replace the
18
+ whole body, so a naive edit wipes the technical section. Read, modify, write:
19
+
20
+ ```bash
21
+ f=$(mktemp)
22
+ gh issue view <n> --json body --jq .body > "$f" # edit ONLY the Status line in "$f"
23
+ gh issue edit <n> --body-file "$f" --remove-label needs-triage
24
+ ```
25
+
26
+ Dropping `needs-triage` is a label write: check `viewerCanLabel` first (capability
27
+ query in `native-metadata.md`). If `false`, run the edit without `--remove-label` —
28
+ a 403 on the label takes the body edit down with it — and report the issue as
29
+ untriaged.
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: laravel-nova-patterns
3
+ description: Laravel Nova router. Use for admin resources, actions, fields, filters, and policies.
4
+ ---
5
+
6
+ # Laravel Nova Patterns
7
+
8
+ ## Use when
9
+
10
+ - task changes Nova admin resources, fields, actions, cards, or filters
11
+ - task touches `app/Nova/*`, resource policies, or Nova tool integration
12
+
13
+ ## Do not use when
14
+
15
+ - task is customer-facing API/domain change without admin UI impact
16
+ - task belongs to non-Laravel admin stacks
17
+
18
+ ## Inspect first
19
+
20
+ - `app/Nova/*` resource classes and custom fields/actions
21
+ - linked Eloquent model + policy files
22
+ - validation rules and lens/filter query logic
23
+
24
+ ## Avoid mistakes
25
+
26
+ - exposing sensitive fields in index/detail views
27
+ - writing expensive unbounded queries in filters/lenses
28
+ - mismatching resource field rules vs model validation/policies
29
+
30
+ ## Router
31
+
32
+ 1. Load `references/conventions.md` for naming, do/don't, and forbidden patterns.
33
+ 2. Load `references/scope.md` for Nova file targets.
34
+ 3. Load `references/workflow.md` only for resource lifecycle flow.
35
+ 4. Verify admin authorization and data visibility before handoff.
36
+
37
+ ## References
38
+
39
+ - references/conventions.md
40
+ - references/scope.md
41
+ - references/workflow.md
42
+
43
+ ## Reference Documentation
44
+
45
+ Up-to-date API docs are cached locally by haus.
46
+
47
+ To refresh (uses etag — fast if unchanged):
48
+
49
+ ```bash
50
+ haus fetch-refs --id haus.laravel-nova-patterns
51
+ ```
52
+
53
+ Then read `.haus-workflow/llms-cache/nova-laravel-com-docs-llms-txt.md` for current API reference.
54
+
55
+ Source: https://nova.laravel.com/docs/llms.txt
@@ -0,0 +1,26 @@
1
+ ## Naming conventions
2
+
3
+ - Nova resource files: `app/Nova/Order.php` — filename matches Eloquent model exactly
4
+ - Nova actions: `app/Nova/Actions/ExportOrders.php` — verb-noun, PascalCase
5
+ - Nova filters: `app/Nova/Filters/OrderStatusFilter.php` — noun + `Filter` suffix
6
+ - Nova lenses: `app/Nova/Lenses/PendingOrdersLens.php` — adjective/noun + `Lens` suffix
7
+ - Nova metrics: `app/Nova/Metrics/NewOrdersCount.php` — noun + metric type suffix (`Count`, `Trend`, `Partition`)
8
+ - Policy files: `app/Policies/OrderPolicy.php` — model name + `Policy`
9
+
10
+ ## Do / don't
11
+
12
+ DO: Use `canSee()` / `canRun()` callbacks to hide or restrict fields/actions by role — DON'T: expose sensitive fields (e.g. `password`, `remember_token`, `secret`) in Nova resources
13
+ DO: Add database indexes for all columns used in filter or lens queries — DON'T: create filter queries with unindexed `LIKE '%x%'` (full table scan)
14
+ DO: Register a policy for every Nova resource in `AuthServiceProvider` — DON'T: leave a Nova resource without an associated policy
15
+ DO: Limit rows returned in lens queries (`->limit()`) — DON'T: write unbounded `orderBy` in lens without a `LIMIT`
16
+ DO: Use `canRun($request, $model)` on destructive or batch actions — DON'T: allow destructive Nova actions without authorization check
17
+ DO: Test Nova resource with a seeded user that has the expected role — DON'T: test Nova only as admin (misses `canSee` bugs)
18
+ DO: Use `BelongsTo` / `HasMany` Nova field types for relations — DON'T: query relations manually inside field callbacks
19
+
20
+ ## Forbidden patterns
21
+
22
+ NEVER: Nova action with no `canRun` or `authorizedToRun` check — any authenticated user can execute
23
+ NEVER: Filter query with `LIKE '%x%'` on unindexed column — degrades to full table scan at scale
24
+ NEVER: Nova resource without a registered policy — allows unauthorized view/edit/delete
25
+ NEVER: Return `password` or raw token fields in any Nova resource — credential exposure
26
+ NEVER: Nova lens with no row limit on unbounded table — OOM or timeout risk
@@ -0,0 +1,30 @@
1
+ # Scope
2
+
3
+ ## In-scope files and dirs
4
+
5
+ - `app/Nova/**/*.php` — Nova resource classes, custom fields, actions, lenses, cards
6
+ - `app/Policies/**/*.php` — model policies used by Nova authorization
7
+ - `app/Nova/Actions/**` — queued and inline Nova actions
8
+ - `app/Nova/Filters/**` — Nova filter classes
9
+ - `app/Nova/Lenses/**` — Nova lens classes
10
+ - `app/Nova/Fields/**` — custom field implementations
11
+ - `routes/nova.php` — custom Nova routes (if present)
12
+ - `config/nova.php` — Nova configuration (auth guard, path, middleware)
13
+ - `resources/views/nova/**` — custom Nova Blade views
14
+
15
+ ## Stack boundaries
16
+
17
+ - Nova resources: fields, rules, relatable, searchable, filterable config
18
+ - Nova actions: `handle()` method, action fields, queued execution
19
+ - Nova authorization: `authorizedToCreate`, `authorizedToUpdate`, policy gates
20
+ - Not in scope: customer-facing API routes without admin panel impact
21
+ - Not in scope: Eloquent model logic not surfaced via Nova resource
22
+
23
+ ## Triggers
24
+
25
+ - Adding or modifying `fields()`, `actions()`, `filters()`, `lenses()` on a resource
26
+ - Changing field visibility rules (`showOnIndex`, `showOnDetail`, `hideWhenUpdating`)
27
+ - Adding or changing Nova action with side effects (email, job dispatch, model update)
28
+ - Modifying policy method (`viewAny`, `create`, `update`, `delete`) used by Nova
29
+ - Adding searchable/relatable configuration on BelongsTo/MorphTo fields
30
+ - Changing Nova config (middleware, auth guard, pagination)
@@ -0,0 +1,36 @@
1
+ # Workflow
2
+
3
+ ## Implementation steps
4
+
5
+ 1. Locate or create Nova resource in `app/Nova/` — name matches Eloquent model
6
+ 2. Define `fields()`: use typed field classes (`Text`, `Number`, `BelongsTo`, `HasMany`)
7
+ 3. Set field visibility explicitly — default is shown everywhere; narrow with `showOnIndex`/`showOnDetail`
8
+ 4. Add `rules()` and `creationRules()`/`updateRules()` for validation
9
+ 5. For actions: implement `handle(ActionFields $fields, Collection $models)` — add `->canRun()` policy check
10
+ 6. For filters: implement `apply(Request $request, Builder $query, $value)` — avoid unbounded scans
11
+ 7. Verify policy: confirm `app/Policies/*Policy.php` has correct gates and is registered in `AuthServiceProvider`
12
+ 8. Test in Nova UI: create, update, delete, run action — confirm authorization blocks unauthorized users
13
+ 9. Run PHPUnit feature tests covering the changed resource behavior
14
+
15
+ ## Commands
16
+
17
+ ```bash
18
+ php artisan nova:resource ModelName # generate Nova resource
19
+ php artisan nova:action ActionName # generate action class
20
+ php artisan nova:filter FilterName # generate filter class
21
+ php artisan nova:lens LensName # generate lens class
22
+
23
+ php artisan test --filter=Nova # run Nova-related tests
24
+ php artisan route:list | grep nova # inspect registered Nova routes
25
+ php artisan policy:make ModelPolicy # generate policy
26
+ ```
27
+
28
+ ## Validation checklist
29
+
30
+ - [ ] Sensitive fields (password, token, PII) excluded from index view
31
+ - [ ] All filter/lens queries use indexed columns — check with EXPLAIN
32
+ - [ ] Action `canRun()` gates checked; unauthorized users cannot execute
33
+ - [ ] BelongsTo / relatable fields have `searchable()` if model count is large
34
+ - [ ] Policy registered in `AuthServiceProvider::$policies`
35
+ - [ ] Nova resource `$model` property matches correct Eloquent class
36
+ - [ ] Queued actions use correct queue connection from config
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: nextauth-patterns
3
+ description: NextAuth.js / Auth.js router. Use for provider setup, session strategy, callbacks, JWT, and route protection in Next.js.
4
+ ---
5
+
6
+ # NextAuth Patterns
7
+
8
+ ## Use when
9
+
10
+ - task changes `next-auth` / `@auth/core` provider config (`auth.ts`, `auth.config.ts`, `app/api/auth/[...nextauth]/route.ts`)
11
+ - task touches session strategy (`jwt` vs `database`), callbacks, or events
12
+ - task adds or modifies route protection via `auth()` / `middleware.ts`
13
+ - task wires a new OAuth provider (Google, GitHub, Azure AD) or credentials provider
14
+
15
+ ## Do not use when
16
+
17
+ - project is Laravel / PHP auth (use `auth-oidc-azure-bankid-patterns`)
18
+ - task is server-to-server API token auth with no session lifecycle
19
+ - task is OIDC outside Next.js (use `auth-oidc-azure-bankid-patterns`)
20
+
21
+ ## Inspect first
22
+
23
+ - `auth.ts` (Auth.js v5) or `app/api/auth/[...nextauth]/route.ts` (v4) — provider list, adapter, callbacks
24
+ - `middleware.ts` — protected paths and `auth()` invocation
25
+ - `app/api/auth/[...nextauth]/options.ts` or `auth.config.ts` — config split for edge runtime compatibility
26
+ - env vars: `NEXTAUTH_SECRET` (v4) / `AUTH_SECRET` (v5), `NEXTAUTH_URL` / `AUTH_URL`, provider client IDs/secrets
27
+ - adapter config when persisting sessions/users to DB (`@auth/prisma-adapter`, `@auth/drizzle-adapter`)
28
+
29
+ ## Avoid mistakes
30
+
31
+ - mixing v4 and v5 APIs — imports, callback shapes, and route handlers differ
32
+ - importing the full `auth.ts` (with adapter) inside `middleware.ts` — Node-only modules break edge runtime
33
+ - forgetting `AUTH_SECRET` in production — sessions fail silently in dev, hard-fail in prod
34
+ - exposing OAuth client secrets in `NEXT_PUBLIC_*` env vars
35
+ - using `jwt` session strategy with an adapter — adapter writes aren't read back
36
+
37
+ ## Router
38
+
39
+ 1. Load `references/conventions.md` for provider, session, and callback patterns.
40
+ 2. Load `references/scope.md` for in-scope files and v4-vs-v5 boundaries.
41
+ 3. Load `references/workflow.md` only for auth flow tracing and edge-runtime diagnosis.
42
+ 4. Keep secrets server-only; split config for edge compatibility.
43
+
44
+ ## References
45
+
46
+ - references/conventions.md
47
+ - references/scope.md
48
+ - references/workflow.md
@@ -0,0 +1,33 @@
1
+ ## Naming conventions
2
+
3
+ - Auth.js v5: `auth.ts` at project root exports `{ handlers, auth, signIn, signOut }` from `NextAuth(...)`
4
+ - Auth.js v5 split config: `auth.config.ts` (edge-safe, no adapter) + `auth.ts` (full, imports config + adapter)
5
+ - NextAuth v4: `app/api/auth/[...nextauth]/route.ts` exports `GET` / `POST` from `NextAuth(authOptions)`
6
+ - v4 options module: `app/api/auth/[...nextauth]/options.ts` exports `authOptions`
7
+ - Providers array: keep ordered consistently across environments (UI shows them in order)
8
+ - Callbacks: `jwt`, `session`, `signIn`, `redirect` — typed with `JWT`, `Session`, `User` from `next-auth`
9
+ - Adapter: import from `@auth/<orm>-adapter` (v5) or `@next-auth/<orm>-adapter` (v4)
10
+ - Custom pages: `pages: { signIn: "/auth/sign-in", error: "/auth/error" }` — file paths under `app/auth/`
11
+ - Middleware: `middleware.ts` at root exports default `auth` (v5) or `withAuth` (v4)
12
+
13
+ ## Do / don't
14
+
15
+ DO: Use `auth()` (v5) to read session in server components — DON'T: call `getServerSession()` in v5 code
16
+ DO: Split config when middleware needs auth — `auth.config.ts` is edge-safe, `auth.ts` is full — DON'T: import `auth.ts` from `middleware.ts`
17
+ DO: Pin `AUTH_SECRET` in all environments via env var — DON'T: rely on dev fallback in production
18
+ DO: Use `database` session strategy when you need server-side session invalidation — DON'T: combine `jwt` strategy with an adapter (adapter writes ignored)
19
+ DO: Type `session.user` with module augmentation in `types/next-auth.d.ts` — DON'T: cast `as any` in callbacks
20
+ DO: Validate redirect targets in `redirect` callback — DON'T: trust `url` parameter blindly (open redirect)
21
+ DO: Use `signIn` callback to return `false` or a URL string to deny — DON'T: throw inside `signIn` (becomes a generic error)
22
+ DO: Set `trustHost: true` in v5 only when behind a proxy with `AUTH_URL` set — DON'T: enable blindly
23
+
24
+ ## Forbidden patterns
25
+
26
+ NEVER: import `auth.ts` (with Prisma/Drizzle adapter) inside `middleware.ts` — edge runtime fails to bundle Node-only modules
27
+ NEVER: expose `AUTH_SECRET`, OAuth client secrets, or DB credentials via `NEXT_PUBLIC_*`
28
+ NEVER: store password hashes via the credentials provider without `bcrypt`/`argon2` — plaintext or weak hashing is a critical bug
29
+ NEVER: log full session or JWT payloads — leaks user PII and tokens
30
+ NEVER: return raw `User` from `authorize` callback (credentials provider) — sanitize to only fields needed in session
31
+ NEVER: skip the `redirect` callback validation — open redirect via `?callbackUrl=` parameter
32
+ NEVER: hard-code provider client IDs/secrets in `auth.config.ts` — env vars only
33
+ NEVER: silently downgrade `database` strategy to `jwt` — session invalidation expectations break
@@ -0,0 +1,33 @@
1
+ # Scope
2
+
3
+ ## In-scope files and dirs
4
+
5
+ - `auth.ts` / `auth.config.ts` — Auth.js v5 entry and split config
6
+ - `app/api/auth/[...nextauth]/route.ts` — v4 catch-all route handler
7
+ - `app/api/auth/[...nextauth]/options.ts` — v4 options module
8
+ - `middleware.ts` — route protection wiring at root
9
+ - `types/next-auth.d.ts` — module augmentation for typed `session.user`
10
+ - `app/auth/**` — custom sign-in / sign-out / error pages
11
+ - `lib/auth.ts` — re-export helpers and server-side session readers
12
+ - `.env` / `.env.example` — `AUTH_SECRET` / `NEXTAUTH_SECRET`, `AUTH_URL`, provider env vars
13
+ - adapter config when present: `lib/db.ts` for Prisma/Drizzle adapter
14
+
15
+ ## Stack boundaries
16
+
17
+ - NextAuth v4 vs Auth.js v5: APIs differ — verify version via `package.json` before applying patterns
18
+ - Edge runtime: middleware must use `auth.config.ts` (no adapter, no Node-only imports)
19
+ - Adapter persistence → combine with `prisma-patterns` (curated opt-in, gated to Prisma projects) or DB skill
20
+ - OAuth provider setup → provider docs are authoritative for scopes/claims
21
+ - Laravel/PHP auth → use `auth-oidc-azure-bankid-patterns`
22
+ - Server-to-server API tokens (no session) → out of scope
23
+
24
+ ## Triggers
25
+
26
+ - Adding a new OAuth provider or credentials provider
27
+ - Switching session strategy (`jwt` ↔ `database`)
28
+ - Adding or modifying a callback (`jwt`, `session`, `signIn`, `redirect`)
29
+ - Wiring or modifying `middleware.ts` route protection
30
+ - Adding an adapter (`@auth/prisma-adapter`, `@auth/drizzle-adapter`)
31
+ - Module augmentation to add custom fields to `session.user`
32
+ - Migrating from NextAuth v4 to Auth.js v5
33
+ - Splitting config for edge compatibility
@@ -0,0 +1,46 @@
1
+ # Workflow
2
+
3
+ ## Implementation steps
4
+
5
+ 1. Confirm version: check `package.json` for `next-auth` (v4) vs `next-auth@beta` / Auth.js v5. APIs differ.
6
+ 2. For v5: ensure `auth.ts` exports `{ handlers, auth, signIn, signOut }` from `NextAuth(authConfig)`.
7
+ 3. If `middleware.ts` needs auth, split: `auth.config.ts` (edge-safe — no adapter, no Node modules) + `auth.ts` (full).
8
+ 4. Add providers to the `providers` array; pull client IDs/secrets from env (`process.env.GOOGLE_CLIENT_ID` etc.).
9
+ 5. For credentials provider, hash passwords with `bcrypt` or `argon2` in `authorize`; never accept plaintext.
10
+ 6. Add adapter only when using `database` session strategy or persisting users; remove if using pure `jwt`.
11
+ 7. Augment types in `types/next-auth.d.ts` to expose custom fields on `session.user`.
12
+ 8. In `redirect` callback, validate `url` is same-origin or in an allowlist before returning.
13
+ 9. Set `AUTH_SECRET` in every environment (`openssl rand -base64 32`).
14
+ 10. Test the flow end-to-end: sign in, refresh page, sign out — confirm session reads in server components via `await auth()`.
15
+
16
+ ## Commands
17
+
18
+ ```bash
19
+ yarn dev # Next dev server (auth flow available at /api/auth/*)
20
+ yarn build && yarn start # production build + run (sanity check edge bundle)
21
+
22
+ # Auth.js v5 env setup
23
+ openssl rand -base64 32 # generate AUTH_SECRET
24
+ yarn next telemetry status # confirm telemetry preference (unrelated but commonly asked)
25
+
26
+ # Provider checks
27
+ curl -I "$AUTH_URL/api/auth/providers" # list configured providers
28
+ curl -I "$AUTH_URL/api/auth/session" # current session (unauthenticated returns {})
29
+
30
+ # Common diagnostic: edge bundling
31
+ yarn build 2>&1 | grep -i "module not found" # catches Node-only imports leaking into middleware
32
+ ```
33
+
34
+ ## Validation checklist
35
+
36
+ - [ ] Version pinned and patterns match v4 vs v5 conventions
37
+ - [ ] `AUTH_SECRET` (v5) or `NEXTAUTH_SECRET` (v4) set in all environments
38
+ - [ ] Middleware imports `auth.config.ts`, not `auth.ts` (no adapter in edge bundle)
39
+ - [ ] Credentials provider hashes passwords with `bcrypt` / `argon2`, never plaintext
40
+ - [ ] `redirect` callback validates same-origin or allowlist before returning
41
+ - [ ] Session strategy matches adapter use (`database` ↔ adapter present; `jwt` ↔ no adapter persistence)
42
+ - [ ] `session.user` custom fields typed via `types/next-auth.d.ts` module augmentation
43
+ - [ ] No `console.log` of session or JWT payload
44
+ - [ ] OAuth secrets only in env vars (no `NEXT_PUBLIC_*` leakage)
45
+ - [ ] End-to-end flow tested: sign in → server-side `auth()` returns session → sign out clears
46
+ - [ ] Regression test added before fixing an auth bug (e.g. integration test that hits `/api/auth/session`)
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: nx-tag-conventions
3
+ description: Haus-specific Nx project tag, module-boundary, and generator-placement conventions. Use alongside the official nx-workspace/nx-generate skills, not instead of them.
4
+ ---
5
+
6
+ # Nx Tag Conventions
7
+
8
+ This supplements `haus.nx-nx-workspace` and `haus.nx-nx-generate` (official, generic Nx
9
+ guidance) with conventions specific to Haus-managed workspaces that those skills don't cover.
10
+
11
+ ## Use when
12
+
13
+ - naming or applying `tags` on a new or existing Nx project
14
+ - adding a custom generator or executor
15
+ - enforcing or reviewing `enforce-module-boundaries` lint rules
16
+
17
+ ## Conventions
18
+
19
+ - Library tags: `scope:<feature>` for domain ownership, `type:ui` / `type:data` / `type:util` /
20
+ `type:feature` for layer — apply both dimensions to every project.
21
+ - Generated executors live at `tools/executors/<executor-name>/executor.ts`.
22
+ - Generated generators live at `tools/generators/<generator-name>/generator.ts`.
23
+ - Enforce tag constraints via `nx.json`'s `enforce-module-boundaries` rule — never commit a
24
+ change that removes an existing boundary constraint without an explicit decision to widen it.
25
+ - Prefer local workspace generators over external plugin generators when both could satisfy a
26
+ request (matches `haus.nx-nx-generate`'s guidance, called out here because it's easy to miss
27
+ once local generators exist in `tools/generators/`).
28
+
29
+ ## Do not use when
30
+
31
+ - exploring workspace structure or running generators — use the official
32
+ `haus.nx-nx-workspace` / `haus.nx-nx-generate` skills for that.
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: package-manager-yarn4-pnpm89
3
+ description: Package manager router for Yarn 4 and pnpm 8.9 workspaces, constraints, and lockfile behavior.
4
+ ---
5
+
6
+ # Package Manager Yarn4 Pnpm89
7
+
8
+ ## Use when
9
+
10
+ - task changes dependency graph, workspace linking, or lockfile behavior
11
+ - task touches `.yarnrc.yml`, `pnpm-workspace.yaml`, root package manager scripts
12
+
13
+ ## Do not use when
14
+
15
+ - task is feature implementation with no dependency/workspace impact
16
+ - repo package manager differs from yarn4/pnpm89
17
+
18
+ ## Inspect first
19
+
20
+ - root `package.json`, lockfile, and manager-specific config files
21
+ - workspace definitions and nohoist/public-hoist rules if present
22
+ - scripts invoking manager-specific commands
23
+
24
+ ## Avoid mistakes
25
+
26
+ - mixing npm install paths in yarn/pnpm managed repos
27
+ - manual lockfile edits that break deterministic installs
28
+ - dependency version drift across workspace packages
29
+
30
+ ## Router
31
+
32
+ 1. Load `references/conventions.md` for naming, do/don't, and forbidden patterns.
33
+ 2. Load `references/scope.md` for manager-specific targets.
34
+ 3. Load `references/workflow.md` only for install/lock/debug flow.
35
+ 4. Keep lockfile and workspace resolution deterministic.
36
+
37
+ ## References
38
+
39
+ - references/conventions.md
40
+ - references/scope.md
41
+ - references/workflow.md
@@ -0,0 +1,25 @@
1
+ ## Naming conventions
2
+
3
+ - Workspace package names: follow root naming convention (e.g. `@scope/package-name`)
4
+ - Patch files: `patches/<package-name>@<version>.patch` in root `patches/` directory
5
+ - `.yarnrc.yml` (Yarn 4): `nodeLinker`, `yarnPath`, and `plugins` entries
6
+ - `.npmrc` (pnpm): `shamefully-hoist`, `strict-peer-dependencies`, workspace catalog entries
7
+ - `packageManager` field in root `package.json`: pinned with exact version via corepack (e.g. `"yarn@4.5.0"`)
8
+
9
+ ## Do / don't
10
+
11
+ DO: Use `workspace:*` (or `workspace:^`) protocol for all internal package dependencies — DON'T: use a fixed version number for workspace deps (breaks in-repo resolution)
12
+ DO: Pin the package manager version in `package.json#packageManager` and use `corepack` to enforce it — DON'T: rely on globally installed package manager versions that differ per developer
13
+ DO: Commit the lockfile (`yarn.lock` / `pnpm-lock.yaml`) on every dependency change — DON'T: add lockfiles to `.gitignore`
14
+ DO: Keep shared dependency versions aligned from a single source of truth — DON'T: duplicate version strings across multiple `package.json` files. (Note: `pnpm catalog:` entries automate this but require pnpm v9+ — the pnpm 8.9 line this skill pins predates them, so align versions manually or upgrade pnpm first.)
15
+ DO: Run install (`yarn install` / `pnpm install`) after any `package.json` change to keep lockfile in sync — DON'T: edit `package.json` without refreshing the lockfile
16
+ DO: Use `--frozen-lockfile` (pnpm) or `--immutable` (Yarn 4) in all CI install steps — DON'T: allow CI to silently update the lockfile during install
17
+
18
+ ## Forbidden patterns
19
+
20
+ NEVER: `npm install` in a Yarn or pnpm workspace — overwrites lockfile with wrong format
21
+ NEVER: Manual edits to `yarn.lock` or `pnpm-lock.yaml` — breaks integrity checksums
22
+ NEVER: Change `nodeLinker` in `.yarnrc.yml` without a full `yarn install` and CI validation — breaks module resolution silently
23
+ NEVER: `--frozen-lockfile` / `--immutable` skipped in CI — allows lockfile drift between branches
24
+ NEVER: Publish a workspace package while still referencing `workspace:*` in its `dependencies` — published package becomes uninstallable by consumers
25
+ NEVER: `--ignore-scripts` in install without documented reason — may silently skip required postinstall build steps
@@ -0,0 +1,30 @@
1
+ # Scope
2
+
3
+ ## In-scope files and dirs
4
+
5
+ - `package.json` (root and workspace packages) — dependencies, scripts, workspaces field
6
+ - `yarn.lock` / `pnpm-lock.yaml` — deterministic lockfiles (do not edit manually)
7
+ - `.yarnrc.yml` — Yarn 4 configuration (nodeLinker, plugins, npmRegistryServer, pnpMode)
8
+ - `pnpm-workspace.yaml` — pnpm workspace glob definitions
9
+ - `.npmrc` — registry auth, scoped registry config (pnpm reads this)
10
+ - `.pnp.cjs`, `.pnp.loader.mjs` — Yarn PnP manifests (generated, do not edit)
11
+ - `.yarn/` — Yarn 4 cache, releases, plugins, sdks
12
+ - `patches/` — `patch-package` or Yarn patch: entries
13
+
14
+ ## Stack boundaries
15
+
16
+ - Yarn 4: PnP mode vs `node-modules` linker; Zero-Installs caching; Corepack version pinning
17
+ - pnpm 8/9: `shamefully-hoist`, `public-hoist-pattern`, workspace protocol (`workspace:*`)
18
+ - Workspace management: adding/removing packages, cross-package dependencies
19
+ - Not in scope: package contents/feature implementation
20
+ - Not in scope: npm-managed projects (no `yarn.lock` or `pnpm-lock.yaml`)
21
+
22
+ ## Triggers
23
+
24
+ - Adding, removing, or upgrading a dependency
25
+ - Adding a new workspace package
26
+ - Changing `nodeLinker` in `.yarnrc.yml` (PnP ↔ node-modules)
27
+ - Adding or removing a `patch:` entry in `package.json`
28
+ - Changing `pnpm-workspace.yaml` glob patterns
29
+ - Pinning or upgrading package manager version via Corepack
30
+ - Adding scoped registry or auth token configuration
@@ -0,0 +1,39 @@
1
+ # Workflow
2
+
3
+ ## Implementation steps
4
+
5
+ 1. Confirm which manager the repo uses: check for `yarn.lock` (Yarn) or `pnpm-lock.yaml` (pnpm)
6
+ 2. Check Corepack version pin in `package.json` `packageManager` field — use matching version
7
+ 3. For dependency additions: use the correct workspace flag to target the right package
8
+
9
+ ### Yarn 4
10
+
11
+ ```bash
12
+ yarn add <pkg> # add to root
13
+ yarn workspace <ws-name> add <pkg> # add to specific workspace
14
+ yarn workspaces foreach run build # run build in all workspaces
15
+ yarn plugin import @yarnpkg/plugin-sdks # one-time: install sdks plugin
16
+ yarn sdks vscode # update editor SDK (requires plugin above)
17
+ yarn dedupe # deduplicate lockfile entries
18
+ ```
19
+
20
+ ### pnpm 8/9
21
+
22
+ ```bash
23
+ pnpm add <pkg> # add to root
24
+ pnpm add <pkg> --filter <ws-name> # add to specific workspace
25
+ pnpm install # install after lockfile change
26
+ pnpm run --filter <ws-name> build # run target in one workspace
27
+ pnpm -r run build # run build in all workspaces
28
+ pnpm dedupe # deduplicate lockfile
29
+ ```
30
+
31
+ ## Validation checklist
32
+
33
+ - [ ] Never run `npm install` in a Yarn/pnpm managed repo — it corrupts lockfile
34
+ - [ ] `yarn.lock` / `pnpm-lock.yaml` committed after every dependency change
35
+ - [ ] Cross-workspace dependencies use `workspace:*` protocol — not `file:` paths
36
+ - [ ] No manually edited lockfile entries
37
+ - [ ] `.yarnrc.yml` `nodeLinker` unchanged unless intentional migration
38
+ - [ ] Corepack `packageManager` field matches CI toolchain version
39
+ - [ ] PnP mode: all tools work with PnP loader (check `.yarn/sdks` for editor support)
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: qliro-patterns
3
+ description: Qliro Checkout router. Use for `@haus-tech/qliro-plugin` integration in Vendure storefronts.
4
+ ---
5
+
6
+ # Qliro Patterns
7
+
8
+ ## Use when
9
+
10
+ - task wires Qliro Checkout via `@haus-tech/qliro-plugin` in a Vendure backend or Next.js storefront
11
+ - task touches Qliro order callbacks, refund flow, or merchant API config
12
+ - task adds or modifies Qliro webhook handlers (order status updates)
13
+
14
+ ## Do not use when
15
+
16
+ - payment provider is Stripe / Klarna / Adyen (use the matching skill)
17
+ - task is generic e-commerce checkout UX with no Qliro API contact
18
+ - project does not use `@haus-tech/qliro-plugin`
19
+
20
+ ## Inspect first
21
+
22
+ - `@haus-tech/qliro-plugin` install + config in Vendure's `vendure-config.ts`
23
+ - env vars: `QLIRO_MERCHANT_API_KEY`, `QLIRO_MERCHANT_ID`, `QLIRO_API_URL` (production vs sandbox URL differs)
24
+ - storefront integration: where Qliro Checkout HTML / iframe snippet is rendered
25
+ - order callback / push notification endpoint (Qliro pushes order status changes)
26
+ - refund flow: server-side endpoint hitting Qliro API with proper auth
27
+
28
+ ## Avoid mistakes
29
+
30
+ - mixing sandbox + production env vars — order corruption
31
+ - exposing `QLIRO_MERCHANT_API_KEY` to client — full merchant compromise
32
+ - treating order push as authoritative without idempotency — Qliro retries on 5xx
33
+ - relying on user-side checkout completion redirect — push notifications are the source of truth
34
+ - skipping signature validation on Qliro push payloads
35
+ - hard-coding currency / locale — Nordic markets have per-country requirements
36
+
37
+ ## Router
38
+
39
+ 1. Load `references/conventions.md` for plugin config, push, and refund patterns.
40
+ 2. Load `references/scope.md` for in-scope files and Vendure-vs-storefront boundaries.
41
+ 3. Load `references/workflow.md` only for order push diagnosis and refund flow.
42
+ 4. Keep merchant key server-only; push handlers idempotent; respect sandbox/production split.
43
+
44
+ ## References
45
+
46
+ - references/conventions.md
47
+ - references/scope.md
48
+ - references/workflow.md
@@ -0,0 +1,28 @@
1
+ ## Naming conventions
2
+
3
+ - Plugin config: registered in `vendure-config.ts` `plugins` array as `QliroPlugin.init({...})`
4
+ - Env vars: `QLIRO_MERCHANT_API_KEY` (server-only), `QLIRO_MERCHANT_ID`, `QLIRO_API_URL`, `QLIRO_TERMS_URL`
5
+ - Order metadata: `qliro_order_id` and `qliro_status` columns on `Order` entity
6
+ - Push handler route: `/payments/qliro/push` (POST) — accepts Qliro callbacks
7
+ - Refund flow: `qliroRefund(orderId, amount, reason)` service method, never inlined in controller
8
+
9
+ ## Do / don't
10
+
11
+ DO: Use the official `@haus-tech/qliro-plugin` — DON'T: implement Qliro Checkout from scratch in Vendure code
12
+ DO: Store `qliro_order_id` on the Vendure `Order` for reconciliation — DON'T: rely on user session alone
13
+ DO: Make the push handler idempotent (check current `qliro_status` before mutating) — DON'T: assume each push is a new event
14
+ DO: Use sandbox `QLIRO_API_URL` (`https://pago.qit.nu` etc.) in dev/staging — DON'T: hit live API from non-production
15
+ DO: Validate push payload signature where the plugin exposes a verification helper — DON'T: trust raw body
16
+ DO: Surface Qliro's localized error copy back to checkout UI — DON'T: replace with English fallbacks (Nordic UX expects native language)
17
+ DO: Pin Qliro plugin version explicitly — DON'T: track `latest`
18
+
19
+ ## Forbidden patterns
20
+
21
+ NEVER: ship `QLIRO_MERCHANT_API_KEY` to client bundle
22
+ NEVER: trust browser-side checkout completion as the order-finalize trigger — Qliro push is authoritative
23
+ NEVER: mutate order state on push without idempotency guard — Qliro retries cause double-completion
24
+ NEVER: log Qliro payloads containing customer personal numbers / addresses — Nordic PII regulations
25
+ NEVER: hard-code currency to SEK — Qliro supports multiple Nordic currencies; read from order
26
+ NEVER: skip the sandbox/production env split — order ledger corruption
27
+ NEVER: deploy without a working push endpoint (404 / 500 means Qliro retries forever)
28
+ NEVER: roll your own Qliro API client when the plugin exposes one — duplicates auth + retry logic
@@ -0,0 +1,30 @@
1
+ # Scope
2
+
3
+ ## In-scope files and dirs
4
+
5
+ - `vendure-config.ts` — `QliroPlugin.init({...})` registration
6
+ - `src/plugins/qliro/**` — local overrides or extensions of the Qliro plugin behavior
7
+ - Storefront Qliro integration: page/component that renders Qliro Checkout snippet
8
+ - Push handler route exposed by the plugin (typically `/payments/qliro/push`)
9
+ - Refund / cancel service code using `@haus-tech/qliro-plugin` exports
10
+ - `.env` / `.env.example` — Qliro env vars
11
+ - `package.json` — `@haus-tech/qliro-plugin` version pin
12
+
13
+ ## Stack boundaries
14
+
15
+ - Requires Vendure backend (`@vendure/core`) and `@haus-tech/qliro-plugin`
16
+ - Storefront can be Next.js, Remix, React Router v7 — same Qliro snippet pattern
17
+ - Not in scope: non-Vendure Qliro integrations (custom Qliro API client)
18
+ - Not in scope: Stripe / Klarna / Adyen (separate skills)
19
+ - Database side → combine with `database-patterns`
20
+ - Vendure plugin development beyond Qliro → `vendure-plugin-patterns`
21
+
22
+ ## Triggers
23
+
24
+ - Adding Qliro to a Vendure project
25
+ - Modifying Qliro plugin config (`init({...})` options)
26
+ - Adding refund / cancel flow
27
+ - Switching sandbox ↔ production
28
+ - Adjusting push handler logic (status transitions, side effects)
29
+ - Upgrading `@haus-tech/qliro-plugin` major version
30
+ - Adding new Qliro market (currency, locale, terms URL)