create-service

Create Service

Scaffold a new service that follows the project architecture. This writes files and may create a branch, so it only runs when you type /create-service.

Architecture

Three layers, one direction. server.ts is thin, handlers/ hold logic, adapters/ wrap everything external.

server.ts      routes only, NEVER business logic
   │
   ▼
handlers/      business logic, one file per domain
   │
   ▼
adapters/      external wrappers (database via StrictDB or native driver, APIs, queues)

This matches the api-conventions skill. Keep them in sync: if the layering changes, change both.

Directory structure

packages/{name}/
├── src/
│   ├── server.ts          # entry point — routes only
│   ├── handlers/          # business logic
│   │   └── index.ts
│   ├── adapters/          # external wrappers
│   │   ├── index.ts
│   │   └── db.ts          # data adapter — StrictDB or native driver, the only place the driver lives
│   └── types.ts           # TypeScript types
├── tests/
│   └── handlers.test.ts
├── package.json
├── tsconfig.json
└── CLAUDE.md              # service-specific instructions

package.json — resolve versions at scaffold time

Do not hardcode dependency versions. Before writing package.json, resolve the current stable version of each dependency (npm view <pkg> version, or context7) and pin those. Hardcoded versions rot the day they ship, and a stale pin is how you get an Express 4 runtime against Express 5 types.

Dependencies to resolve and include:

• runtime: express (current major is 5)
• dev: tsx, typescript, vitest, @types/express

Make the @types/express major match the express major. Verify, don't assume.

{
  "name": "@project/{name}",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/server.ts",
    "start": "node dist/server.js",
    "test": "vitest run"
  },
  "dependencies": {
    "express": "<resolved>"
  },
  "devDependencies": {
    "tsx": "<resolved>",
    "typescript": "<resolved>",
    "vitest": "<resolved>",
    "@types/express": "<resolved, major matching express>"
  }
}