ring

Executing a phased plan from ring:writing-plans in rolling waves: the main agent supervises, dispatching one workflow per wave-unit (phase or epic — user's choice) that implements its tasks with TDD and signed commits via ring:committing-changes, reviews the returned work, checkpoints with the user, then elaborates the next phase against the real landed code. Use when a phased plan exists and you want session-supervised execution with a human reviewing each wave. Skip when no plan exists (use ring:writing-plans) or the full gated specialist + reviewer pool is wanted (use ring:running-dev-cycle).

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.

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.

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.

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.

Delegating tasks to Gandalf, a Lerian AI teammate reachable over Tailscale, and returning its response. Use when you need to publish an HTML/markdown report to Alfarrabio and get a URL, post a Slack notification, or ask Gandalf for business/product context via a full agent session. Tailscale-network only, no auth token. Skip when off the Tailscale network or the task can be done locally.

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).

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).

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.

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.

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.

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.

Writing a Technical Requirements Document that designs the technical architecture of the system or feature: components and boundaries, data flow, integration points, and failure modes — in technology-agnostic patterns, 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.

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.

Committing working-tree changes as atomic conventional commits: analyzes the diff, groups it into coherent commits, confirms the plan, then creates GPG-signed commits carrying the mandatory X-Lerian-Ref trailer and offers to push. Use when the user says 'commit' or has changes ready to record. Skip when the tree is clean, work is still in progress, or the user wants raw git commands without grouping.

Creating a handoff document that captures session state (completed work, decisions, open items, next steps) and delivering it via Plan Mode so the user gets the native 'clear context and continue implementing' resume option. Use when ending a session, when context grows large, or the user says 'handoff', 'save session', or 'context transfer'. Skip when context is minimal or work is fully complete with no resume planned.

Creating an isolated git worktree for parallel branch work: selects the directory by priority order, verifies/adds .gitignore safety, auto-installs the detected toolchain's dependencies, runs a baseline test, and reports readiness. Use before a feature that needs isolation from the main workspace or before executing an implementation plan. Skip for a quick fix on the current branch or when already in the feature's worktree.

Exploring a codebase across phases: scopes the target, detects architecture, components, and layers, deep-dives each discovered perspective, then synthesizes findings into actionable guidance with file:line evidence. Use to understand how a feature or system works before planning changes, or to orient on an unfamiliar codebase. Skip for a single signature lookup, a file-exists check, or reading an error from a known file.

Fixing lint to a clean state: runs the linter, groups reported issues into independent streams, and dispatches one parallel fixer agent per stream (ring:backend-go for Go, ring:general-purpose otherwise), iterating until clean. Use when a codebase has lint errors across multiple files. Skip for a single error (fix directly), already-passing lint, or view-only requests; security lints are reported, not auto-fixed.

Generating an internal Operations-facing update/migration guide from the git diff between two refs, documenting per-change client impact, deploy ordering, monitoring, and rollback notes in English, pt-br, or both. Use when preparing a version release or recording what changed for the Ops team. Runs read-only by default and previews before writing. Skip with no git repo or a trivial single-file change.

Reviewing code by dispatching the default reviewer subagents in parallel (plus conditional specialists for lib-observability, lib-systemplane, or lib-streaming when the diff triggers them), then aggregating findings by severity into a report. Use as Gate 8 of ring:running-dev-cycle at epic cadence over the cumulative diff, or before merging. Report-only. Skip for a single-command Go pre-merge verdict (use ring:verifying-code).

Enforcing the RED-GREEN-REFACTOR loop: write one failing test and watch it fail, write minimal code to pass, then refactor green. Use when starting implementation of a new feature or bugfix, or writing any new production code. Requires pasted failure output as proof of RED; code written before its test must be deleted, not stashed. Skip for exploratory spikes or when only modifying existing tests.

Hardening a skill so it resists rationalization under pressure: run combined-pressure scenarios on a subagent without the skill (RED), capture excuses verbatim, write/edit the skill (GREEN), then plug loopholes (REFACTOR) until compliance holds. Use when deploying or editing a discipline-enforcing skill that an agent could rationalize away. Skip for pure reference skills with no rules to violate.

Enforcing Ring's orchestrator protocol every conversation: dispatch specialist/Explore agents instead of operating tools directly, honor the >3-file hard gate, and run skill discovery before any task. Use at conversation start, before any task, when a request matches auto-trigger phrases (fix issues, refactor, find where, visualize), or when tempted to read/edit files directly. Never skip — mandatory.

Generating self-contained, Lerian-branded HTML artifacts — Mermaid diagrams, comparison tables/matrices, code diffs, dashboards, 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, or visual diff/plan/review output. Skip for simple tables that fit the terminal, mermaid.live links, or text-only answers.

Writing or editing a Ring skill: SKILL.md structure, frontmatter and Agent-Search-Optimization rules, token-efficiency targets, and bulletproofing (Iron Law, rationalization tables, Red Flags) so discipline-enforcing skills resist excuses. Use when creating or revising a skill. Delegates pressure-testing to ring:testing-skills-with-subagents. Skip for pure reference skills with no rules, or project conventions (put those in CLAUDE.md).

Adding database-per-tenant isolation into a Go service end-to-end via an 11-gate cycle: detects the stack, audits compliance, then dispatches backend agents to implement tenantId-from-JWT routing through the lib-commons v5 dispatch layer (config, middleware, repositories, metrics, tests) and runs reviewers. Use when adding tenant isolation to a Go service. Skip for non-Go services or organization_id-style soft tenancy.

Applying or switching a repository's license (Apache 2.0, Elastic License v2, or Lerian 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.

Auditing a dependency for supply-chain risk before install (pip/npm/go/cargo): checks typosquatting, maintainer/age risk, vulnerability DBs (OSV, GHSA, Socket), and lockfile hash pinning, then emits a risk score and approve/conditional/escalate/block decision. Use when adding or updating a dependency, reviewing a dependency PR, or investigating a compromise. Skip when no new dependency is involved or it is already vetted.