Skills
skills/parhumm/jaan-to/backend-service-implement

backend-service-implement

SKILL.md

backend-service-implement

Bridge spec to code — generate full service implementations with business logic from TODO stubs and upstream specs.

Context Files

  • $JAAN_CONTEXT_DIR/tech.md - Tech stack context (CRITICAL — determines framework, ORM, patterns)
    • Uses sections: #current-stack, #frameworks, #constraints, #patterns
  • $JAAN_CONTEXT_DIR/config.md - Project configuration
  • $JAAN_TEMPLATES_DIR/jaan-to-backend-service-implement.template.md - Output template
  • $JAAN_LEARN_DIR/jaan-to-backend-service-implement.learn.md - Past lessons (loaded in Pre-Execution)
  • ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol
  • ${CLAUDE_PLUGIN_ROOT}/docs/research/70-dev-backend-service-implementation-generation.md - Research: service layer architecture, ORM queries, RFC 9457 errors, pagination, transactions, idempotency, JWT lifecycle

Input

Upstream Artifacts: $ARGUMENTS

Accepts 1-4 file paths or directory references:

  • backend-scaffold — Path to scaffold output (route handlers with TODO stubs, service stubs, ORM schema)
  • backend-api-contract — Path to OpenAPI 3.1 YAML (endpoint specs, request/response schemas, error codes)
  • backend-data-model — Path to data model document (table definitions, relationships, constraints, indexes)
  • backend-task-breakdown — Path to BE task breakdown (vertical slices with implementation notes)
  • Empty — Interactive wizard prompting for each artifact

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: backend-service-implement Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read context files if available:

  • $JAAN_CONTEXT_DIR/tech.md — Know the tech stack for framework-specific service generation
  • $JAAN_CONTEXT_DIR/config.md — Project configuration

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_backend-service-implement

Language exception: Generated code output (variable names, code blocks, schemas, SQL, API specs) is NOT affected by this setting and remains in the project's programming language.

PHASE 1: Analysis (Read-Only)

Thinking Mode

ultrathink

Use extended reasoning for:

  • Cross-referencing scaffold TODO stubs against API contract + data model + task breakdown
  • Deriving business logic from endpoint relationships and status code semantics
  • Planning service implementation order (dependency graph)
  • Identifying state machines, transactions, and idempotency requirements

Step 1: Validate & Parse Inputs

For each provided path:

  • backend-scaffold: Read route handlers, service stubs, ORM schema. Extract all // TODO comments and map to endpoint operations
  • backend-api-contract: Read api.yaml. Extract paths, schemas, error responses, security schemes, pagination config
  • backend-data-model: Read data model doc. Extract table definitions, constraints, indexes, relationships, migration notes
  • backend-task-breakdown: Read task breakdown. Extract vertical slices, implementation notes, acceptance criteria, business rules

Report which inputs found vs missing; suggest fallback for missing:

  • Missing scaffold: generate service implementations from API contract + data model (scaffold-less mode)
  • Missing API contract: derive endpoints from scaffold route definitions
  • Missing data model: derive from Prisma/Eloquent schema in scaffold
  • Missing task breakdown: derive business rules from API contract status codes and schema differences

Present input summary:

INPUT SUMMARY
─────────────
Sources Found:    {list}
Sources Missing:  {list with fallback suggestions}
Entities:         {extracted entity/resource names}
TODO Stubs:       {count from scaffold}
Endpoints:        {count from API contract}
Tables:           {count from data model}
Task Slices:      {count from task breakdown}
Business Rules:   {count of derived rules}

Step 2: Detect Tech Stack

Read $JAAN_CONTEXT_DIR/tech.md:

  • Extract framework from #current-stack (default: Fastify v5+)
  • Extract ORM from #current-stack (default: Prisma)
  • Extract DB from #current-stack (default: PostgreSQL)
  • Extract patterns from #patterns (auth, error handling, logging)
  • If tech.md missing: ask framework/ORM/DB via AskUserQuestion

Multi-Stack Detection:

tech.md value Framework ORM/DB Service Pattern Output
Node.js / TypeScript Fastify v5+ Prisma Plain exported functions + Prisma singleton .ts files
PHP Laravel 12 / Symfony 7 Eloquent / Doctrine Service classes + Repository pattern .php files
Go Chi / stdlib (Go 1.22+) sqlc / GORM Feature-based internal packages .go files

