Create Service Skill

Generate a new service that follows our architecture patterns.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                       YOUR SERVICE                           │
├─────────────────────────────────────────────────────────────┤
│  ┌───────────────────────────────────────────────────────┐  │
│  │              SERVER (server.ts)                        │  │
│  │  - Express/Fastify entry point                        │  │
│  │  - Defines routes                                     │  │
│  │  - NEVER contains business logic                      │  │
│  └───────────────────────────────────────────────────────┘  │
│                            │                                 │
│                            ▼                                 │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                HANDLERS (handlers/)                    │  │
│  │  - Business logic lives here                          │  │
│  │  - One file per domain                                │  │
│  └───────────────────────────────────────────────────────┘  │
│                            │                                 │
│                            ▼                                 │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                ADAPTERS (adapters/)                    │  │
│  │  - External service wrappers                          │  │
│  │  - Database, APIs, etc.                               │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Directory Structure

packages/{name}/
├── src/
│   ├── server.ts        # Entry point — routes only
│   ├── handlers/        # Business logic
│   │   └── index.ts
│   ├── adapters/        # External service wrappers
│   │   └── index.ts
│   └── types.ts         # TypeScript types
├── tests/
│   └── handlers.test.ts
├── package.json
├── tsconfig.json
└── AGENTS.md            # Service-specific instructions

Template: package.json

json
1{
2  "name": "@project/{name}",
3  "version": "1.0.0",
4  "type": "module",
5  "scripts": {
6    "build": "tsc",
7    "dev": "tsx watch src/server.ts",
8    "start": "node dist/server.js",
9    "test": "vitest run"
10  },
11  "dependencies": {
12    "express": "^4.21.0"
13  },
14  "devDependencies": {
15    "tsx": "^4.0.0",
16    "typescript": "^5.7.0",
17    "vitest": "^3.0.0",
18    "@types/express": "^5.0.0"
19  }
20}

Template: src/server.ts

typescript
1import express from 'express';
2import { handlers } from './handlers/index.js';
3
4const app = express();
5const PORT = process.env.PORT || 3000;
6
7app.use(express.json());
8
9// Health check
10app.get('/health', (_req, res) => {
11  res.json({ status: 'ok', service: '{name}' });
12});
13
14// Routes — delegate to handlers (NEVER put logic here)
15app.post('/api/v1/:action', handlers.handleAction);
16
17// Unhandled rejection handler
18process.on('unhandledRejection', (reason, promise) => {
19  console.error('Unhandled Rejection:', reason);
20  process.exit(1);
21});
22
23// Uncaught exception handler
24process.on('uncaughtException', (error) => {
25  console.error('Uncaught Exception:', error);
26  process.exit(1);
27});
28
29app.listen(PORT, () => {
30  console.log(`{name} running on port ${PORT}`);
31});

Template: src/types.ts

typescript
1export interface ServiceConfig {
2  port: number;
3  name: string;
4  environment: 'development' | 'staging' | 'production';
5}
6
7// Add your domain types here

Template: tsconfig.json

json
1{
2  "compilerOptions": {
3    "target": "ES2022",
4    "module": "ESNext",
5    "moduleResolution": "bundler",
6    "outDir": "dist",
7    "rootDir": "src",
8    "strict": true,
9    "esModuleInterop": true,
10    "skipLibCheck": true,
11    "declaration": true
12  },
13  "include": ["src/**/*"],
14  "exclude": ["node_modules", "dist", "tests"]
15}

Auto-Branch (if on main)

Before scaffolding a new service, check the current branch:

bash
1git branch --show-current

Default behavior (auto_branch = true in Codex-mastery-project.conf):

• If on main or master: automatically create a feature branch and switch to it:

  bash
  1git checkout -b feat/<service-name>

  Report: "Created branch feat/<service-name> — main stays untouched."
• If already on a feature branch: proceed
• If not a git repo: skip this check

To disable: Set auto_branch = false in Codex-mastery-project.conf. When disabled, warn and ask the user before proceeding on main.

After Creating — Checklist

• Directory structure matches template
• package.json has correct scripts
• TypeScript strict mode enabled
• Entry point has unhandledRejection AND uncaughtException handlers
• All routes use /api/v1/ prefix
• Business logic in handlers/ (not server.ts)
• No file exceeds 300 lines
• Port assigned in root AGENTS.md port table
• Service added to docs/ARCHITECTURE.md
• Basic test file created
• .dockerignore created (if using Docker)

RuleCatch Report

After the service is scaffolded, check RuleCatch:

• If the RuleCatch MCP server is available: query for violations in the new service files
• Report any violations found
• If no MCP: suggest checking the RuleCatch dashboard