From agentforge
Definition-of-done for any code change in core-be — propagate every edit to all the artifacts that mirror it: its own tests at the right layer, the cross-cutting suites (security, integration, load/k6, global, chaos, contract), docs (OVERVIEW, reference, TSDoc, .env.example), agent-os rules, and skills (counts, trigger maps, hardcoded route/constant sets). Use after editing any src/ code, middleware, config, route, constant, or shared count so nothing that describes or verifies the change is left stale.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agentforge:change-completeness-guardThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A change is **not done** when the code compiles and one test passes. It is done when
A change is not done when the code compiles and one test passes. It is done when every artifact that mirrors the change has moved with it. In this repo a single fact is often stated in five places at once — code, its own test, a cross-cutting test, a doc, and a skill — so a change that touches only the code leaves the other four stale, and the drift is invisible until a human (or CI months later) trips over it.
Worked example (the lesson this skill encodes): a route-set size lived as the literal "8 writes" in the
idempotency-guardskill, indocs/reference/api/frontend-auth-guide.md, and in two test comments undersrc/tests/security/andsrc/tests/load/. Changing the route set in code (8 → 13) compiled and passed its own e2e, but left four stale mirrors. This guard exists so the next such change updates all five layers in the same commit.
After any code edit, walk this checklist. Skip a layer only when you can name why it does not apply (not by forgetting it).
src/tests/unit/
or a co-located __tests__/unit/; route/DB behaviour → domain __tests__/*.test.ts e2e).
A change with no test delta is a red flag — state why (pure rename, comment-only, or
already covered by an existing assertion you can point to). Run test-generator.src/tests/security/ — auth, idempotency, rate-limit, header, secret-leak policy.src/tests/integration/ — multi-component flows.src/tests/global/ — repo-wide invariants (import paths, no-direct-db-in-services,
snake-case body keys, etc.); these fail loudly when a structural rule is broken.src/tests/contract/ — outbound Stripe/Resend/S3 contracts (run contract-test-maintainer).src/tests/chaos/ — fault-injection (run chaos-test-maintainer).src/tests/load/k6/scenarios/ — k6 throughput/limits; update a scenario or its env
defaults when a tuning knob (pool size, cap, tolerance) moves.src/tests/performance/ — latency/budget guards.Convention (do not over-add): the mechanism is tested once at the layer that owns it, on a representative case — not duplicated into every suite. A route-agnostic middleware is proven on one representative route; a shared util is unit-tested directly. Mirror the convention of the suites already present rather than fanning the same assertion across layers.
src/**/*.overview.md,
the relevant docs/reference/**, TSDoc on any added/renamed export (gate: pnpm tsdoc:check),
route schema blocks for OpenAPI, and .env.example for any new env var. Run the matching
skill (overview-doc-maintainer, docs-maintainer, tsdoc-export-guard,
route-schema-doc-guard, env-schema-add).agent-os/rules/*.mdc (and the always-applied rules table). Run
structure-maintainer.agent-os/skills/skill-index/SKILL.md (the N project skills count + the skill table),
agent-os/skills/groups.json (every skill in exactly one group), agent-os/docs/skill-triggers.md,
and the N project skills count in CLAUDE.md / AGENTS.md. Run structure-maintainer;
the pnpm agent-os:check gate asserts these stay in sync.| When you change… | …also update (same commit) | Skill / gate |
|---|---|---|
A route (*.routes.ts) | params/body schema, docs/routes.txt, OpenAPI, e2e test, seeds | api-contract-guard → route-catalog |
A config flag set on a set of routes | every route in the set, the count/doc that names the set, the policy test that asserts it | api-contract-guard / idempotency-guard |
A Drizzle schema (*.schema.ts) | migration, RLS, seeds, sql-design review, repo + e2e tests | schema-generator → db-migration-maintainer |
An env var (env-schema.ts) | .env.example, hosted-env mapping, the unit test asserting the default, docs | env-schema-add |
| A user-facing string | en and es locale keys; no raw literal in code | i18n-message-guard |
| An event / queue / worker | registry wiring, durability/metric, worker + emit tests | workers-events |
| A tuning constant (pool size, cap, tolerance, TTL) | every test/doc/k6-scenario that restates the number; the registry that owns it | production-hardening-guard + this guard |
| A shared count or hardcoded list (in code or docs) | grep the literal repo-wide and fix every mirror (see below) | this guard |
| A public export (added/renamed) | TSDoc summary (+ @remarks on service/worker/policy), importers | tsdoc-export-guard |
| A folder layout / file move | CLAUDE.md, README.md, rules, skills, OVERVIEW | structure-maintainer |
| A skill (added/renamed) | skill-index count + table, groups.json, skill-triggers.md, CLAUDE.md / AGENTS.md | structure-maintainer + pnpm agent-os:check |
8/13), a route path, a constant name, a
header, an env key — across src/, docs/, and agent-os/. Stale duplicates of a fact
are the most common miss; the literal is the fastest way to find them.agent-os/skills/skill-index/SKILL.md)
and agent-os/docs/skill-triggers.md: the file-pattern → skill map tells you which owner
skill(s) to run for the files you touched. Run only those (no duplicate invocations).pnpm validate (lint + types), pnpm test:global
(repo-wide invariants), pnpm routes:catalog:check, pnpm tsdoc:check, pnpm agent-os:check
(skill/rule/doc count sync), and the pre-commit guard each fail on a specific class of
stale mirror. Treat a gate failure as "a mirror you missed," not noise.pnpm validate # lint + format + typecheck on the change
pnpm test:global # repo-wide structural invariants (import paths, body-key casing, …)
pnpm agent-os:check # skill/rule/doc counts + index ↔ disk in sync
pnpm guard:pre-commit # the full local gate (mirrors CI sync checks)
Plus the card/skill-specific pnpm test:* for the layer you touched (see test-generator).
Related: skill-index (which owner skill to run), test-generator (test layer/pyramid), structure-maintainer (docs/rules/skills sync), before-commit-guard (the commit gate).
npx claudepluginhub nikunjmavani/core-be --plugin agentforgeCreates bite-sized, testable implementation plans from specs or requirements, with file structure and task decomposition. Activates before coding multi-step tasks.