Step 3: Map TODOs to Implementation Plan

3.1: TODO Inventory

Parse all // TODO: implement stubs from scaffold. For each:

  1. Identify the endpoint (method + path)
  2. Match to API contract operation (request/response schemas, error codes)
  3. Match to data model tables (required queries, relationships)
  4. Match to task breakdown slice (business rules, acceptance criteria)

3.2: Business Logic Derivation

Derive implementation patterns from API spec semantics:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Business Logic Derivation Patterns" for HTTP status code patterns, schema difference analysis, endpoint relationship patterns, and task breakdown derivation rules.

3.3: State Machine Detection

When API specs include status fields with constrained transitions:

  • Extract enum values from schema
  • Map action endpoints to transitions (e.g., POST /orders/{id}/confirm)
  • Generate transition map and validation function

3.4: Dependency Graph

  1. Shared helpers (error factory, pagination, cursor encoding)
  2. Auth service (JWT lifecycle — if auth endpoints exist)
  3. Independent resource services (no cross-service dependencies)
  4. Dependent resource services (reference other services)
  5. Cross-cutting middleware (idempotency, rate limiting)

Step 4: Clarify Implementation Scope

Use AskUserQuestion:

  1. Scope question:

    • Question: "Implement all TODOs or select vertical slices?"
    • Header: "Scope"
    • Options:
      • "All TODOs" — Implement every TODO stub found
      • "Select slices" — Choose specific vertical slices from task breakdown
      • "Priority subset" — Start with core CRUD, add complex logic later

  2. Auth question (if auth endpoints detected):

    • Question: "What JWT library should be used for authentication?"
    • Header: "Auth"
    • Options:
      • "jose (Recommended)" — Modern JWT with Web Crypto API, edge-compatible
      • "jsonwebtoken" — Legacy but widely used
      • "Already implemented" — Auth service exists, skip generation
      • "No auth" — Skip auth implementation

  3. Pagination question (if list endpoints detected):

    • Question: "Which pagination strategy for list endpoints?"
    • Header: "Pagination"
    • Options:
      • "Cursor-based (Recommended)" — Stable under writes, O(1) seek, opaque cursor
      • "Offset-based" — Simple page + limit, for admin/dashboard endpoints
      • "Both" — Cursor for public API, offset for admin
      • "Already implemented" — Pagination helpers exist

  4. Transaction depth (if multi-step operations detected):

    • Question: "How should multi-step operations be handled?"
    • Header: "Transactions"
    • Options:
      • "Interactive transactions (Recommended)" — Prisma $transaction with isolation levels
      • "Sequential batch" — Simple array transactions for independent writes
      • "Optimistic concurrency" — Version-based updates with conflict detection
      • "Mix by operation" — Choose per operation based on complexity

  5. Idempotency question (if POST/PUT endpoints exist):

    • Question: "Should POST/PUT endpoints support idempotency keys?"
    • Header: "Idempotency"
    • Options:
      • "Yes (Recommended)" — Idempotency-Key header with DB storage, 24h TTL
      • "Critical endpoints only" — Only for payment/order creation
      • "No" — Skip idempotency support

Step 5: Present Implementation Plan

IMPLEMENTATION PLAN
═══════════════════

STACK: {framework} + {orm} + {database}

TODO COVERAGE
─────────────
Total TODOs:     {count}
Implementing:    {count} ({scope choice})
Skipping:        {count} (if partial scope)

SERVICES ({count})
──────────────────
{For each service:}
  {resource}.service.ts
    - {method}: {description} ({status codes})
    ...

SHARED HELPERS
──────────────
  - error-factory.ts (RFC 9457 problem details, error type registry)
  - pagination.ts ({strategy} pagination helper)
  {- cursor.ts (cursor encode/decode) — if cursor pagination}
  {- auth.service.ts (JWT lifecycle with jose) — if auth}
  {- idempotency.ts (Idempotency-Key middleware) — if enabled}

STATE MACHINES ({count if any})
───────────────────────────────
  {resource}: {state1} → {state2} → ...

DEPENDENCY ORDER
────────────────
1. Shared helpers
2. {ordered service list}

HARD STOP — Review Implementation Plan

Use AskUserQuestion:

  • Question: "Proceed with generating service implementations?"
  • Header: "Generate"
  • Options:
    • "Yes" — Generate all planned service files
    • "No" — Cancel
    • "Edit" — Let me revise the scope or architecture first

