@haus-tech/haus-workflow 6.7.1 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +41 -85
  3. package/dist/cli.js +17629 -23486
  4. package/docs/before-you-start.md +17 -22
  5. package/docs/glossary.md +10 -8
  6. package/package.json +3 -6
  7. package/packages/agents/issue-creator.md +59 -0
  8. package/packages/configs/eslint/eslint.config.mjs +90 -0
  9. package/packages/configs/lighthouse/lighthouserc.yml +35 -0
  10. package/packages/configs/prettier/.prettierignore +28 -0
  11. package/packages/configs/prettier/prettier.config.cjs +12 -0
  12. package/packages/packages.yaml +81 -0
  13. package/packages/skills/adr-decisions/SKILL.md +113 -0
  14. package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
  15. package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
  16. package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
  17. package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
  18. package/packages/skills/bullmq-patterns/SKILL.md +53 -0
  19. package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
  20. package/packages/skills/bullmq-patterns/references/scope.md +30 -0
  21. package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
  22. package/{library/global → packages}/skills/haus-workflow/SKILL.md +28 -41
  23. package/packages/skills/haus-workflow/references/init.md +57 -0
  24. package/{library/global → packages}/skills/haus-workflow/references/new.md +15 -20
  25. package/packages/skills/i18next-patterns/SKILL.md +52 -0
  26. package/packages/skills/i18next-patterns/references/conventions.md +32 -0
  27. package/packages/skills/i18next-patterns/references/scope.md +29 -0
  28. package/packages/skills/i18next-patterns/references/workflow.md +39 -0
  29. package/packages/skills/issue-authoring/SKILL.md +184 -0
  30. package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
  31. package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
  32. package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
  33. package/packages/skills/laravel-nova-patterns/SKILL.md +45 -0
  34. package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
  35. package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
  36. package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
  37. package/packages/skills/nextauth-patterns/SKILL.md +48 -0
  38. package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
  39. package/packages/skills/nextauth-patterns/references/scope.md +33 -0
  40. package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
  41. package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
  42. package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
  43. package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
  44. package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
  45. package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
  46. package/packages/skills/qliro-patterns/SKILL.md +48 -0
  47. package/packages/skills/qliro-patterns/references/conventions.md +28 -0
  48. package/packages/skills/qliro-patterns/references/scope.md +30 -0
  49. package/packages/skills/qliro-patterns/references/workflow.md +46 -0
  50. package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
  51. package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
  52. package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
  53. package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
  54. package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
  55. package/packages/skills/strapi-patterns/SKILL.md +53 -0
  56. package/packages/skills/strapi-patterns/references/conventions.md +33 -0
  57. package/packages/skills/strapi-patterns/references/scope.md +29 -0
  58. package/packages/skills/strapi-patterns/references/workflow.md +47 -0
  59. package/packages/skills/vendure-app-patterns/SKILL.md +34 -0
  60. package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
  61. package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
  62. package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
  63. package/packages/skills/vendure-plugin-patterns/SKILL.md +45 -0
  64. package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
  65. package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
  66. package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
  67. package/packages/skills/whats-installed/SKILL.md +55 -0
  68. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
  69. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
  70. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
  71. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
  72. package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
  73. package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
  74. package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
  75. package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
  76. package/packages/skills/writing-documentation/SKILL.md +153 -0
  77. package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
  78. package/packages/skills/writing-documentation/references/claude-template.md +43 -0
  79. package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
  80. package/packages/skills/writing-documentation/references/summary-template.md +81 -0
  81. package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
  82. package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
  83. package/packages/templates/agentic-workflow-poc.md +180 -0
  84. package/packages/templates/agentic-workflow-standard.md +170 -0
  85. package/packages/templates/decision-template.md +27 -0
  86. package/packages/templates/decisions-ci-gate.yml +32 -0
  87. package/packages/templates/lefthook-branch-guard.yml +27 -0
  88. package/packages/templates/lefthook-lighthouse.yml +28 -0
  89. package/packages/templates/lefthook-quality.yml +34 -0
  90. package/packages/templates/lefthook-security.yml +27 -0
  91. package/packages/templates/start-here.md +72 -0
  92. package/library/catalog/decisions-triggers.json +0 -26
  93. package/library/catalog/haus-lock.schema.json +0 -4
  94. package/library/catalog/manifest.json +0 -5941
  95. package/library/catalog/validation-rules.json +0 -169
  96. package/library/global/settings-fragments/hooks.json +0 -53
  97. package/library/global/skills/haus-workflow/references/init.md +0 -88
  98. package/scripts/postinstall.mjs +0 -62
  99. /package/{library/global → packages}/agents/request-assessor.md +0 -0
  100. /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
  101. /package/{library/global → packages}/agents/request-designer.md +0 -0
  102. /package/{library/global → packages}/agents/request-scorer.md +0 -0
  103. /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
  104. /package/{library/global → packages}/agents/request-specifier.md +0 -0
  105. /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
  106. /package/{library/global → packages}/skills/request/SKILL.md +0 -0
  107. /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
  108. /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
  109. /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
  110. /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
  111. /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
  112. /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
  113. /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
  114. /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
  115. /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
  116. /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
  117. /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
  118. /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
  119. /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
  120. /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
  121. /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
  122. /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
  123. /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
  124. /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
  125. /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
  126. /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
  127. /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
