mirror of
https://github.com/LerianStudio/ring
synced 2026-04-21 13:37:27 +00:00
c1d4fe6d45
Introduces a new parallel reviewer, `ring:dead-code-reviewer`, to systematically identify orphaned code resulting from changes. This enhances codebase hygiene by detecting unused helpers, types, and tests, thereby reducing technical debt and improving maintainability. The parallel code review system is expanded from 6 to 7 concurrent reviewers. All related workflows, skills, commands, and documentation have been updated to integrate this new capability. - Add the `ring:dead-code-reviewer` agent, which analyzes code across three concentric rings (target, direct dependents, ripple effect) to find unreachable code. - Update the `/ring:codereview` command and `ring:requesting-code-review` skill to dispatch all 7 reviewers in a single parallel step. - Adjust project documentation, including architecture diagrams, manuals, and agent guides, to reflect the 7-reviewer workflow.
274 lines
8.1 KiB
Markdown
274 lines
8.1 KiB
Markdown
# Agent Design Reference
|
|
|
|
This document contains agent output schema archetypes and standards compliance requirements for Ring agents.
|
|
|
|
---
|
|
|
|
## Agent Output Schema Archetypes
|
|
|
|
Agents use standard output schema patterns based on their purpose:
|
|
|
|
### Implementation Schema
|
|
|
|
**For agents that write code/configs:**
|
|
|
|
```yaml
|
|
output_schema:
|
|
format: "markdown"
|
|
required_sections:
|
|
- name: "Summary"
|
|
pattern: "^## Summary"
|
|
required: true
|
|
- name: "Implementation"
|
|
pattern: "^## Implementation"
|
|
required: true
|
|
- name: "Files Changed"
|
|
pattern: "^## Files Changed"
|
|
required: true
|
|
- name: "Testing"
|
|
pattern: "^## Testing"
|
|
required: true
|
|
- name: "Next Steps"
|
|
pattern: "^## Next Steps"
|
|
required: true
|
|
```
|
|
|
|
**Used by:** `ring:backend-engineer-golang`, `ring:backend-engineer-typescript`, `frontend-bff-engineer-typescript`, `ring:devops-engineer`, `ring:qa-analyst`, `ring:sre`, `finops-automation`
|
|
|
|
---
|
|
|
|
### Analysis Schema
|
|
|
|
**For agents that analyze and recommend:**
|
|
|
|
```yaml
|
|
output_schema:
|
|
format: "markdown"
|
|
required_sections:
|
|
- name: "Analysis"
|
|
pattern: "^## Analysis"
|
|
required: true
|
|
- name: "Findings"
|
|
pattern: "^## Findings"
|
|
required: true
|
|
- name: "Recommendations"
|
|
pattern: "^## Recommendations"
|
|
required: true
|
|
- name: "Next Steps"
|
|
pattern: "^## Next Steps"
|
|
required: true
|
|
```
|
|
|
|
**Used by:** `ring:frontend-designer`, `finops-analyzer`
|
|
|
|
---
|
|
|
|
### Reviewer Schema
|
|
|
|
**For code review agents:**
|
|
|
|
```yaml
|
|
output_schema:
|
|
format: "markdown"
|
|
required_sections:
|
|
- name: "VERDICT"
|
|
pattern: "^## VERDICT: (PASS|FAIL|NEEDS_DISCUSSION)$"
|
|
required: true
|
|
- name: "Summary"
|
|
pattern: "^## Summary"
|
|
required: true
|
|
- name: "Issues Found"
|
|
pattern: "^## Issues Found"
|
|
required: true
|
|
- name: "Categorized Issues"
|
|
pattern: "^### (Critical|High|Medium|Low)"
|
|
required: false
|
|
- name: "What Was Done Well"
|
|
pattern: "^## What Was Done Well"
|
|
required: true
|
|
- name: "Next Steps"
|
|
pattern: "^## Next Steps"
|
|
required: true
|
|
```
|
|
|
|
**Used by:** `ring:code-reviewer`, `ring:business-logic-reviewer`, `ring:security-reviewer`, `ring:dead-code-reviewer`
|
|
|
|
**Note:** `ring:business-logic-reviewer` and `ring:security-reviewer` extend the base Reviewer Schema with additional domain-specific required sections:
|
|
- `ring:business-logic-reviewer` adds: "Mental Execution Analysis", "Business Requirements Coverage", "Edge Cases Analysis"
|
|
- `ring:security-reviewer` adds: "OWASP Top 10 Coverage", "Compliance Status"
|
|
|
|
---
|
|
|
|
### Exploration Schema
|
|
|
|
**For deep codebase analysis:**
|
|
|
|
```yaml
|
|
output_schema:
|
|
format: "markdown"
|
|
required_sections:
|
|
- name: "EXPLORATION SUMMARY"
|
|
pattern: "^## EXPLORATION SUMMARY$"
|
|
required: true
|
|
- name: "KEY FINDINGS"
|
|
pattern: "^## KEY FINDINGS$"
|
|
required: true
|
|
- name: "ARCHITECTURE INSIGHTS"
|
|
pattern: "^## ARCHITECTURE INSIGHTS$"
|
|
required: true
|
|
- name: "RELEVANT FILES"
|
|
pattern: "^## RELEVANT FILES$"
|
|
required: true
|
|
- name: "RECOMMENDATIONS"
|
|
pattern: "^## RECOMMENDATIONS$"
|
|
required: true
|
|
```
|
|
|
|
**Used by:** `ring:codebase-explorer`
|
|
|
|
---
|
|
|
|
### Planning Schema
|
|
|
|
**For implementation planning:**
|
|
|
|
```yaml
|
|
output_schema:
|
|
format: "markdown"
|
|
required_sections:
|
|
- name: "Goal"
|
|
pattern: "^\\*\\*Goal:\\*\\*"
|
|
required: true
|
|
- name: "Architecture"
|
|
pattern: "^\\*\\*Architecture:\\*\\*"
|
|
required: true
|
|
- name: "Tech Stack"
|
|
pattern: "^\\*\\*Tech Stack:\\*\\*"
|
|
required: true
|
|
- name: "Global Prerequisites"
|
|
pattern: "^\\*\\*Global Prerequisites:\\*\\*"
|
|
required: true
|
|
- name: "Task"
|
|
pattern: "^### Task \\d+:"
|
|
required: true
|
|
```
|
|
|
|
**Used by:** `ring:write-plan`
|
|
|
|
---
|
|
|
|
## Standards Compliance (Conditional Output Section)
|
|
|
|
The `ring-dev-team` agents include a **Standards Compliance** output section that is conditionally required based on invocation context.
|
|
|
|
### Schema Definition
|
|
|
|
All ring-dev-team agents include this in their `output_schema`:
|
|
|
|
```yaml
|
|
- name: "Standards Compliance"
|
|
pattern: "^## Standards Compliance"
|
|
required: false # In schema, but MANDATORY when invoked from ring:dev-refactor
|
|
description: "Comparison of codebase against Lerian/Ring standards. MANDATORY when invoked from ring:dev-refactor skill."
|
|
```
|
|
|
|
### Conditional Requirement: `invoked_from_dev_refactor`
|
|
|
|
| Context | Standards Compliance Required | Enforcement |
|
|
|---------|------------------------------|-------------|
|
|
| Direct agent invocation | Optional | Agent may include if relevant |
|
|
| Via `ring:dev-cycle` | Optional | Agent may include if relevant |
|
|
| Via `ring:dev-refactor` | **MANDATORY** | Prompt includes `MODE: ANALYSIS ONLY` |
|
|
|
|
**How It's Triggered:**
|
|
1. User invokes `/ring:dev-refactor` command
|
|
2. The skill dispatches agents with prompts starting with `**MODE: ANALYSIS ONLY**`
|
|
3. This prompt pattern signals to agents that Standards Compliance output is MANDATORY
|
|
4. Agents load Ring standards via WebFetch and produce comparison tables
|
|
|
|
**Detection in Agent Prompts:**
|
|
```text
|
|
If prompt contains "**MODE: ANALYSIS ONLY**":
|
|
→ Standards Compliance section is MANDATORY
|
|
→ Agent MUST load Ring standards via WebFetch
|
|
→ Agent MUST produce comparison tables
|
|
|
|
If prompt does NOT contain "**MODE: ANALYSIS ONLY**":
|
|
→ Standards Compliance section is optional
|
|
→ Agent focuses on implementation/other tasks
|
|
```
|
|
|
|
### Affected Agents
|
|
|
|
All ring-dev-team agents support Standards Compliance:
|
|
|
|
| Agent | Standards Source | Categories Checked |
|
|
|-------|------------------|-------------------|
|
|
| `ring:backend-engineer-golang` | `golang.md` | lib-commons, Error Handling, Logging, Config |
|
|
| `ring:backend-engineer-typescript` | `typescript.md` | Type Safety, Error Handling, Validation |
|
|
| `ring:devops-engineer` | `devops.md` | Dockerfile, docker-compose, CI/CD |
|
|
| `frontend-bff-engineer-typescript` | `frontend.md` | Component patterns, State management |
|
|
| `ring:frontend-designer` | `frontend.md` | Accessibility, Design patterns |
|
|
| `ring:qa-analyst` | `qa.md` | Test coverage, Test patterns |
|
|
| `ring:sre` | `sre.md` | Health endpoints, Logging, Tracing |
|
|
|
|
### Output Format Examples
|
|
|
|
**When ALL categories are compliant:**
|
|
```markdown
|
|
## Standards Compliance
|
|
|
|
Fully Compliant - Codebase follows all Lerian/Ring Standards.
|
|
|
|
No migration actions required.
|
|
```
|
|
|
|
**When ANY category is non-compliant:**
|
|
```markdown
|
|
## Standards Compliance
|
|
|
|
### Lerian/Ring Standards Comparison
|
|
|
|
| Category | Current Pattern | Expected Pattern | Status | File/Location |
|
|
|----------|----------------|------------------|--------|---------------|
|
|
| Error Handling | Using panic() | Return error | Non-Compliant | handler.go:45 |
|
|
| Logging | Uses fmt.Println | lib-commons/zap | Non-Compliant | service/*.go |
|
|
| Config | os.Getenv direct | SetConfigFromEnvVars() | Non-Compliant | config.go:15 |
|
|
|
|
### Compliance Summary
|
|
- **Total Violations:** 3
|
|
- **Critical:** 0
|
|
- **High:** 1
|
|
- **Medium:** 2
|
|
- **Low:** 0
|
|
|
|
### Required Changes for Compliance
|
|
|
|
1. **Error Handling Migration**
|
|
- Replace: `panic("error message")`
|
|
- With: `return fmt.Errorf("context: %w", err)`
|
|
- Files affected: handler.go, service.go
|
|
|
|
2. **Logging Migration**
|
|
- Replace: `fmt.Println("debug info")`
|
|
- With: `logger.Info("debug info", zap.String("key", "value"))`
|
|
- Import: `import "github.com/LerianStudio/lib-commons/zap"`
|
|
- Files affected: internal/service/*.go
|
|
```
|
|
|
|
### Cross-References
|
|
|
|
| Document | Location | What It Contains |
|
|
|----------|----------|-----------------|
|
|
| **Skill Definition** | `dev-team/skills/dev-refactor/SKILL.md` | HARD GATES requiring Standards Compliance |
|
|
| **Standards Source** | `dev-team/docs/standards/*.md` | Source of truth for compliance checks |
|
|
| **Agent Definitions** | `dev-team/agents/*.md` | output_schema includes Standards Compliance |
|
|
| **Session Hook** | `dev-team/hooks/session-start.sh` | Injects Standards Compliance guidance |
|
|
|
|
---
|
|
|
|
## Related Documents
|
|
|
|
- [CLAUDE.md](../CLAUDE.md) - Main project instructions (references this document)
|
|
- [PROMPT_ENGINEERING.md](PROMPT_ENGINEERING.md) - Language patterns for agent prompts
|
|
- [WORKFLOWS.md](WORKFLOWS.md) - How to add/modify agents
|