Do NOT proceed to Phase 2 without explicit approval.

PHASE 2: Generation (Write Phase)

Phase 2 Output — Flat folder (no nested subfolder)

All files in $JAAN_OUTPUTS_DIR/backend/service-implement/{id}-{slug}/:

{id}-{slug}/
├── {id}-{slug}.md                        # Implementation guide + decisions log
├── {id}-{slug}-services/                  # Service files by domain
│   ├── {resource}.service.ts              # Per-resource service implementation
│   ├── auth.service.ts                    # Auth/JWT service (if applicable)
│   └── ...
├── {id}-{slug}-helpers/                   # Shared helper files
│   ├── error-factory.ts                   # RFC 9457 error creation
│   ├── pagination.ts                      # Pagination utility
│   ├── cursor.ts                          # Cursor encode/decode (if cursor pagination)
│   └── idempotency.ts                     # Idempotency middleware (if enabled)
└── {id}-{slug}-readme.md                  # Integration instructions

File extensions adapt to detected stack (.ts for Node.js, .php for PHP, .go for Go).

Step 6: Generate Shared Helpers

Generate helpers in dependency order (these are used by services):

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Helper Generation Patterns" for Error Factory (RFC 9457), Pagination Helper, Auth Service, and Idempotency Middleware generation templates.

Step 7: Generate Service Implementations

7.1: Service Structure

Node.js/TypeScript (Fastify + Prisma):

// Plain exported functions importing Prisma singleton
// Module caching acts as built-in singleton (no DI container needed)
// Testable via vi.mock()

import { prisma } from '../lib/prisma.js';
import { createProblemDetail, BusinessError } from '../helpers/error-factory.js';
import { paginateWithCursor } from '../helpers/pagination.js';
import type { RequestContext } from '../types.js';

PHP (Laravel + Eloquent):

// Service class with constructor injection
// Repository pattern optional (Eloquent IS the repository)
// API Resources for response transformation

Go (Chi/stdlib + sqlc):

// Feature-based internal package
// Constructor injection with small interfaces (1-3 methods)
// Accept interfaces, return structs

7.2: Per-Method Implementation

For each TODO stub, generate the full implementation:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Per-Method Implementation Patterns" for CREATE, READ, LIST, UPDATE, DELETE, and ACTION operation implementation steps.

7.3: State Machine Generation

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "State Machine Generation" for transition map template and validation function code.

7.4: Cross-Service Operations

For operations spanning multiple services:

  • Use Prisma interactive $transaction with explicit isolation level
  • Pass tx (transaction client) to all participating service methods
  • Keep transactions short — move side effects outside
  • Set maxWait: 5000 and timeout: 10000

Step 8: Generate Implementation Guide

8.1: Executive Summary

1-2 sentences: resource count, stack, key patterns implemented (pagination, auth, idempotency).

8.2: Implementation Decisions Log

For each decision made during generation:

Decision Choice Rationale
Pagination Cursor-based Stable under concurrent writes, O(1) seek
Auth jose JWT Web Crypto API, edge-compatible
Transactions Interactive Multi-step inventory reservation
... ... ...

8.3: TODO Coverage Report

Service TODOs Found TODOs Implemented Coverage
user.service.ts 5 5 100%
order.service.ts 8 8 100%
... ... ... ...
Total {n} {n} 100%

8.4: Service Dependency Map

Mermaid diagram showing service dependencies and shared helpers.

Step 9: Generate Integration README

  1. Setup — How to integrate generated services into the scaffold project
  2. File Placement — Where each generated file goes relative to the project root
  3. Dependencies — NPM packages to install (jose, etc.)
  4. Configuration — Environment variables needed (JWT_SECRET, etc.)
  5. Testing — How to test individual services (vi.mock() pattern)
  6. Next Steps — Downstream skills:
    • /jaan-to:qa-test-generate — Generate tests for these implementations
    • /jaan-to:sec-audit-remediate — Security audit the implementations

Step 10: Quality Check

Before preview, verify every item in the checklist (coverage, error handling, patterns, security, code quality).

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Quality Check Checklist" for the full verification checklist.

If any check fails, fix before preview.

Step 11: Preview & Approval

Present generated output summary:

  • File count and total lines
  • TODO coverage percentage
  • Service list with method counts
  • Helpers generated

Use AskUserQuestion:

  • Question: "Write service implementation files to output?"
  • Header: "Write Files"
  • Options:
    • "Yes" — Write the files
    • "No" — Cancel
    • "Refine" — Make adjustments first

