globussoft-crm

Pre-push grep audit for cross-cutting changes (auth-status code flips, response-envelope reshapes, DELETE-success status flips, /api/health body reshapes). The per-push gate's spec list is a strict subset of e2e-full's; cross-cutting changes that pass per-push can red e2e-full because the bare *.spec.js smoke tests aren't in the per-push gate list. Without this audit, every cross-cutting change pays a release-validation round-trip (~15 min) to discover its missed specs. With it, both layers go green on the first try. Today's v3.4.14 cycle hit this twice (#537 401-vs-403 missed 7 specs;

Closes a multi-piece GitHub issue (e.g. `[Bug] Patients page: missing pagination, no bulk/individual tag add, no CSV/XLSX export & template`) by enumerating its sub-items, shipping one slice per cron tick as a file-disjoint pair (backend + frontend; or two backends; or backend + PRD), and only closing the issue after the final slice. Use when an open issue's body lists ≥3 sub-features. Encodes the discipline established across the #820 arc (14 commits across 10 ticks #181 → #197): pagination → bulk-tags → tag-chip → CSV → XLSX backend → XLSX button → template backend → template button → backend filters → frontend filters → import backend → import button → tag-remove backend → tag-remove UI. Each tick shipped 1 small slice; the issue closed naturally once 7/8 items were green.

Authors a NEW `docs/PRD_<FEATURE>.md` for a multi-day or product-call-blocked feature. Use when an open issue (`[Gap]` / `[Zylu-Gap]` / `[Travel Gap]` / `[Bug]` with multi-piece scope) needs a design call before implementation can start, and writing the PRD makes the open questions explicit so the call can actually happen. Encodes the §1-§10 template + 4-7 DD + 5-7 OQ + MANUAL_CODING_BACKLOG D-cluster cross-ref shape that 12+ bonus PRDs followed across the 2026-05-24 → 2026-05-25 cron arc (Purchase Orders, Payment Gateway Config, IE Jobs, Integrations Hub, Tag Master, AI Chat History, Customer Segments, Staff Detail, Wallet Top-up, POS New Sale, POS Polymorphic Invoice, Mini Website). Saves ~15 min of structural decisions per PRD; ships a usable design-call surface.

Authors a new `backend/services/<vendor>Client.js` stub for a cred-blocked third-party integration. Use when a vendor API (RFU Zikr Cabs, Haramain Rail, Booking.com, AdsGPT, RateHawk, Callified, etc.) is on the roadmap but the credentials haven't landed yet — ship the API surface inert so downstream consumers (routes, frontend admin pages, cron engines) can be built end-to-end. Encodes the 8-instance recipe established across adsGptClient / ratehawkClient / callifiedClient / bookingExpediaClient / bookingCom / haramainRailClient / zikrCabsClient: INTEGRATION constant + BUDGET_CAP_KEY + DEFAULT_CAP_CENTS + checkBudgetCap with CJS self-mocking seam + provider-specific search/details/book methods + bookX() throws `XXX_NOT_YET_ENABLED` + 12+ vitest cases including one regression-pin for the seam. Future stubs clone this in ~30 min vs ~90 min from scratch.

Post-push verification + batch close-out for commits with multiple `Closes

Pattern for one-shot paramiko SSH scripts that clean demo's MySQL database of E2E test pollution (E2E_*, _teardown_*, IsoTest *), polluted seed entries, or schema-migration orphans. Use when a pen-test or QA report flags "ledger contains ~N duplicate rows" / "list shows N rows of test data" / "seed-X polluted with Y prefix" — these are operator-side cleanups, NOT code fixes. Encodes the dotenv + paramiko + tenant-scope-by-default + BEFORE/AFTER counts + idempotency + JSON-summary pattern that 3 successful scripts have used (cleanup-orphan-touchpoints.py, seed-drugs-on-demo.py, cleanup-demo-pollution.py). Pairs with applying-demo-ssh-config for non-DB ops.

Orchestrates a wave of parallel closer agents to ship multiple independent gate specs / unit tests / fixes in one round. Use when the user asks to "fire up parallel agents" or when there's a batch of disjoint pickups (R-1/R-4 small-route specs, R-5 cron-engine vitests, G-x engine specs) and waiting for them sequentially would be slow. Encodes the patterns that worked in v3.4.x — disjoint-files invariant (no two agents touching the same route or workflow YAML), max 4-5 concurrent agents (5 worked; 8 had merge collisions), when to spawn a discovery agent first vs jump straight to closers, the standing-rule preamble that points agents at the existing skills, and the rebase-on-collision recovery pattern.

Process for class-fix sweeps that touch many routes' response shape (e.g. flip every DELETE handler from "200 + {message}" to "204 No Content", or migrate every error response from {message:} to {error, code}). Pin shape with user FIRST, identify all touch sites with a fixed grep, sweep routes + their specs in lockstep in one PR, verify zero hits on the OLD shape post-sweep. Anti-pattern: shipping per-route — partial-state where some routes return 200 and others 204 is worse than either consistent shape. The canonical example is commit 8853546 (#550 sweep) that closed yesterday.

Pre-dispatch effort estimate for regression-coverage agents. The card's stated estimate ("0.25 day", "1 day") rarely matches actual delivery time because nearly half the dispatches end up shipping inline backend gaps alongside the spec. Reading the target route's commit history (`git log --oneline -- backend/routes/<file>`) is a 30-second sniff test that predicts whether the dispatch will stay Path A (pin existing contract — card's estimate is accurate) or drift into Path B (ship missing code inline — budget +50-100% on top). 11 waves today produced a clean Path-A-vs-Path-B split correlated with engine maturity; this skill encodes the heuristic.

Pre-spec-authoring grep audit when implementing a regression-coverage card from docs/regression-coverage-backlog.md, docs/E2E_GAPS.md, or a similar gap card. Gap cards drift from actual code — action verbs, numerical bounds, error codes, field names, endpoint shapes, and format tokens often differ from what the card claims. Without this audit, the spec pins the gap card's hypothesis instead of the route's actual contract; the test passes today (good) and goes red the moment someone changes either side (bad signal). With it, every spec pins reality + documents drift in the commit body. Today's session logged 19 instances of drift across 14 waves; every single regression-coverage agent surfaced at least one drift item. Pattern is overwhelming.

Stop-the-line response when the deploy.yml api_tests gate is red for more than 2 consecutive pushes. A red gate silently blocks demo deploys — every subsequent push also fails because the underlying spec/route mismatch persists, and the demo accumulates a deploy backlog while testers report bugs against stale code. Triggers immediate triage: pull CI failure log, classify as spec-too-strict vs route-bug, ship one bundled fix commit. Without this discipline the gap compounds (this session: 90 minutes red → 3 distinct bugs across 3 commits, demo stuck 5 weeks behind main, tester filed ghost regressions against code that no longer existed on main).

Code-grep verification step before estimating or starting work on a GitHub issue or TODOS.md row. Issue framings drift — the implementation may already exist, the named function may already be wired, the "501 stub" may not be a 501 anywhere. Verifying first means the actual gap (often test-coverage, not implementation) gets fixed instead of duplicating shipped work. Runs in 2-5 minutes; saves hours of phantom-work agent runs. Especially critical before dispatching a parallel-agent wave — agent prompts narrow correctly when the parent agent has already verified.

Updates the project's version-bumping doc set after a meaningful release-worthy session ends. Use when a parallel-agent wave (or a focused multi-day pickup) lands enough commits to warrant a version bump (typically every 6+ commits or 100+ new tests). Touches 5 files in lockstep — CHANGELOG.md (vX.Y.Z entry with the test-surface-delta table; this is the ONLY file that narrates the arc), README.md (version pin + intro stat refresh — no "What's new" section), CLAUDE.md (version pin + one-line stat refresh — no arc paragraph), TODOS.md (handoff block refresh for the next session), docs/E2E_GAPS.md (mark items ✅ shipped + status block bump). Bundled CHANGELOG + TODO templates capture the format every existing v3.4.x entry uses.

SSH onto crm.globusdemos.com and apply a config-file or filesystem change with a backup → validate → reload-or-rollback safety net. Use when a fix is operator/ops-shaped rather than code-shaped — Nginx config, /etc files, manual systemd unit edits, /var/www file fixups. Encodes the paramiko + SFTP + sudo + nginx-t pattern that landed

Routes agent-discovered findings (bugs, contract drift, shipped specs, route gaps, standing-rule violations) into the correct doc(s) — TODOS.md, docs/E2E_GAPS.md, CHANGELOG.md, CLAUDE.md, or a new GitHub issue — so nothing surfaced mid-wave is lost between waves. Invoke at the END of every parallel-agent wave (orchestrator) or at task FINISH (individual agent that surfaces something out-of-scope). Without this, drift findings sit in chat history and evaporate when context compacts.

Posts an agent-activity log entry so the user can watch background agents progress in real time via the CRM's Developer page (/developer). Use at the START of any non-trivial task (gate-spec authoring, vitest writing, engine fix, parallel-wave dispatch), at major MILESTONES (after a commit lands, after a wire-in step finishes), and at FINISH (success or failure). The user has the Developer page open polling every 3 seconds; entries appear there immediately. Without this, parallel waves are opaque to the user — they only see the final report when the agent finishes. With it, they see start / commit / done in real time.

Wires a new e2e/tests/<name>-api.spec.js into both .github/workflows/deploy.yml and coverage.yml gate-spec lists. Use after writing a new gate spec so it actually runs in CI on every push. Inserts the spec line BEFORE tests/teardown-completeness.spec.js with the trailing backslash (avoids the c8a8ad4 missing-backslash incident where one absent backslash silently dropped two later specs from the bash invocation). Handles the rebase-on-push-collision case when sibling parallel agents are touching the same workflow files concurrently.

Adds a new admin-gated POST endpoint that manually triggers a cron engine for the requesting tenant. Use when writing a cron-engine spec (G-9/G-10/G-11/G-12/G-14/G-15 pattern) and the engine has no manual-trigger surface — without one, the spec can only wait for the cron tick which is non-deterministic. Encodes the canonical mirror pattern (verifyToken + verifyRole(['ADMIN']) + per-tenant scope via req.user.tenantId + return envelope shape) plus the optional confirmDestructive body guard for destructive ops like GDPR retention. Pairs with writing-api-gate-spec for the test side.

Authors a new Playwright API spec for routes in this CRM. Use when adding gate coverage for an under-tested route — the R-1/R-4/R-6 small-route picks, G-x cron-engine specs, or any item from the regression-coverage-backlog. Encodes the standing rules every spec needs (JWT key is userId not id, body strips id/createdAt/updatedAt/tenantId/userId, header JSDoc, RUN_TAG conventions linked to e2e/test-data-patterns.js, afterAll cleanup pattern with the _teardown_ prefix not _CLEANED_, no Co-Authored-By in commits) so a fresh agent doesn't re-derive them. After the spec is green, hand off to the wiring-spec-into-gate skill to add it to CI.

Authors a vitest unit test for a backend lib/, middleware/, services/, or cron/ module. Use when adding unit-level coverage for a JS module (R-2/R-3 lib pair, R-5 cron-engine pair, G-16 service-module pattern,