Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ tracking, import/merge workflows, or synchronization with another skills reposit
- Product Kit owns exploration, research, PRDs, requirements/questions, and WBS.
Reuse its record contract rather than duplicating requirements or resolutions.
- Engineering Kit owns technical decisions, implementation plans and execution,
specialized reviews, business-rule modeling, and verification. Keep delivery
adopted implementation conventions, specialized reviews, business-rule modeling,
and verification. Keep delivery
breakdowns distinct from implementation plans; no automatic handoff is required.
- Design Kit owns interface design, critique, accessibility, UX copy, and study planning.
Product Kit owns research synthesis; Engineering Kit owns functional verification.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ repository; there is no upstream import, tracking, or merge workflow.
| Plugin | Purpose | Skills | Version |
| --- | --- | --- | --- |
| [Product Kit](plugins/product-kit/README.md) | Research, requirements, PRDs, and delivery breakdowns | 6 | 0.3.2 |
| [Engineering Kit](plugins/engineering-kit/README.md) | Technical decisions, implementation, reviews, and verification | 11 | 0.1.1 |
| [Engineering Kit](plugins/engineering-kit/README.md) | Technical decisions, implementation, reviews, and verification | 12 | 0.2.0 |
| [Design Kit](plugins/design-kit/README.md) | Interface design, critique, accessibility, UX copy, and research planning | 10 | 0.1.0 |