@@ -0,0 +1,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,184 @@
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
+ - **Haus-shipped**: the finding concerns the haus program or content it
35
+ ships. That is a command's behaviour, output or exit code, a wrong or
36
+ missing finding from doctor, the decision gate or the CI gate, a guard hook,
37
+ a file the CLI writes and owns (`.claude/settings.json`,
38
+ `.claude/rules/haus.md`, the managed blocks in `CLAUDE.md` and `AGENTS.md`,
39
+ `.haus-workflow/WORKFLOW.md`, `.haus-workflow/synced.json`), a skill or
40
+ agent `haus sync` wrote from a package (the folders
41
+ `.haus-workflow/synced.json` lists under `.claude/`), or a template or config
42
+ haus ships under `packages/`. A local issue about
43
+ shipped content is invisible upstream and the defect ships to every other
44
+ consumer, so file it where it is fixed once for everyone:
45
+ `gh issue create -R WeAreHausTech/haus-workflow …`. Already in that repo,
46
+ routing is a no-op: file locally. A skill or agent haus pulls from a pinned
47
+ upstream (superpowers and the other upstream entries of `packages.yaml`) goes
48
+ there too: haus owns the pin and the selection.
49
+
50
+ Upstream-routed issues cross a repo boundary. NEVER include client code,
51
+ secrets, internal URLs, or client-identifying paths: name the shipped item and
52
+ its path as shipped in `packages/` (for a CLI finding, the command and the
53
+ haus version), describe the defect against the shipped content, and call the
54
+ discovering project only "a consumer repo".
55
+
56
+ If upstream filing is unavailable (no access, unauthenticated, issues
57
+ disabled), do not drop the finding: file it project-local with one extra
58
+ header line, and say so in your report:
59
+ `> **Routing:** haus-shipped, upstream filing failed (<reason>); re-file to WeAreHausTech/haus-workflow`
60
+
61
+ A retro candidate is a finding like any other: route it by what it is about.
62
+ File one issue per candidate the human picks, and none for the rest.
63
+
64
+ ## Common header (every issue)
65
+
66
+ ```markdown
67
+ > **Type:** finding | deferred | idea · **Severity/Size:** <value> · **Source:** <where + date>
68
+ > **Status:** Awaiting human approval — do not implement before sign-off.
69
+ > **Failing test exists:** Yes — `<path>` / No / n/a
70
+ ```
71
+
72
+ Keep the header even with native fields set — the approval gate and failing-test
73
+ flag have no native equivalent.
74
+
75
+ ### Recording approval
76
+
77
+ **Read `references/recording-approval.md` before touching a `Status` line** — it holds
78
+ the named-evidence bar (without that evidence you edit nothing and start nothing), the
79
+ exact approved-status format, and the read-modify-write recipe that keeps `gh issue edit`
80
+ from wiping the technical section.
81
+
82
+ ## Templates
83
+
84
+ ### finding — a bug or review finding
85
+
86
+ Sections, in order: `Summary` · `Consequences` · `What's affected` · `Risks` ·
87
+ `Is it visible in the application?` · `---` · `Technical description`
88
+ containing `Reproduction`, `Root cause`, `Suggested fix`, `Verification`,
89
+ `Related`.
90
+
91
+ Rules:
92
+
93
+ - Never claim a reproduction that was not performed — write "code-read, not
94
+ reproduced" explicitly.
95
+ - When a pattern repeats, note every occurrence.
96
+ - Record environment traps (e.g. reproduces only in a bundled build, not via
97
+ raw imports — omitting that sends a fixer down the wrong path).
98
+ - If the finding implies an architecture decision, draft or reference an ADR
99
+ via the `adr-decisions` skill and link it under `Related`.
100
+
101
+ ### deferred — scope pushed out of a plan
102
+
103
+ Sections: `What was deferred` · `Why it was deferred` (the decision and who
104
+ made it) · `What we are doing instead` · `What would make this worth doing`
105
+ (the trigger — the critical field: it lets the item be re-evaluated
106
+ later) · `Rough size` · `---` · `Technical notes` ·
107
+ `Related plan/ADR`.
108
+
109
+ No root cause or reproduction — there is no defect.
110
+
111
+ ### idea — the lightest template
112
+
113
+ Sections: `What` (one sentence) · `Why / what problem it solves` ·
114
+ `Rough size` (a guess is fine) · `What would make this worth doing` ·
115
+ `Context when the idea came up` (where in the code, what task was in
116
+ progress — what makes the idea recoverable six months later).
117
+
118
+ ## Operating rules
119
+
120
+ - Titles in plain language a non-developer understands — no jargon, finding IDs,
121
+ or file paths.
122
+ - One issue per item; merge only on explicit request.
123
+ - Never invent detail. Unverified reproductions or root causes must be
124
+ labelled as such. An issue with honest gaps beats a confident guess.
125
+ - `has-failing-test` label wherever a red test exists.
126
+ - Dedupe search scope: open and closed issues, titles and bodies, in English
127
+ and Swedish (`gh issue list --search`, `gh search issues`).
128
+ - **Keep dedupe queries to 2–3 distinctive words, and run several narrow ones
129
+ rather than one long one.** GitHub free-text terms are ANDed within a single
130
+ indexed field, so a query mixing title-only and body-only words matches
131
+ nothing and silently reports "no duplicate". Verified: an issue whose title
132
+ matched `placeholder bug report` and whose body matched `skill verification`
133
+ was returned by each query alone and by neither combined. A long query is the
134
+ failure mode that manufactures duplicates.
135
+ - Run both engines: `gh issue list --search` and `gh search issues` disagree on
136
+ the same query; treat a hit from either as a duplicate.
137
+
138
+ ## Procedure
139
+
140
+ 1. Route each item (Routing section above), then confirm GitHub issues are
141
+ available on its destination:
142
+ `gh repo view [<owner>/<repo>] --json nameWithOwner,hasIssuesEnabled`.
143
+ If this fails for the local repo (no GitHub remote, `gh` missing or
144
+ unauthenticated) or reports `hasIssuesEnabled: false`, abort immediately —
145
+ file nothing — and tell whoever invoked you to create a background-task
146
+ chip instead. If it fails only for the upstream repo, fall back to
147
+ project-local filing with the routing marker line instead of aborting.
148
+ 2. **Read `references/native-metadata.md` before running the detection query** — it
149
+ holds the detection query itself, the union inline-fragment gotcha, the truncation
150
+ and permission cases, the native-vs-fallback table, and the mutations. Do not
151
+ improvise the query from memory — the issue-fields schema is still rolling out,
152
+ and a guessed field name errors in a way that reads as "this repo has no issue
153
+ fields". Run the detection query; pick native or fallback per row of that table.
154
+ Confirm every label you intend to pass exists on the destination repo
155
+ (`gh label list [-R <owner>/<repo>]`) — a missing
156
+ label makes `gh issue create` fail outright. Do NOT create the missing ones:
157
+ labels are shared repo taxonomy, creating them unattended is exactly the kind
158
+ of unapproved change this skill exists to avoid. Drop the missing ones, keep
159
+ the rest, and list every label you skipped so a human can add them
160
+ deliberately. If `needs-triage` itself is missing, still file — then say so
161
+ prominently, because the issue is now untriaged with nothing marking it.
162
+ 3. Draft the body to a temp file using the matching template. **YOU MUST write
163
+ EVERY issue body through a QUOTED heredoc — `cat > "$f" <<'EOF'` — never
164
+ unquoted:** this draft, the approval-record edit, the step-7 cross-reference
165
+ pass, any body write at all. Unquoted, it expands `$VAR`, `${...}`,
166
+ `` ` ` `` and `$(...)` inside the code snippets the technical section quotes,
167
+ silently corrupting the issue and potentially executing repo-derived commands.
168
+ 4. Dedupe search — IMMEDIATELY before `gh issue create`, not at batch start
169
+ (a batch-start check goes stale and produces duplicates, as it did in
170
+ the pilot). Search the destination repo: `gh issue list -R <owner>/<repo> --search`,
171
+ `gh search issues --repo <owner>/<repo>`.
172
+ 5. `gh issue create [-R <owner>/<repo>] --title '<plain title>' --body-file <tmp> --label needs-triage [--label …]`
173
+ 6. Query the created issue's `viewerCanType`/`viewerCanSetFields`/`viewerCanLabel`;
174
+ set native type/priority/effort only where the flag allows, then read the
175
+ state back — the ack does not prove the value landed. The capability query, the
176
+ three mutations (`updateIssueIssueType`, `setIssueFieldValue`, `addSubIssue`) and
177
+ the read-back query are all in `references/native-metadata.md` — read it before
178
+ mutating.
179
+ 7. After the whole batch: relationships pass (`addSubIssue`, `#n` cross-ref
180
+ edits via `gh issue edit`) — issue numbers do not exist until creation,
181
+ so this pass must wait.
182
+ 8. Report a table: issue URL · type · priority · effort · labels · relations —
183
+ plus, honestly, every fallback used and why (absent setup, truncation, or a
184
+ `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.
@@ -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,45 @@
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
+ For the current API reference, fetch https://nova.laravel.com/docs/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
@@ -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