Proven engineering practices, enforced through skills.
Ring is a comprehensive skills library and workflow system for AI agents that transforms how AI assistants approach software development. Currently implemented as a Claude Code plugin marketplace with 4 active plugins and 69 skills (see .claude-plugin/marketplace.json for current versions), the skills themselves are agent-agnostic and can be used with any AI agent system. Ring provides battle-tested patterns, mandatory workflows, and systematic approaches across the entire software delivery value chain.
Without Ring, AI assistants often:
- Skip tests and jump straight to implementation
- Make changes without understanding root causes
- Claim tasks are complete without verification
- Forget to check for existing solutions
- Repeat known mistakes
Ring solves this by:
- Enforcing proven workflows - Test-driven development, systematic debugging, proper planning
- Providing 69 specialized skills (14 core + 31 dev-team + 18 product planning + 6 technical writing)
- 32 specialized agents - 10 review/planning + 15 developer + 4 product research + 3 technical writing
- Automating skill discovery - Skills load automatically at session start
- Preventing common failures - Built-in anti-patterns and mandatory checklists
Ring is Lerian-first, open-source-friendly. Design decisions prioritize the Lerian engineering team's daily needs while keeping the architecture clean and reusable for external adoption. This means:
- Lerian-specific skills stay active — Internal integrations and domain-specific workflows remain in the marketplace because the team uses them
- The architecture is universal — Skills, agents, and the plugin system work with any codebase or team
- Archival is usage-driven — Skills are archived when they stop being used, not because they're "too specific"
Review & Planning Agents (default plugin):
ring:code-reviewer- Foundation review (architecture, code quality, design patterns)ring:business-logic-reviewer- Correctness review (domain logic, requirements, edge cases)ring:security-reviewer- Safety review (vulnerabilities, OWASP, authentication)ring:test-reviewer- Test quality review (coverage, edge cases, assertions, test anti-patterns)ring:nil-safety-reviewer- Nil/null safety review (traces pointer risks, missing guards, panic paths)ring:consequences-reviewer- Ripple effect review (traces how changes propagate beyond modified files - caller chains, consumer contracts, downstream breakage)ring:dead-code-reviewer- Dead code review (orphaned code detection, reachability analysis, dead dependency chains)ring:review-slicer- Review slicer (groups large multi-themed PRs into thematic slices for focused parallel review)ring:write-plan- Implementation planning agentring:codebase-explorer- Deep architecture analysis (deep-analysis, complements built-in Explore)- Use
ring:codereviewskill to orchestrate parallel review workflow
Developer Agents (dev-team plugin):
ring:backend-engineer-golang- Go backend specialist for financial systemsring:backend-engineer-typescript- TypeScript/Node.js backend specialist (Express, NestJS, Fastify)ring:frontend-bff-engineer-typescript- BFF & React/Next.js frontend with Clean Architecturering:frontend-designer- Visual design specialistring:frontend-engineer- Senior Frontend Engineer (React/Next.js)ring:devops-engineer- DevOps and infrastructure specialistring:prompt-quality-reviewer- Agent Quality Analystring:qa-analyst- Backend QA specialist (unit, integration, load, chaos)ring:qa-analyst-frontend- Frontend QA specialist (accessibility, visual, E2E, performance)ring:sre- Observability and reliability specialistring:ui-engineer- UI component specialist (design systems, accessibility)ring:helm-engineer- Helm chart specialist (chart structure, security, Lerian conventions)ring:lib-commons-reviewer- lib-commons usage review (correct API usage, reinvented-wheel opportunities across 35+ packages)ring:multi-tenant-reviewer- Multi-tenant usage review (lib-commons/multitenancy patterns, tenant isolation, JWT tenantId propagation)ring:performance-reviewer- Performance review (code hotspots, infra misconfigurations, Go/TypeScript/Python)
Standards Compliance: Refactor-capable dev-team agents produce a
## Standards Complianceoutput section with conditional requirement:
- Optional when invoked directly or via
ring:dev-cycle- MANDATORY when invoked from
ring:dev-refactor(triggered by**MODE: ANALYSIS ONLY**in prompt)When mandatory, agents load Ring standards via WebFetch and produce comparison tables with:
- Current Pattern vs Expected Pattern
- Severity classification (Critical/High/Medium/Low)
- File locations and migration recommendations
See
dev-team/docs/standards/*.mdfor standards source. Cross-references: CLAUDE.md (Standards Compliance section),dev-team/skills/dev-refactor/SKILL.md
Product Research Agents (ring-pm-team plugin):
ring:repo-research-analyst- Repository structure and codebase analysisring:best-practices-researcher- Industry best practices researchring:framework-docs-researcher- Framework documentation researchring:product-designer- Product design and UX research
Technical Writing Agents (ring-tw-team plugin):
ring:functional-writer- Functional documentation (guides, tutorials, conceptual docs)ring:api-writer- API reference documentation (endpoints, schemas, examples)ring:docs-reviewer- Documentation quality review (voice, tone, structure, completeness)
Plugin versions are managed in .claude-plugin/marketplace.json
The following plugins have been archived and are not actively maintained. They remain available in .archive/ for reference:
| Plugin | Description | Status |
|---|---|---|
pmm-team |
Product Marketing (GTM, positioning, competitive intel) | Archived - functionality may be restored based on demand |
finance-team |
Financial planning and analysis | Archived - under evaluation |
ops-team |
Operations management | Archived - under evaluation |
To restore an archived plugin, move its folder from .archive/ to the root directory and register it in marketplace.json.
Ring works across multiple AI development platforms:
| Platform | Format | Status | Features |
|---|---|---|---|
| Claude Code | Native | ✅ Source of truth | Skills, agents, hooks |
| Factory AI | Transformed | ✅ Supported | Droids, skills |
| Cursor | Transformed | ✅ Supported | Skills, agents |
| Cline | Transformed | ✅ Supported | Prompts |
Transformation Notes:
- Claude Code receives Ring content in its native format
- Factory AI:
agents→droidsterminology - Cursor: Skills → ~/.cursor/skills/, Agents → ~/.cursor/agents/
- Cline: All content → structured prompts
Platform-Specific Guides:
See the installer README for platform-specific setup and transformation details.
The Ring installer automatically detects installed platforms and transforms content appropriately.
Linux/macOS/Git Bash:
# Interactive installer (auto-detects platforms)
curl -fsSL https://raw.githubusercontent.com/lerianstudio/ring/main/install-ring.sh | bash
# Or clone and run locally
git clone https://github.com/lerianstudio/ring.git ~/ring
cd ~/ring
./installer/install-ring.shWindows PowerShell:
# Interactive installer (auto-detects platforms)
irm https://raw.githubusercontent.com/lerianstudio/ring/main/install-ring.ps1 | iex
# Or clone and run locally
git clone https://github.com/lerianstudio/ring.git $HOME\ring
cd $HOME\ring
.\installer\install-ring.ps1Install to specific platforms without the interactive menu:
# Install to Claude Code only (native format)
./installer/install-ring.sh install --platforms claude
# Install to Factory AI only (droids format)
./installer/install-ring.sh install --platforms factory
# Install to multiple platforms
./installer/install-ring.sh install --platforms claude,cursor,cline
# Install to all detected platforms
./installer/install-ring.sh install --platforms auto
# Dry run (preview changes without installing)
./installer/install-ring.sh install --platforms auto --dry-run# List installed platforms and versions
./installer/install-ring.sh list
# Update existing installation
./installer/install-ring.sh update
# Check for available updates
./installer/install-ring.sh check
# Sync (update only changed files)
./installer/install-ring.sh sync
# Uninstall from specific platform
./installer/install-ring.sh uninstall --platforms cursor
# Detect available platforms
./installer/install-ring.sh detectFor Claude Code users, you can also install from the marketplace:
- Open Claude Code
- Go to Settings → Plugins
- Search for "ring"
- Click Install
# Clone the marketplace repository
git clone https://github.com/lerianstudio/ring.git ~/ring
# Skills auto-load at session start via hooks
# No additional configuration needed for Claude CodeThe codereview pipeline uses Mithril, an external code analysis tool installed via go install. Mithril performs static analysis, AST extraction, call graph generation, and context compilation for AI-assisted code review.
Install via go install github.com/lerianstudio/mithril@latest. See the Mithril repository for full installation details and release notes.
When you start a new Claude Code session with Ring installed, you'll see:
## Available Skills:
- ring:using-ring (Check for skills BEFORE any task)
- ring:test-driven-development (RED-GREEN-REFACTOR cycle)
- ring:codereview (Parallel 10-reviewer dispatch)
- ring:explore-codebase (Two-phase codebase exploration)
... and 65 more skills
Before ANY action → Check skills
Before ANY tool → Check skills
Before ANY code → Check skills
RED → Write failing test → Watch it fail
GREEN → Minimal code → Watch it pass
REFACTOR → Clean up → Stay green
Testing & Quality (2):
ring:test-driven-development- Write test first, watch fail, minimal codering:lint- Parallel lint fixing with agent dispatch
Collaboration & Planning (3):
ring:codereview- Parallel 10-reviewer dispatch with severity-based handlingring:worktree- Isolated developmentring:commit- Smart commit organization with atomic grouping, conventional commits, and trailers
Meta Skills (3):
ring:using-ring- Mandatory skill discoveryring:writing-skills- TDD for documentationring:testing-skills-with-subagents- Skill validation
Integration (1):
ring:gandalf-webhook- Send tasks to Gandalf (AI team member) via webhook for Slack, Google Workspace, and Jira interactions
Session & Learning (4):
ring:explore-codebase- Two-phase codebase explorationring:release-guide- Generate Ops Update Guide from git diff analysisring:visualize- Generate self-contained HTML pages to visually explain systems, code changes, and dataring:create-handoff- Create handoff documents capturing session state for seamless context-clear and resume
Audit & Readiness (1):
ring:production-readiness-audit- 44-dimension production readiness audit; runs explorers in batches of up to 10, appends incrementally to a single report; output: scored report (0-430, max 440 with multi-tenant) with severity ratings. See default/skills/production-readiness-audit/SKILL.md for invocation and implementation details.
Orchestration & Refactoring (7):
ring:using-dev-team- Introduction to developer specialist agentsring:dev-cycle- Lean backend development workflow orchestrator: Gate 0 implementation-owned TDD/coverage/docker-compose/runtime/delivery verification, Gate 8 review, Gate 9 validationring:dev-cycle-frontend- 9-gate frontend development workflow orchestratorring:dev-refactor- Backend/codebase standards analysisring:dev-refactor-frontend- Frontend standards analysis and task generationring:dev-simplify- Whole-codebase structural simplification sweep (hunts unjustified abstractions, adapters, shims; KILL/REVIEW/KEEP output; DELETE-by-default burden of proof for pre-public applications)ring:dev-cycle-management- Development cycle state management (status reporting and cancellation)
Backend Gate Skills:
ring:dev-implementation- Gate 0: TDD implementationring:dev-multi-tenant- Multi-tenant adaptation (database-per-tenant isolation, integrated into Gate 0)ring:dev-docker-security- Docker image security audit for Docker Hub Health Score grade Aring:dev-helm- Helm chart creation and maintenance following Lerian conventionsring:dev-service-discovery- Service/module/resource hierarchy scanner for dispatch layerring:dev-readyz- Comprehensive readiness probes (/readyz) with per-dependency status and TLS validationring:dev-streaming-instrumentation- Wire lib-streaming event emission from a validated instrumentation map
Deprecated Skills (Reference Only):
ring:dev-delivery-verification- DEPRECATED: delivery verification merged into ring:dev-implementation Step 7 (Gate 0 exit criterion). Skill preserved for reference only.
Testing & Validation:
ring:dev-goroutine-leak-testing- Goroutine leak detection and regression testingring:dev-k6-load-testing- k6 load test generation following Lerian platform conventionsring:dev-validation- Gate 9: User approvalring:dev-report- Assertiveness scoring and metricsring:dev-verify-code- Atomic Go code verification with MERGE_READY/NEEDS_FIX verdict
Migration & Reference (6):
ring:using-lib-commons- Comprehensive reference for lib-commons v5.0.2 (Lerian's shared Go library with 30+ packages)ring:using-runtime- Deep reference and 6-angle audit for commons/runtime: SafeGo, panic recovery, observability trident, policy selection, framework integration. Catches naked goroutine launches that cause silent production failures.ring:using-assert- Deep reference and 6-angle audit for commons/assert: production runtime assertions with observability trident, full domain predicate catalog (double-entry, transaction state machine, financial validations), AssertionError unwrapping patterns. Converts financial invariants into production-enforced rules.ring:dev-systemplane-migration- Migrate Lerian Go services from .env/YAML config to systemplane (database-backed hot-reloadable config)ring:dev-llms-txt- Generate or audit llms.txt files following llmstxt.org spec for AI-friendly repository entry pointsring:dev-licensing- Repository license management (Apache 2.0, Elastic v2, Proprietary)
Security (1):
ring:dev-dep-security-check- Supply-chain gate for dependency installations (validates identity, vulnerabilities, suspicious signals)
Frontend Gate Skills (4):
ring:dev-frontend-accessibility- Frontend accessibility validation gatering:dev-frontend-visual- Visual regression and UI quality gatering:dev-frontend-e2e- End-to-end testing gatering:dev-frontend-performance- Frontend performance validation gate
Frontend and backend dev-cycle workflows both use
ring:codereview(core plugin) as the review gate.
Pre-Development Workflow (includes ring:using-pm-team + 9 gates):
ring:using-pm-team- Introduction to product planning workflow
ring:pre-dev-research- Research phase (parallel agents)ring:pre-dev-prd-creation- Business requirements (WHAT/WHY)ring:pre-dev-feature-map- Feature relationshipsring:pre-dev-trd-creation- Technical architecture (HOW)ring:pre-dev-api-design- Component contractsring:pre-dev-data-model- Entity relationshipsring:pre-dev-dependency-map- Technology selectionring:pre-dev-task-breakdown- Work incrementsring:pre-dev-subtask-creation- Atomic units
Workflow Orchestrators:
ring:pre-dev-feature- 5-gate orchestrator for small features (<2 days)ring:pre-dev-full- 10-gate orchestrator for large features (>=2 days)
Additional Planning Skills:
ring:pre-dev-design-validation- Gate 1.5/2.5: Design validation for UI featuresring:pre-dev-delivery-planning- Gate 4 (Small) / Gate 9 (Large): Delivery roadmap and timelinering:delivery-status- Delivery progress tracking against roadmapring:deep-doc-review- Deep cross-reference review of pre-dev documentation artifacts
Documentation Creation:
ring:using-tw-team- Introduction to technical writing specialistsring:write-guide- Patterns for guides, tutorials, conceptual docsring:write-api- API reference documentation patternsring:documentation-structure- Document hierarchy and organizationring:voice-and-tone- Voice and tone guidelines (assertive, encouraging, human)ring:review-docs- Quality checklist and review process
User: "Add user authentication to the app"
Claude: I'm using ring:pre-dev-feature to scope this feature...
[Pre-dev workflow: PRD, TRD, tasks]
Claude: I'm using ring:test-driven-development to implement...
[RED-GREEN-REFACTOR cycle for each component]
Claude: I'm using ring:codereview to validate...
[10-reviewer parallel dispatch]
User: "The app crashes when clicking submit"
Claude: Investigating the crash:
Phase 1: [Gathering evidence]
Phase 2: [Pattern analysis]
Phase 3: [Hypothesis testing]
Phase 4: [Implementing fix with test]
User: "Plan an e-commerce platform"
Claude: I'll use the pre-dev workflow to plan this systematically...
Gate 1: PRD Creation [Business requirements]
Gate 2: Feature Map [Domain groupings]
Gate 3: TRD Creation [Architecture patterns]
... [Through all 10 gates]
User: "Review my authentication implementation"
Claude: Dispatching all 10 reviewers in parallel...
[Launches ring:code-reviewer, ring:business-logic-reviewer, ring:security-reviewer,
ring:test-reviewer, ring:nil-safety-reviewer, ring:consequences-reviewer,
ring:dead-code-reviewer, ring:performance-reviewer, ring:multi-tenant-reviewer,
ring:lib-commons-reviewer simultaneously]
Code reviewer: PASS. Clean architecture, good tests.
Business reviewer: FAIL. Missing password reset flow (HIGH severity).
Security reviewer: FAIL. JWT secret hardcoded (CRITICAL severity).
Test reviewer: PASS. Good coverage, assertions well-structured.
Nil-safety reviewer: PASS. No unguarded nil dereferences found.
Consequences reviewer: PASS. No downstream breakage detected.
Performance reviewer: PASS. No hotspots or goroutine leaks found.
Multi-tenant reviewer: PASS. No multi-tenant code in scope.
lib-commons reviewer: PASS. Correct usage of lib-commons/resilience, no reinvented wheels detected.
Aggregating issues by severity:
- CRITICAL: JWT secret hardcoded in auth.ts:42
- HIGH: Password reset flow missing from requirements
Dispatching fix subagent to address Critical/High issues...
[Fixes applied]
Re-running all 10 reviewers in parallel...
All reviewers: PASS. Ready for production.
Key benefits:
- All reviewers run simultaneously (not sequential)
- Comprehensive - Get all feedback at once, easier to prioritize
- Tech debt tracking - Low/Cosmetic issues tracked with TODO/FIXME comments in code
- Model-specific - All reviewers run on for deep analysis
Monorepo Marketplace - Multiple specialized plugin collections:
ring/ # Monorepo root
├── .claude-plugin/
│ └── marketplace.json # Multi-plugin marketplace config (4 active plugins)
├── default/ # Core Ring plugin (ring-default)
│ ├── skills/ # 14 core skills
│ │ ├── skill-name/
│ │ │ └── SKILL.md # Skill definition with frontmatter
│ │ └── shared-patterns/ # Universal patterns (15 patterns)
│ ├── hooks/ # Session initialization
│ │ ├── hooks.json # Hook configuration
│ │ ├── session-start.sh # Loads skills at startup
│ │ └── generate-skills-ref.py # Auto-generates quick reference
│ ├── agents/ # 10 specialized agents
│ │ ├── code-reviewer.md # Foundation review (`ring:code-reviewer`)
│ │ ├── business-logic-reviewer.md # Correctness review (`ring:business-logic-reviewer`)
│ │ ├── security-reviewer.md # Safety review (`ring:security-reviewer`)
│ │ ├── test-reviewer.md # Test quality review (`ring:test-reviewer`)
│ │ ├── nil-safety-reviewer.md # Nil/null safety review (`ring:nil-safety-reviewer`)
│ │ ├── consequences-reviewer.md # Ripple effect review (`ring:consequences-reviewer`)
│ │ ├── dead-code-reviewer.md # Dead code analysis (`ring:dead-code-reviewer`)
│ │ ├── review-slicer.md # Review slicing for large PRs (`ring:review-slicer`)
│ │ ├── write-plan.md # Implementation planning (`ring:write-plan`)
│ │ └── codebase-explorer.md # Deep architecture analysis (`ring:codebase-explorer`)
│ └── docs/ # Documentation
├── dev-team/ # Developer Agents plugin (ring-dev-team) - 31 skills, 15 agents
│ └── agents/ # 15 specialized developer agents
│ ├── backend-engineer-golang.md # Go backend specialist (`ring:backend-engineer-golang`)
│ ├── backend-engineer-typescript.md # TypeScript/Node.js backend specialist (`ring:backend-engineer-typescript`)
│ ├── frontend-bff-engineer-typescript.md # BFF & React/Next.js specialist (`ring:frontend-bff-engineer-typescript`)
│ ├── devops-engineer.md # DevOps and infrastructure specialist (`ring:devops-engineer`)
│ ├── frontend-designer.md # Visual design specialist (`ring:frontend-designer`)
│ ├── frontend-engineer.md # Frontend engineer (`ring:frontend-engineer`)
│ ├── helm-engineer.md # Helm chart specialist (`ring:helm-engineer`)
│ ├── lib-commons-reviewer.md # lib-commons usage review (`ring:lib-commons-reviewer`)
│ ├── multi-tenant-reviewer.md # Multi-tenant usage review (`ring:multi-tenant-reviewer`)
│ ├── performance-reviewer.md # Performance review (`ring:performance-reviewer`)
│ ├── prompt-quality-reviewer.md # Agent quality reviewer (`ring:prompt-quality-reviewer`)
│ ├── qa-analyst.md # Backend QA specialist (`ring:qa-analyst`)
│ ├── qa-analyst-frontend.md # Frontend QA specialist (`ring:qa-analyst-frontend`)
│ ├── sre.md # Observability and reliability specialist (`ring:sre`)
│ └── ui-engineer.md # UI component specialist (`ring:ui-engineer`)
├── pm-team/ # Product Planning plugin (ring-pm-team)
│ └── skills/ # 18 product planning skills
│ └── pre-dev-*/ # PRD, TRD, API, Data, Tasks
└── tw-team/ # Technical Writing plugin (ring-tw-team)
├── skills/ # 6 documentation skills
├── agents/ # 3 technical writing agents
└── hooks/ # SessionStart hook
For core Ring skills:
-
Create the skill directory
mkdir default/skills/your-skill-name
-
Write SKILL.md with frontmatter
--- name: ring:your-skill-name description: Single paragraph (≤500 chars target, 1,536 cap). States WHAT the skill does, WHEN to invoke, and WHEN to skip. --- # Your Skill Name ## When to use - Specific condition that mandates this skill - Another trigger condition ## Skip when - When NOT to use → alternative skill - Another exclusion
Schema fields:
- Required:
name(must usering:prefix),description - Optional:
argument-hint,allowed-tools,model,disable-model-invocation,user-invocable,paths - Trigger / skip / sequence / related content lives in body H2 sections (
## When to use,## Skip when,## Sequence,## Related). See docs/FRONTMATTER_SCHEMA.md for the canonical schema.
- Required:
-
Update documentation
- Skills auto-load via
default/hooks/generate-skills-ref.py - Test with session start hook
- Skills auto-load via
-
Submit PR
git checkout -b feat/your-skill-name git add default/skills/your-skill-name git commit -m "feat(skills): add your-skill-name for X" gh pr create
For product/team-specific skills:
-
Create plugin structure
mkdir -p product-xyz/{skills,agents,hooks,lib} -
Register in marketplace Edit
.claude-plugin/marketplace.json:{ "name": "ring-product-xyz", "description": "Product XYZ specific skills", "version": "0.1.0", "source": "./product-xyz", "homepage": "https://github.com/lerianstudio/ring/tree/product-xyz" } -
Follow core plugin structure
- Use same layout as
default/ - Create
product-xyz/hooks/hooks.jsonfor initialization - Add skills to
product-xyz/skills/
- Use same layout as
- Mandatory sections: When to use, How to use, Anti-patterns
- Include checklists: TodoWrite-compatible task lists
- Evidence-based: Require verification before claims
- Battle-tested: Based on real-world experience
- Clear triggers: Unambiguous "when to use" conditions
- Skills Quick Reference - Auto-generated at session start from skill frontmatter
- CLAUDE.md - Repository guide for Claude Code
- MANUAL.md - Quick reference for all skills, agents, and workflows
- ARCHITECTURE.md - Architecture diagrams and component relationships
- Installer - Multi-platform installation and migration
Ring embodies these principles:
- Skills are mandatory, not optional - If a skill applies, it MUST be used
- Evidence over assumptions - Prove it works, don't assume
- Process prevents problems - Following workflows prevents known failures
- Small steps, verified often - Incremental progress with continuous validation
- Learn from failure - Anti-patterns document what doesn't work
Teams using Ring report:
- 90% reduction in "works on my machine" issues
- 75% fewer bugs reaching production
- 60% faster debugging cycles
- 100% of code covered by tests (enforced by TDD)
Ring is built on decades of collective software engineering wisdom, incorporating patterns from:
- Extreme Programming (XP)
- Test-Driven Development (TDD)
- Domain-Driven Design (DDD)
- Agile methodologies
- DevOps practices
Special thanks to the Lerian Team for battle-testing these skills in production.
MIT - See LICENSE file
Remember: If a skill applies to your task, you MUST use it. This is not optional.
