ring

Writing a rolling-wave phased implementation plan from a spec before coding: a phase-epic-task hierarchy where Phase 1 is detailed into dispatch-ready tasks and later phases stay epic-level for elaboration during execution. Use when a multi-file feature needs decomposition; runs after ring:exploring-codebases or pre-dev gates, hands off to ring:executing-plans or ring:running-dev-cycle. Skip for single-file changes or spikes.

Applying or switching a repository's license (Apache 2.0, Elastic License v2, or Proprietary): rewrites the LICENSE file, updates Go/TS source headers, sets SPDX identifiers, and validates consistency after user confirmation. Use when asked to set, apply, or switch a license, or when scaffolding a service with no LICENSE. Skip when license, headers, and SPDX already match, or for non-code repos.

Generating or auditing a repository's llms.txt per the llmstxt.org spec, and creating CLAUDE.md / AGENTS.md when missing, by analyzing README, build files, docs, and API surface. Use when creating an llms.txt, auditing an existing one for spec compliance and live links, or improving a repo's AI readability. Skip when the llms.txt is current, the task is code-only with no doc scope, or the repo needs no LLM discoverability.

Managing an in-progress development cycle without driving it: status reports phase, epic/gate progress, assertiveness, and elapsed time from current-cycle.json; cancel confirms, marks the cycle cancelled, and writes a partial feedback report. Use when checking the status of, or cancelling, a running dev cycle. Skip when no cycle is active or the question is general project status, not cycle-specific.

Planning a frontend refactor: audits an existing React/Next.js frontend against Ring standards (architecture, design system, accessibility, testing) and produces a prioritized task list (findings.md + tasks.md) for ring:running-dev-cycle-frontend. Plans only — no edits. Use when an existing frontend needs to meet standards or an audit is requested. Skip for greenfield, single-file fixes, or backend (use ring:planning-backend-refactor).

Running the frontend (React/Next.js/TS) dev cycle from a plan.md (ring:writing-plans format; legacy tasks.md only for in-flight cycles) or backend handoff: drives frontend agents through Gate 0 TDD plus accessibility/visual/E2E/perf checks, Gate 7 parallel review, and Gate 8 user validation, with rolling-wave phase boundaries. Use when starting or resuming a gated frontend dev cycle. Skip for backend (use ring:running-dev-cycle) or docs-only work.

Running the backend dev cycle: implements every task in a rolling-wave plan.md (ring:writing-plans format) for a Go/TS service, driving specialist agents through Gate 0 implementation/TDD, Gate 8 parallel review, and Gate 9 validation per epic, elaborating later phases at each phase boundary. Use when starting or resuming a gated backend dev cycle with a plan.md (legacy tasks.md only for cycles already in flight; new cycles need the canonical plan format). Skip for frontend (use ring:running-dev-cycle-frontend) or docs-only work.

Authoring Grafana dashboards for Go services instrumented with lib-observability telemetry (tracing, metrics, log), plus a reference mode for RED/USE panel patterns and Grafonnet templates. Sweep mode inventories telemetry, runs PM deliberation on themes/SLIs/alerts, authors Grafonnet libsonnet compiled to JSON, and installs a CI drift gate. Use when scaffolding dashboards. Skip when the service is non-Go or emits no telemetry.

Planning the 8-gate Large Track pre-dev workflow (research, PRD, feature map, TRD, API contract, data model, dependency map, plan) with per-gate human approval. Use for features 2+ days that add dependencies, data models, multi-service integration, or new architecture. Skip for small features (use ring:planning-small-features). Plans only — no edits.

Planning the lightweight 4-gate Small Track pre-dev workflow (research, PRD, TRD, plan) with human approval and state tracking at each gate. Use for features under 2 days that reuse existing patterns and add no new dependencies, data models, or services. Skip for larger or complex features — use ring:planning-large-features instead. Plans only — no edits.

Writing a Technical Requirements Document that designs the technical architecture of the system or feature: components and boundaries, data flow, integration points, failure modes, and the mandatory program structure (DDD/hexagonal source tree) — in technology-agnostic patterns (code structure excepted), plus auth/pagination and BFF contracts for fullstack. Gate 3 of ring:planning-large-features (after ring:mapping-feature-relationships, before ring:designing-api-contracts) and Gate 2 of ring:planning-small-features (after ring:writing-prds, before ring:writing-plans). Use when the PRD passed validation. Skip when the PRD is unvalidated or the architecture is already documented.

Reviewing a Go/TS service's operational risk by mapping integration failure points (external HTTP calls, queue consumers, outbound webhooks), simulating stuck intermediate states for each entity in a flow, and classifying each scenario into tiers — then emitting operational runbooks (Tier 2) or gap specs (Tier 3). Two entry modes: explore an existing codebase, or read a dev-cycle plan.md and epic artifacts. Use before production hardening, incident retros, or at dev-cycle end. Skip for prototypes, pure libraries, or when no integration boundaries exist.

