ring-dev-readyz

name

ring:dev-readyz

description

Readiness implementation orchestrator for Lerian services. Drives a 12-gate cycle that detects stack, audits existing /readyz compliance, dispatches language-specific engineers (Go / TypeScript / Next.js) to implement the canonical /readyz contract, ValidateSaaSTLS() enforcement, metrics emission, startup self-probe, graceful-drain coupling, circuit-breaker integration, and multi-tenant carve-out — then runs 13 parallel reviewers.

Readyz & Self-Probe Development Cycle

When to use

• New service being created
• Service has external dependencies (DB, cache, queue, HTTP upstreams)
• Service lacks /readyz or has incomplete dependency checks
• Service missing startup self-probe, SaaS TLS enforcement, or metrics

Skip when

• Pure library package with no deployable service or HTTP server
• Task is documentation-only, configuration-only, or non-code
• Service has no external dependencies AND no network listeners
• CLI tool or batch job that does not serve HTTP traffic

You orchestrate. Agents implement. NEVER use Edit/Write/Bash on source files. All code changes go through Task(subagent_type="ring:backend-engineer-{language}"). TDD mandatory for all implementation gates (RED → GREEN → REFACTOR).

Agents:

Who	Responsibility
ring:backend-engineer-golang	Go services
ring:backend-engineer-typescript	TypeScript backend/BFF
ring:frontend-bff-engineer-typescript	Next.js BFF
ring:codebase-explorer	Gate 1 analysis
ring:visualize	Gate 1.5 HTML preview
13 reviewers	Gate 9

Readiness Architecture

/readyz — runtime dependency probe for K8s readinessProbe. /health — liveness probe gated by startup self-probe.

Standards references (WebFetch by implementation agents):

Resource	URL
Ring SRE standards	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md
Go bootstrap standards	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/bootstrap.md
This skill (authoritative)	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/skills/dev-readyz/SKILL.md

Canonical response contract:

{
  "status": "healthy",
  "checks": {
    "postgres": { "status": "up", "latency_ms": 2, "tls": true },
    "redis":    { "status": "skipped", "reason": "REDIS_ENABLED=false" },
    "upstream_fees": { "status": "degraded", "breaker_state": "half-open", "latency_ms": 12 }
  },
  "version": "1.2.3",
  "deployment_mode" 

Status vocabulary: up / down / degraded / skipped / n/a — no others.

Aggregation rule: top-level "unhealthy" + HTTP 503 if ANY check is down or degraded.

Endpoint paths:

Stack	Readiness	Liveness
Go API	/readyz	/health
TypeScript API	/readyz	/health
Next.js	/api/admin/health/readyz	same

Forbidden anti-patterns (block progression in Gate 0):

1. Response caching in front of /readyz
2. /ready alias (not /readyz)
3. /health/live + /health/ready split
4. strings.Contains(uri, "tls=true") — use url.Parse
5. Reflection on *amqp.Connection for TLS state
6. Inline TLS checks at each connection site — use ValidateSaaSTLS()
7. process.exit() in Next.js instrumentation.ts on probe failure

Mandatory agent instruction (include in EVERY dispatch):

WebFetch https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/skills/dev-readyz/SKILL.md and sre.md. Follow the canonical response contract exactly. Five-value status vocabulary. Aggregation: 503 iff any check is down or degraded. Forbidden anti-patterns 1-7: MUST NOT introduce any. TDD: RED → GREEN → REFACTOR.

Gate Overview

Gate	Name	Condition	Agent
0	Stack Detection + /readyz Compliance Audit	Always	Orchestrator
1	Codebase Analysis	Always	ring:codebase-explorer
1.5	Implementation Preview (HTML report)	Always	ring:visualize
2	/readyz Endpoint Implementation	Always	ring:backend-engineer-{language}
3	TLS Detection (url.Parse)	Always	ring:backend-engineer-{language}
4	SaaS TLS Enforcement (ValidateSaaSTLS)	Always	ring:backend-engineer-{language}
5	Metrics Emission	Always	ring:backend-engineer-{language}
6	Circuit Breaker + Multi-Tenant Carve-Out	Skip only if no breakers AND single-tenant	ring:backend-engineer-{language}
7	Startup Self-Probe + /health + Graceful Drain	Always — NEVER skippable	ring:backend-engineer-{language}
8	Tests	Always	ring:backend-engineer-{language}
9	Code Review	Always	13 parallel reviewers
10	User Validation	Always	User
11	Activation Guide	Always	Orchestrator

Gates execute sequentially. Existing /readyz code ≠ compliance. Gate 0 Phase 2 audit is mandatory.

Gate 0: Stack Detection + Audit

Orchestrator executes directly. Three phases:

Phase 1: Stack Detection

grep -rn "postgresql\|pgx" internal/ go.mod
grep -rn "mongodb\|mongo" internal/ go.mod
grep -rn "redis\|valkey" internal/ go.mod
grep -rn "rabbitmq\|amqp" internal/ go.mod
grep -rn "http.Client\|upstream" internal/
grep -rn "circuitbreaker\|gobreaker" internal/
grep "DEPLOYMENT_MODE\|saas" .env* internal/

Phase 2: Compliance Audit (S1-S9) (if /readyz code detected)

• S1: Response contract shape (all required fields present)
• S2: Status vocabulary (only 5 valid values)
• S3: Aggregation rule (503 on down/degraded)
• S4: Endpoint path (exact /readyz, not /ready)
• S5: No response caching
• S6: TLS detection uses url.Parse, not strings.Contains
• S7: ValidateSaaSTLS() called at bootstrap for SaaS mode
• S8: Three readyz metrics emitted
• S9: Startup self-probe gates /health

Phase 3: Anti-Pattern Detection Check for each of the 7 forbidden anti-patterns. Any match = COMPLIANT: false.

Severity Reference

Severity	Criteria
CRITICAL	DEPLOYMENT_MODE=saas without ValidateSaaSTLS; TLS reflection; response caching
HIGH	Wrong status vocabulary; aggregation rule wrong; metrics not emitted; self-probe missing
MEDIUM	Missing reason on skipped/n/a; drain grace too short
LOW	Missing per-dep description; inconsistent version string