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.