Ring:dev Readyz

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:

Readiness Architecture

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

Standards references (WebFetch by implementation agents):

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": "saas"
}

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:

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

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