SOP-002: Service Onboarding

SOP-002: Service Onboarding

Purpose

Onboard a new service into the ADLC pipeline so that it can be developed, tested, reviewed, and deployed through the standard automation. Covers project setup, spec creation, registry update, and first pipeline run.

Scope

Applies to any new microservice being added to the ODS Platform or a new project (e.g., lejecos). Covers initial repo setup, spec writing, service-project mapping, Coolify provisioning request, and first dev cycle.

Prerequisites

Procedure

1. Create the spec (if not exists)

mkdir -p ~/dev/specs/{project}/specs/{service}/

Write spec.md following the standard format with: - Service description and responsibilities - API endpoints with request/response schemas - Acceptance criteria (AC-001, AC-002, …) - At least one “zero-state” acceptance criterion (lesson from OID spec gap) - Database schema requirements - Event topics (Redpanda CloudEvents) - Multi-tenancy requirements (tenant_id in every query)

2. Initialize the project directory

mkdir -p ~/dev/projects/{service}/tasks
cd ~/dev/projects/{service}
git init
git checkout -b dev

For Rust services:

cargo init --name {service}

For Node/TypeScript services:

npm init -y

Create tasks/lessons.md:

## Lessons Learned

(none yet)

Create tasks/todo.md:

## Task: Initial implementation

### Objective
Implement {service} per spec.

### Plan
- [ ] Database schema + migrations
- [ ] Domain models + unit tests
- [ ] API endpoints + integration tests
- [ ] Health check endpoint
- [ ] Dockerfile

3. Create the CLAUDE.md for the service

Every service repo must have a root-level CLAUDE.md with: - Tech stack specifics - Build/test commands - Database schema name - Environment variables required - Service-specific rules

4. Update the service-project map

python3 -c "
import json
f = '$HOME/dev/ops/agents/service-project-map.json'
m = json.load(open(f))
m['{service}'] = {'project': '{project}', 'type': 'rust|node', 'phase': 'P0'}
json.dump(m, open(f, 'w'), indent=2)
"

5. Update progress.md

Add the service tasks to ~/dev/specs/{project}/gestion/progress.md:

## {service}

- [ ] DEV: {TASK-ID} -- {description}

6. Update external dependencies registry

Check if the service has external dependencies and update:

# Add entries to ~/dev/ops/external-deps.md

7. Create Coolify config placeholder

cat > ~/dev/ops/coolify/{service}.json << 'EOF'
{
  "service": "{service}",
  "project": "{project}",
  "provisioned_at": null,
  "note": "PENDING — needs Coolify app creation"
}
EOF

Post to Slack DM requesting Coolify app creation if this is a web service.

8. Create GitHub repository

cd ~/dev/projects/{service}
gh repo create jniox/ods-{service} --private --source=. --push

9. Trigger first pipeline run

The next /check-pipeline cycle will detect the new service and spawn dev agents for pending tasks. To trigger immediately:

/agent dev "SERVICE: {service}. PROJECT: {project}. TASK: {first-task-id} -- {description}. Spec: ~/dev/specs/{project}/specs/{service}/spec.md"

Verification

Rollback

If onboarding was premature or incorrect: 1. Remove from service-project map 2. Remove progress.md entries 3. Remove Coolify config placeholder 4. Archive (do not delete) the project directory: mv ~/dev/projects/{service} ~/dev/projects/.archived/{service}

References