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