Step 12: Generate ID and Folder Structure

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/backend/service-implement"
mkdir -p "$SUBDOMAIN_DIR"
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")
slug="{project-name-slug}"
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"

Preview output configuration:

Output Configuration

  • ID: {NEXT_ID}
  • Folder: $JAAN_OUTPUTS_DIR/backend/service-implement/{NEXT_ID}-{slug}/
  • Main file: {NEXT_ID}-{slug}.md

Step 13: Write Output

  1. Create output folder: mkdir -p "$OUTPUT_FOLDER"
  2. Create services subdirectory: mkdir -p "$OUTPUT_FOLDER/${NEXT_ID}-${slug}-services"
  3. Create helpers subdirectory: mkdir -p "$OUTPUT_FOLDER/${NEXT_ID}-${slug}-helpers"
  4. Write all files:
    • Main doc: $OUTPUT_FOLDER/${NEXT_ID}-${slug}.md
    • Service files: $OUTPUT_FOLDER/${NEXT_ID}-${slug}-services/{resource}.service.ts
    • Helper files: $OUTPUT_FOLDER/${NEXT_ID}-${slug}-helpers/{helper}.ts
    • Integration readme: $OUTPUT_FOLDER/${NEXT_ID}-${slug}-readme.md
  5. Update subdomain index:
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
add_to_index \
  "$SUBDOMAIN_DIR/README.md" \
  "$NEXT_ID" \
  "${NEXT_ID}-${slug}" \
  "{Project Title} Service Implementations" \
  "{Executive summary — 1-2 sentences}"
  1. Confirm completion:

Service implementations written to: $JAAN_OUTPUTS_DIR/backend/service-implement/{NEXT_ID}-{slug}/ Index updated: $JAAN_OUTPUTS_DIR/backend/service-implement/README.md

Step 14: Suggest Next Actions

Service implementations generated successfully!

TODO Coverage: {n}/{n} (100%)

Next Steps:

  • Copy service files to your project (see integration readme for placement)
  • Run /jaan-to:qa-test-generate to generate tests for these implementations
  • Run /jaan-to:sec-audit-remediate to audit the implementations for security issues
  • Run your existing test suite to verify integration

Step 15: Capture Feedback

Use AskUserQuestion:

  • Question: "How did the service implementations turn out?"
  • Header: "Feedback"
  • Options:
    • "Perfect!" — Done
    • "Needs fixes" — What should I improve?
    • "Learn from this" — Capture a lesson for future runs

If "Learn from this": Run /jaan-to:learn-add backend-service-implement "{feedback}"

Key Generation Rules — Node.js/TypeScript (Research-Informed)

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Key Generation Rules — Node.js/TypeScript (Research-Informed)" for the full rules list covering Service Layer, Prisma Queries, Error Handler, RFC 9457, JWT, Cursor Pagination, Idempotency, Transactions, Import Extensions, and DTO Mapping.

Multi-Stack Support (Research-Informed)

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Multi-Stack Service Patterns" for PHP (Laravel + Symfony) and Go stack-specific service patterns.

Anti-Patterns to NEVER Generate

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Anti-Patterns" for per-stack anti-pattern lists (All Stacks, Node.js, PHP, Go).

Skill Alignment

  • Two-phase workflow with HARD STOP for human approval
  • Multi-stack support via tech.md detection
  • Template-driven output structure
  • Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

  • All TODO stubs from scaffold have corresponding implementations
  • Every API contract endpoint has service method coverage
  • RFC 9457 error handling implemented with type registry
  • Pagination helper generated and used in all list endpoints
  • Auth service generated (if auth endpoints exist) with JWT lifecycle
  • Idempotency middleware generated (if enabled) for POST/PUT
  • State machines generated for resources with status transitions
  • Transactions used for multi-step operations with side effects outside
  • Quality checks passed (coverage, error handling, patterns, security, code quality)
  • Implementation guide with decisions log and TODO coverage report
  • Integration readme with setup instructions and next steps
  • Output follows v3.0.0 structure (ID, folder, index)
  • Index updated with executive summary
  • User approved final result
Weekly Installs
7
Repository
parhumm/jaan-to
GitHub Stars
9
First Seen
Feb 23, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
amp7
gemini-cli7
github-copilot7
codex7
kimi-cli7
cursor7