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:

# 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

## 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:

1. Triad first (Doctor, Safety, Statekeeper)
2. Data Models (foundation for everything else)
3. Error Handling (user experience)
4. Testing (confidence to change)
5. 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.