Skip to content

Commit 43d8cd7

Browse files
buzz-codeclaude
andauthored
Add agent skills and roadmap guideline from multi-repo-codespace (#207)
* Add agent skills and roadmap guideline from multi-repo-codespace Copy project-relevant skills from multi-repo-codespace .github/skills (all except run-one-project, which only wraps the codespace start script), symlink .claude/skills to them, and add the roadmap guideline and skills index to AGENTS.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012m7WPGj4ePE7vjCiM6yH7b * Sync copilot-instructions.md with AGENTS.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012m7WPGj4ePE7vjCiM6yH7b --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent aca6868 commit 43d8cd7

16 files changed

Lines changed: 1300 additions & 2 deletions

File tree

‎.claude/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.github/skills

‎.github/copilot-instructions.md‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ School attendance management system: teachers, students, classes, attendance rep
1010
- **Shared submodules**: `client/shared` -> `nra-client`, `server/shared` -> `nra-server`
1111

1212
Initialize before first use: `git submodule update --init --recursive`
13-
Never modify code in `client/shared` or `server/shared` directly — those are separate repos.
13+
Avoid modifying code in `client/shared` or `server/shared` directly when possible — they're separate repos used by other projects. Prefer keeping changes local to this repo. If a change genuinely belongs in the shared code, it's fine to edit it there and go through the normal commit/push flow for that repo.
1414

1515
## Testing
1616

@@ -51,4 +51,26 @@ Auth: JWT via `server/shared/auth/`. Permissions: `client/shared/utils/permissio
5151

5252
**3. Surgical Changes** — Touch only what is necessary. Do not improve adjacent code or formatting. Match existing style. Every changed line must trace to the user's request.
5353

54-
**4. Goal-Driven Execution** — Define verifiable success criteria before starting. For multi-step tasks, write a brief plan with checkpoints and verify each one.
54+
**4. Goal-Driven Execution** — Define verifiable success criteria before starting. For multi-step tasks, write a brief plan with checkpoints and verify each one.
55+
56+
**5. Update the Roadmap** — Every new client-facing feature (new page, user-visible capability, UI flow) gets an entry at the end of `client/src/roadmapFeatures.js` (array is `.reverse()`d for display, newest first):
57+
```js
58+
{ html: '<Hebrew description>', status: 'בוצע', statusColor: 'success' }
59+
```
60+
Skip for internal/backend-only changes.
61+
62+
## Skills
63+
64+
`.github/skills/` (symlinked from `.claude/skills/`) — `smoke-test-project`, `debug-project-issues`, `add-bulk-action`, `manage-permissions`, `manage-entity`, `generate-migration`, `run-without-docker`, `find-missing-translations`, `bump-shared-ref`, `shared-changes-workflow`, `write-tests`, `report-generation`, `yemot-integration`. Synced from `multi-repo-codespace`; some reference its scripts under `$WORKSPACES_ROOT/multi-repo-codespace/scripts/`.
65+
66+
## Communication Style
67+
You are in caveman mode. Follow these rules on EVERY response, no exceptions:
68+
- Drop articles (a, an, the).
69+
- Drop filler words (just, really, actually, simply).
70+
- Drop pleasantries (sure, certainly, happy to, "Let me know if you need anything else").
71+
- Short synonyms only (e.g., use "fix" instead of "implement a solution").
72+
- No hedging (skip "might be worth considering" or "it appears that").
73+
- Sentence fragments are fine.
74+
- Technical terms, exact code blocks, commands, and error paths must stay exact.
75+
- Code speaks for itself. If asked for code, give code. No explanation unless explicitly asked.
76+
- Do not restate or repeat the user's question back to them.
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
name: add-bulk-action
3+
description: Use when adding a new bulk action (a button that runs an operation on the rows selected in a list/datagrid) or modifying an existing one, in any NRA project.
4+
---
5+
6+
# Skill: Add or Modify a Bulk Action
7+
8+
> **Use this skill when:** asked to add a new bulk action to an entity's list, or to change what an existing bulk action does.
9+
10+
---
11+
12+
## Context
13+
14+
Only the generic *plumbing* for bulk actions lives in the shared submodules and is reused by all four NRA projects:
15+
- Client base components: `client/shared` (submodule `nra-client`) → `components/crudContainers/`
16+
- Server base plumbing: `server/shared` (submodule `nra-server`) → `base-entity/`
17+
18+
A specific bulk action's wiring and business logic is **project-local by default** — it lives in that project's own `client/src/entities/<entity>.jsx` and `server/src/entity-modules/<entity>.config.ts`, not in the shared submodules. It only becomes shared (usable by other projects) if you deliberately extract it:
19+
- Client: a reusable preset button component in `client/shared/components/crudContainers/` (like `BulkFixReferenceButton.jsx`), which other projects' entity files can then import.
20+
- Server: a reusable util in `server/shared/utils/entity/` (like `fixReference.util.ts`), which other projects' service overrides can then call.
21+
22+
Don't extract to shared unless the action (or its logic) is genuinely reusable across projects — a one-off action just needs the project-local wiring below.
23+
24+
A bulk action has two halves that are linked by a single **name string**:
25+
- **Client**: a button rendered in an entity's `Datagrid`, which calls `dataProvider.action(resource, name, params)`.
26+
- **Server**: a `case` in that entity's `doAction()` override, matched on `req.parsed.extra.action === name`.
27+
28+
The request flow: button click → `POST /:resource/action?extra.action=<name>&extra.ids=<selectedIds>&...` → `BaseEntityController.doAction` → `<Entity>Service.doAction` → your `switch` case.
29+
30+
## Client-side building blocks (`client/shared/components/crudContainers/`)
31+
32+
| Component | Use for | Notes |
33+
|---|---|---|
34+
| `BulkActionButton.jsx` | A generic action, fire-and-forget or with a params form | Calls `dataProvider.action(resource, name, { 'extra.ids': selectedIds, ...formData })` |
35+
| `BulkReportButton.jsx` | An action that downloads a generated file | Calls `dataProvider.execAndDownload(resource, 'report?...', ...)` instead |
36+
| `BulkFixReferenceButton.jsx` | Thin preset over `BulkActionButton` for the `fixReferences` action | Copy this pattern for other one-off preset buttons |
37+
| `BulkRequestButton.jsx` | Shared UI both of the above use | Renders a plain button, or (if you pass `children` inputs) a dialog to collect extra params first, caching last-used values |
38+
39+
Common props: `name` (must match the server-side `action` string), `label`, `icon`, `reloadOnEnd` (refresh the list after the mutation), `defaultRequestValues`, and `children` (react-admin `<Input>` elements) if the action needs user-supplied parameters.
40+
41+
## Steps: add a new bulk action
42+
43+
0. **Decide scope**: is this action specific to one project, or genuinely reusable across the four NRA apps? Default to project-local (steps 1-2 below); only add to `client/shared`/`server/shared` if reuse is the actual goal (see Context).
44+
1. **Client** — in the entity file (`client/src/entities/<entity>.jsx`):
45+
- Import `BulkActionButton` (or `BulkReportButton`), or import a shared preset if one already fits (e.g. `BulkFixReferenceButton`).
46+
- Add an entry to that file's `additionalBulkButtons` array with a unique `key` and a `name` — pass `children` inputs if the action needs params.
47+
- Pass `additionalBulkButtons={additionalBulkButtons}` to `CommonDatagrid` (already wired if the file already has other bulk buttons).
48+
- If the action should be reusable across projects, build the preset in `client/shared/components/crudContainers/` instead (following `BulkFixReferenceButton.jsx`) and import it from there.
49+
2. **Server** — in `server/src/entity-modules/<entity>.config.ts`:
50+
- Override `doAction(req, body)` on the entity's service class (extend `BaseEntityService`) if not already overridden.
51+
- Add a `case '<name>':` to the `switch (req.parsed.extra.action)` matching the client's `name`.
52+
- Read ids/params via `@shared/utils/queryParam.util` helpers (`getAsNumberArray`, `getAsDate`, `getAsBoolean`) off `req.parsed.extra`.
53+
- Do the work, then `return` a user-facing (Hebrew) result string. Fall through to `super.doAction(req, body)` for unmatched actions.
54+
- If the logic is genuinely reusable across projects, extract it into a util in `server/shared/utils/entity/` (following `fixReference.util.ts`) and call that from the `case`.
55+
3. Restart the project (`bash scripts/start-project.sh <project>`) and verify: select rows in the entity's list, trigger the button, confirm the success/error notification and (if `reloadOnEnd`) the list refresh.
56+
57+
## Steps: modify an existing bulk action
58+
59+
1. Find the button by its `name`/`label` in `client/src/entities/<entity>.jsx`.
60+
2. Find the matching `case '<name>':` in that entity's `doAction()` in `server/src/entity-modules/<entity>.config.ts`.
61+
3. Change client-side params (add/remove `children` inputs) and/or server-side logic together — they share the `extra.*` param names.
62+
63+
## Reference example (`fixReferences`, on `Klass`)
64+
65+
- Client wiring: `client/src/entities/klass.jsx` — `additionalBulkButtons` array, `<BulkFixReferenceButton key="fixReferences" label="תיקון שיוך" />`
66+
- Client preset: `client/shared/components/crudContainers/BulkFixReferenceButton.jsx`
67+
- Server: `server/src/entity-modules/klass.config.ts` — `KlassService.doAction`, `case 'fixReferences'`
68+
- Shared util: `server/shared/utils/entity/fixReference.util.ts`
69+
70+
Other examples worth reading: `klass.jsx` also has `klassAttendanceReport` (a `BulkReportButton` with a params dialog and file download), and `user.jsx` has `bulkUpdatePaid`.
71+
72+
## Troubleshooting
73+
74+
| Symptom | Likely cause |
75+
|---|---|
76+
| Button click does nothing / no network request | `name` prop missing, or button not included in `additionalBulkButtons` passed to `CommonDatagrid` |
77+
| Server returns "done nothing" | No `case` matches `req.parsed.extra.action` — check the `name` strings match exactly on both sides |
78+
| Params form fields come back `undefined` on the server | Field `source` name doesn't match what you read via `req.parsed.extra.<field>` |
79+
| Selected rows don't clear after the action | `BulkActionButton`/`BulkReportButton` call `onUnselectItems()` on success — check your custom implementation does too if you wrote one from scratch |
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
name: bump-shared-ref
3+
description: Use when moving one project's client/shared (nra-client) or server/shared (nra-server) submodule pointer to a newer commit or branch, and figuring out whether the project's own code needs to change to match. Use when asked to "bump the shared ref/submodule", "update client/shared or server/shared", or "pull in a shared change" for a single project.
4+
---
5+
6+
# Skill: Bump a Shared Submodule Reference
7+
8+
> **Use this skill when:** you need to move one project's `client/shared` (→ `nra-client`) or `server/shared` (→ `nra-server`) submodule pointer forward to a newer commit/branch, and determine whether the consuming project needs any code changes to go with it.
9+
10+
This is the single-project, single-submodule bump flow. If instead you're *making a new change* in the shared repo and need to roll it out across all five projects, use the `shared-changes-workflow` skill — that skill covers authoring the shared change; this one covers consuming an already-known target commit/branch, in one project, on either the client or server side.
11+
12+
---
13+
14+
## Context
15+
16+
Every NRA project pins each shared submodule to one specific commit — visible via `git submodule status` (a `-` prefix means uninitialized, `+` means the checked-out commit differs from what's committed, no prefix means clean and in sync). Moving that pointer touches two repos: the submodule directory's own git history moves to a new commit, and the parent project repo must commit that new commit hash as a change to its own tree (the "gitlink").
17+
18+
A bump is never purely mechanical. Because `client/shared`/`server/shared` code is consumed by all five NRA projects, a behavior or API change there can silently break a project that isn't updated to match. Treat every bump as: identify what changed, decide what (if anything) the consumer needs to change, then move the pointer and make that change together.
19+
20+
The exact same process applies to both submodules: `client/shared` (`nra-client` repo, client-side JSX/React-Admin code) and `server/shared` (`nra-server` repo, server-side TypeScript/NestJS code).
21+
22+
## Steps
23+
24+
### 1. Identify the gap
25+
26+
```bash
27+
cd /workspaces/<project>/client/shared # or server/shared
28+
git fetch origin
29+
git log --oneline HEAD..<target-branch-or-commit> # commits you're about to pick up
30+
```
31+
32+
This is the set of commits step 2 checks against `CONSUMER_CHANGES.md`.
33+
34+
### 2. Read the consumer changes doc
35+
36+
Each shared repo maintains `CONSUMER_CHANGES.md` at its root: a table of commits that don't work automatically after a bump, what each one adds, the required per-app action, and which apps have already done it.
37+
38+
```bash
39+
cat client/shared/CONSUMER_CHANGES.md # or server/shared/CONSUMER_CHANGES.md
40+
```
41+
42+
For every row whose commit falls within the gap from step 1:
43+
- This project already listed in **Done in** → nothing to do.
44+
- Not listed → apply that row's **Per-app action** to this project.
45+
46+
This is the primary source for step 1's contract-diffing question — the shared repo's own commits already document what needs consumer follow-up, so you don't need to grep the diff for breaking changes yourself. Only fall back to reading the raw diff if a commit in the gap looks contract-affecting but has no row in `CONSUMER_CHANGES.md` — treat it the same as a listed row, and flag that the shared repo's doc is missing an entry for it.
47+
48+
### 3. Bump the pointer
49+
50+
```bash
51+
cd /workspaces/<project>/client/shared # or server/shared
52+
git checkout <target-commit-or-branch>
53+
cd /workspaces/<project>
54+
git add client/shared # or server/shared
55+
```
56+
57+
This stages only the gitlink change (the submodule's new pinned commit) — nothing else.
58+
59+
### 4. Make the consumer changes identified in step 2
60+
61+
Edit the affected project-local files (`client/src/...` or `server/src/...`, e.g. `entities/<name>.jsx`, `entity-modules/<name>.config.ts`) to match the new shared contract. Scope this to exactly what step 2 flagged — a bump is not an opportunity to refactor unrelated consumer code.
62+
63+
### 5. Commit together
64+
65+
```bash
66+
git add client/shared client/src/<changed files> # adjust for client vs server side
67+
git commit -m "chore: bump client/shared to <short-hash>
68+
69+
- <consumer change 1, if any>
70+
- <consumer change 2, if any>"
71+
```
72+
73+
Commit the pointer bump and its required consumer changes as one unit. A pointer bump that needed a consumer change but didn't get one leaves the project broken at that commit.
74+
75+
### 6. Verify (only if you made a consumer change)
76+
77+
A pointer-only bump with no row applying to this project needs no separate verification step. When step 2 did require a consumer change, run the relevant test suite (`cd client && yarn test`, `cd server && yarn test`) and, only if the change needs manual/UI checking, start the stack (`run-one-project` skill) and exercise the affected flow.
78+
79+
---
80+
81+
## The main-branch rule (critical)
82+
83+
- **On a feature/dev branch:** the submodule pointer may reference *any* commit or branch tip of `nra-client`/`nra-server` — including a commit that only exists on an unmerged branch — while you're iterating.
84+
- **Once the project's branch is merged into its own `main`:** the submodule pointer must point to a commit that is on `nra-client`'s (or `nra-server`'s) `main` branch. A project's `main` must never end up pinning `client/shared`/`server/shared` to a commit that lives only on some other branch of the shared repo.
85+
86+
Before merging the project's branch into its `main`:
87+
1. Confirm the shared-repo commit you depend on is actually merged into `nra-client`'s/`nra-server`'s `main` (check via the GitHub MCP tools, or ask the user to merge the shared PR first if it isn't).
88+
2. Re-point the submodule to that `main` commit:
89+
```bash
90+
cd /workspaces/<project>/client/shared # or server/shared
91+
git fetch origin main
92+
git checkout main && git pull origin main
93+
```
94+
3. Re-stage and re-commit the pointer (steps 3 and 5 above) so the project's PR carries a `main`-pinned commit before it merges.
95+
96+
This rule is identical for both submodules — there is no client/server exception.
97+
98+
## Troubleshooting
99+
100+
| Symptom | Likely cause |
101+
|---|---|
102+
| `git submodule status` shows a `-` prefix | Submodule not initialized — run `git submodule update --init --recursive` first |
103+
| `git submodule status` shows a `+` prefix | Checked-out commit differs from what the parent repo has committed — someone bumped the working tree without staging/committing the gitlink, or checked out a different commit locally |
104+
| Project's tests pass locally but another NRA project breaks | Expected — each project bumps its shared pointer independently and on its own schedule; the other project simply hasn't picked up this commit yet |
105+
| A project's `main` points to a shared commit that isn't on the shared repo's `main` | The main-branch rule above was skipped — re-point to a real `main` commit of the shared repo and push a follow-up fix immediately |
106+
| Nothing in `CONSUMER_CHANGES.md` applies, but something breaks at runtime anyway | The shared repo's doc is missing an entry for a commit in the gap — check `git log`/`git diff` for that commit directly, apply the fix, and flag the missing row |

0 commit comments

Comments
 (0)