Elevate Code

Transform any project into production-quality software using proven patterns.

The Problem: Most projects fail in predictable ways—users can't set them up, accidents cause data loss, crashes waste hours of progress, code becomes unmaintainable, errors are cryptic. These aren't bugs; they're missing patterns.

The Solution: Elevate systematically applies 12 battle-tested patterns that distinguish amateur code from production software.

Quick Start

Mode	When to Use	What Happens
New Project	Starting from scratch	Detect type → Generate scaffold with all patterns
Audit	Reviewing existing code	Detect type → Scan → Gap report
Transform	Elevating existing project	Audit + Propose + Generate missing pieces

The 12 Patterns

The Foundation: The Triad (Patterns 1-3)

Three non-negotiable properties. If your project lacks any of these, fix them first.

Setup should verify. Mistakes should undo. Crashes should resume.

#	Pattern	Litmus Test
1	Health (Doctor)	Can a new user run `tool doctor` and know what's missing?
2	Safety (Safety Net)	Can a mistake be undone in under 60 seconds?
3	Resilience (Statekeeper)	Can interrupted work resume without losing progress?

The Complete Set (Patterns 4-12)

#	Pattern	Problem It Solves
4	Architecture	"The code is a tangled mess"
5	Data Models	"What shape is this data?"
6	Code Organization	"Where does this code go?"
7	Error Handling	"It failed but I don't know why"
8	Testing	"I'm afraid to change anything"
9	Build & Deploy	"How do I ship this?"
10	CLI UX	"This tool is confusing"
11	Documentation	"How does this work?"
12	State Persistence	"Where did my data go?"

Elevation Workflow

Step 1: Detect Project Type

Scan for file markers to identify project type and load the appropriate checklist:

File Markers	Project Type	Checklist
`pyproject.toml` + `[project.scripts]`	Python CLI	python-cli.md
`package.json` + `"bin"` field	Node.js CLI	node-cli.md
`manifest.json` + `"background"`	Browser Extension	browser-extension.md
`pyproject.toml` + `fastapi` in deps	REST API (Python)	rest-api.md
`package.json` + `express`/`hono`/`fastify`	REST API (Node)	rest-api.md
`mcp.json` OR `@modelcontextprotocol` imports	MCP Server	mcp-server.md
`action.yml` or `action.yaml`	GitHub Action	github-action.md

Step 2: Scan for Existing Patterns

For each of the 12 patterns, grep for indicators and score as Present, Partial, or Missing:

bash

# Triad
grep -rE "(doctor|check|verify|preflight)" .         # Health
grep -rE "(undo|restore|trash|dry-run)" .            # Safety
grep -rE "(checkpoint|resume|state\.json)" .         # Resilience

# Structure
grep -rE "(@dataclass|interface |TypedDict)" .       # Data Models
grep -rE "(pytest|vitest|conftest|\.test\.)" .       # Testing

# Quality
grep -rE "(retry|backoff|graceful)" .                # Error Handling

Step 3: Generate Gap Report

markdown

## Gap Analysis: <project-name>

**Project Type**: <detected-type>
**Patterns Detected**: X/12

### Present
- [x] Pattern Name - evidence found

### Partial
- [~] Pattern Name - what exists, what's missing

### Missing
- [ ] Pattern Name - why it matters

Step 4: Propose Transformations

For each gap, propose specific changes. Prioritize by impact:

•Triad first (Doctor, Safety, Statekeeper)
•Data Models (foundation for everything else)
•Error Handling (user experience)
•Testing (confidence to change)
•Everything else

Step 5: Generate Scaffold

For missing patterns, generate files from templates/<project-type>/:

•Customize with project name
•Show diff preview before writing

Success Criteria

A fully elevated project passes:

• Triad: doctor ✓, undo ✓, resume ✓
• Type Safety: All data structures typed (dataclass/interface)
• Module Separation: One module = one responsibility
• Error Messages: Include what + why + fix
• Tests: Mocked external deps, >80% coverage on core
• Build Config: Standard tooling (pyproject.toml / package.json)
• AI Collaboration: CLAUDE.md with architecture
• Output Modes: Human + --json + --quiet

Elevate: Because production-quality isn't about perfection—it's about patterns.