Open a GitHub Pull Request with automatic base branch detection, scope allowlist enforcement, PR template filling, and post-create base verification. Replaces ring:generating-pr-descriptions. Use after pushing a branch when ready to open a PR. Skip if the branch is not yet pushed or there are uncommitted changes — commit first with ring:committing-changes.

Executing a phased plan in rolling waves where each phase runs as one multi-agent workflow harness: the supervisor elaborates the phase into tasks against the real landed code, launches a workflow that implements with TDD and runs mandatory in-harness review plus an adversarial contrarian pass (and researchers when the phase hits an unknown) before returning verified work, then reviews it, checkpoints with the user, and rolls to the next phase. Use when each wave should be a reviewed multi-agent harness, not a lone subagent. Skip when one supervised subagent per wave suffices (ring:executing-plans) or the full gated cycle is wanted (ring:running-dev-cycle).

Controlled plan execution with human review checkpoints - loads plan, executes in batches, pauses for feedback. Supports one-go (autonomous) or batch modes.

Implementing a single planned task (Task N.M.T) end-to-end: selects the right backend agent by language and service type, drives one TDD RED->GREEN turn, then verifies coverage, lint, license headers, runtime, and delivery before handoff. Runs as Gate 0 before ring:reviewing-code. Use to drive ONE task inside an already-running cycle. Skip when asked to implement a whole plan.md or multiple tasks (use ring:running-dev-cycle).

Commit changes with scope allowlist enforcement, atomic grouping, GPG-signed conventional commits, and trailer management. Detects the repo's PR-validation scope policy before proposing any message. Use when the user asks to commit or has changes ready to record. Skip when the working tree is clean or the user wants raw git commands without grouping.

End-to-end git orchestrator: branch → commit → push → PR, with a full plan presented before any execution. Detects base branch and scope allowlist once and propagates to all phases. Use when ready to ship a complete unit of work. Skip if only one phase is needed: commit-only → ring:committing-changes, PR-only → ring:opening-pull-requests.

Generating self-contained, Lerian-branded HTML artifacts — D2 diagrams, comparison tables/matrices, code diffs, dashboards, slide decks, and plan/diff/recap reviews — from mandatory templates, then opening them in the browser. Use for architecture overviews, any table with 4+ rows or 3+ columns, slide presentations, or visual diff/plan/review output. Skip for simple tables that fit the terminal or text-only answers.

Expert prompt engineering and optimization for LLMs and AI systems. Covers core patterns (zero-shot, few-shot, CoT, role-playing, constitutional, tree-of-thoughts), common use cases, and a three-phase process. Use when crafting or optimizing prompts for AI systems. Skip when the prompt is trivial or already performing well.

Generating pull request descriptions from git branch changes with automatic title generation, change-type detection, and smart analysis. Uses branch-only scope to avoid full history analysis. Use when preparing a PR for review. Skip when the PR is a single trivial commit or description already exists.

Forensic code search and analysis with optional Chain of Draft (CoD) ultra-concise mode. Five-phase methodology (clarification, planning, execution, analysis, synthesis) with severity assessment. Use for targeted investigation of specific patterns, bugs, or vulnerabilities. Skip for broad architecture mapping (use ring:exploring-codebases instead).

React composition patterns that scale. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or during architecture review. Skip for simple components with 1-2 props or non-React code.

Analyzing different approaches for a task or problem with structured comparisons, effort estimates, and recommendations. Use when facing strategic decisions, architecture choices, or multiple viable approaches. Skip when there's an obvious single approach or the decision is already made.

Cleaning redundant and obvious comments following clean code principles while preserving meaningful documentation. Supports git scope filtering (staged, unstaged, branch, commit-range). Use when code has excessive comments, during code review, or post-refactor cleanup. Skip when reviewing documentation files or comments are already minimal.

Using lib-observability v1.1.0, Lerian's OpenTelemetry foundation (lib-commons, lib-systemplane, lib-streaming depend on it), in two modes. Sweep Mode detects DIY zap/slog logging, raw OTel metrics, hand-rolled redaction, and hard-coded attribute strings. Reference Mode catalogs the log, metrics, zap, redaction, and constants packages. Go-only. Skip for non-Go or assert/runtime/tracing.

Using lib-systemplane, the hot-reload runtime-config plane (Postgres LISTEN/NOTIFY or MongoDB change streams), in two modes. Sweep Mode detects DIY config reload (SIGHUP, fsnotify, viper, pgx LISTEN), manual tenant-scoping, hand-built admin CRUD, and v4 residue. Reference Mode catalogs client lifecycle and migration-only provisioning. Go-only. Gated migration goes to ring:migrating-to-lib-systemplane. Skip for non-Go.

Migrating a Lerian Go app off lib-commons observability imports (deprecated shims or removed APIs) to lib-observability via a fixed mapping table, then bumps go.mod and validates the build; ring:backend-go applies the edits. Covers log/zap/runtime/assert, opentelemetry/tracing, HTTP middleware, context helpers, and direct systemplane import moves. Use when lib-commons observability imports remain or the build breaks on removed APIs.