Product Kit owns the shared requirements, questions, and decisions. Engineering
Expand Down
2 changes: 1 addition & 1 deletion plugins/engineering-kit/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "engineering-kit",
"version": "0.1.1",
"version": "0.2.0",
"description": "Engineering architecture, implementation planning, focused reviews, business rules, and web-app verification.",
"author": {
"name": "Concepta"
Expand Down
6 changes: 4 additions & 2 deletions plugins/engineering-kit/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "engineering-kit",
"version": "0.1.1",
"version": "0.2.0",
"description": "Engineering architecture, implementation planning, focused reviews, business rules, and web-app verification.",
"author": {
"name": "Concepta"
Expand All @@ -12,7 +12,8 @@
"claude-code",
"engineering",
"architecture",
"planning"
"planning",
"nestjs"
],
"skills": "./skills/",
"interface": {
Expand All @@ -27,6 +28,7 @@
],
"defaultPrompt": [
"Help me make and document an architecture decision.",
"Place a new NestJS endpoint using the modular NestJS rules.",
"Create an implementation plan for this approved specification.",
"Re-examine this existing solution from a clean sheet."
]
Expand Down
3 changes: 2 additions & 1 deletion plugins/engineering-kit/README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# Engineering Kit

Engineering workflows for Codex and Claude Code, installed as
`engineering-kit@conceptadev`. The kit contains 11 focused skills and their helpers.
`engineering-kit@conceptadev`. The kit contains 12 focused skills and their helpers.

## Skills

| Skill | Outcome |
| --- | --- |
| [architecture](skills/architecture/SKILL.md) | A grounded technical choice or architecture decision record |
| [modular-nestjs](skills/modular-nestjs/SKILL.md) | File placement and implementation rules for a modular NestJS API |
| [writing-plans](skills/writing-plans/SKILL.md) | An executable implementation plan from settled requirements |
| [executing-plans](skills/executing-plans/SKILL.md) | Carry out an existing authorized implementation plan |
| [webapp-verification](skills/webapp-verification/SKILL.md) | Browser evidence and appropriate regression coverage |
Expand Down
1 change: 1 addition & 0 deletions plugins/engineering-kit/SOURCES.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Skills, helpers, and fixtures derive from [Leo Farias's skills](https://github.c
| `writing-plans`, `executing-plans` | [Superpowers](https://github.com/obra/superpowers), respective `skills/` directories, `b36e0829c6d0140e93cfef2ca599b1b07d4a7797` | [MIT](licenses/superpowers-MIT.txt) |
| `code-simplifier` | [Anthropic Code Simplifier](https://github.com/anthropics/claude-plugins-official), `plugins/code-simplifier/agents/code-simplifier.md`, `ceb9b72b4c4c20ad39efce780edd0aabe80ebce3` | [Apache-2.0](licenses/anthropic-code-simplifier-Apache-2.0.txt) |
| Remaining skills and local adaptations | Leo Farias | [BSD-3-Clause](LICENSE) |
| `modular-nestjs` | Original to this kit. No external skill source | [BSD-3-Clause](LICENSE) |

Concepta's publisher metadata does not replace the original copyright notices.
No external source repository or plugin is required to run these skills.
73 changes: 73 additions & 0 deletions plugins/engineering-kit/skills/modular-nestjs/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
name: modular-nestjs
description: >-
Use when building, changing, or reviewing a NestJS API that follows modular NestJS:
the first URL segment after /api names the module, request and response schemas are
Zod contracts, and only repositories and one transaction runner touch the database.
Covers file placement, module shape, tests, transactions, errors, TypeORM, and gates.
Do not use to choose NestJS versus another stack, to write an architecture decision,
or for an application that has not adopted this convention.
---

<!-- Original engineering-kit skill. See ../../SOURCES.md. -->

# Modular NestJS

Apply these rules when the user asks for modular NestJS, or when the repository already follows them. If the repository uses a different NestJS layout, follow that layout and say so. Do not convert it unless the user asks.

This skill is generic. Do not invent a product name, a requirement catalog, or a tenancy model.

## Boundaries

- Choosing NestJS, the database, or a module boundary is the `architecture` skill. This skill starts after that choice.
- Turning requirements into a task list is `writing-plans`. When the plan targets a repository that uses this convention, the plan's paths follow this skill.
- Carrying out an approved plan is `executing-plans`. Obey this skill while placing files.
- A project document owns runtime, deployment, and database roles. Do not invent those rules.

## The one rule

The first segment of the URL after `/api` is the module name. Use that name for the module folder, the main file prefix, the contracts folder, and the web feature folder.

```text
URL /api/users/:id/role
module folder apps/api/src/users/
contracts packages/contracts/src/users/
use-case tests apps/api/src/users/e2e/
```

A sub-resource belongs to that module. A table with no route of its own belongs to the module whose routes change it.

Two exceptions only:

- Health routes live in `apps/api/src/health/` at `/health/*`, without the `/api` prefix.
- `common/`, `config/`, `database/`, and `logging/` have no routes.

## What to read

Read only the reference the task needs.

| Task | Reference |
| --- | --- |
| Place a file, name a module, or split a topic | [references/structure.md](references/structure.md) |
| Add schemas, tests, or a contract-phase slice | [references/contracts-and-delivery.md](references/contracts-and-delivery.md) |
| Write a repository, a command, or a query | [references/persistence.md](references/persistence.md) |
| Auth, validation, OpenAPI, errors, or logs | [references/http.md](references/http.md) |
| Entity, relation, query, migration, or seed | [references/typeorm.md](references/typeorm.md) |
| Security, gates, a new project, or the feature checklist | [references/quality.md](references/quality.md) |

## Apply the change

1. Derive the module from the URL. Do not add a domain folder above the modules.
2. Create only the files the change needs. Two or more files of one kind go in that kind's folder. One file stays loose.
3. For a new use case, add the contract, the failing use-case test, and the service stub before the repository and the rules.
4. A command runs in one `TransactionRunner.run`. A query does not open a transaction.
5. A service throws a module exception. It does not throw a NestJS HTTP exception, return an entity, or import the ORM.
6. Every route declares `@RequirePermission(...)`, `@Authenticated()`, or `@Public()`. Every `@Body`, `@Query`, and `@Param` declares a Zod schema.
7. Stop when the repository already has a rule this skill does not cover. Ask. Do not invent the missing rule.

## Check before you finish

- The new path follows the URL.
- The module does not export its repository.
- The success test of a new use case failed before the behavior existed, unless the repository's own process says otherwise.
- You did not add a DTO class, `@ManyToMany`, a skipped test, `any`, or `console`.
42 changes: 42 additions & 0 deletions plugins/engineering-kit/skills/modular-nestjs/evals/evals.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
{
"skill_name": "modular-nestjs",
"evals": [
{
"id": 1,
"prompt": "Add POST /api/orders/:id/cancel to a NestJS API that follows modular NestJS. Do not implement the business rule yet. The repository already has the foundation: auth decorators, TransactionRunner, the contracts package, and the acceptance ratchet. Cancellation is allowed only for an OPEN order in the caller's active context, writes an audit event, and returns the order id and status. Tell me which files to add and what the contract-phase stub and use-case test must do.",
"expected_output": "A contract-phase slice whose paths come from the orders URL, with schemas, a service stub that throws the not-implemented exception, and a failing success test. No repository rule yet.",
"files": [],
"expectations": [
"Places the route in apps/api/src/orders and the schemas in packages/contracts/src/orders.",
"The controller only maps the route to one service call, takes the principal from the session, and declares a permission decorator and a schema on the id param.",
"The service stub throws UseCaseNotImplementedException and does not open a transaction or import the ORM.",
"The use-case test lives in orders/e2e, expects the successful cancel to fail until implementation, and includes the denied cases that apply.",
"Does not invent a product name, a tenancy model, or a domain folder above the module."
]
},
{
"id": 2,
"prompt": "Our NestJS API already follows modular NestJS. Implement cancel order now. The contract-phase test expects 200 and status CANCELED. The order row must change only when its status is still OPEN. The audit event must commit with the status change. An unknown id and an order in another context must both return 404.",
"expected_output": "An implementation that uses one transaction, a conditional update, a module not-found exception, and no ORM import in the service.",
"files": [],
"expectations": [
"The command calls TransactionRunner.run once and passes that context to the repository and the audit write.",
"The status change is a conditional update on OPEN, not a read-check-write.",
"A missing row and a row outside the active context both become the module not-found exception.",
"The repository stays private to the module, returns an entity or a boolean, and the service converts the result to the contract type.",
"Does not add @ManyToMany, a DTO class, a NestJS HTTP exception, or a skipped test."
]
},
{
"id": 3,
"prompt": "We have an existing NestJS app that uses class-validator DTOs, a shared src/modules folder, and Prisma. Add one field to the existing cats update DTO. Do not adopt a new architecture.",
"expected_output": "A small change that follows the existing DTO layout and does not rewrite the application into modular NestJS.",
"files": [],
"expectations": [
"Keeps the existing DTO, folder, and Prisma patterns.",
"Does not introduce a contracts package, TransactionRunner, Zod schemas, or a new module layout.",
"States that modular NestJS was not applied because the repository has not adopted it and the user did not ask for a conversion."
]
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
[
{
"query": "Add POST /api/users/:id/deactivate using the modular NestJS rules. Put the files where the URL says they go.",
"should_trigger": true
},
{
"query": "Where do the orders repository, entity, and contract schema live in a modular NestJS API?",
"should_trigger": true
},
{
"query": "Scaffold the foundation for a new NestJS API that follows the modular NestJS guide, before the first feature.",
"should_trigger": true
},
{
"query": "The contract phase for products is next. Add the Zod schema, the service stub, and the failing use-case test.",
"should_trigger": true
},
{
"query": "Review this NestJS module against the modular NestJS file and transaction rules.",
"should_trigger": true
},
{
"query": "This users service is over 300 lines. Split it into a modular NestJS topic without splitting by verb.",
"should_trigger": true
},
{
"query": "A command writes a user and an audit event. How should the transaction and the module boundary work?",
"should_trigger": true
},
{
"query": "Replace this @ManyToMany with the join entity the modular NestJS guide requires.",
"should_trigger": true
},
{
"query": "Choose NestJS or Hono for the new public API and record the decision.",
"should_trigger": false
},
{
"query": "Write an ADR for whether orders and payments share a database.",
"should_trigger": false
},
{
"query": "Add one optional field to our existing class-validator DTO. Keep the current NestJS layout.",
"should_trigger": false
},
{
"query": "Fix the empty-state copy on the React orders page.",
"should_trigger": false
},
{
"query": "Turn the approved payment idempotency spec into an implementation plan. Do not place files yet.",
"should_trigger": false
},
{
"query": "Execute the plan in docs/plans/cancel-order.md and commit each task.",
"should_trigger": false
},
{
"query": "Review this pull request for bugs and missing tests.",
"should_trigger": false
},
{
"query": "Write the business vocabulary and rules for order cancellation in SBVR.",
"should_trigger": false
},
{
"query": "The checkout test fails only in CI. Find the cause.",
"should_trigger": false
},
{
"query": "Create a product requirements document for the new export feature.",
"should_trigger": false
}
]
Loading
Loading