# Ring:planning Backend Refactor

> 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-r…

- **Type:** Skill
- **Install:** `agentstack add skill-lerianstudio-ring-planning-backend-refactor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [LerianStudio](https://agentstack.voostack.com/s/lerianstudio)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [LerianStudio](https://github.com/LerianStudio)
- **Source:** https://github.com/LerianStudio/ring/tree/main/dev-team/skills/planning-backend-refactor
- **Website:** https://lerian.studio

## Install

```sh
agentstack add skill-lerianstudio-ring-planning-backend-refactor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Dev Refactor Skill

## When to use
- User wants to refactor existing project to follow standards
- Legacy codebase needs modernization
- Project audit requested

## Skip when
- Greenfield project → Use ring:planning-large-features or ring:planning-small-features instead
- Single file fix → Use ring:running-dev-cycle directly
- Frontend project → Use ring:planning-frontend-refactor

Analyzes existing backend codebase against Ring/Lerian standards and generates refactoring tasks for ring:running-dev-cycle.

You orchestrate. Agents analyze. NEVER run Bash/Grep/Read to analyze code directly — dispatch agents.

## Gap Principle

Every divergence from Ring standards = a mandatory gap to implement. No exceptions.

All divergences → FINDING-XXX → REFACTOR-XXX task → ring:running-dev-cycle input.

## Architecture Pattern Applicability

| Service Type | Apply Hexagonal/Lerian Pattern? |
|---|---|
| CRUD API | ✅ YES |
| Complex business logic | ✅ YES |
| Event-driven systems | ✅ YES |
| CLI tools / scripts | ❌ NO |
| Workers / background jobs | ❌ NO |
| Simple lambdas | ❌ NO |

## Execution Steps

### Step 1: Validate Prerequisites

- Check `docs/PROJECT_RULES.md` exists → STOP if missing
- Detect stack: `go.mod` → Go; `package.json` + Express/Fastify/NestJS (no React) → TypeScript
- If `package.json` + React/Next.js → STOP: use `ring:planning-frontend-refactor`

### Step 2: Generate Codebase Report

Dispatch `ring:codebase-explorer`:

```
Generate comprehensive codebase report: project structure, architecture pattern,
tech stack, code patterns (config, database, handlers, errors, telemetry, testing),
key files inventory with file:line references, code snippets.
Output: docs/ring:planning-backend-refactor/{timestamp}/codebase-report.md
```

### Step 3: Dispatch Specialist Agents (parallel)

Verify `codebase-report.md` exists before dispatching.

**For Go projects — dispatch backend analysis:**

```yaml
Task 1: ring:backend-go (MODE: ANALYSIS only)
  - Load golang.md via WebFetch
  - Check all sections per shared-patterns/standards-coverage-table.md
  - Flag framework/library mismatches vs standards
  - File size enforcement: >1000 lines = ISSUE-XXX (HIGH), >1500 = CRITICAL
  - Multi-tenant analysis per shared-patterns/multi-tenant-analysis.md
  - Check tests, coverage, docker-compose/local runtime, and observability as backend-owned responsibilities
  - Output: Standards Coverage Table + ISSUE-XXX per finding
```

**For TypeScript projects:**
Use `ring:backend-ts` with the same analysis contract.

### Step 4: Map Findings → Tasks

After all agents complete:

1. Save individual agent reports to `docs/ring:planning-backend-refactor/{timestamp}/`
2. Map each ISSUE-XXX → FINDING-XXX (normalize severity, add file:line, current vs expected)
3. Generate `docs/ring:planning-backend-refactor/{timestamp}/findings.md`
4. Map each FINDING-XXX → one REFACTOR-XXX task (1:1 mapping)
5. Generate `docs/ring:planning-backend-refactor/{timestamp}/tasks.md` (ring:running-dev-cycle compatible)

**Findings template:**
```markdown
# {project-name} Refactor Findings

## FINDING-001: {Pattern Name} in {file_path}
- **Severity:** CRITICAL | HIGH | MEDIUM | LOW
- **File:** {path}:{line}
- **Current:** {code or description}
- **Expected:** {Ring standard}
- **Standard Reference:** {standards doc section}
```

**Tasks template:**
```markdown
# {project-name} Refactor Tasks

## REFACTOR-001: {Pattern Name} in {file_path}
- **Finding:** FINDING-001
- **Estimated Complexity:** trivial | moderate | complex
- **Acceptance Criteria:**
  - [ ] {specific, testable criteria}
```

### Step 5: Visual Change Report + User Approval

Generate visual HTML summary of KILL/CHANGE/ADD operations → dispatch `ring:visualizing`.

Present to user for approval. Wait for explicit APPROVED.

### Step 6: Save + Handoff

Save all artifacts to `docs/ring:planning-backend-refactor/{timestamp}/`.

Handoff to `ring:running-dev-cycle`: feed tasks.md as input.

## Agent Analysis Report Template

```markdown
# {Agent Name} Analysis Report

## EXPLORATION SUMMARY
High-level architecture assessment

## KEY FINDINGS
ISSUE-XXX list with file:line, current, expected

## ARCHITECTURE INSIGHTS
Patterns detected, notable deviations

## RELEVANT FILES
Files most impacted by findings

## RECOMMENDATIONS
Priority order for refactoring
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LerianStudio](https://github.com/LerianStudio)
- **Source:** [LerianStudio/ring](https://github.com/LerianStudio/ring)
- **License:** Apache-2.0
- **Homepage:** https://lerian.studio

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lerianstudio-ring-planning-backend-refactor
- Seller: https://agentstack.voostack.com/s/lerianstudio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.