Adopting the lib-commons/v5 shared Huma (OAS 3.1) OpenAPI wrapper + RFC 9457 problem model (commons/net/http/{openapi,problem}) in a Lerian Go service: wire openapi.New/ServeSpec + problem.Install (central >=500 scrub) on BOTH runtime and spec-gen paths, the per-rail problem.MapError flex seam, and rename-only spec regen. Orchestrates a gated cycle dispatching ring:backend-go. Use for greenfield Huma or migrating a service off a local openapi/humaerr wrapper. Skip for non-Go or non-HTTP work.

Planning a backend refactor: audits an existing Go or TypeScript backend against Ring/Lerian standards and produces a prioritized task list (findings.md + tasks.md) ready for ring:running-dev-cycle. Plans only — no edits. Use when an existing backend service needs to meet standards or an audit is requested. Skip for greenfield projects, single-file fixes, or frontend (use ring:planning-frontend-refactor).

Designing the API contract as a real OpenAPI 3.1 specification (openapi.yaml with full paths, operations, schemas, components, Lerian error envelope, and auth schemes) from the validated TRD. Gate 4 of ring:planning-large-features, Large Track only; runs after ring:writing-trds, before ring:designing-data-model. Use when a system exposes APIs that components or clients consume. Skip for Small Track, a system with no API surface, or an unvalidated TRD.

Designing the physical data model as a real stack-native schema (schema.sql with CREATE TABLE DDL, indexes, and constraints for Postgres/Go; schema.prisma for Prisma/TS; Postgres schema.sql as fallback) from the Gate 4 OpenAPI spec and TRD. Gate 5 of ring:planning-large-features; runs after ring:designing-api-contracts, before ring:pinning-dependency-versions. Use when the system stores persistent data. Skip for Small Track, no persistent data, or an unvalidated API contract.

Mapping how features relate and phasing the work: categorizing PRD features, grouping them into domains, charting cross-feature journeys, dependencies, and integration points, and defining the binding Phases that plan.md mirrors one-to-one at Gate 7. Gate 2 of ring:planning-large-features; runs after ring:writing-prds, before ring:writing-trds. Use for Large Track features with multiple interacting parts. Skip for Small Track or a single simple feature.

Pinning an explicit versioned dependency manifest (dependencies.md plus PROJECT_RULES.md): exact package versions, CVE and license checks, compatibility matrices, and per-component cost analysis against Ring Standards. Gate 6 of ring:planning-large-features; runs after ring:designing-data-model, before ring:writing-plans. Use when the schema is validated and you are about to lock products and versions. Skip for Small Track or when versions are already locked.

Reconciling pre-dev artifacts (research.md, prd.md, feature-map.md, trd.md, openapi.yaml, schema file, dependencies.md, plan.md) against each other to surface contradictions and gaps that break implementation, then applying approved corrections before ring:running-dev-cycle. Use after ring:planning-small-features or ring:planning-large-features. Skip for end-user docs (use ring:reviewing-docs), code review (use ring:reviewing-code), or before the docs exist.

Researching the product/feature in depth before any planning document is written: the product itself, technical approach, third-party integrations, prior art, and existing codebase grounding (file:line refs) via parallel repo/web/docs agents using firecrawl and exa. Gate 0 of ring:using-pm-team (both tracks); runs before ring:writing-prds. Use before pre-dev planning a new feature or modification. Skip for trivial changes or when a recent research.md already exists.

Routing feature planning through the ring-pm-team pre-dev workflow: choosing the Small Track (4 gates, <2 days) or Large Track (8 gates, 2+ days) and entering via ring:planning-small-features or ring:planning-large-features. Indexes pre-dev gates, standalone utilities, and research agents. Use when starting a feature that needs systematic planning. Skip for quick exploratory work, known-solution bug fixes, or trivial changes.

Validating that UX specifications are complete before technical design: a read-only checklist over wireframes, states, responsive behavior, accessibility, and component-library alignment, emitting a DESIGN VALIDATED / NEEDS REVISION verdict to design-validation.md. Standalone utility — run after a product-designer pass and before the TRD when the feature has UI; the pre-dev orchestrators recommend it when the feature has UI. Use to check UI design completeness. Skip for backend-only, API-only, or no-UI work.

Writing a Product Requirements Document that explains to the squad WHAT is being built and WHY: problem, explicit scope in/out, functional requirements, and testable acceptance criteria. Gate 1 of ring:using-pm-team; runs after ring:researching-features and stays technology-free (no architecture, frameworks, or schemas). Use when starting a new feature or asked to plan or produce requirements. Skip when a validated PRD exists, for pure technical changes, or bug fixes.

Auditing a service's production readiness against Ring engineering standards across base dimensions plus a conditional multi-tenant dimension, then emitting a scored report and an HTML dashboard. Use before production deploy, periodic review, onboarding, or a major release. Skip for prototypes, libraries, or single-dimension checks.