gen-module
Skill1 starsChanged 3 months agoMITView on GitHub
Scaffold a complete new feature module under src/modules/<feature>/ — schema, entity, dto, repository, service, controller, and (when needed) errors — following this project's Functional Clean Architecture spec exactly as the src/modules/books/ reference module demonstrates. Use this whenever the user asks to add a new resource, feature, or module, wants CRUD for something (e.g. "add an authors module", "scaffold a orders feature", "generate the CRUD files for reviews", "I need a new endpoint for X with a database table"), or describes a new domain concept that needs a table + API — even if they don't say "module" or name this skill explicitly. Also the right skill for the GREEN step of Spec-Driven TDD — "implement the reservations module to make the failing tests pass", "the RED tests are written, now generate the code" — it checks tests/modules/<feature>/ for existing failing tests first and derives the spec from them instead of asking. Always trigger before hand-writing any file under src/modules/ for a feature that doesn't exist yet.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arch-auditSkill
- feature-flowSkill
- feature-planSkill
- test-badassSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 23
If tests/modules/<feature-name>/ has no test files yet, there's nothing to derive from — proceed to Step 1 exactly as normal.
- Distinctive: line 29
Before writing anything, you need three things.
- Distinctive: line 35
Don't guess field types or business rules silently — a wrong guess here means every generated file inherits the mistake.
- Distinctive: line 57
Add the new controller's import and mount it, without disturbing anything already there:
- Distinctive: line 69
Run, in order, and fix anything that fails before considering the module done:
- Very specific: line 83
No default exports: Every export is inline at its definition (export function foo(), export const bar = ..., export type Baz = ...) — never …
- Very specific: line 92
Check tests/modules/<feature-name>/ for existing RED tests first (Step 0) — derive the spec from them if present, and only fall back to …
- Distinctive: line 93
Ask for the feature spec (name, fields, business rules) before generating anything, if the request doesn't already supply it and no RED …
- Very specific: line 97
Run bunx biome check --write .
- Distinctive: line 101
Don't invent a field type or a business rule the user didn't specify and no existing test implies — ask.
- Distinctive: line 102
Don't edit or weaken an existing RED test to make generated code pass — fix the code, or stop and flag a real spec gap.
- Very specific: line 103
Don't collapse schema/entity/dto into one shared shape "since they're identical right now" — keep them as three separate files even when a …
- Very specific: line 104
Don't add a repository parameter to a service.ts function, and don't wrap the service module in a factory — service.ts hard-imports the …
- Very specific: line 105
Don't rewrite the whole src/index.ts file to add a mount line — edit in the new import and .route() call only.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Generating a feature module (gen-module)
This skill produces every file a new module needs, matching src/modules/books/ file-for-file in structure and convention — that module is the verified, working reference this skill is built from, not just an example to loosely follow. When you're unsure how something should look, read the real books files, not just this skill.
Step 0 — TDD Awareness: check for existing RED tests first
Before asking anyone anything, check whether tests/modules/<feature-name>/ already has .spec.ts/.e2e.spec.ts files. If it does, you're in a Spec-Driven TDD context — either test-badass was run directly, or feature-flow is mid-pipeline — and those tests are already a complete, precise, executable spec. Reading real typed test code and re-asking the user to restate the same thing risks producing an answer that quietly disagrees with what the tests already pin down, so skip Step 1's questions and derive the spec from the tests instead:
- Fields and types — from typed fixtures (
const input: CreateReservationDto = { bookId: '...', memberId: '...' }), not guessed from a name. - Business rules and branches — from the
describe('GIVEN ...')blocks; each one names a precondition the generated code must actually handle. - Error codes and status codes — from assertions like
toMatchObject({ code: 'RESERVATION_BOOK_UNAVAILABLE' })orexpect(res.status).toBe(409). These becomeerrors.tsfactories and the specific guard logic inservice.tsthat throws them. - Routes and response shapes — from
.request('/reservations', { method: 'POST', ... })calls and the assertions made on the response body.
Write the minimal src/modules/<feature-name>/ implementation that satisfies exactly what the tests exercise — no extra fields, routes, or validation beyond what a test actually checks, even if it looks like a natural CRUD extension. Anything you add that no test covers is untested code by definition, which this project's Testing Trophy approach treats as a gap, not a bonus. If the tests leave something genuinely ambiguous (e.g. no test touches a route the plan doc mentions), don't silently invent behavior for it — generate the part that's actually tested and say plainly what's uncovered.
RED tests are frozen input, not a draft to edit. If a test's assertion seems wrong once you're looking at what it'd take to satisfy it, that's a signal to stop and flag a real spec gap — never loosen or rewrite the test so the generated code passes; that's cheating the RED→GREEN transition, not completing it. Once every file is generated, run bun test (not just the Step 4 checks) to confirm the existing tests now pass — that's what makes this GREEN.
If tests/modules/<feature-name>/ has no test files yet, there's nothing to derive from — proceed to Step 1 exactly as normal.
Step 1 — Gather the feature spec
Skip this step entirely if Step 0 already derived the spec from existing tests.
Before writing anything, you need three things. If the user's request doesn't already give them, ask:
- Feature name — singular and plural (e.g. "author" / "authors"). Plural drives the module directory, file prefix, table name, and route paths; singular drives type and function names — exactly like
book/booksin the reference module. - Fields — name, type, and whether each is client-supplied (goes in the create DTO) or system-managed (like
books.isOnLoan, defaulted and omitted from create input). A name and a rough type per field is enough (title: string,price: number,publishedAt: date) — infer the Drizzle column type, Zod validation, and nullability from that unless the user is more specific. - Any business rules that need a module-specific error — e.g.
bookshasduplicateIsbnError(a uniqueness check) andbookOnLoanError(a state-guard on delete). Not every module needs this — ask only if the fields hint at a uniqueness constraint or a state that blocks an operation. If there's nothing like that, skip theerrors.tsfile entirely; it's optional (seedocs/01-module-layout.md).
Don't guess field types or business rules silently — a wrong guess here means every generated file inherits the mistake.
Step 2 — Generate the files, in this order
Each kind depends on the ones before it, so generate them in this order: schema → entity → dto → repository → errors (if needed) → service → controller.
Read references/templates.md now — it contains the full, real code for all 7 books files with inline notes on exactly what to change per file for a new feature (which lines are structural boilerplate to copy verbatim, and which are feature-specific and need renaming/rewriting). Don't improvise the shape of a file from memory; the templates are the source of truth.
dto.ts and controller.ts carry this module's OpenAPI documentation, and it's not optional decoration — a generated module with response codes but no prose is unfinished, the same way a module missing a 404 case would be. Every schema field gets .openapi({ example, description }), every top-level schema (the response shape, the create DTO, a path param) gets its own .openapi({ description }), and every createRoute({...}) call gets a summary + description. The templates show exactly how this looks — follow them field-for-field and route-for-route, don't just copy the examples and skip the descriptions.
Naming convention (matches book/books exactly):
| Placeholder | Example | Used for |
| plural, lowercase | authors | module directory (src/modules/authors/), file prefix (authors.schema.ts), table name (pgTable('authors', ...)), route paths (/authors), controller variable (authorsController) |
| singular, camelCase | author | repository singleton (authorRepository), single-record function names (getAuthor, createAuthor, deleteAuthor) |
| singular, PascalCase | Author | domain type (Author, NewAuthor), repository type (AuthorRepository), factory name (createAuthorRepository), DTO type (AuthorDto) |
listAuthors stays plural (it returns many); getAuthor/createAuthor/deleteAuthor stay singular (each operates on one record) — same pattern as listBooks vs getBook/createBook/deleteBook.
Step 3 — Wire into src/index.ts
Add the new controller's import and mount it, without disturbing anything already there:
import { authorsController } from '@/modules/authors/authors.controller';
// ...
app.route('/', authorsController);Use Edit, not a full rewrite — src/index.ts already has other modules and the error-handler/Swagger wiring in it. Don't touch the .doc()/swaggerUI() registration lines unless the user asks — those are wired to a specific first-registered controller and are a separate, pre-existing decision (see docs/02-clean-architecture.md and the configs/swagger.ts note in docs/plans/ARCHITECTURE.md) — don't silently duplicate or move that wiring while adding a new module.
Step 4 — Verify
Run, in order, and fix anything that fails before considering the module done:
bunx biome check --write .
bunx tsc --noEmitA module that doesn't pass both isn't finished — this project's own reference module (books) passes both cleanly, and every generated module should too.
The non-negotiable constraints
These aren't stylistic preferences — they're what makes the generated code actually match this project's architecture, not just superficially resemble it. Full reasoning for each lives in docs/02-clean-architecture.md and docs/03-repository-pattern.md.
- No
class, nothis, no inheritance anywhere in the generated files. Every kind is plain functions and plain data. The one exception is instantiating a framework's own class (new OpenAPIHono()insidecreateController(), which you call rather than reimplement) — that's framework glue, not something this skill writes fresh. - No default exports. Every export is inline at its definition (
export function foo(),export const bar = ...,export type Baz = ...) — never a trailingexport { ... }block gathering things at the bottom of a file. - Explicit return types on every exported function.
service.tsuse cases,repository.tsmethods (via the factory's own return type, not repeated per method — see the repository template),errors.tsfactories. Private helpers (toEntity()) may still infer. generateId()from@/shared/id, called inservice.ts, never inrepository.tsor the schema's column default. Theidcolumn itself must have no default at all (spreadidColumnfrom@/shared/columns— never write a custom id column with.defaultRandom()).repository.tsis a curried factory,create<Feature>Repository(db = defaultDb), returning an object of closures that map rows to the domain entity via a privatetoEntity()before returning anything.service.tsimports the exported singleton (<feature>Repository) directly — never a factory call, never a repository parameter.controller.tsusescreateController()(from@/shared/error-handler), nevernew OpenAPIHono()directly. Handlers stay inline arrow functions passed to.openapi(...)— never extracted into a named function (Hono's type inference forc.req.valid(...)depends on this). Every timestamp field in a response goes through.toISOString()via ato<Feature>Dto()mapper — never returned as a rawDate.- When RED tests already exist for this feature (Step 0), they are the spec. Generate code to satisfy them; never edit the tests themselves to fit whatever the generated code happens to do.
Do
- Check
tests/modules/<feature-name>/for existing RED tests first (Step 0) — derive the spec from them if present, and only fall back to asking the user when there's nothing to derive from. - Ask for the feature spec (name, fields, business rules) before generating anything, if the request doesn't already supply it and no RED tests exist to derive it from.
- Generate files in dependency order:
schema→entity→dto→repository→errors(optional) →service→controller. - Give every module-specific error (in
errors.ts) its own OpenAPIexampleon the relevant response — seedocs/04-error-handling.md. - Give every
dto.tsschema field an.openapi({ example, description }), every top-level schema its own.openapi({ description }), and everycontroller.tsroute asummary+description— see the templates for the exact style. A generated module with no OpenAPI prose is as unfinished as one with no422case. - Run
bunx biome check --write .andbunx tsc --noEmitafter generating, and fix what they flag; also runbun testwhen Step 0 applied, to confirm the RED tests are now green.
Don't
- Don't invent a field type or a business rule the user didn't specify and no existing test implies — ask.
- Don't edit or weaken an existing RED test to make generated code pass — fix the code, or stop and flag a real spec gap.
- Don't collapse
schema/entity/dtointo one shared shape "since they're identical right now" — keep them as three separate files even when a new module's fields make them look the same, exactly likebooks. - Don't add a repository parameter to a
service.tsfunction, and don't wrap the service module in a factory —service.tshard-imports the repository singleton, full stop. - Don't rewrite the whole
src/index.tsfile to add a mount line — edit in the new import and.route()call only.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

