orbital-express: Skill for Claude Code

Add an action to an existing feature

Actions are the real-time API handlers. Naming: V{version}{Action}[By{Role}][On{Device}] (e.g. V1Update, V1UpdateByAdmin). Read README "Actions Folder" + "Actions Folder Structure: Deep Dive".

Steps

1. Plan/sign-off: define the endpoint contract, authorization, errors, side effects, route/controller wiring, and tests; get sign-off before scaffolding or edits. Confirm complete feature structure with yarn repair <Feature> --dry-run, then yarn repair <Feature>.

2. Scaffold: yarn gen <Feature> -a V1<Action>. This validates names/targets first, exclusively creates the action + integration test, and deterministically rebuilds actions/index.js. Existing source/test conflicts abort before any write. Never hand-create or pass .js.

3. Write the action (app/<Feature>/actions/V1<Action>.js) following the JS file structure:

   • JSDoc header: description, route(s) (GET/POST), the i18n note, auth requirement (Must be logged in/out/Can be both), Roles: [...], req.params, req.args (each arg typed: @id - (NUMBER - OPTIONAL) [DEFAULT - ...]), Success, and every Error: code (this list is your test checklist).
   • const i18n = lang.getLocalI18n();
   • Joi schema → validate req.args → on error return errorResponse(req, ERROR_CODES.BAD_REQUEST_INVALID_ARGUMENTS, joiErrorsMessage(error)); then req.args = value; (Joi has now coerced types: '5'→5).
   • Business logic in a try. When returning a record, exclude sensitive fields: attributes: { exclude: models.<x>.getSensitiveData() }.
   • For multi-step writes, open a transaction (const t = await models.db.transaction()); on a business-rule failure mid-transaction use errorResponseRollback(t, req, ERROR_CODES.X); on success t.commit(). If you emit a socket event, emit after commit.
   • Flat success return: { status, success: true, ...payload } (201 on create, 202 on background-job handoff, else 200). Name keys after content; never nest under data.
   • In the catch, throw error (let it propagate to the error middleware — never return res.status(500)).
   • // END V1<Action>.