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