build-service

What this skill does

# Build Service

Orchestrates the complete service creation/extension lifecycle from spec to commit. Absorbs manifest declaration and service implementation into a unified pipeline: spec discovery, operation declaration, project scaffolding, implementation, testing, quality gates, review, and commit.

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Build complete backend services following the `@theriety/service` architecture — from specification through manifest declaration, implementation, testing, quality verification, review, and commit.
**When to use**:
- Creating a new service package from scratch
- Adding operations, integrations, or webhooks to an existing service
- Declaring operation manifests with schema definitions
- Implementing a service defined in a DESIGN.md or Notion specification

**Prerequisites**:
- Domain entities identified (or `@theriety/data-{domain}` exists)
- Service operations specified (names + brief descriptions)
- For extend mode: existing `@theriety/service-{name}` package

**What this skill does NOT do**:
- Create data packages (use `build-data`)
- Perform only scaffolding without implementation (use `coding:draft-code`)
- Fix only test failures (use `coding:fix`)
- Audit existing services (use `audit-service`)

### Your Role

You are a **Service Delivery Director** who orchestrates like a construction project manager — ensuring foundations are laid before walls go up. You never execute tasks directly, only delegate and coordinate. Your management style emphasizes:

- **Sequential Integrity**: Each phase builds on the previous — manifests before scaffolding, scaffolding before implementation, implementation before testing
- **Mode Awareness**: Detect new vs extend mode early, skip irrelevant steps
- **Reference-Driven Quality**: Every subagent receives exact code patterns and reference file paths
- **Verification Gates**: No step proceeds without prior step's validation

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **Service Name**: kebab-case name (e.g., `notifications`, `billing`) — maps to `@theriety/service-{name}`
- **Operations List**: Array of operation names with brief descriptions

#### Optional Inputs

- **Data Domain**: The `@theriety/data-{domain}` package (default: auto-detect)
- **External Integrations**: Third-party APIs to integrate (e.g., Stripe, SendGrid)
- **Peer Services**: Other `@theriety/service-*` services this one calls
- **Webhooks**: External webhook handlers needed
- **Guards**: Authorization scopes and rules for `ensure()` calls
- **--extend flag**: Force extend mode
- **--notion-url**: Notion page with operation specifications

#### Expected Outputs

- **Manifest Package**: Complete `@theriety/manifest-{name}` with operation schemas (if new)
- **Service Package**: Complete `@theriety/service-{name}` package at `services/{name}/`
- **Test Suite**: Unit tests (`spec/**/*.spec.ts`) + integration tests (`spec/**/*.spec.int.ts`)
- **Verification Report**: typecheck + lint + test pass/fail results

#### Data Flow Summary

User provides service specification → Step 1 discovers/validates requirements → Step 2 declares operation manifests → Step 3 scaffolds service (new mode) → Step 4 implements operations → Step 5 runs quality gates → Step 6 reviews → Step 7 commits or hands over.

### Visual Overview

```plaintext
  YOU                              SUBAGENTS
(Orchestrates Only)             (Perform Tasks)
   |                                   |
   v                                   v
[START]
   |
   v
[Step 1: Spec Discovery] -------- (You: parse inputs, detect mode, verify deps)
   |
   v
[Step 2: Declare Operations] ----> (Subagents: schema defs, manifest build, integration)
   |
   +-- new mode --+
   |              v
   |   [Step 3: Project Setup] --> (Sub-skill: coding:setup-project)
   |              |
   +-- extend ----+
   |
   v
[Step 4: Draft→Implement→Test] -> (Sub-skills: coding:draft-code → complete-code → complete-test)
   |                    +- Operations batch
   |                    +- Integrations batch
   |                    +- Webhooks batch
   v
[Step 5: Quality Gate] ---------> (Sub-skills: coding:fix + coding:lint + coding:refactor)
   |                                  Fix cycle (max 3)
   v
[Step 6: Review] ----------------> (Sub-skill: coding:review)
   |
   v
[Step 7: Commit Gate] -----------> (Sub-skill: coding:commit or coding:handover)
   |
   v
[END]

Legend:
═══════════════════════════════════════════════════════════════
• LEFT COLUMN: You plan & orchestrate (no execution)
• RIGHT SIDE: Subagents execute tasks in parallel
• ARROWS (───→): You assign work to subagents
• DECISIONS: You decide based on subagent reports
═══════════════════════════════════════════════════════════════
```

## 3. SKILL IMPLEMENTATION

### Skill Steps

1. Step 1: Spec Discovery
2. Step 2: Declare Operations
3. Step 3: Project Setup (skip if extend mode)
4. Step 4: Draft → Implement → Test
5. Step 5: Quality Gate
6. Step 6: Review
7. Step 7: Commit Gate

---

### Step 1: Spec Discovery

**Step Configuration**:

- **Purpose**: Parse service specification, detect new/extend mode, verify dependencies, produce file manifest
- **Input**: User's service specification (name, operations, domain, integrations, peers, webhooks, guards)
- **Output**: Validated requirements object + file manifest + mode (new/extend)
- **Sub-skill**: (none — orchestrator performs directly)
- **Parallel Execution**: No

#### Phase 1: Planning (You)

**What You Do**:

1. **Parse inputs** from user request:
   - Service name (kebab-case)
   - Operations list with descriptions
   - Data domain name
   - External integrations, peer services, webhooks, guards (all optional)

2. **Detect mode**:
   - Run `ls /Users/alvis/Repositories/core/services/{name}/ 2>/dev/null`
   - If directory exists → **extend mode**
   - If not → **new mode**

3. **Verify packages exist**:
   - Run `ls /Users/alvis/Repositories/core/packages/manifest-{name}/ 2>/dev/null`
   - Run `ls /Users/alvis/Repositories/core/packages/data-{domain}/ 2>/dev/null`
   - If manifest missing and new mode → Step 2 will create it
   - If data package missing → STOP and inform user

4. **If Notion URL provided**, fetch operation specifications from Notion using MCP tools

5. **In extend mode**, read:
   - `services/{name}/src/index.ts` to identify existing operations
   - `services/{name}/package.json` to identify existing deps

6. **Produce file manifest** listing all files to create/modify

7. **Use TodoWrite** to create task list for all remaining steps

**OUTPUT**: Validated requirements + file manifest + mode

#### Phase 4: Decision (You)

1. If all dependencies verified → **PROCEED** to Step 2
2. If packages missing → **STOP** and ask user
3. If requirements ambiguous → **ASK** for clarification

---

### Step 2: Declare Operations

**Step Configuration**:

- **Purpose**: Create operation manifest schemas with type-safe definitions, mock implementations, and service integration
- **Input**: Validated requirements from Step 1
- **Output**: Complete manifest package with all operation schemas
- **Sub-skill**: (none — uses direct subagents following declare-service-operation patterns)
- **Parallel Execution**: Yes (schemas can be created in parallel)
- **Skip condition**: If all operations already have manifests (extend mode with existing ops)

#### Phase 1: Planning (You)

1. **Determine manifest project**: Check if `manifests/{name}/` exists
2. **If new manifest needed**, follow the manifest project structure and per-operation subagent pattern in `references/manifest-declaration.md`
3. **Create batches** — one per operation (max 10 per batch)
4. **Use TodoWrite** to track

For Phase 2 (schema/manifest subagent prompt + schema patterns), Phase 3 (review checks), and Phase 4 (decision rules), see `references/manifest-declaration.md`.

---

### Step 3: Project Setup

**Step Configuration**:

- **Purpose**: Scaffol